Context7 On-Premise can back up its data into a single archive, on a schedule or on demand. You can use the archive to rebuild your deployment on a fresh machine. It contains:
- The SQLite database: configuration, credentials, and indexed libraries.
- The vector index in
/data/vectors. - The encryption key file
/data/.encryption-key, which protects stored secrets.
Two things are not in the archive:
- A key set with
ENCRYPTION_KEY. Keep your own copy of it. - An external vector store (Milvus or pgvector). Back it up separately.
Built-in backups work only with the embedded SQLite database. When DATABASE_URL is set (Postgres), scheduled and manual backups are turned off. This is also true on a single container with VECTOR_STORE=lancedb.
In that case, back up these yourself:
- Postgres, with your provider’s tools.
- Your vectors: the
/data/vectorsvolume (LanceDB), or your Milvus or pgvector store.
Backups run safely while the server is serving traffic. The database snapshot uses SQLite’s online backup API, so you don’t need a maintenance window.
A backup archive holds the database and, if you do not set ENCRYPTION_KEY, the encryption key file. Anyone with the archive can then read your stored credentials, such as LLM API keys and Git tokens. Protect backups as carefully as the data volume itself. For S3, use a private bucket with server-side encryption.
Configuring Backups#
Open Workspace Settings › Backup in the dashboard. Choose a destination, set a schedule, and save.
Local or Network Path#
Writes archives to a directory on the server’s filesystem. Use this for air-gapped deployments or when you back up to an NFS mount.
When running in Docker, mount a dedicated volume for backups so they survive independently of the data volume:
Then set the backup directory to /backups in the dashboard.
S3#
Works with AWS S3 and any S3-compatible store such as MinIO or Ceph.
| Field | Description |
|---|---|
| Bucket | Bucket name (required) |
| Region | Bucket region, defaults to us-east-1 |
| Access Key ID / Secret | Static credentials. Leave blank to use the AWS default credential chain (IAM role, environment variables) |
| Endpoint | Custom endpoint for S3-compatible storage. Leave blank for AWS |
| Path-style addressing | Enable for most MinIO setups |
| Key prefix | Optional prefix inside the bucket, e.g. context7/ |
The secret key is stored encrypted in the local database.
Schedule and Retention#
Pick a preset (daily, every 6 hours, weekly) or enter a custom cron expression. Retention keeps the newest N archives and prunes older ones automatically; choose Keep all to retain everything.
If an indexing job is running when a scheduled backup fires, the backup still completes, but that one library may be only partially indexed. Schedule backups for quiet hours, or simply re-index that library after a restore.
Running a Backup Manually#
Click Back up now in the dashboard, or call the API:
All backup endpoints require an admin session and keep working even if your license has expired, so you can always get your data out.
| Endpoint | Description |
|---|---|
POST /api/backup | Start a backup in the background |
GET /api/backup/status | Whether a backup is running, plus the last result |
GET /api/backups | List available archives |
GET /api/backups/<name>/download | Download an archive (local destination only) |
GET /api/backups/<name>/manifest | Read an archive’s manifest and check it against this installation (includes currentSchemaVersion) |
POST /api/backups/<name>/restore | Stage a restore. It is applied on the next restart |
POST /api/backups/restore/restart | Restart the server to apply a staged restore |
GET /api/backup/config / PUT | Read or update the backup configuration |
Restoring#
Restore a backup from the dashboard (for local backups) or with the offline CLI (for S3 backups, scripted recovery, or a fresh machine).
In every case the restore never deletes your current data. It moves the existing database, vector index, and encryption key file (if there is one) into a pre-restore-<timestamp> directory inside the data volume, so you can roll back. Delete that directory once you’ve verified the restore.
A backup created by a newer Context7 version cannot be restored into an older installation; the restore tool will refuse and tell you to upgrade first. Backups from older versions restore fine, and the database is migrated automatically the next time the server starts.
The restore also checks the encryption key. The archive records which key encrypted the stored credentials. It stores a fingerprint of the key, never the key itself. The restore stops when:
- This installation’s
ENCRYPTION_KEYis different from the backup’s key. SetENCRYPTION_KEYto the backup’s key. Or remove it, so the key file from the archive is used. - The backup used
ENCRYPTION_KEY, but this installation has none. The archive has no key in this case. Set the sameENCRYPTION_KEY, then restore.
Backups from earlier versions do not record the key and restore without this check.
From the dashboard#
Open Workspace Settings › Backup, find the backup in the list, and click the restore icon. Context7 validates the archive, shows what it contains (Created, Projects, and Schema), and asks you to confirm. It then stages the restore and restarts to apply it, because the live database and vector index cannot be swapped while the server is running. Under Docker or Kubernetes the server comes back automatically; otherwise start it again after it stops.
Offline with the CLI#
Run the CLI with the server stopped. For S3 backups, download the archive to the machine first.
Docker#
If the archive is not already inside a mounted volume (for example, you downloaded it from S3), copy it in first:
Kubernetes#
Scale the StatefulSet down, run the restore in a one-off pod that mounts the same PVC, then scale back up:
Use kubectl cp to place the archive on the volume first if it isn’t there already.
Running locally#
If you run Context7 without Docker:
The command prompts for confirmation before replacing anything. Pass --yes to skip the prompt in scripts.
Disaster Recovery Checklist#
- Deploy a fresh Context7 instance on the new machine (same or newer version). If the old deployment set
ENCRYPTION_KEY, set the same value. - Don’t run the setup wizard. Stop the server instead.
- Copy your latest backup archive onto the machine.
- Run the restore as shown above.
- Start the server. Your configuration, credentials, users, indexed libraries, and search index are all back.
If the backup used the key file, the key is inside the archive. Restored credentials then work at once on the new machine. If the old deployment set ENCRYPTION_KEY, set the same value on the new one before step 4. You do not need to enter anything else again.