Docs / Hosting OwnBase

Backups, restore, updates

Use the built-in commands rather than copying files by hand:

ownbase-server backup  --data ./data --out ./backups/2026-09-06
ownbase-server verify-backup --from ./backups/2026-09-06
ownbase-server restore --from ./backups/2026-09-06 --data ./data

backup writes a consistent database snapshot (including anything still in the write-ahead log), every attachment referenced by that snapshot, and a manifest.json recording the schema version, checksums, and row counts from the copied database. --out must be a new or empty directory outside the workspace data directory. Stop the server first for a backup that is certain to be complete. If an attachment disappears during capture, backup fails instead of reporting success. The copy is captured and verified in an owned staging folder beside the destination, then published into --out. Failed staging is removed; a later capture reconciles interrupted operation records without deleting unrecognized folders or active captures.

verify-backup checks checksums, safe attachment paths, the actual database schema, row counts, foreign keys and attachment inventory without changing a workspace. An omitted attachment is rejected even if all listed checksums match. It then lists what starting the backup would reach outside itself: the addresses its apps are sent events, commands and button clicks at, messages waiting to be posted, app events not yet delivered, and how many sign-ins it would accept. Sign-ins ended after the backup was taken are valid again in a restore, so after restoring a real workspace, ask people to look at their signed-in devices and end any they had already ended. Settings given on the command line or in the environment are not in a backup: --public-url, --retention-days, --storage-limit-mb, --allow-private-hooks, --trust-proxy, OWNBASE_ICE_SERVERS, and any proxy or certificate in front of the server. Note them where you keep the backup.

restore verifies the backup, stages and re-verifies it beside the target, and only then swaps it in; the previous data directory is renamed to data.superseded-<timestamp> rather than deleted. Stop the server before restoring: a restore, like recover, is refused while a server has the data directory open, and a server started while a restore is running is refused until it has finished. A backup from a newer server than the one restoring it is refused instead of half-applied.

Only one server can have a data directory open at a time. A second one started on the same directory, through any path or link to it, is refused before it opens anything and says which process has it. The lock is the operating system's, held on workspace.lock inside the directory, so it goes when that process exits or crashes, and there is nothing to clear by hand afterwards. workspace.owner.json beside it only describes the holder. Keep the data directory on a local disk: file locking on a network share is not dependable, for this lock or for SQLite itself.

A restore has to let go of that lock to move the old directory aside and the restored one in. So that nothing starts in between, a second lock is held beside the directory, on data.lock for a directory named data: by a restore from start to finish, and for a moment by anything else that takes the directory. The file is removed when the lock is let go. If one is left behind after a crash, it is empty and the next start removes it.

To check that a backup really holds what you need, restore it into a new directory and start that copy with --isolated:

ownbase-server restore --from ./backups/2026-09-06 --data ./restore-check
ownbase-server --data ./restore-check --isolated --port 8600

The copy holds the original's apps, their signing secrets and its queue of scheduled messages. Started normally, it would post messages that were due a second time and call the same apps as the same workspace. An isolated start posts no scheduled message, delivers no app event, answers slash commands and buttons with "this is an isolated copy of the workspace, which does not contact apps", and does not announce itself on the local network. It listens on this machine only unless --host says otherwise. Sign in, read, search and open attachments as usual. What it holds back stays queued, so delete the copy when you are done rather than starting it normally, or the queue goes out from there.

Backups on a schedule#

The server can take backups by itself:

ownbase-server --data ./data --backup-dir ./backups --backup-every-hours 24 --backup-keep 7

Each one goes into a dated folder in --backup-dir, such as backup-2026-10-25T03-00-00Z, and is the same as one backup writes: verified before it is kept, checked with verify-backup, put back with restore --from. Once a new one is verified, the oldest past --backup-keep are removed. Only folders named that way are counted or removed, so anything else in the directory is left alone. --backup-dir must be outside --data. The defaults are every 24 hours and keeping 7. The same settings can be given as OWNBASE_BACKUP_DIR, OWNBASE_BACKUP_EVERY_HOURS and OWNBASE_BACKUP_KEEP.

The next backup is due that long after the newest one already in the directory, so restarting the server does not take another, and a server that was stopped past the time takes one a minute after it starts. A backup that fails is tried again within the hour, and the status says how many have failed since the last one that worked. While a backup copies attachments the server removes none, so a file deleted during the copy is still there for it and the backup is complete without stopping the server. The removals wait in their queue and go when the copy ends.

The copy and its checks run in a separate process, so chat does not wait on them. Stopping the server stops a backup that is running; the half-made copy is removed by the next one. An --isolated copy takes no backups, since it would otherwise write into the original's directory and remove the original's older backups.

Backups somewhere else#

Backups on the same disk as the workspace go with it if that disk or machine is lost. --backup-offsite also sends each scheduled backup, as one .zip, to an S3-compatible bucket: Cloudflare R2, Amazon S3, Backblaze B2, MinIO and the like.

export OWNBASE_BACKUP_OFFSITE_ACCESS_KEY_ID=...
export OWNBASE_BACKUP_OFFSITE_SECRET_ACCESS_KEY=...
ownbase-server --data ./data --backup-dir ./backups \
  --backup-offsite https://<account-id>.r2.cloudflarestorage.com/ownbase-backups/acme

The address is the bucket's S3 endpoint, then the bucket, then an optional folder in it (acme above). The keys are read only from the environment, so they never show in a process list, and the region from OWNBASE_BACKUP_OFFSITE_REGION (auto unless set, which is what R2 wants). The address can also be given as OWNBASE_BACKUP_OFFSITE_URL. Each copy is named after its backup, such as acme/backup-2026-11-04T03-00-00Z.zip. Once one is sent, the oldest past --backup-offsite-keep (default: the same as --backup-keep) are removed from the bucket. As in --backup-dir, nothing named any other way is touched.

A backup up to 32 MB goes in one request; a larger one goes in 32 MB parts, which never holds more than one part in memory. Every request is signed and its body's SHA-256 is checked by the bucket. A send that fails leaves the backup on disk as it is; the server log says why, the status counts the failures, and the same backup is sent again within the hour. A newer backup takes its place.

To restore, download the zip and give it to restore --from, as with a copy the owner downloaded. For R2:

cf r2 buckets objects get acme/backup-2026-11-04T03-00-00Z.zip --bucket-name ownbase-backups > backup.zip
ownbase-server restore --from backup.zip --data ./data

Cloudflare R2. Create a bucket (Standard storage, not Infrequent Access, which charges for every read), and an R2 API token with Object Read & Write on that bucket only. The token's Access Key ID and Secret Access Key are the two keys above, and the endpoint is shown on the bucket's settings page. R2's free tier is 10 GB-month of storage, a million writes and ten million reads a month, and downloads cost nothing. A daily backup uses about five requests, plus one per 32 MB above that, so with seven kept the storage is the only part that grows: seven times the size of a backup. A lifecycle rule that aborts unfinished multipart uploads after a day keeps a send cut short from being stored. R2 has no spending cap, so set a usage alert under Notifications → Usage Based Billing as well.

Encrypted backups#

A backup holds every message and file, and the secrets the workspace keeps as plain values: two-step sign-in secrets, app signing secrets and push keys. Give the server a backup passphrase and every backup taken from then on is one encrypted file that nobody can read without it, wherever it ends up:

export OWNBASE_BACKUP_PASSPHRASE='several unrelated words you will not forget'
ownbase-server --data ./data --backup-dir ./backups --backup-offsite https://...

Or put the passphrase alone in a file that only the server's account can read and pass --backup-passphrase-file /etc/ownbase/backup-passphrase (or OWNBASE_BACKUP_PASSPHRASE_FILE). A last line break in the file is ignored; everything else, spaces included, is the passphrase. It is never taken as a command-line value, which anyone on the machine can see in a process list. It must be at least 12 characters. The server refuses to start, and the commands refuse to run, when the passphrase is empty, too short, given both ways, or the file cannot be read. The server never logs it.

If you lose the passphrase, you lose those backups. Nobody can open them without it, OwnBase included, and there is no way round that. Keep it somewhere apart from the server, such as a password manager, and somewhere a second person can reach it.

With a passphrase set:

  • Scheduled backups are files named like the folders were, ending in .encrypted, such as backup-2026-11-14T03-00-00Z.encrypted. Each is captured and verified as usual, encrypted, then read back in full and checked before it is kept. --backup-keep counts plain folders and encrypted files together, so the plain backups from before a passphrase was set are pruned in their turn.
  • The copy sent with --backup-offsite is that same file, as acme/backup-2026-11-14T03-00-00Z.encrypted. The bucket never holds anything readable. --backup-offsite-keep counts .zip and .encrypted copies together.
  • backup --out ./backups/2026-11-14 writes ./backups/2026-11-14.encrypted, a file rather than a folder. The name must not exist yet.
  • restore and verify-backup read encrypted and plain backups both. An encrypted one needs the same passphrase, set the same way. They say so when none is given, say when the passphrase is wrong, and say when the file is damaged or cut short, all before anything is restored. The file is decrypted into a folder beside itself while they work, every part checked first, and that folder is removed afterwards, so that disk needs room for the workspace twice.

To check a backup by hand, and to restore one taken offsite:

export OWNBASE_BACKUP_PASSPHRASE='...'
cf r2 buckets objects get acme/backup-2026-11-14T03-00-00Z.encrypted --bucket-name ownbase-backups > backup.encrypted
ownbase-server verify-backup --from backup.encrypted
ownbase-server restore --from backup.encrypted --data ./restore-check
ownbase-server --data ./restore-check --isolated --port 8600

Changing the passphrase applies to backups taken afterwards; older ones still need the passphrase they were taken with, so keep it until they have been pruned. Unsetting it goes back to plain backups.

Not covered: the copy the owner downloads from Workspace settings stays a plain zip, since the owner may not hold the host's passphrase and can read everything in it already; the desktop app's backups; and the copy of the database the server takes before an upgrade, which stays inside the data directory beside the live database it copies. The live database itself is not encrypted: a key kept beside it would protect nothing.

The file starts with the words OwnBase encrypted backup, then the scrypt salt and cost the key was derived with, then the backup's zip encrypted with AES-256-GCM in 64 KiB parts (the STREAM construction, as age uses). Each part is bound to its position and to whether it is the last, so a part changed, moved, dropped or cut off fails the check.

A copy for the owner to download#

The workspace's owner can download the whole workspace from Workspace settings → General → Download a copy, without access to the server. Make a copy takes a fresh backup, the same as backup makes, and Download saves it as one .zip named after the workspace and the day. Admins and members are not offered it. The copy stays on the server for an hour after it is ready, longer if a download is still running, and is removed after that, when a new one is made, and when the server stops.

The zip holds the backup's own files, dated when it was taken, so it goes back the same way:

ownbase-server verify-backup --from "./My Workspace 2026-10-25.zip"
ownbase-server restore --from "./My Workspace 2026-10-25.zip" --data ./data

Both unpack the zip into a folder beside it while they work and remove that folder afterwards, so that disk needs room for the workspace once more. A copy over 4 GB, or with more than 65,535 files, uses ZIP64, which Windows Explorer, macOS and unzip all read.

The copy is made where scheduled backups go, in a .copies folder, or in the system's temporary folder when there are none; copiesDir changes it for an embedded server. That disk needs room for the whole workspace; the server checks before it starts and says how much it needs. No attachment is removed while the copy is made. The download link is good once, for a minute, and only for the owner signed in on the device that asked for it. Making and downloading a copy both go in the administrative record.

The copy holds every message, file and account, the secrets apps use, and the sign-ins in use when it was made. Keep it as safe as the server. It is not encrypted, even when a backup passphrase is set.

Store backups away from the host, encrypted (see "Encrypted backups"). For Docker, run the same commands inside the container against the mounted volume, or set OWNBASE_BACKUP_DIR to a second volume.

Before upgrading, take a backup. Rebuild and restart with Compose; SQLite migrations run automatically. To roll back a schema change, restore the matching backup and previous application version together — the server refuses to open a database newer than it understands, so an application rollback alone will not start.

The server also copies the database itself before any upgrade that changes the schema, so there is something to roll back to even when nobody remembered. The copy goes in pre-upgrade/ inside the data directory, is named for the schema versions it sits between, and the startup output says where it went. The three most recent are kept, counting the one just taken, which is never removed. "Most recent" means from the latest schema first, and only then by the time in the name, so a clock set wrong cannot push out the copy an upgrade has just made. Only copies that open at the schema their name records, as this workspace, count towards the three; a copy that does not is left where it is for you to look at. If the copy cannot be written — most often a full disk — the server refuses to upgrade and changes nothing. The copy is the database only: attachments are not duplicated, since no migration touches them. To roll back with it, stop the server, put the copy in place of workspace.db, and start the previous release. Everything written since the upgrade is lost with it — messages, accounts, settings. Attachments uploaded since then stay on disk with nothing pointing at them; a release that reconciles orphaned attachments frees them on start, and an older one leaves them for you to remove. --skip-upgrade-backup turns the copy off, for someone who has just taken a backup and has no room for a second one. Deleting a container preserves the named volume; docker compose down -v deletes it, so avoid that command for real data.

There are no separate Redis, Postgres, or message broker services to maintain. Monitor disk usage for uploads and history, resource use, health, and backups.

Schema v13 keeps a persistent queue for deleted attachments. Message and file metadata are removed atomically; physical file removal follows the commit. Temporary filesystem failures remain queued for retry every 15 seconds and on restart. Cleanup handles at most 100 queued files per pass; shutdown awaits the active pass before closing the database. A locked file can remain on disk until cleanup succeeds, but the download API no longer serves it after deletion commits.

Schema v58 rebuilds the search index from every message, so that a word inside Chinese, Japanese, Korean or Thai text can be found. It runs once, on the first start after the upgrade, before anyone can sign in: about 0.4 seconds for 100,000 messages and 5 seconds for a million on a desktop PC. From v58 the index is kept up to date by a function the server adds to its own database connection, so the sqlite3 shell can read messages but cannot change their words or add new ones.

Updating the desktop app#

The Windows app from a release updates itself from dl.ownbase.site, the Release workflow's copy of each release on Cloudflare R2, not from GitHub. It reads https://dl.ownbase.site/latest.json, which the workflow writes only after every file of a release is there, and takes the release it names when that is newer. It looks when it starts and every four hours after, downloads in the background, and installs when you restart or quit, never during a call. It checks the download against the SHA-512 in that release's latest.yml. When dl.ownbase.site cannot be reached there is no update that time; the app tries again a few hours later. Builds released before 15 November 2026 still look on GitHub, so they take one last update from there (or install from ownbase.site), and update from R2 after that. The Mac app, signed ad hoc, only says a new release is out, from the same latest.json, and links to the download. With Update automatically off, under Account settings → Updates, the app looks only when you ask it to. Builds made anywhere but the Release workflow never look. updates.log in the app's data folder (%APPDATA%\OwnBase on Windows) says which version updated to which, and why one could not.

This page is made from docs/DEPLOYMENT.md.