Install on Docker (Linux)

Run CrossWatch on a Linux host using Docker or Docker Compose.

This is the fastest “works everywhere” install.

We do not provide support for installing or troubleshooting container runtimes.

These pages assume Docker (or your NAS container manager) is already installed and working.

If Docker itself is broken, use your platform docs first.

The install guides are provided for reference only.

What you need

• Docker Engine.

• Docker Compose plugin (docker compose).

• A persistent host folder for CrossWatch state.

Do not run without the /config volume. You will lose state when the container is recreated.

1) Create a config folder

Example:

sudo mkdir -p /opt/crosswatch/config

2) Run with Docker Compose (recommended)

Create docker-compose.yml:

services:
  crosswatch:
    image: ghcr.io/cenodude/crosswatch:latest
    container_name: crosswatch
    ports:
      - "8787:8787"
    environment:
      - TZ=UTC
    volumes:
      - /opt/crosswatch/config:/config
    restart: unless-stopped

Start it:

docker compose up -d

Open http://<host-ip>:8787.

3) Run with Docker (one-liner)

docker run -d \
  --name crosswatch \
  -p 8787:8787 \
  -v /opt/crosswatch/config:/config \
  -e TZ=UTC \
  --restart unless-stopped \
  ghcr.io/cenodude/crosswatch:latest

Updating

Docker Compose

docker compose pull
docker compose up -d

Docker

Permission issues on /config

If the container can’t write to /config:

• Fix host permissions (recommended).

• Or set APP_UID/APP_GID to match the folder owner.

Next steps

• Continue with First-time setup.

• See the full reference in Docker setup.