maptool/docs/deployment.adoc

Deployment

Table of Contents

• Layout on the server
• The runner’s "host" label
• Puma’s bind address
• CI deploy job

MapTool deploys as a Docker container on the same server the Gitea Actions runner runs on. The deploy job in .gitea/workflows/ci.yml runs directly inside the runner’s own container (see "The runner’s host label" below) and calls docker compose directly against the host’s Docker daemon — no systemd unit is involved for this app.

Layout on the server

/srv/docker/maptool/ holds:

• A checkout of this repository (kept in sync by the deploy job, see below) — Dockerfile, docker-compose.yaml, application code.

• data/, not part of that sync — uploaded GPX files and offline.pmtiles. Persisted via a bind mount (./data:/app/data in docker-compose.yaml), so a redeploy (docker compose up --build) never touches it.

The runner’s "host" label

The Gitea Actions runner (gitea/runner:3) normally runs each job in a fresh, isolated container spawned via its mounted /var/run/docker.sock — that’s how the check job runs (runs-on: ubuntu-latest). Such a job container has no access to the host filesystem or to a host systemctl, so it can’t reach /srv/docker/maptool or manage a systemd unit.

The deploy job instead uses runs-on: host, a label configured in the runner’s own config.yaml that makes the runner (gitea-runner, the binary inside the gitea/runner:3 image) execute the job’s steps directly inside the runner’s own container, without spawning a new one. That container already has /var/run/docker.sock mounted, so docker/docker compose commands run there act directly on the host’s Docker daemon — this is the same runner used for check, just with a second execution mode, not a separate runner.

For this to work, the runner’s own docker-compose.yaml (the one that starts the runner itself, not this app) needs one more bind mount so /srv/docker inside the runner container is the same path as on the real host:

services:
  runner:
    image: docker.io/gitea/runner:3
    # ...
    volumes:
      - ./config.yaml:/config.yaml
      - ./data:/data
      - /var/run/docker.sock:/var/run/docker.sock
      - /srv/docker:/srv/docker

And the runner’s config.yaml needs the host label added alongside whatever docker-mode labels it already has. If config.yaml is empty (no prior customization), generate a real default first rather than hand-writing one — schemas vary across runner versions:

docker exec <runner-container> gitea-runner config generate > config.yaml

(config generate — not generate-config, which is deprecated; and the binary is gitea-runner, not act_runner.)

Then add the label to the generated runner: labels: list — the generated defaults are commented out, and this list fully replaces the runner’s built-in defaults rather than adding to them, so all of them need to be uncommented too, not just the new one:

runner:
  labels:
    - "host:host"
    - "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
    - "ubuntu-24.04:docker://docker.gitea.com/runner-images:ubuntu-24.04"
    - "ubuntu-22.04:docker://docker.gitea.com/runner-images:ubuntu-22.04"

The 1:1 path match matters: the deploy job’s working directory (/srv/docker/maptool) needs to resolve to the same path whether read from inside the runner container or by the Docker daemon on the real host, because docker-compose.yaml’s relative bind mount (./data`) gets resolved to an absolute path by the docker compose CLI before being sent to the daemon — if that path only existed inside the runner container, the daemon (running on the bare host) would create/mount the wrong (or a nonexistent) directory.

After editing both files, recreate the runner container so it picks up the new volume and label (docker compose up -d in the runner’s own directory).

Puma’s bind address

config/puma.rb binds to 127.0.0.1 by default (see docs/architecture.adoc) — fine for local dev, but inside a container that would make the app unreachable through Docker’s published port (loopback is scoped to the container’s own network namespace). docker-compose.yaml sets BIND_HOST=0.0.0.0 to override that for the deployed container specifically; Docker’s own port publishing (ports: in the compose file) is the network boundary there instead of Puma’s bind address.

CI deploy job

.gitea/workflows/ci.yml’s `deploy job runs after check passes, only on a push to main, with runs-on: host:

1. Checks out the repo with plain git (fetch + checkout, authenticated via a one-off http.extraHeader), not actions/checkout@v4 — that’s a JS action, and host-mode jobs run directly in the runner container, which has git but no Node.js runtime to execute JS actions with.

2. Copies the checkout into /srv/docker/maptool/ using plain cp/rm (no rsync in the runner image): clears everything in the target except data/, copies the fresh checkout over, then drops the copied .git.

3. cd /srv/docker/maptool && docker compose -p maptool up --build -d — rebuilds the image and recreates the container if anything changed; a no-op restart if nothing did.

No sudo, no systemd, no SSH — the runner container’s existing access to /var/run/docker.sock and (once added) /srv/docker is enough.