---
title: Back up a self-hosted Venom Cloud
description: Scheduled backups of the database and the server's files to its own disk or your S3-compatible bucket, a verify restore into a scratch database, and a full export to download, all from Settings, Server backups.
section: deploy
order: 48
audience: [operator]
sources: [services/nodejs-cloud/lib/selfhost/ops.ts, services/nodejs-cloud/lib/selfhost/ops-pure.ts, "services/nodejs-cloud/app/(console)/(shell)/settings/server-backups/page.tsx", "services/nodejs-cloud/app/api/console/selfhost-export/[id]/route.ts", scripts/release/public/install-cloud.sh, scripts/test-install-cloud.sh, scripts/s3-stub.py, docs/adr/0074-selfhost-updates.md]
features: [cloud.console-settings]
---

A server installed with [`install-cloud.sh`](/docs/deploy/install-server) backs itself up: the database as a gzip'd SQL dump, and the server's own files next to it. Settings, Server backups (`/settings/server-backups`, owners and admins) sets the schedule and where copies go, and runs a backup, a restore check or a full export when you ask. This page is about the whole install. To copy one organisation's configuration to another install, use [Backup & restore](/docs/cloud/console-settings#backup) instead.

## How it works

The app never touches the server's disk or Docker. The settings and every request are rows in the database. Each server runs `venom-cloud tick` from cron every five minutes: it reads them, does the work and writes back what happened. If no server has reported in the last 15 minutes, the page says so and hides the buttons. With several app servers on one database (an [AWS Auto Scaling group](/docs/deploy/aws)), one of them takes each scheduled backup and each request.

## What a backup holds

- **The database:** `venom-cloud-<time>.sql.gz`, a `pg_dump` of everything.
- **The server's files** (on by default): `venom-cloud-files-<time>.tar.gz` with `.env`, the compose file, the Caddyfile, the database CA bundle if there is one, and the upgrade state. `.env` holds the secrets, `VENOM_VAULT_KEYS` among them, and without it the vault's sealed keys cannot be opened after a restore. Treat this archive like the secrets it holds.

Both stay in the backup directory (`/opt/venom/backups` unless the installer was told otherwise), mode 600. The newest N scheduled backups are kept; older ones are deleted. The backups taken before an upgrade or a restore are never pruned.

## The schedule

**As installed** keeps what the installer set: daily for the Production profile, off for Standard. Or pick daily or weekly, the hour (and the day, for weekly) and how many to keep. The hour is in the time zone of the [automatic updates](/docs/deploy/updates#automatic-updates). **Back up now** takes one at once (`manual-<time>.sql.gz` and `manual-files-<time>.tar.gz`), with the same copy to your bucket. Manual backups are never pruned.

## Your own bucket

Choose "This server's disk and my S3-compatible bucket" and give the bucket as `s3://bucket/prefix`. For anything other than AWS S3 (Cloudflare R2, MinIO, Backblaze B2, Wasabi), also give the endpoint, the region (R2: `auto`) and, for MinIO, path-style URLs. Each backup's files are then uploaded to `prefix/<file name>` with a SigV4-signed PUT ([multipart](#large-backups) past 256 MB). The server signs it with `openssl` and sends it with `curl`, so nothing else is installed.

The bucket's credentials never go into the database or the console. Each server signs with its own:

- **An instance role** (the [AWS stack](/docs/deploy/aws) gives its servers one that may write to its bucket), found through the instance metadata service; or
- **Keys in its `.env`**: run `venom-cloud backup s3-key` on the server. It asks for an access key ID and its secret (typed without echo) and keeps them in `.env`. Give the key only `s3:PutObject` and `s3:AbortMultipartUpload` on the prefix.

The page warns when a server has neither. The upload goes only to the bucket you named. The AWS stack's `VENOM_BACKUP_S3` (from `install-cloud.sh --backup-s3`) keeps being used while the schedule is "As installed". Once you pick a schedule here, only the bucket set here gets copies. If the copy fails, the backup counts as failed and says why, and the files stay on the server.

### Large backups

S3 takes at most 5 GB in one PUT. A file larger than the part size (256 MB) goes up as a multipart upload instead: the server starts the upload, sends the file in 256 MB parts, each cut to a temporary file next to the backup and signed on its own, and completes it. A part that hits a temporary error (a timeout, a 5xx) is retried up to twice. If it still fails, the server aborts the upload, so the bucket keeps no half-uploaded parts that you would pay for, and the backup counts as failed with the part that failed. Past 2.5 TB the parts get bigger, so a file never needs more than S3's 10,000 parts.

To change the part size, set `VENOM_BACKUP_S3_PART_MB` in the server's `.env` (at least 5). Some S3-compatible stores have their own part limits. A server that dies in the middle of an upload cannot abort it, so add a lifecycle rule to the bucket that deletes incomplete multipart uploads after a few days. The [AWS stack's](/docs/deploy/aws) bucket has one (7 days).

## Verify restore

A backup you have never restored is a hope. **Verify restore** has a server load a backup (the newest, or one you name such as `venom-cloud-20261110T032700Z.sql.gz`) into a scratch database, check that it loads without an error and holds the migrations and the organisations, and drop the scratch database again. The live database is not touched. The result shows in the Latest table and the history. On the Production profile, the database user needs permission to create databases; if it has none, the check fails and says so.

On the server, `venom-cloud verify-restore [FILE]` does the same.

## Full export

**Full export** has a server take a fresh dump and the files archive and pack them into one `venom-cloud-export-<time>.tar.gz`. It is stored in the database for 24 hours, and the Requests table shows a download link meanwhile. The download is audited (`selfhost.export_downloaded`). It holds the whole database and `.env` with every secret, so only owners and admins can start or download one. An export larger than 2 GB is refused: use `venom-cloud backup` on the server and copy the files instead.

## Restore

A restore replaces the live database, so it stays a command on the server:

```sh
venom-cloud backup --list
venom-cloud restore /opt/venom/backups/venom-cloud-20261110T032700Z.sql.gz --yes
```

It takes a safety backup of the current database first. To move to a new server, install there, copy the files archive's `.env` over the new one (the vault keys must match), then restore the dump.
