Skip to main content

Quick Start

Start Outpost next to your other containers and let it check them for new images every night.

Prerequisites

  • Docker Engine — On Linux, for amd64 or arm64.
  • Docker socket — Outpost talks to Docker through /var/run/docker.sock, which you mount into the container.
  • A user ID and group ID — Outpost runs as PUID and PGID (both 1000 by default) and joins the socket's group on its own.

Pick an Image

Each release publishes the same multi-platform image to both registries:

  • cbnventures/outpost on Docker Hub
  • ghcr.io/cbnventures/outpost on the GitHub Container Registry

Use either registry for a released image. To try an unpublished working copy, build it from source with the repository's own compose.yml, as shown below.

Build From Source

Clone the repository and let Docker Compose build and start Outpost from its compose.yml:

bash
git clone https://github.com/cbnventures/outpost.git
cd outpost

# Build the image and start Outpost in the background.
docker compose up --build --detach

The image is built and tagged cbnventures/outpost:latest on your host, and Outpost starts with the settings in that compose.yml, which reads overrides such as TZ from a .env file next to it. Skip ahead to Check That It Started, and run docker compose logs outpost from the clone wherever this page uses docker logs outpost.

Outpost skips this image as locally built, so it doesn't update itself. On Docker 28 or older with the containerd image store, Docker doesn't record that the image was built here, so once a release is published Outpost could replace your build with it; label the container io.cbnventures.outpost.enable=false to keep it.

Start Outpost

By default, Outpost checks every running container at 04:00 in your time zone. New images are pulled and the containers are recreated on them. The schedule and update behavior can be changed later from the dashboard's Settings page.

info

Outpost checks its own container last and hands it to a short-lived helper container, which swaps it onto the new image, as described in Updates and Rollback. Outpost finds that container from Linux process metadata, with Docker's container-ID hostname only as a fallback, so host networking or a custom hostname doesn't hide it.

If Outpost can't find its own container, it leaves alone every container running an image named outpost, such as cbnventures/outpost:latest, so it never stops itself in the middle of a check.

Check That It Started

Read the container logs:

bash
docker logs outpost

A healthy start prints the dashboard address, the schedule with its next run time in UTC, and the label mode. Until the dashboard account exists, it also prints a setup code:

text
Outpost
  Dashboard: http://localhost:22601/admin/
  Schedule: 0 0 4 * * * (next run 2026-10-25T08:00:00.000Z)
  Mode: opt-out
No account exists yet. Open the dashboard to create it with the setup code.
  Setup code: K7Q2M-XR9TD-P4W8N
  Expires: 2026-10-24T22:30:00.000Z

If Outpost can't reach the Docker socket, the server stops before printing this and the error repeats in the logs. See Troubleshooting for the fix.

Open the Dashboard

Open http://localhost:22601/admin/ on the Docker host, or http://<server-ip>:22601/admin/ from another computer on its network. The first time, it asks you to set up your account:

  1. Enter the setup code from the log under One-time code. A code works for 30 minutes, and restarting the container prints a new one.
  2. Choose a username and a password of at least 12 characters, and repeat the password under Confirm password.
  3. Select Create account.

The dashboard then opens signed in. It shows every running container, the next scheduled check, and the results of past checks.

Run a First Check Now

You don't have to wait for the schedule. Pick one of these:

  • Use the dashboard — Select Check now on the overview.
  • Check on every start — Turn on Check when Outpost starts on the Settings page.
  • Trigger it over HTTP — Create an access token with the updates:run scope on the dashboard's Access tokens page, then call the checks endpoint as shown in HTTP API and Metrics.
bash
# Paste the token and press Enter. It isn't shown or saved to the shell history.
read -r -s OUTPOST_TOKEN

curl --request POST \
  --header "Authorization: Bearer $OUTPOST_TOKEN" \
  http://127.0.0.1:22601/api/v1/checks

Each container gets one line in the logs when the cycle finishes:

text
postgres (postgres:17): up-to-date - sha256:9c1d...
web (ghcr.io/example/web:latest): updated - Recreated with ghcr.io/example/web:latest
outpost (cbnventures/outpost:latest): up-to-date - sha256:4e7b...

tip

To try Outpost without changing any container, turn on Monitor only on the Settings page first. Outpost then only reports which containers have a newer image, though it still pulls an image when the registry can't report a digest.

What Is Next

Start with the Quick Start