Upgrading

A SideDoc deployment has no server-side state, so an upgrade is a replacement: start the new image (or copy the new files), check it, and switch traffic. Rolling back is the same in reverse.

Before you upgrade

1. Read the release notes, in particular for:
   • new, renamed or removed settings (compare with Configuration);
   • a new datamodel version or a raised minimum supported version (see Schemas);
   • CSP changes, if you host the files yourself.
2. Tell users to back up first: Back up now in Settings… if they use backups, otherwise an export of the documents they care about. Their workspace in the browser survives an upgrade, but a datamodel change can ask them to convert documents.

Container

git fetch --tags && git checkout v0.7.0          # example: the release you upgrade to
docker buildx build -f docker/Dockerfile --build-arg VERSION=0.7.0 -t sidedoc:0.7.0 .
docker run --rm --read-only --tmpfs /tmp --env-file sidedoc.env sidedoc:0.7.0 true

The last command runs only the entrypoint's validation and exits: 0 means the new image accepts your settings, 64 prints what it rejects. Then replace the running container (with Compose: change SIDEDOC_IMAGE or SIDEDOC_VERSION and run docker compose up -d; with Kubernetes: change the image tag and let the Deployment roll).

Use explicit version tags, not latest, so that you know what runs and can roll back.

Static hosting

Build the new release into a fresh directory and switch over atomically, for example by pointing a symlink at the new directory. Copying over the old files leaves stale assets behind and can serve a mix of old and new files during the copy.

Keep the old /assets/ files for a while if you can: a browser that loaded the old index.html just before the switch still requests the old bundle names. Keep your own config.js when you deploy, because the build contains an empty placeholder.

After an upgrade, compare your server's headers with Static hosting, which follows the current docker/entrypoint.sh and docker/nginx.conf.

After the upgrade

curl -fsS https://sidedoc.example.org/healthz                      # container only
curl -fsS https://sidedoc.example.org/schemas/versions.json | jq .latest
curl -sI  https://sidedoc.example.org/ | grep -i content-security-policy

Open the editor, create a document and open an existing export. Check the browser console for CSP violations.

Caching

index.html, config.js and other HTML are sent with Cache-Control: no-cache, and bundles have content-hashed names, so browsers load the new version on the next page load. If a CDN sits in front, make sure it honours these headers or purge it after the upgrade. Schemas and vocabularies are cached for one hour; published schema versions never change, so this only delays the appearance of a new version.