Upgrades, rollbacks and backups

Upgrading to a new release

Upload, check and extract the new archive as for the first install, then run its installer. It needs no options: it remembers the main host, the aliases, the email address, --rpc and the ports.

scp collab-2.2.1.tar.gz collab-2.2.1.tar.gz.sha256 root@SERVER:/var/www/html/
ssh root@SERVER
cd /var/www/html
sha256sum -c collab-2.2.1.tar.gz.sha256
tar xzf collab-2.2.1.tar.gz
sudo ./collab-2.2.1/server/install.sh

Afterwards, delete the extracted folder and the archive, or keep them until the next upgrade.

What happens, step by step

1. The new release is copied to /var/www/collab/releases/2.2.1, next to the old ones.
2. The settings are kept: "Kept the settings in /etc/collab/collab.env".
3. config.js is written again with the new release's tools, from the same deployment record and site settings. When the bytes come out the same, it says "kept … (deployed)".
4. The content policy step writes the site's policy into the new release's pages.
5. nginx's file is written again, with the new release's cache rule, and nginx is reloaded. If nginx refuses it, the previous file comes back and the site stays on the old release.
6. The old release's prerendered pages are removed, then current switches: "current: 2.2.0 -> 2.2.1". Until the prerender job has written its pages again, the new release's own pages serve, so no page loads a mix of the two releases' scripts.
7. Releases older than the two before are deleted.
8. The certificate is kept, the units are written again, the admin service restarts, and a prerender run is requested at once.

The summary then says "This site is deployed: config.js names its contracts and was kept."

What is kept

In the release rehearsal's upgrade from 2.2.0 to 2.2.1, site.json, deployments/29.json and config.js came out byte for byte the same, and only the version changed in collab.env.

A release of another minor version

A release accepts deployments of its own major and minor version: COLLAB 2.2.x needs COLLAB DAO v2.2.x contracts. When a release of another minor version (2.3, say) finds the published 2.2 deployment, the installer warns:

warning: the published deployment does not fit this release: … Publish a deployment of this release from /admin.

It keeps the published record. Deploy the new release's contracts from the Deploy tab and publish them. A new version of COLLAB means a new DAO factory; DAOs created by the old one keep working on chain.

Going back to an earlier release

Run the older release's own copy of the installer, which stays in releases/:

sudo /var/www/collab/releases/2.2.0/server/install.sh

It ends with "This ran from an installed release (/var/www/collab/releases/2.2.0): keep that folder, it is part of the site." It does what an upgrade does, in the other direction: nginx gets that release's cache rule back, the newer release's prerendered pages are removed, current switches, and the prerender job writes the pages again.

You can go back to the two releases before the current one; older ones are deleted. A release that is gone can be installed again from its archive.

The same version with new files

Running an installer whose release version is already installed:

• with the same SHA256SUMS, changes nothing in releases/: "Release 2.2.0 is in place already: /var/www/collab/releases/2.2.0";
• with other files, for example the same release rebuilt with new documentation, replaces the installed copy without a gap: the site serves the new copy while the old one is replaced ("Copied the release to /var/www/collab/releases/2.2.0"), and current keeps naming it.

Extract such an archive into an empty folder: delete the old collab-2.2.0/ first. tar over it keeps the files the new archive no longer has, and the installer copies web/, tools/, server/, deploy/ and docs/ into releases/ as they are, without checking them against SHA256SUMS.

Every file of the release's web/ folder counts in its assets version, the ?v= its pages name, which web/BUILD.json records. When that version changed, the installer does what an upgrade does: nginx's long cache names the new ?v=, the old prerendered pages are removed, and the prerender run requested at the end writes them again. The settings, the deployment, the preview images and the /data/ cache are kept.

Backups

What to back up

What cannot be made again is small:

sudo tar czf /root/collab-backup-$(date +%F).tar.gz /etc/collab \
  /var/www/collab/shared/site.json /var/www/collab/shared/config.js \
  /var/www/collab/shared/deployments /var/www/collab/shared/history

• The archive holds the admin token and the secrets: keep it as private as the server. Never write it under /var/www/html, where the release archives go: nginx's default site serves every file there to anyone who asks for its name.
• shared/prerender/, shared/data/ and shared/jobs/ are written again by the next prerender run; its caches read the chain's history again.
• The certificate is issued again by the installer when it is missing.
• The releases come from their archives.

The deployment record is also public: it is the deployments/29.json you downloaded from the Deploy tab or that Foundry wrote. Keep a copy of it with the release you deployed.

Restoring

On the same server, after a mistake or a damaged file:

sudo systemctl stop collab-admin
sudo tar xzf /root/collab-backup-2026-11-02.tar.gz -C /
sudo /var/www/collab/current/server/install.sh

tar, run as root, puts the files back with their owners and modes, and the installer writes config.js again from them and starts the services. To go back to one earlier deployment record or site.json only, take it from shared/history/ and publish it from the admin page instead; see Publish, unpublish and check.

Moving to another server

1. Install the same release on the new server, as for a first install. With the names still pointing at the old server, it runs without a certificate for now.
2. Stop its admin service: sudo systemctl stop collab-admin.
3. Copy the backup to the new server's /root and restore it there: sudo tar xzf /root/collab-backup-….tar.gz -C /.
4. Run the installer again: sudo /var/www/collab/current/server/install.sh. It takes the restored settings: the same main host, aliases and admin token.
5. Point the names' DNS at the new server. Once they resolve to it, run the installer once more for the certificate.
6. Check the site with deploy/check_site.py (Status, logs and the collab command).

Until step 5's certificate is issued, the new server has no HTTPS site for the names. Visitors whose DNS already leads there see the "being set up" notice over HTTP, and browsers that have seen the site's HSTS header, which use HTTPS only, cannot open it. Run step 5 as soon as the names resolve to the new server.

Related

• Installing COLLAB on a server
• Status, logs and the collab command
• Operator security checklist
• Release notes