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.
actors/<Actor>/<SHA-256 of the key>/<run id>/actor.sqlite
actors/<Actor>/<SHA-256 of the key>/<run id>/files.tar.zstThe bucket prefix also holds these files:
signing-key.pem
latest.json
runs/<run id>/manifest.json
runs/<run id>/manifest.sigAn export folder holds manifest.json, manifest.sig, and signing-key.pem at its root instead.
| File | Contents |
|---|---|
actor.sqlite | The 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.zst | The actor’s Akter.fs files as a POSIX ustar archive compressed with zstd. |
manifest.json | The format akter-backup/1, createdAtMillis, source, recipients, and every actor with its artifacts. |
manifest.sig | A 64-byte Ed25519 signature over the exact bytes of manifest.json. |
signing-key.pem | The public key that checks manifest.sig. |
latest.json | The 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
| Field | Contents |
|---|---|
source | {"kind":"local"} for an akterd data folder. {"kind":"wal","shards":[{"shard":N,"lsn":N}]} marks a cut replayed from Akter Cloud WAL segments. |
recipients | The sorted age recipients of the run, or [] when the artifacts are plaintext. |
actors[].actor, actors[].key | The actor name and its key. |
actors[].keyDigest | The SHA-256 of the key, the folder name under actors/<Actor>/. |
actors[].watermark | The actor’s commit position in this copy. |
actors[].database, actors[].files | Each artifact’s path, sha256, bytes, plaintextSha256, and encrypted. |
actors[].fileDigests | Every 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.
| Cadence | When the next push starts | Most recent data a restore can lose |
|---|---|---|
continuous | 1 second after the previous push started | About one push |
15m | 15 minutes after the previous push started | 15 minutes and one push |
hourly | One hour after the previous push started | One hour and one push |
daily | One day after the previous push started | One 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 thatlatest.jsonnames 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_IDAKTER_BACKUP_SECRET_ACCESS_KEYAKTER_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
- Create a bucket in Amazon S3, Cloudflare R2, or an S3-compatible store such as MinIO.
- Create an access key that can read, write, and list that bucket.
- In the project root, run
akter backup configure.
akter backup configure --bucket s3://acme-akter-backups/prod --region us-west-2 --cadence 15m- For an R2 bucket, pass
r2://<account id>/<bucket>and leave out--region. - For MinIO, add
--endpointwith the server URL. - Commit
akter.backup.json. - Set
AKTER_BACKUP_ACCESS_KEY_IDandAKTER_BACKUP_SECRET_ACCESS_KEYin the shell that runs backups. - Start the backup loop.
akter backup run- To push one backup and exit, add
--once. - 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.
- Move the old private key out of the key folder.
- Run
akter backup configurewith a new bucket prefix. It creates a new signing key. - Keep the old prefix and the old
signingPublicKeywhile you still need the old runs.
Encrypt backups with age
- Create an age identity and keep it outside the bucket.
age-keygen -o backup-identity.txt- Copy the
age1public key thatage-keygenprints. - Run
akter backup configureagain with one--recipientfor each public key.
akter backup configure --bucket s3://acme-akter-backups/prod --region us-west-2 --cadence 15m --recipient age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8pExport actors to a folder
- To export every actor from the local data folder, run
akter exportwith--out.
akter export --out ./export- To export some actors, name each one as
<Actor>/<key>.
akter export Order/ord_1 Cart/cart_9 --out ./export- To copy the latest backup from the bucket instead, add
--remote.
akter export --remote --out ./export- To decrypt and check encrypted artifacts, add
--identitywith your age identity file.
akter export --remote --identity backup-identity.txt --out ./export- When
sqlite3is not onPATH, 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_checkon 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.
- To check a backup in the bucket instead, download
latest.jsonandsigning-key.pemfrom the prefix. Then download themanifestandsignaturefiles thatlatest.jsonnames, and every artifact the manifest lists.
aws s3 cp s3://acme-akter-backups/prod/latest.json .- Compare
signing-key.pemwithsigningPublicKeyin yourakter.backup.json. Trust the export only when they match. - Check the manifest signature.
opensslprintsSignature Verified Successfully.
openssl pkeyutl -verify -pubin -inkey signing-key.pem -rawin -in manifest.json -sigfile manifest.sig- Compute the SHA-256 of each artifact.
sha256sum actors/*/*/*/*- Compare each digest with the
sha256value of that artifact inmanifest.json. - To decrypt an
.ageartifact, pass your identity file toage.
age -d -i backup-identity.txt -o actor.sqlite actor.sqlite.age- Compare the SHA-256 of the decrypted file with
plaintextSha256. - Check each database.
sqlite3printsok.
sqlite3 actor.sqlite 'PRAGMA integrity_check'- Unpack each file archive.
mkdir files && tar --zstd -xf files.tar.zst -C files- When your
tarhas no--zstdoption, pipe the archive throughzstd.
mkdir files && zstd -dc files.tar.zst | tar -xf - -C files- Compare the SHA-256 of each unpacked file with its entry in
fileDigests. - To find the folder of one actor key, hash the key.
printf '%s' 'ord_1' | sha256sum