Limits and backups

Limits

• One host only. The server and the worker may run as two processes on the same host. Both default to RELIC_METRICS_LISTEN_ADDRESS=:8091, so give the second one its own, such as :8092; otherwise it exits.
• The data must be on a local disk. On Linux, Relic refuses to start on NFS, SMB/CIFS, FUSE, NCP, AFS, Coda, 9P, CephFS or Lustre. On macOS and Windows, it does not check.
• On Windows, the migration lock file does not work. Start the server first, and the worker once the server is up.
• SQLite allows one writer at a time. Reads continue; concurrent pushes queue.
• RELIC_DATABASE_STATEMENT_TIMEOUT and RELIC_DATABASE_MAX_CONNECTIONS apply to PostgreSQL only.
• Text sorts by byte.

relic_disk_free_bytes, relic_disk_size_bytes and relic_db_sqlite_file_bytes measure the volume and the database. RelicDiskSpaceLow fires below 10% free (Monitoring). When the database's disk is full, writes answer 507 with "the disk is full" (resource_exhausted on the Relic API), as they do when the object store's disk is full ("object storage is full"). Reads go on, and writes work again once there is space, without a restart.

Backups

Back up the database, the content and RELIC_ENCRYPTION_KEY. Without the key, Relic cannot read the sealed secrets in the database.

With relic server setup, the data is in ~/.local/share/relic and the key in ~/.config/relic/server.env. With --system, they are in /var/lib/relic and /etc/relic/relic.env, and the certificate authority in /etc/relic/tls.

Back up the database while Relic runs. The snapshot is consistent, and an existing file is never overwritten:

relic server database backup --database-url "sqlite://$HOME/.local/share/relic/relic.db" /backups/relic-$(date +%F).db

Then copy the content. Back up the database first: content added in between is only unreferenced in the copy.

rsync -a ~/.local/share/relic/objects/artifacts/ /backups/objects/

Copy the settings, which hold RELIC_ENCRYPTION_KEY. Keep them apart from the other backups (Secrets at rest):

cp ~/.config/relic/server.env /secure/relic-settings/

Copy the certificate authority, or clients must trust a new one (TLS):

cp -r ~/.config/relic/tls /secure/relic-settings/

To restore:

1. Stop Relic.
2. Put the snapshot in place of relic.db, and delete relic.db-wal and relic.db-shm if they exist.
3. Copy the content back under objects/artifacts/.
4. Start Relic.

Upgrade

The server applies the new release's migrations when it starts. Migrations only go forward and downgrades are not supported, so take a backup first. To go back, restore the backup and install the old release.

The install script replaces only the relic-indexer builds it downloads, so set RELIC_INDEXER_PLATFORMS to every platform you installed.

For the user service, install the new release over the binary the service runs:

curl -fsSL https://relic.build/install.sh | env RELIC_VERSION=v0.2.0-beta.4 sh

Run setup again. It keeps the settings and restarts the server on the new binary:

relic server setup

For the system service, install the new release in /usr/local/bin:

curl -fsSL https://relic.build/install.sh | sudo env RELIC_VERSION=v0.2.0-beta.4 RELIC_INSTALL_DIR=/usr/local/bin sh

Run setup again as root:

sudo relic server setup --system

When you run the server by hand, stop it, replace the binary and start it again.

Moving between PostgreSQL and SQLite

relic server database copy copies every table into an empty database, from SQLite to PostgreSQL or back:

relic server database copy --from sqlite:///var/lib/relic/data/relic.db \
  --to 'postgres://relic:<password>@db:5432/relic?sslmode=require'

1. Stop the server and the worker.
2. Run the copy. It migrates the target, refuses one that has data, copies in one transaction and compares the row counts.
3. Point RELIC_DATABASE_URL at the target and start Relic with the same RELIC_ENCRYPTION_KEY.

The content stays where it is. To move it to S3, copy objects/artifacts/ into the artifacts bucket first; the keys are the same. Background jobs are not copied.