mirror of
https://github.com/mauriceboe/TREK.git
synced 2026-11-20 11:06:06 +00:00
633e9bcdc1
- Database-Postgres: supported versions, the version 18 client and the tool search order, sslrootcert with a client before 16, how to create a role that is not a superuser and move an older compose install to one, a current schema other than public, and the space a restore needs. - Updating: the manual rollback clears the whole schema and loads the copy in one transaction, as TREK's restore does; dropping only the tables left the collation, the trigger functions and the sequences behind. A unit test keeps the printed statement equal to CLEAR_SCHEMA_SQL, and the boot's rollback hint points at that section. - Troubleshooting, Install-Docker-Compose, Environment-Variables, README and server/CLAUDE.md follow.
257 lines
20 KiB
Markdown
257 lines
20 KiB
Markdown
# Updating
|
|
|
|
How to update TREK to a newer version without losing data.
|
|
|
|
## Before You Update
|
|
|
|
Back up your data first. Go to Admin Panel → **Backup** and create a manual backup, or copy your `./data` and `./uploads` directories to a safe location. See [Backups](Backups) for details.
|
|
|
|
## Image Tags
|
|
|
|
| Tag | Example | Behavior |
|
|
|---|---|---|
|
|
| `latest` | `mauriceboe/trek:latest` | Always the newest release across all major versions |
|
|
| Major version | `mauriceboe/trek:5` | Latest release pinned to that major version |
|
|
| Minor version | `mauriceboe/trek:5.0` | Latest patch of that minor version; never moves to the next minor. Published from 5.0.0 on: 4.x releases have no minor tag, so pin those by major or full version |
|
|
| Full version | `mauriceboe/trek:5.0.0` | Exact release; never changes |
|
|
| Prerelease | `mauriceboe/trek:latest-pre` | The newest test build of the next version. For trying it out on a copy of your data, not for the instance you rely on |
|
|
|
|
Use `latest` or a major-version tag if you want updates on each redeploy. A minor-version tag still brings fixes but waits for you to move to the next minor, which is where larger changes and database upgrades usually land. Use a full version tag for explicit control: update by changing the tag, not by re-pulling.
|
|
|
|
## Docker Compose (Recommended)
|
|
|
|
**`latest`, major-version or minor-version tag:**
|
|
|
|
```bash
|
|
docker compose pull && docker compose up -d
|
|
```
|
|
|
|
This pulls the newest matching image and recreates the container with your existing volumes. Your data is untouched.
|
|
|
|
**Pinned full-version tag:**
|
|
|
|
Edit `docker-compose.yml`, update the tag in the `image:` line (e.g. `5.0.0` → `5.0.1`), then redeploy:
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
## Docker Run
|
|
|
|
If you started TREK with `docker run`, pull the new image and replace the container:
|
|
|
|
```bash
|
|
docker pull mauriceboe/trek
|
|
docker rm -f trek
|
|
docker run -d --name trek -p 3000:3000 \
|
|
-v ./data:/app/data \
|
|
-v ./uploads:/app/uploads \
|
|
-e ENCRYPTION_KEY=<your-key> \
|
|
--restart unless-stopped \
|
|
mauriceboe/trek
|
|
```
|
|
|
|
> **Tip:** Not sure which volume paths you used? Check before removing:
|
|
> ```bash
|
|
> docker inspect trek --format '{{json .Mounts}}'
|
|
> ```
|
|
|
|
## Helm (Kubernetes)
|
|
|
|
> **⚠️ Chart repository moved:** The Helm chart is no longer served at `https://mauriceboe.github.io/TREK` (the project moved from a personal repo to the `liketrek` organization). The canonical chart URL is now `https://chart.liketrek.com` — a custom domain (CNAME) for the GitHub Pages site at `https://liketrek.github.io/TREK`, so it stays stable even if the repository moves again. If your `trek` repo still points to an old URL, switch it before updating:
|
|
>
|
|
> ```bash
|
|
> helm repo remove trek
|
|
> helm repo add trek https://chart.liketrek.com
|
|
> ```
|
|
>
|
|
> You can check which URL you have configured with `helm repo list`. Existing releases are unaffected — only the repo URL changes.
|
|
|
|
To update to the newest chart release:
|
|
|
|
```bash
|
|
helm repo update
|
|
helm upgrade trek trek/trek
|
|
```
|
|
|
|
Your existing values and PVCs (data, uploads) are preserved. To pin an exact chart version instead, pass `--version <x.y.z>`.
|
|
|
|
See [Install-Helm](Install-Helm) for the full installation walkthrough and values reference.
|
|
|
|
## Database Migrations
|
|
|
|
TREK runs any pending database migrations automatically at startup. No manual migration steps are required after pulling a new image.
|
|
|
|
Migrations only go forward, so going back to an older image means going back to a copy of the database from before the update. Images from 5.0 on refuse to start on a database a newer TREK has migrated. Images from 4.3.x and earlier do not check this: they start on the newer database without a warning, so restore the copy before you start one of them.
|
|
|
|
TREK takes that copy itself. Right before a startup applies pending migrations, it writes the database to `data/pre-migrate-<schema>-<time>.db` (next to `travel.db`, or next to the file `TREK_DB_FILE` names) and logs the path. On PostgreSQL it writes a `.pgdump` file instead; see [Rolling back a Postgres update](#rolling-back-a-postgres-update). `<schema>` names what the copy holds: `legacy-244` for a 4.3.3 install, or the last migration's number for a newer one. The newest three are kept (`TREK_DB_PRE_MIGRATE_SNAPSHOT_KEEP`). A restart with nothing to migrate and a brand-new install take no copy.
|
|
|
|
If the copy cannot be written (the disk is full, or the data directory is read-only), TREK does not migrate and refuses to start, with a message naming the path. Free some space and start again. If you cannot, and you have a backup of your own, `TREK_DB_PRE_MIGRATE_SNAPSHOT=false` starts without the copy.
|
|
|
|
To go back to the previous image after an update:
|
|
|
|
1. Stop TREK.
|
|
2. Copy the `pre-migrate-…db` file over `data/travel.db` and delete `data/travel.db-wal` and `data/travel.db-shm`.
|
|
3. Start the previous image.
|
|
|
|
An image from 5.0 on that refuses a newer database names the copy it can run, if one is in the data directory. An image from 4.3.x or earlier neither refuses nor points at the copy, so for those, steps 1 to 3 are the only way back. Uploads are not part of this copy; they are not changed by migrations. The copy is a safety net for the update, not a backup: keep taking backups as described in [Backups](Backups).
|
|
|
|
### Rolling back a Postgres update
|
|
|
|
On a [PostgreSQL database](Database-Postgres) the copy TREK takes before a migration is `data/pre-migrate-<schema>-<time>.pgdump`, a `pg_dump` custom-format file, and the procedure is different from the SQLite one above. The copy holds the database only. Anything written after it was taken is lost when you roll back, and the uploads are not affected.
|
|
|
|
The copy cannot be loaded over the migrated schema: it recreates TREK's tables, its `nocase` collation, its trigger functions and its sequences, and every one of them still exists. Dropping only the tables is not enough, because the functions, the collation and the sequences a table does not own stay behind, and the load then stops at the first one that already exists. So the steps below clear the whole schema and load the copy in one transaction, the way TREK's own restore does: a load that fails leaves the database as it was.
|
|
|
|
1. Stop TREK.
|
|
2. Turn the copy into a SQL script, with client tools of a version that carries the CVE-2025-8714 fix (18.0, 17.6, 16.10, 15.14 or 14.19 at least) and that is at least as new as the server. Name the schema TREK's tables are in, normally `public`:
|
|
|
|
```bash
|
|
pg_restore --no-owner --no-privileges --schema=public --file=restore.sql data/pre-migrate-<schema>-<time>.pgdump
|
|
```
|
|
|
|
3. Save this block as `clear-schema.sql`. It drops every table, view, sequence, function, collation and type in the current schema, which is what TREK's restore runs before it loads a backup:
|
|
|
|
```sql
|
|
DO $clear$
|
|
DECLARE r record;
|
|
BEGIN
|
|
FOR r IN SELECT c.oid::regclass AS name, c.relkind FROM pg_class c
|
|
WHERE c.relnamespace = current_schema()::regnamespace AND c.relkind IN ('r', 'p', 'v', 'm', 'S', 'f')
|
|
AND NOT EXISTS (SELECT 1 FROM pg_depend d WHERE d.objid = c.oid AND d.deptype IN ('e', 'a', 'i'))
|
|
LOOP
|
|
EXECUTE format('DROP %s IF EXISTS %s CASCADE',
|
|
CASE r.relkind WHEN 'v' THEN 'VIEW' WHEN 'm' THEN 'MATERIALIZED VIEW' WHEN 'S' THEN 'SEQUENCE'
|
|
WHEN 'f' THEN 'FOREIGN TABLE' ELSE 'TABLE' END, r.name);
|
|
END LOOP;
|
|
FOR r IN SELECT p.oid::regprocedure AS sig FROM pg_proc p
|
|
WHERE p.pronamespace = current_schema()::regnamespace
|
|
AND NOT EXISTS (SELECT 1 FROM pg_depend d WHERE d.objid = p.oid AND d.deptype = 'e')
|
|
LOOP
|
|
EXECUTE format('DROP ROUTINE IF EXISTS %s CASCADE', r.sig);
|
|
END LOOP;
|
|
FOR r IN SELECT format('%I.%I', n.nspname, c.collname) AS name FROM pg_collation c
|
|
JOIN pg_namespace n ON n.oid = c.collnamespace
|
|
WHERE n.nspname = current_schema()
|
|
AND NOT EXISTS (SELECT 1 FROM pg_depend d WHERE d.objid = c.oid AND d.deptype = 'e')
|
|
LOOP
|
|
EXECUTE format('DROP COLLATION IF EXISTS %s CASCADE', r.name);
|
|
END LOOP;
|
|
FOR r IN SELECT t.oid::regtype AS name FROM pg_type t
|
|
WHERE t.typnamespace = current_schema()::regnamespace AND t.typtype IN ('e', 'd', 'r')
|
|
AND NOT EXISTS (SELECT 1 FROM pg_depend d WHERE d.objid = t.oid AND d.deptype IN ('e', 'i'))
|
|
LOOP
|
|
EXECUTE format('DROP TYPE IF EXISTS %s CASCADE', r.name);
|
|
END LOOP;
|
|
END
|
|
$clear$;
|
|
```
|
|
|
|
4. Clear the schema and load the script in one transaction, connected as TREK's own role (the URL in `TREK_DB_URL`):
|
|
|
|
```bash
|
|
psql "postgres://user@host:5432/trek?sslmode=require" --no-psqlrc --single-transaction --set=ON_ERROR_STOP=1 --file=clear-schema.sql --file=restore.sql
|
|
```
|
|
|
|
Put the password in the `PGPASSWORD` environment variable rather than in the URL, which keeps it out of the command line. Delete `restore.sql` afterwards: it holds the whole database in plain text.
|
|
5. Start the previous image with the same `TREK_DB_URL`.
|
|
|
|
On a server you administer, dropping the database and creating it again with the same owner, then loading the copy with `pg_restore --no-owner --no-privileges --single-transaction -d <url> <copy>`, works as well.
|
|
|
|
A TREK image without PostgreSQL support cannot read this database at all. It would start on a new SQLite file instead. An image from 5.0 on that refuses a newer database names the copy it can run, if one is in the data directory.
|
|
|
|
## After the Update
|
|
|
|
The first time a user opens TREK on the desktop after an update, a notice headed **Update installed** opens on top of the app: three cards with the headline features of that release, a note from the maintainer, a **Release notes** link to the full notes on GitHub, and links for supporting the project. Every user sees it once per version. Closing it keeps it closed on that version, and the next update brings it back, a patch release included. The phone does not show it.
|
|
|
|
The full notes for every version are also in the admin panel under the **GitHub** tab. See [Admin-GitHub-Releases](Admin-GitHub-Releases).
|
|
|
|
## Upgrading to 4.3.0
|
|
|
|
A few defaults change with 4.3.0. None of them needs a manual step, but they are worth knowing before you pull the image:
|
|
|
|
- **Place search asks a new service.** Suggestions, the full search, the category buttons, import geocoding, offline downloads and the Road trip search now ask the TREK Places API at `https://places.liketrek.com`, so your server makes outbound requests to that host. Set `TREK_PLACES_ENABLED=false` to keep searching the way it did before, or `TREK_PLACES_URL` to point at a copy you run yourself. [TREK-Places-API](TREK-Places-API) lists what is sent.
|
|
- **New variables.** `NOMINATIM_URL` points every geocoding call at a Nominatim of your own, `ALLOW_LINK_LOCAL_IPS` lets a rootless Podman container reach its host gateway, and `AMAP_API_KEY`, `AMAP_API_SECRET` and `AMAP_API_BASE` put Amap into place search for mainland China. All of them are optional. See [Environment-Variables](Environment-Variables).
|
|
- **`OVERPASS_TIMEOUT_MS` now defaults to `25000`** instead of `12000`. If you set a lower value by hand, remove it: the query gives Overpass 20 seconds of work, and a shorter timeout hangs up on answers that were still coming.
|
|
- **SSO sessions on an OIDC-only instance last 30 days.** The login page sends `remember=1` on that path, so the session gets the `SESSION_DURATION_REMEMBER` lifetime (default `30d`) instead of `SESSION_DURATION` (default `24h`). Lower `SESSION_DURATION_REMEMBER` if that is too long. With password login on, the SSO button follows the Remember-me switch instead. See [OIDC-SSO](OIDC-SSO).
|
|
- **Booked nights get a stop.** A migration puts every existing stay that has a place on its check-in day as a hotel stop, so the trips you already have show their hotels in the [Road-Trip](Road-Trip) view without anyone re-saving a booking. Under **Days** nothing changes: that stop stays hidden behind the badge the booking already shows. See [Accommodations](Accommodations).
|
|
- **Two things are on by default.** The **Links** tab in Collab, which an admin switches off under **Admin → Addons**, and the routing counters, daily totals of the route requests the planner makes that never leave the instance. An admin reads them at `/api/route-usage/summary`; an `app_settings` row named `route_usage_enabled` with the value `false` switches them off.
|
|
|
|
## Upgrading to 4.3.1
|
|
|
|
Two things change with 4.3.1. Neither needs a manual step on Docker, but they are worth knowing before you pull the image:
|
|
|
|
- **Booked nights lead their day.** A migration moves every booked night to the head of its check-in day, behind only a stop whose own time is at or before the check-in, and the stops without an hour follow it: a hotel booked for ten in the morning is reached at ten in the [Road-Trip](Road-Trip) view, not at a quarter past twelve behind a whole day of untimed stops. A night booked for the end of a driving day heads that day too when its stops carry no time of their own, so such a day now reads hotel first. A via point drawn on the road into that hotel from the stop that is now last is removed, because that leg no longer exists in the day, the same way a drag would remove it; the other vias follow their stops. Under **Days** nothing changes. To put a hotel back at the end, drag it down the day in the Road Trip rail, or give the first stop after it a start time at or before the check-in, which brings the untimed stops behind that one along; a time on the last stop alone leaves the hotel in the middle of the day. See [Accommodations](Accommodations#on-the-route).
|
|
- **Source installs need a build toolchain, or `--ignore-scripts`.** The server runs better-sqlite3 13, which ships its binaries inside the package, so nothing is compiled any more; the Docker image and the Helm chart are unaffected. On an install that runs `npm ci` itself, outside Docker, a lockfile-driven `npm ci` still runs node-gyp against those binaries and stops without Python 3 and a C++ toolchain (`build-essential` on Debian/Ubuntu, the Xcode Command Line Tools on macOS, the Visual Studio Build Tools on Windows; npm/cli#9837). Either keep those installed, as [Development-environment](Development-environment) lists them, or run `npm ci --ignore-scripts`, which is what the image does.
|
|
|
|
## Upgrading to 5.0
|
|
|
|
5.0 is a large release. Apart from the point below about the Places API, updating needs no manual step on any install method: migrations run at startup, and TREK copies the database first (see [Database Migrations](#database-migrations)).
|
|
|
|
- **A new look, and a phone interface of its own.** Dialogs are redesigned and the phone gets its own screens instead of a squeezed desktop layout. Open apps switch over after **Reload page** (see [Open apps after an update](#open-apps-after-an-update)).
|
|
- **New features.** Tours, TREK Studio for journeys, the AI Assistant addon, notifications in an inbox, trip settings and a Help Center inside the app. The addons are switched on or off under **Admin → Addons**; see [Addons-Overview](Addons-Overview) and [Help-Center](Help-Center).
|
|
- **AI assistant secrets are encrypted** with your `ENCRYPTION_KEY` like the other stored secrets, and the connections need no action on update. A key rotation covers them; see [Encryption-Key-Rotation](Encryption-Key-Rotation).
|
|
- **Web Push needs no VAPID setup.** TREK generates its key pair on first start and keeps it in the database. See [Environment-Variables](Environment-Variables#web-push).
|
|
- **Remove any `APP_VERSION` override.** The version now comes from the image itself. A leftover `APP_VERSION=` line in your compose file, `.env` or Portainer stack only gets in the way.
|
|
- **Tours asks the TREK Places API first.** The grades, surfaces and kinds of way under a planned tour and the horse routes around the map are read from `https://places.liketrek.com`, and the Overpass mirrors are asked only when it has no answer. An `OVERPASS_URL` pointed at an internal Overpass therefore no longer keeps these lookups inside your network: set `TREK_PLACES_ENABLED=false`, or point `TREK_PLACES_URL` at a copy you run yourself. [TREK-Places-API](TREK-Places-API#what-leaves-your-instance) lists what is sent.
|
|
|
|
## Encryption Key Note
|
|
|
|
If you are upgrading from a version that predates the dedicated `ENCRYPTION_KEY` (i.e. you have no `ENCRYPTION_KEY` environment variable set), TREK automatically falls back to `./data/.jwt_secret` on startup and immediately promotes it to `./data/.encryption_key`. No manual steps are required — the transition is handled at first boot after the upgrade.
|
|
|
|
If you want to rotate to a new key at any point (not required for a normal update), see [Encryption-Key-Rotation](Encryption-Key-Rotation) for the full procedure.
|
|
|
|
## Proxmox VE (LXC)
|
|
|
|
If you installed TREK via the [Proxmox VE Community Scripts](https://community-scripts.org/scripts/trek), run the following command inside the **LXC container** and select **Update** when prompted:
|
|
|
|
```bash
|
|
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/trek.sh)"
|
|
```
|
|
|
|
> **Tip:** Always check the [community-scripts TREK page](https://community-scripts.org/scripts/trek) to confirm the latest command before running.
|
|
|
|
The script stops the service, backs up your data and uploads, applies the new release, restores the backup, and restarts. No manual steps required.
|
|
|
|
To verify the update completed and check for errors:
|
|
|
|
```bash
|
|
# Inside the container (pct enter <id> from the Proxmox shell)
|
|
journalctl -u trek -n 50
|
|
```
|
|
|
|
## Portainer
|
|
|
|
Open the **Stacks** list, click the TREK stack, then click **Redeploy**.
|
|
|
|
**`latest`, major-version or minor-version tag**: enable the **Re-pull image and redeploy** switch before confirming. Portainer pulls the newest matching image and recreates the container.
|
|
|
|

|
|
|
|
**Pinned full-version tag** (e.g. `5.0.0`), edit the stack, update the tag in the `image:` line, then click **Update the stack**. No re-pull switch needed; the tag change forces a fresh pull.
|
|
|
|

|
|
|
|

|
|
|
|
Portainer's **Recreate** on a single container keeps that container's environment, which on images before 5.0 included the previous release's `APP_VERSION`. TREK then kept reporting the old version and open apps did not switch to the new interface. Images from 5.0 on take the version from a file inside the image, so a recreated container reports the image it actually runs.
|
|
|
|
See [Install-Portainer](Install-Portainer) for the full installation walkthrough.
|
|
|
|
## Unraid
|
|
|
|
In the Unraid Docker tab, click the TREK container and select **Update**. Unraid will pull the latest image and restart with the same volumes.
|
|
|
|
## TrueNAS SCALE
|
|
|
|
Back up your data and uploads, then update TREK from **Apps → Installed Applications** when an update is available. TrueNAS catalog updates may arrive separately from TREK releases. See [Install-TrueNAS-SCALE](Install-TrueNAS-SCALE) and [Database Migrations](#database-migrations) for storage and rollback guidance.
|
|
|
|
## Open apps after an update
|
|
|
|
A browser tab or installed app that stays open while you update notices the new version as soon as it reconnects to the restarted server. It shows a small notice with **Reload page**, which loads the new version without waiting for the next start; a page that is closed and opened again switches on its own. The notice stays away while the device is offline and can be closed until the next start.
|
|
|
|
## Next Steps
|
|
|
|
- [Backups](Backups) — schedule automatic backups so you always have a restore point before updates
|
|
- [Encryption-Key-Rotation](Encryption-Key-Rotation) — if you need to rotate or migrate the encryption key
|
|
- [Install-Docker-Compose](Install-Docker-Compose) — switch to Compose for easier future updates
|