Skip to content
Documentation
Run a server
Upgrades

Upgrades

This page shows how to put a new version of lasboltd on a server and how to go back if it fails.

How a migration works

  • The database has a schema version in the meta table (key schema_version).
  • The program has numbered SQL migrations inside it. At start, lasboltd runs each migration that the database has not seen yet. Each one runs in its own transaction.
  • If a migration fails, the start stops with store: migration <n>: .... That migration is rolled back.
  • A program refuses a database with a newer schema than its own: store: database schema <n> is newer than this server (<m>). Old programs cannot open a database that a new program migrated.
  • There is no down migration. To go back, you restore a backup.

This means: take a backup before each upgrade, and keep the old binary.

Upgrade

Read the changes

Read the commit log or the release notes between your version and the new one. Look for changes in flags and in the data.

Build the new version 

git pull
make build
bin/lasboltd version

Make a backup 

sudo -u lasbolt sh -c 'set -a; . /etc/lasbolt/lasboltd.env; set +a; exec lasboltd backup now'
sudo -u lasbolt sh -c 'set -a; . /etc/lasbolt/lasboltd.env; set +a; exec lasboltd backup list'

Check that the new file is the newest in the list. Copy it off the server if you can.

Keep the old binary and install the new one 

sudo cp /usr/local/bin/lasboltd /usr/local/bin/lasboltd.previous
sudo cp /usr/local/bin/lasboltctl /usr/local/bin/lasboltctl.previous
sudo install -m 0755 bin/lasboltd bin/lasboltctl /usr/local/bin/

Restart 

sudo systemctl restart lasboltd
sudo systemctl status lasboltd
sudo -u lasbolt lasboltctl status

The migrations run at this point. The status must show the new version and state: unsealed. Look at the log for errors:

journalctl -u lasboltd -n 50 --no-pager

Check the app

Log in on the web app and in one client. Check that sync works.

The server stops with SIGTERM and closes the event streams, then waits up to 10 seconds for requests to end. Clients reconnect by themselves. A restart makes a short gap and no data loss.

Roll back

If the new version fails after the migrations ran, the database may be on a newer schema than the old binary can open.

Stop the service 

sudo systemctl stop lasboltd

Put the old binary back 

sudo install -m 0755 /usr/local/bin/lasboltd.previous /usr/local/bin/lasboltd
sudo install -m 0755 /usr/local/bin/lasboltctl.previous /usr/local/bin/lasboltctl

Restore the backup that you made before the upgrade

See Backups and restore. Use the backup from the step “Make a backup”.

sudo -u lasbolt sh -c 'set -a; . /etc/lasbolt/lasboltd.env; set +a; exec lasboltd restore /var/lib/lasbolt/backups/<file>'

Start the service 

sudo systemctl start lasboltd

A restore loses the changes made after the backup, until the clients push them again (most come back). Purges made after the backup are lost. If the upgrade failed at once, almost nothing is lost.

If the old binary starts and does not complain about the schema, the migration did not run, and you do not need to restore.

Last updated on
Backups and restoreSealing and keys