Skip to content

Backups and exports

akter backup copies every actor of an Akter data folder to a bucket that you own. The folder is .akter/dev by default, the same folder as akter dev. Pushes run on a cadence that you choose. akter export writes the same files to a folder on demand. Stock sqlite3, tar, zstd, sha256sum, openssl, and age read every file without Akter software.

Every backup is stock SQLite files and tar.zst archives⁠

Each actor has one folder for each run that copied it. The same layout holds in the bucket and in an export folder.

Text
actors/<Actor>/<SHA-256 of the key>/<run id>/actor.sqlite
actors/<Actor>/<SHA-256 of the key>/<run id>/files.tar.zst

The bucket prefix also holds these files:

Text
signing-key.pem
latest.json
runs/<run id>/manifest.json
runs/<run id>/manifest.sig

An export folder holds manifest.json, manifest.sig, and signing-key.pem at its root instead.

FileContents
actor.sqliteThe actor’s full database at one commit, akter_* system tables included. It uses rollback-journal mode, so it opens with no -wal file.
files.tar.zstThe actor’s Akter.fs files as a POSIX ustar archive compressed with zstd.
manifest.jsonThe format akter-backup/1, createdAtMillis, source, recipients, and every actor with its artifacts.
manifest.sigA 64-byte Ed25519 signature over the exact bytes of manifest.json.
signing-key.pemThe public key that checks manifest.sig.
latest.jsonThe newest run as run, createdAtMillis, manifest, and signature. A push writes it last. Akter trusts it only when every field matches the signed manifest.

The run id is createdAtMillis padded to 20 digits. The archive stores modes 0644 and 0755, owner and group 0, and modification times in whole seconds. Paths longer than ustar allows use a pax header. Partial uploads in .akter-upload.* files stay out of the archive.

Manifest fields⁠

FieldContents
source{"kind":"local"} for an akterd data folder. {"kind":"wal","shards":[{"shard":N,"lsn":N}]} marks a cut replayed from Akter Cloud WAL segments.
recipientsThe sorted age recipients of the run, or [] when the artifacts are plaintext.
actors[].actor, actors[].keyThe actor name and its key.
actors[].keyDigestThe SHA-256 of the key, the folder name under actors/<Actor>/.
actors[].watermarkThe actor’s commit position in this copy.
actors[].database, actors[].filesEach artifact’s path, sha256, bytes, plaintextSha256, and encrypted.
actors[].fileDigestsEvery file inside files.tar.zst with its path, sha256, and bytes.

When the config names age recipients, every artifact ends in .age. Then sha256 covers the encrypted bytes and plaintextSha256 covers the decrypted bytes.

The cadence sets how much data a restore can lose⁠

Each cadence measures from the start of the previous push. When a push takes longer than the cadence, the next push starts as soon as it finishes.

CadenceWhen the next push startsMost recent data a restore can lose
continuous1 second after the previous push startedAbout one push
15m15 minutes after the previous push started15 minutes and one push
hourlyOne hour after the previous push startedOne hour and one push
dailyOne day after the previous push startedOne day and one push

When a push fails, akter backup run prints the failure and tries again at the next cadence.

A push copies only the actors that changed⁠

A push cuts every actor and compares each cut with the latest signed manifest. It keeps the previous artifacts of an actor only when all of these match:

  • The watermark, which is the actor’s commit position.
  • The SHA-256 of the database.
  • The SHA-256 of the files archive.
  • The age recipients of the run.

Every other actor gets new artifacts under the new run id. A state change, a table write, and an Akter.fs file write all reach the next push. A change of recipients copies every actor again, so the latest manifest names no artifact for the old recipients.

Every run writes a new signed manifest that lists every actor, so the latest manifest alone describes the whole environment. A removed actor is absent from the next manifest. When nothing changed, the push writes nothing.

Keep every artifact in the bucket⁠

A kept actor points at artifacts from an earlier run. A push that finds no change writes nothing, so the latest run can be months old. Akter never deletes an object from the bucket. Follow these rules for bucket lifecycle settings:

  • Never expire objects under actors/. The latest manifest can name an artifact from any earlier run.
  • Never expire objects under runs/. The run that latest.json names can be of any age, and each manifest is small.
  • Turn on bucket versioning when your provider supports it. A deleted object can then come back.

Each push uploads a full copy of every changed actor. With continuous, a busy app adds the size of its changed actors about every second. Pick a longer cadence when bucket growth matters.

Bucket credentials stay outside actor state⁠

akter-backup reads bucket credentials from three environment variables at push, status, and pull time:

  • AKTER_BACKUP_ACCESS_KEY_ID
  • AKTER_BACKUP_SECRET_ACCESS_KEY
  • AKTER_BACKUP_SESSION_TOKEN, which is optional

Akter never writes these values to akter.backup.json, to a file, to actor state, or to a log. Keep them in your secret vault or your CI secret store.

akter.backup.json holds no secrets, so you can commit it. It names the bucket, the cadence, the region, the optional endpoint, the age recipients, and the signing key.

Turn on backups⁠

  1. Create a bucket in Amazon S3, Cloudflare R2, or an S3-compatible store such as MinIO.
  2. Create an access key that can read, write, and list that bucket.
  3. In the project root, run akter backup configure.
Terminal
akter backup configure --bucket s3://acme-akter-backups/prod --region us-west-2 --cadence 15m
  1. For an R2 bucket, pass r2://<account id>/<bucket> and leave out --region.
  2. For MinIO, add --endpoint with the server URL.
  3. Commit akter.backup.json.
  4. Set AKTER_BACKUP_ACCESS_KEY_ID and AKTER_BACKUP_SECRET_ACCESS_KEY in the shell that runs backups.
  5. Start the backup loop.
Terminal
akter backup run
  1. To push one backup and exit, add --once.
  2. To check the last run and the next run, run akter backup status.

akter backup configure creates the signing key at $XDG_CONFIG_HOME/akter/backup-signing-key.pem when it does not exist. When XDG_CONFIG_HOME is not set, the key goes to ~/.config/akter. A second run keeps the existing key.

When the key is under your home folder, akter.backup.json names it with a ~/ path. Copy the private key to the same place on every machine that runs akter backup run. That includes teammates' machines and CI.

Rotate the signing key⁠

A push checks the latest run against the configured public key. After you replace the key, a push treats the old runs as tampered and stops. Start a new prefix for the new key instead.

  1. Move the old private key out of the key folder.
  2. Run akter backup configure with a new bucket prefix. It creates a new signing key.
  3. Keep the old prefix and the old signingPublicKey while you still need the old runs.

Encrypt backups with age⁠

  1. Create an age identity and keep it outside the bucket.
Terminal
age-keygen -o backup-identity.txt
  1. Copy the age1 public key that age-keygen prints.
  2. Run akter backup configure again with one --recipient for each public key.
Terminal
akter backup configure --bucket s3://acme-akter-backups/prod --region us-west-2 --cadence 15m --recipient age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p

Export actors to a folder⁠

  1. To export every actor from the local data folder, run akter export with --out.
Terminal
akter export --out ./export
  1. To export some actors, name each one as <Actor>/<key>.
Terminal
akter export Order/ord_1 Cart/cart_9 --out ./export
  1. To copy the latest backup from the bucket instead, add --remote.
Terminal
akter export --remote --out ./export
  1. To decrypt and check encrypted artifacts, add --identity with your age identity file.
Terminal
akter export --remote --identity backup-identity.txt --out ./export
  1. When sqlite3 is not on PATH, pass its location with --sqlite3.

Every export checks what it wrote⁠

akter export reads .akter/dev by default, the same folder as akter dev. A local and a remote export run the same checks before they exit:

  • The Ed25519 signature over manifest.json.
  • The stored SHA-256 of every artifact.
  • sqlite3 PRAGMA integrity_check on every database.
  • The SHA-256 of every archived file against fileDigests.

An encrypted artifact gets the last two checks only with --identity. Without it, the actor reports still encrypted. When sqlite3 cannot run, the export fails with the sqlite3 binary <path> did not run.

Verify an export with stock tools⁠

Run these steps in the export folder. They need no Akter software.

  1. To check a backup in the bucket instead, download latest.json and signing-key.pem from the prefix. Then download the manifest and signature files that latest.json names, and every artifact the manifest lists.
Terminal
aws s3 cp s3://acme-akter-backups/prod/latest.json .
  1. Compare signing-key.pem with signingPublicKey in your akter.backup.json. Trust the export only when they match.
  2. Check the manifest signature. openssl prints Signature Verified Successfully.
Terminal
openssl pkeyutl -verify -pubin -inkey signing-key.pem -rawin -in manifest.json -sigfile manifest.sig
  1. Compute the SHA-256 of each artifact.
Terminal
sha256sum actors/*/*/*/*
  1. Compare each digest with the sha256 value of that artifact in manifest.json.
  2. To decrypt an .age artifact, pass your identity file to age.
Terminal
age -d -i backup-identity.txt -o actor.sqlite actor.sqlite.age
  1. Compare the SHA-256 of the decrypted file with plaintextSha256.
  2. Check each database. sqlite3 prints ok.
Terminal
sqlite3 actor.sqlite 'PRAGMA integrity_check'
  1. Unpack each file archive.
Terminal
mkdir files && tar --zstd -xf files.tar.zst -C files
  1. When your tar has no --zstd option, pipe the archive through zstd.
Terminal
mkdir files && zstd -dc files.tar.zst | tar -xf - -C files
  1. Compare the SHA-256 of each unpacked file with its entry in fileDigests.
  2. To find the folder of one actor key, hash the key.
Terminal
printf '%s' 'ord_1' | sha256sum