Skip to main content

Upgrading & backups

Keeping OtoDock current is a quick, safe routine — and your data stays put across upgrades. This page covers both.

Releases & versioning​

OtoDock releases are published on the GitHub Releases page with notes on what changed. Every release ships container images tagged with its version (ghcr.io/otodock/otodock-proxy:<version>, and matching tags for the other services), and the compose file you installed with pins the release it shipped with — so nothing on your server changes until you decide to upgrade. Before 1.0, read the release notes before a jump: breaking changes are called out there.

For source installs, VERSIONS.md in the repository pins the full toolchain and base images, so builds are reproducible; upgrades bump these for you.

Before you upgrade: back up​

OtoDock ships two small standalone scripts — they only need Docker and the running stack, so they work for every install method. On a Docker Compose install, download them once next to your compose file:

curl -fsSLO https://raw.githubusercontent.com/OtoDock/oto-dock/main/scripts/backup.sh
curl -fsSLO https://raw.githubusercontent.com/OtoDock/oto-dock/main/scripts/restore.sh
chmod +x backup.sh restore.sh

(On a source install they're already there, at scripts/backup.sh and scripts/restore.sh.)

Then a backup is one command:

./backup.sh

It writes a timestamped, compressed snapshot of the database to ./backups/. You can point it elsewhere and control how many to keep:

OTODOCK_BACKUP_DIR=/srv/backups OTODOCK_BACKUP_RETAIN=30 ./backup.sh

Schedule it (cron, a systemd timer) for regular automatic backups.

What's in a backup — and the other half

backup.sh captures the database: users, agents and their settings, chats, tasks, triggers, usage — a consistent snapshot taken with PostgreSQL's own dump tool, safe to run while OtoDock is live. Your agent files (workspaces, knowledge documents, uploads) live in the otodock-agents data volume — grab that half with one command too:

docker run --rm -v otodock-agents:/data -v "$PWD/backups":/out alpine \
  tar czf /out/otodock-agents-$(date +%F).tar.gz -C /data .

With the database dump, the agents archive, and your .env file (it holds the key that decrypts stored credentials — keep a copy somewhere safe) you can rebuild an install from nothing.

Upgrading a Docker Compose install​

# 1. Back up (above)
./backup.sh

# 2. Pick the new release: set (or bump) one line in .env —
#    versions are on the GitHub Releases page
#        OTODOCK_VERSION=0.5.0

# 3. Pull and restart
docker compose pull
docker compose up -d

OtoDock applies any needed database updates automatically on startup — your existing data is never lost. It persists across upgrades because the database, agent files, and session state live in named volumes, separate from the application containers.

If you've enabled add-ons (the telephony overlay, for example), the same two commands upgrade them too — COMPOSE_FILE in your .env covers every docker compose command.

Upgrading a source install​

The repository checkout is the install, so updating is a git pull plus a rebuild:

# Containerised, built from source
git pull
scripts/compose.sh up -d --build
# Native (bare-metal development)
git pull
scripts/dev-setup.sh          # reconciles the pinned toolchain, venvs, and dashboard build
sudo systemctl restart otodock-proxy   # or restart your foreground process

dev-setup.sh is idempotent and never touches your secrets; if a release bumps the pinned Python or Node, it rebuilds the affected virtualenvs for you.

Restoring from a backup​

If you ever need to roll back, stop the OtoDock server (leave PostgreSQL running), restore, then start it again:

docker compose stop otodock-proxy      # native: sudo systemctl stop otodock-proxy
./restore.sh ./backups/otodock-otodock-<timestamp>.sql.gz
docker compose start otodock-proxy

The script confirms before overwriting the current database, and OtoDock brings the schema up to date automatically on the next start. To restore agent files from a volume archive, untar it back the same way it was taken:

docker run --rm -v otodock-agents:/data -v "$PWD/backups":/out alpine \
  tar xzf /out/otodock-agents-<date>.tar.gz -C /data

PostgreSQL major versions​

The bundled PostgreSQL is pinned to a major version (16.x), and upgrades never jump it under you — a plain docker compose pull only picks up patch releases. If a future OtoDock release moves to a new PostgreSQL major, the release notes will say so and the path is the standard one: back up with backup.sh, start the new version, restore.

Next steps​