<!-- MIT License. Copyright (c) 2026 Decentralized Science Labs LLC. -->
<!-- summary: Upgrading a COLLAB server with the new release's installer, what it keeps, going back with an older release's installer, backups, restoring and moving servers. -->
# Upgrades, rollbacks and backups

A COLLAB server is upgraded by running the newer release's installer, and taken back by running an
older release's own installer. This page is for the operator: what an upgrade does and keeps, how
to go back, what to back up and how to restore it, and how to move the site to another server.

## 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.

```bash
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

| Kept | Where |
|---|---|
| The admin token, the two secrets and the installer's options | `/etc/collab/collab.env` |
| The site settings | `shared/site.json` |
| The published deployment | `shared/deployments/29.json` |
| The history of replaced files | `shared/history/` |
| The certificate | `/etc/letsencrypt/live/collab/` |
| Sign-in sessions | they stay valid: the token and secrets do not change |
| The prerender job's images and `/data/` cache | `shared/prerender/og/`, `shared/data/` |
| The two previous releases | `releases/` |

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:

```text
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/`:

```bash
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.

> **Warning.** Never switch `current` by hand (`ln -sfn`). nginx keeps a release's scripts and
> styles in browsers' caches for a year under that release's `?v=` addresses, and only the
> installer changes which ones. After a bare switch it would go on keeping the newer release's
> `?v=` addresses for a year while they serve the older files, and the newer release's prerendered
> pages would stay.

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:

```bash
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:

```bash
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](publish.md#the-history-folder).

## 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](monitoring.md#checking-the-live-site)).

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](INSTALL.md)
- [Status, logs and the collab command](monitoring.md)
- [Operator security checklist](server-security.md)
- [Release notes](RELEASE_NOTES.md)