ASTRODOCK documentation Home GitHub

Guides

Upgrading

Astrodock updates itself from the dashboard, on request. It never does so unprompted — you press the button. If you would rather do it from the server, it is two commands.

From the dashboard

Settings → About This Astrodock shows the version you are running and checks whether a newer one has been released. When there is, Update Now does the whole thing:

  1. Confirms who you are, because this replaces every running container.
  2. Takes a database backup first, automatically.
  3. Pulls the new image and recreates the stack. The dashboard stops responding for a minute or so here — that is the platform restarting, not a failure. The page reconnects by itself.
  4. Checks the new version actually came back. If it did not, it puts the previous one back without being asked, and says so.

Your apps keep running throughout — this replaces the platform, not the things it hosts.

When the button is not there

Two installs cannot be updated this way, and the page says which applies to you: one built from source (there is no published image to pull — use git pull and a rebuild), and one not started by Docker Compose. Everything installed with the standard script can use it.

From the server

The same thing by hand. Two commands, from your install directory — /opt/astrodock unless you chose another:

Which version am I on?

The dashboard shows it in the bottom-left corner, and Settings → About This Astrodock says whether a newer release has been tagged. Astrodock checks GitHub for that once every six hours and never installs anything by itself — you always run the upgrade. You can switch the check off under Settings → Logs & Privacy.

Back up first

Always take a fresh backup before upgrading, so you have something to roll back to if anything goes sideways. It takes one command — see Backups & restore.

  1. Pull the new image

    cd /opt/astrodock && docker compose pull

    Downloads the published Astrodock image. Nothing changes on the running stack yet.

  2. Bring the stack back up

    docker compose up -d

    Compose recreates only the services that changed and leaves your data volumes untouched.

Staying on a specific version

By default the stack tracks latest, so a pull takes you to the newest release. To pin a version instead, set ASTRODOCK_VERSION=v0.0.6 in your .env and run the two commands above — that is also how you go back to an earlier release if one gives you trouble.

If you built from source

A source install has the repository on the server and builds its own images, so it updates differently — git pull, then rebuild: 

git pull
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

The standard install has no repository on the box: install.sh downloads the compose file and the Caddy config, not a checkout. git pull there will only tell you it is not a git repository. The dashboard says which kind you have — Settings → About This Astrodock reports built from source when it applies.

Migrations run automatically

When the api (control plane) starts, it applies any pending schema migrations itself. There's no separate migrate command to remember — bringing the stack up is enough.

Check it came back healthy

After up -d, confirm everything restarted cleanly:

docker compose ps          # every service should be "Up" (postgres "healthy")
docker compose logs -f api  # watch migrations run and the control plane start listening

In the api logs you should see it apply migrations (if any), then start serving. Then open the dashboard and glance at the Health page to confirm your apps are responding.

If a service won't come up

Read its logs directly, e.g. docker compose logs api or docker compose logs caddy. Most upgrade hiccups are a config value the new version expects — check the release notes and your .env against the latest .env.example.

Your app data is preserved

Upgrades rebuild the platform's container images, not its data. Everything in the Docker volumes — the control-plane database, every internal per-app database, and the object store — stays exactly where it is. Your apps and their data carry across the upgrade untouched.

Rolling back

If an upgrade goes wrong, you have two ways back:

  • Pin the previous version and bring the stack up on it again. Set ASTRODOCK_VERSION in your .env to the release you were on, then: 
    docker compose pull
docker compose up -d

    On a source install, git checkout <previous-tag> and rebuild with the build overlay instead.

  • Restore from backup if a migration changed data in a way an older version can't read. Use the backup you took before upgrading — see Backups & restore for the procedure.

Migrations move forward

Schema migrations are designed to be applied going forward, not reversed. If you downgrade the code after a migration ran, restoring the pre-upgrade backup is the reliable way to get a matching database. This is exactly why you back up first.

Related