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 are published on the GitHub Releases page with notes on what changed, and every release ships versioned container images. The compose file you installed with pins the release it shipped with — 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.

Upgrading a Docker Compose install​

# 1. Back up (one command — see Backups below)
./backup.sh

# 2. Pick the new release: set (or bump) one line in .env —
#    the current release is shown below; all versions are on the Releases page
#        OTODOCK_VERSION=1.4.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.

Backups​

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 — safe to run while OtoDock is live:

./backup.sh

It writes a timestamped, compressed snapshot of the database to ./backups/. You can point it elsewhere and control how many to keep — and schedule it (cron, a systemd timer) for regular automatic backups:

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

What a full backup is​

Three pieces rebuild an install from nothing:

  1. The database — users, agents and their settings, chats, tasks, triggers, usage. This is what backup.sh captures, with PostgreSQL's own dump tool.

  2. Agent files — workspaces, knowledge documents, uploads. They live in the otodock-agents Docker volume; archive it with:

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

  3. Your .env file — it holds the key that decrypts stored credentials. Keep a copy somewhere safe; without it, a restored database can't decrypt the credentials in it.

Upgrading a source install​

The repository checkout is the install, so updating is a git pull plus a rebuild. (VERSIONS.md in the repository pins the full toolchain and base images, so builds are reproducible — upgrades bump these for you.)

# 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​