Upgrade from v4

This page explains how to move a v4 site to Release 5.0.0 with one command. The site is unusable while it moves, so schedule a maintenance window. There is no figure yet for how long it takes. Practise on a copy of the data and time it first.

What changes from v4Copy Anchor Link

• There is no datastore-services any more. Every node connects to the databases itself through a connection string, and there are two new nodes: file-services and tile-indexer.
• The containers of every node and every app are all replaced with new ones. Existing users stay as they are, and the system makes no extra administrator.
• The API accepts only a Bearer token or an API key to prove who you are.
• There is a new container, portal. It serves the platform's front page at /, and signing in directly now takes people there instead of to a 404 or Drive. Public access is off, so nothing is open for people who are not signed in until an administrator turns it on (Public access).
• The system copies the old v4 logs into the Audit log. When the copy is done, it deletes the Activities older than AUDIT_RETENTION_DAYS (default 365 days). To keep them longer, set this value before the first start. 0 keeps everything.

Before you startCopy Anchor Link

1. The four databases must meet the Requirements: MongoDB 4.2 or newer (the log database 5.0 or newer), the content database a replica set, and its user able to write awhere-tiles.
2. If you have your own proxy, add /api/file pointing to file-services, placed before the /api rule. Add /api/item/<id>/actions/getTile/ pointing to tile-services. Change /api/log to point to port 3000 (v4 used 4000). Send all the remaining paths, including /, to portal as the rule with the lowest priority. Then set it to remove the X-Auth-* headers (If you use your own proxy).
3. Have disk space ready for the backup: enough for the four databases plus the v4 images.

Move the siteCopy Anchor Link

awhere setup --from-v4 /path/to/v4-env --v4-prefix v4-

• /path/to/v4-env is the folder that holds the v4 env files. It can also point at a single file, such as the compose .env. If v4 runs on Docker, the file is usually next to compose.yaml. If it runs on Apple Container, it is in /etc/awhere.
• --v4-prefix is the prefix of the v4 container names. Always give it.
• The command reads the database addresses, PLATFORM_URL and NAMESPACE from the v4 files for you. If you give any of these as a flag, the flag wins.

The command works in the order below. It does not stop or change anything in the old site until the backup is complete.

1. It checks, without changing anything, that the four databases answer and that no OAuth client uses an id that an app also uses. If a check fails, the command stops and shows what to fix.
2. It backs up to --backup-dir: a dump of the four databases, the env files and every v4 image. If you do not give --backup-dir, the command makes a folder v4-backup-<date> and prints its name.
3. It asks you to confirm, then stops the v4 containers whose names start with the value of --v4-prefix. The command does not touch v4's MongoDB, NATS, Redis or proxy.
4. It sets up, runs Preflight and deploys the new site. The new site starts its own NATS and Redis. The four databases stay where they were.

If an OAuth client uses the same id as an app, ask the owner of the client whether it is still in use. If it is, have them make a new client of their own and then delete the old one permanently, because a client deleted with a soft delete still holds that id.

After the upgradeCopy Anchor Link

1. Run awhere status and awhere preflight, then open the System page in Configuration. Every node must be on Release 5.0.0 and every Migration must show Done or Running. The old Audit log appears when the Migration logging-copy-legacy-logs is done.

2. Give users back the right to read the Audit log. In v4 everyone could read it, but now only the admin role and roles with the viewAuditLog permission can. The usage numbers need the viewUsage permission. The Roles page has no checkbox for these two permissions yet, so set them in the database directly with the command below (this command changes real data). Replace <role> with the id of the role, then have the users in that role sign in again.

   Copy Text

   mongosh "$DATASTORE_URL" --quiet --eval '
     printjson(db.roles.updateOne({ _id: "<role>" }, { $set: { "administration.viewAuditLog": true, "administration.viewUsage": true } }))'

3. On the Apps page, check that each app's address is right: PLATFORM_URL followed by the app's path. Then open Drive and check that thumbnails show.

Do not delete anything of v4 until you are sure the new site works.

Go back to v4Copy Anchor Link

awhere rollback --to-v4 <backup-dir>

<backup-dir> is the backup folder that awhere setup --from-v4 printed. The command stops the containers of the new site (the data stays) and starts the v4 containers from the backup. It does not restore the databases for you. It prints the restore commands for you to run. You must also change v4's proxy settings back yourself. Audit log entries made after the upgrade stay in the database, but v4 cannot read them.