v_1.5_patch_0.2
This commit is contained in:
jpmvaz
+193
@@ -0,0 +1,193 @@
|
||||
# Upgrading an existing installation to v1.5 Patch 0.2
|
||||
|
||||
**Short answer: yes.** This release changes only application code. Your
|
||||
database, uploaded files, and brand images are never touched by the upgrade,
|
||||
and the new database table is created automatically on the first start.
|
||||
|
||||
**If you are already on v1.3, v1.4 or v1.5 (any patch)**, the archive folder is named
|
||||
`martinhal-isdss`, the same as your install, so extracting on top of it works
|
||||
directly.
|
||||
|
||||
**If you are coming from v1.1/v1.2**, the folder inside the archive was renamed
|
||||
from `martinhal-datahub` to `martinhal-isdss`, so a plain "unzip on top" would
|
||||
create a *second* directory beside your install instead of updating it. Use the
|
||||
commands below either way — they extract the contents *into* your existing
|
||||
folder and are safe in both cases.
|
||||
|
||||
---
|
||||
|
||||
## What is preserved
|
||||
|
||||
| Item | Where it lives | Preserved? |
|
||||
|------|----------------|-----------|
|
||||
| User accounts & passwords | `data/datahub.db` | ✅ untouched |
|
||||
| MFA enrolments | `data/datahub.db` | ✅ untouched |
|
||||
| Folders & files (metadata) | `data/datahub.db` | ✅ untouched |
|
||||
| Uploaded file contents | `uploads/` | ✅ untouched |
|
||||
| Brand images | `brand/` | ✅ untouched |
|
||||
| Access requests & approvals | `data/datahub.db` | ✅ untouched |
|
||||
| Customised email templates | `data/datahub.db` | ✅ untouched |
|
||||
| Audit logs | `data/datahub.db` | ✅ untouched |
|
||||
| Version Control entries | `data/datahub.db` | ✅ untouched |
|
||||
| Email log history | `data/datahub.db` | ✅ untouched |
|
||||
| Saved mail server settings | `data/datahub.db` | ✅ untouched |
|
||||
| Customised email templates | `data/datahub.db` | ✅ never overwritten |
|
||||
| `SMTP_*` settings in `.env` | `.env` | ✅ still used automatically |
|
||||
| Your `.env` file | `.env` | ✅ not in the archive |
|
||||
|
||||
The archive ships `data/`, `uploads/`, and `brand/` containing only an empty
|
||||
`.gitkeep` placeholder — no database and no files — so extracting over your
|
||||
install cannot overwrite your data.
|
||||
|
||||
**Two files WILL be replaced:** `docker-compose.yml` and `.env.example`. If you
|
||||
edited your compose file (ports, extra volumes, a reverse proxy), back it up
|
||||
first and re-apply your changes afterwards. Your `.env` is safe.
|
||||
|
||||
---
|
||||
|
||||
## Always: back up first
|
||||
|
||||
```bash
|
||||
# Docker (named volumes)
|
||||
docker compose stop
|
||||
docker run --rm -v datahub-data:/d -v "$PWD:/backup" alpine \
|
||||
tar czf /backup/isdss-backup-$(date +%F).tar.gz -C /d .
|
||||
|
||||
# Plain install
|
||||
tar czf isdss-backup-$(date +%F).tar.gz data uploads brand .env
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Docker upgrade
|
||||
|
||||
```bash
|
||||
cd /path/to/your/existing/install
|
||||
|
||||
cp docker-compose.yml docker-compose.yml.bak # keep your customisations
|
||||
docker compose down # keeps volumes (never use -v)
|
||||
|
||||
# extract the archive's CONTENTS into this directory
|
||||
unzip -o ../martinhal-isdss-v1.5-patch0.2.zip -d /tmp/isdss-new
|
||||
cp -a /tmp/isdss-new/martinhal-isdss/. .
|
||||
|
||||
# re-apply anything you had customised in compose, then rebuild
|
||||
docker compose up -d --build
|
||||
docker compose logs -f
|
||||
```
|
||||
|
||||
Named volumes (`datahub-data`, `datahub-uploads`, `datahub-brand`) are not
|
||||
recreated by a rebuild, so all data carries over. Do **not** run
|
||||
`docker compose down -v` — that deletes the volumes.
|
||||
|
||||
## Plain (non-Docker) upgrade
|
||||
|
||||
```bash
|
||||
cd /path/to/your/existing/install
|
||||
# stop the running server first (Ctrl-C, or systemctl stop <your-unit>)
|
||||
|
||||
unzip -o ../martinhal-isdss-v1.5-patch0.2.zip -d /tmp/isdss-new
|
||||
cp -a /tmp/isdss-new/martinhal-isdss/. .
|
||||
|
||||
npm install # optional: no new dependencies in 1.3, but harmless
|
||||
npm start # the schema updates itself on boot
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
> **This release changes no database structure.** It adds a page that reads
|
||||
> what is already there, so the upgrade is purely a code swap.
|
||||
|
||||
## What happens automatically on first start
|
||||
|
||||
- New tables (`version_entries`, `mail_log`, `legislation_entries`) are created
|
||||
via `CREATE TABLE IF NOT EXISTS`. Existing tables are left exactly as they are.
|
||||
- Columns are added with `ALTER TABLE ADD COLUMN`, which is non-destructive:
|
||||
`folders.recorded_date`, and `access_requests.access_duration` /
|
||||
`access_expires_at`. Existing rows keep all their data. The server prints a
|
||||
line for each on the first start after an upgrade.
|
||||
- **Existing approvals are preserved as permanent.** Anyone who already had
|
||||
access keeps it, with no expiry, so nobody is locked out by the new validity
|
||||
windows. Only approvals granted from now on carry a time limit.
|
||||
- Existing `SMTP_*` / `MAIL_FROM` environment variables keep working unchanged.
|
||||
The new **Email Server** page shows them as coming from the environment; you
|
||||
only need to touch it if you want to manage the settings in the interface
|
||||
instead.
|
||||
- The first-boot setup wizard does **not** reappear, because your database
|
||||
already contains users. You sign in with your existing credentials.
|
||||
- Default email templates are only inserted when missing, so your customised
|
||||
subjects and bodies are kept.
|
||||
|
||||
---
|
||||
|
||||
## Behaviour changes to expect (no data loss, but visible)
|
||||
|
||||
1. **Folder contents are now hidden until access is granted.** Regular users
|
||||
see only top-level folder names; sub-folders and files appear once a folder
|
||||
request is approved. Your existing folders and files are all still there —
|
||||
administrators see everything as before.
|
||||
2. **Folder approval now cascades.** A user approved for a folder can open
|
||||
everything inside it without further requests.
|
||||
3. **Existing file-level approvals still work.** Anyone who was previously
|
||||
approved for a specific file keeps that access; nothing needs re-approving.
|
||||
4. Two new admin tabs appear in Data Management: **Email Server** (SMTP
|
||||
configuration) and **Email Log** (every message sent, exportable/emailable).
|
||||
5. New access requests email every administrator with a pending-approval
|
||||
notice. If you had customised the `request_to_admin` template, **your
|
||||
wording is kept** — the improved default (with the review link and pending
|
||||
count) is available via **Restore default** in the template editor.
|
||||
6. **Email is now mandatory on user accounts.** Existing accounts are not
|
||||
touched and nobody is locked out. If any account has no address it is
|
||||
flagged in Data Management → Users (and in the server log at startup) so you
|
||||
can add one. New accounts cannot be created without an address, and an
|
||||
existing address can be changed but not cleared.
|
||||
7. **Folders now require a Recorded Date**, and View Data shows it alongside a
|
||||
derived **Legal Validity** date (recorded + 30 days). Folders created before
|
||||
the upgrade have no date: they keep working, are flagged in Data Management,
|
||||
and you can set a date on each with the calendar button.
|
||||
8. The folder tree in Data Management is now collapsible, and a new
|
||||
**Legislation** page appears in the left menu for everyone.
|
||||
9. **Dates are now shown as DD-MM-YYYY** everywhere, including CSV exports.
|
||||
Stored values are unchanged; only the presentation differs.
|
||||
10. **Approving a request now requires choosing a validity period** (24 hours,
|
||||
15 days, 30 days, or forever), counted from the moment of approval. View
|
||||
Data shows a live countdown per folder, or *Access Denied* where there is
|
||||
no access.
|
||||
11. A new **Storage** page appears in the Administration menu for
|
||||
administrators, showing server disk space and per-folder usage. It only
|
||||
reads the existing data, so there is nothing to configure.
|
||||
12. Signed-in pages now show the **ISDSS logo** in the sidebar instead of the
|
||||
monogram. The login and setup screens are unchanged. The image ships in
|
||||
`public/assets/`, so it arrives with the upgrade automatically.
|
||||
13. Users can set a **profile picture** (My Account), shown by their name in the
|
||||
sidebar. Pictures live in a new `avatars/` Docker volume, added
|
||||
automatically.
|
||||
14. The platform can copy each sent email into the mail server's **Sent folder**
|
||||
over IMAP, configured under Email server. It is optional and best-effort: if
|
||||
IMAP is not set up, sending is unaffected.
|
||||
15. **Uploading files into a folder is fixed.** A dialog bug closed the upload
|
||||
window before the transfer finished; files now upload reliably, with a
|
||||
progress bar showing how far along the transfer is.
|
||||
16. The interface is rebranded to **ISDSS** and the footer now reads
|
||||
`© 2026 Martinhal IT - Joao Vaz - Version 1.5 Patch 0.2`.
|
||||
|
||||
---
|
||||
|
||||
## Verifying the upgrade
|
||||
|
||||
After starting, confirm:
|
||||
|
||||
```bash
|
||||
# should report your existing accounts, not "no users yet"
|
||||
docker compose logs | grep "user account"
|
||||
```
|
||||
|
||||
Then sign in and check: your folders appear under Data Management, a file
|
||||
downloads correctly, and **Logs** still shows your historical entries.
|
||||
|
||||
## Rolling back
|
||||
|
||||
Stop the service, restore the backup archive over `data/`, `uploads/`, and
|
||||
`brand/`, put the previous code back, and start again. Because the upgrade only
|
||||
*adds* a table, an older build will still run against the upgraded database —
|
||||
it simply ignores `version_entries`.
|
||||
Reference in New Issue
Block a user