Skip to main content

Upgrading & backups

Keeping OtoDock current is a short 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.

Upgrading a Docker install​

One script does the upgrade. Download it into the install folder, the one holding .env and docker-compose.yml, and run it there:

curl -fsSLO https://raw.githubusercontent.com/OtoDock/oto-dock/main/scripts/upgrade.sh
bash upgrade.sh --dry-run                    # prints every step, changes nothing
bash upgrade.sh                              # upgrades to the latest release
bash upgrade.sh --to 1.7.1                   # or to a specific release

What it does, in order, and each step says so before it runs:

  1. Checks that this folder is a Docker install and that Docker works.
  2. Downloads the release's docker-compose.yml and docker-compose.phone.yml and checks them against your .env before anything changes. If the new release refuses a value, the upgrade stops here and the old release keeps running.
  3. Dumps the database to backups/upgrade-<time>/ and copies .env and the compose files next to it.
  4. Puts the new compose files in place and sets OTODOCK_VERSION in .env. No other line of .env is written. The names of the settings that are new in the release are printed for you to review in config.env.example, and their defaults apply until you set them.
  5. Pulls the images, starts the stack and waits for the server to report healthy. The first start after an upgrade takes a few minutes, because the server builds its tool environments and updates the database. The script waits up to five minutes for this. For a large database, give it more time with OTODOCK_UPGRADE_WAIT_S=900 bash upgrade.sh.

If the script stops before the stack is started, it puts .env and the compose files back as they were, and the old release keeps running. If it stops after the start, the new files stay in place, because the database may already be updated and the old release cannot run on it. Look at docker compose ps and docker compose logs otodock-proxy, fix the cause, and run the script again. To go back instead, put the files back from backups/upgrade-<time>/, then restore its dump as described under Restoring from a backup.

If you prefer to upgrade by hand, back up, download the release's two compose files over yours, set OTODOCK_VERSION=<release> in .env, then run docker compose pull and docker compose up -d.

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 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 are 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 cannot 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, and upgrades bump these for you.

# Containerised, built from source
git pull
scripts/compose.sh up -d --build
# Native (bare-metal development)
sudo systemctl stop otodock-proxy    # or stop your foreground process
git pull
scripts/dev-setup.sh                 # plus --service / --phone if used
sudo systemctl start otodock-proxy   # --service starts it for you

Run dev-setup.sh as the user the server runs as, with the server stopped. It is idempotent and never touches your secrets: it brings the CLIs and the toolchain to their pinned versions and rebuilds the virtualenv when the pinned Python moves.

Paired machines​

A paired machine updates its satellite on its own when it reconnects after the upgrade, unless an admin switched it to manual updates.

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 stays on one major version (16.x), and an OtoDock upgrade only moves it to a newer patch release of that version. Such a move recreates the database container on the new image and keeps its data. If a future OtoDock release moves to a new PostgreSQL major, its release notes will say so and give the steps: back up with backup.sh, start the new version, then restore.

Next steps​