Backups and upgrades
Preserve state, workspaces, and decryption keys before changing an installation.
A usable backup needs both stored data and the material that makes it usable. A database dump without the vault keyring cannot recover encrypted credentials; a keyring without the database cannot recover agent state.
Server backup inventory
| Item | Why it matters |
|---|---|
| PostgreSQL data | Profiles, conversations, memories, skills, schedules, integration state, and persisted runtime records |
gateway_home / workspace files | Agent repositories, installed user tools, SSH material, and other persistent filesystem work |
| Gateway configuration | Image versions, public URL, time zone, network policy, and runtime settings |
| Encryption keyring | Required to decrypt vault values already stored in the database |
| Owner access credential | Needed to regain administrative access |
Keep the encryption keyring protected separately from database backups, while maintaining a clear recovery procedure that can obtain both. Back up any additional bind mounts or external storage you configured.
A database dump
From the repository directory for your own Compose installation, a PostgreSQL custom-format dump can be created with:
umask 077
docker compose exec -T postgres pg_dump -U jian -d jian -Fc > jian-database.dumppg_dump gives a consistent database snapshot, but does not snapshot filesystem changes in gateway_home. Coordinate a quiet/stopped-write window or a consistent storage snapshot when you need database and file state from the same point in time.
Verify that the command succeeded, the dump can be inspected with PostgreSQL tooling, and the backup is copied to the intended protected destination. A filename existing is not a restoration test.
Restore into an isolated environment
Before relying on a backup, rehearse restoring it into a separate database and workspace location with matching encryption keys and compatible images. Inspect profiles, a conversation, a memory, a workspace file, and a configured credential's usability.
Do not start a restored copy against the same live channel accounts or external automations without planning for duplicate consumers and scheduled effects. Validate the restore in isolation before making it authoritative.
Desktop local backups
Quit Jian before copying its embedded database directory. Preserve the app's gateway database, workspaces, and local credential file, together with the OS credential-store material needed to unseal it.
A raw copy of local-gateway.json is not necessarily portable to another OS account or machine: normal storage is sealed by the operating system. Do not claim a successful migration until the restored app can decrypt and use its credentials. See local storage.
Update a server
- Read the target release's upgrade notes.
- Capture a verified backup and record the current image tags.
- Set the intended
JIAN_VERSIONin the deployment configuration, or deliberately followlatest. - Pull and recreate both services:
make pull
make up
make ps- Check web and gateway health, sign in, inspect existing data, and run a small provider-backed request.
- Check connected worker versions and update them where required.
Schema migrations run during startup when a release includes them. A later version may change storage in ways an older binary cannot read. Rollback planning must include data compatibility, not only changing an image tag back.
Desktop and Remote updates
The desktop app has its own update flow. Linux AppImage updates differ from installing a new Debian package. Standalone Jian Remote follows its own npm/service update process; see worker updates.
Keep published desktop, gateway, and worker major.minor lines compatible. Patch updates within a line may be compatible, but release notes still describe fixes and any special operation needed.
Avoid accidental data loss
docker compose down retains named volumes. docker compose down -v removes them. The latter is not an upgrade or restart procedure. Likewise, replacing .env with newly generated encryption keys does not repair a vault containing data encrypted with the old ones.
Read the release notes before each rollout.