194 lines
8.7 KiB
Markdown
194 lines
8.7 KiB
Markdown
# 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`.
|