Getting Started¶

The fastest way to run WebATM is with Docker — no Python or Node toolchain needed. If you plan to modify the code, run it from source instead and see the Development Workflow.

Option 1: Docker (recommended)¶

Requires Docker 20.10+ with Docker Compose 2.0+. The repository's docker-compose.yml defines both build variants: the standalone webatm service (enabled by default) and a commented-out webatm-integrated service that bundles the BlueSky simulator in the same container. Both pull prebuilt images from GHCR, so no local build is needed.

Standalone (webatm)¶

Connects to a BlueSky server you run yourself (by default on the Docker host, via BLUESKY_SERVER_HOST=host.docker.internal).

1. Start with Docker Compose (pulls ghcr.io/amvlab/webatm:latest)

   docker compose up -d webatm
   

2. Open the web interface at http://localhost:8082

3. View logs

   docker compose logs -f webatm
   

4. (Optional) Mount your BlueSky working directory

   Mounting your local BlueSky directory into the container enables the in-app file manager for scenario/, plugins/, settings.cfg, and output/. Uncomment the volumes: block of the webatm service in docker-compose.yml and point the host side at your BlueSky directory:

   services:
     webatm:
       # ...
       volumes:
         - /path/to/your/bluesky:/bluesky
   

   The part before the colon is the path on your machine; the part after is where it appears inside the container. Enter that container-side path (/bluesky) in the web UI under Settings → BlueSky base path, and apply the mount with docker compose up -d (the container is recreated automatically).

Integrated (webatm-integrated)¶

A single container that ships the simulator itself, with Start/Stop/Restart controls and a live server log in the UI — see the Integrated Build for details.

1. Enable the service: uncomment the webatm-integrated service in docker-compose.yml. Both services default to host port 8082, so also comment out the standalone webatm service (or map one of them to a different host port to run both side by side).

2. Start with Docker Compose (pulls ghcr.io/amvlab/webatm-integrated:latest)

   docker compose up -d webatm-integrated
   

3. Open the web interface at http://localhost:8082 — the server lifecycle controls are in Settings, and the server log has its own console tab.

4. View logs

   docker compose logs -f webatm-integrated
   

5. (Optional) Persist BlueSky's config directory

   BlueSky lives inside the container at /home/webatm/bluesky (settings.cfg, scenario/, plugins/, output/), so by default its state is lost when the container is recreated. To keep it across restarts, uncomment the volumes: block of the webatm-integrated service and point the host side at a directory of your choice:

   services:
     webatm-integrated:
       # ...
       volumes:
         - /path/to/your/bluesky-config:/home/webatm/bluesky
   

   Unlike the standalone variant, no UI configuration is needed — the file manager is pre-wired to that path. Apply the mount with docker compose up -d.

docker build -t webatm:latest .                                        # standalone
docker build -f Dockerfile.integrated -t webatm-integrated:latest .    # integrated

Option 2: Prebuilt release (source, no Node.js)¶

Use this to run WebATM directly from source without installing Node.js or building the frontend yourself. You still clone the repo for the Python source, then drop in two tarballs that contain the runtime assets that aren't checked into git: a small per-version code tarball and a larger static-asset tarball that changes rarely.

1. Clone the repository

   git clone https://github.com/amvlab/WebATM
   cd WebATM
   

2. Download and extract the prebuilt code tarball

   Grab the latest webatm-prebuilt-<version>.tar.gz from the Releases page and extract it from the repo root:

   tar -xzf ~/Downloads/webatm-prebuilt-<version>.tar.gz
   

   This lands:

   • WebATM/static/dist/ — prebuilt webpack bundles
   • WebATM/static/vendor/ — third-party CSS/fonts (FontAwesome, MapLibre)

3. Download and extract the static-asset tarball

   Grab the assets tarball pinned by the repo's .assets-version file (e.g. webatm-assets-v1.tar.gz) from the Releases page and extract it from the repo root:

   tar -xzf ~/Downloads/webatm-assets-<tag>.tar.gz
   

   This lands:

   • WebATM/static/tiles/ — offline basemap (world.pmtiles) and navigation overlay (navdata.pmtiles)
   • WebATM/static/glyphs/ — map fonts
   • WebATM/static/navdata/ — navigation database

   This bundle changes rarely (only when tiles, fonts, or navdata roll), so a single download usually carries across many code releases.

4. Install Python dependencies and start

   uv sync
   uv run script/run_webatm.sh
   

5. Open the web interface at http://localhost:8082

6. (Optional) Enable the offline basemap

   The assets tarball already includes WebATM/static/tiles/world.pmtiles. To use it, open Settings → Map Display Configuration → Offline (Local PMTiles) in the web UI — see Offline Use (PMTiles).

Option 3: Running from source¶

1. Clone the repository

   git clone https://github.com/amvlab/WebATM
   cd WebATM
   

2. Install Python dependencies (with uv)

   uv sync
   

   This creates a virtual environment and installs the runtime and development dependencies pinned in uv.lock. Prefix commands with uv run (e.g. uv run python WebATM.py) to use that environment, or activate it with source .venv/bin/activate.

3. Build frontend assets

   script/build_frontend.sh
   

4. Start the application

   script/run_webatm.sh
   

5. Open the web interface at http://localhost:8082

Everything beyond running the app — linting, type checking, the test suites, rebuilding the frontend on change, and building this documentation site — is covered in the Development Workflow.