Docker setup

Run CrossWatch in Docker and persist state by mounting /config.

Run CrossWatch (CW) in Docker. Always mount /config to persist state.

If you use Portainer or a NAS container UI, mirror these same values.

Expose 8787 and attach a persistent volume to /config.

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.

Before you run

• Pick a Docker volume name for CW state.

  • Example: crosswatch_config

• Decide which port to expose.

  • Default UI port: 8787

• Set your timezone.

  • Example: TZ=Europe/Amsterdam

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

Create the volume (once)

docker volume create crosswatch_config

Run it

Docker

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

Open http://localhost:8787.

Docker Compose (recommended)

Updating

Pull the latest image. Then restart the container.

Docker

docker pull ghcr.io/cenodude/crosswatch:latest
docker stop crosswatch
docker rm crosswatch
docker run -d \
  --name crosswatch \
  -p 8787:8787 \
  -v crosswatch_config:/config \
  -e TZ=Europe/Amsterdam \
  --restart unless-stopped \
  ghcr.io/cenodude/crosswatch:latest

Docker Compose

Optional environment variables

You normally only need TZ.

Override these only if you know why:

• TZ — container timezone (used for timestamps in logs and the UI).

  • Default: UTC

  • Common values:

    • UTC

    • Europe/Amsterdam

    • Europe/London

    • America/New_York

    • America/Los_Angeles

    • Asia/Singapore

    • Asia/Tokyo

    • Australia/Sydney

• CONFIG_BASE — base path for config.json, state.json, statistics.json, etc.

  • Default: /config (leave as-is)

• WEB_HOST — bind address for the web UI inside the container.

  • Default: 0.0.0.0

• WEB_PORT — port for the web UI inside the container.

  • Default: 8787

• APP_USER — username created inside the container that runs CW.

  • Default: appuser

• APP_GROUP — group name created inside the container.

  • Default: appuser

• APP_UID — numeric UID used for APP_USER (helps match your host user).

  • Default: 1000

• APP_GID — numeric GID used for APP_GROUP.

  • Default: 1000

• APP_DIR — application directory inside the container.

  • Default: /app (leave as-is)

• RUNTIME_DIR — runtime/config directory used by the entrypoint.

  • Default: /config (leave as-is)

• RELOAD — enable Python auto-reload for development.

  • Default: no (set to yes for dev only)

Use an IANA timezone name (like Europe/Amsterdam), not a GMT offset.

Troubleshooting

UI does not load

• Confirm the container is running: docker ps

• Check logs: docker logs crosswatch --tail 200

• /config is not accessible or writable on my NAS.

  • Align NAS file permissions with APP_UID/APP_GID and APP_USER/APP_GROUP.

• Confirm the port mapping matches the URL you open.

  • Example: -p 8787:8787 -> http://localhost:8787

Summary

Run CW in Docker and persist data by mounting /config.

Expose the UI port (default 8787) and set TZ.

Use Docker Compose for easier updates and restarts.

Next steps

• What do you need? - choose providers and a setup path

• Best practices - safer defaults for your first pairs

• Settings - connect providers and configure pairs

• HTTPS/TLS - put the UI behind HTTPS (recommended)