Docker operations
Pre-built image workflow, restart vs force-recreate, and where to put API tokens.
Pulse ships as a pre-built Docker image. You load it once, mount config.yml, and run docker compose up. You do not build from source.
What runs in production
| Piece | Role |
|---|---|
pulse-1.0.0-image.tar.gz | The application (load with docker load) |
config.yml | Your squads, workflow status names, credentials |
docker-compose.yml | Starts the container, maps port 8080, mounts config |
The image is frozen at release time. To get a newer version, load a new pulse-x.y.z-image.tar.gz and run docker compose up -d (update the image tag in docker-compose.yml if needed).
restart vs force-recreate (the token gotcha)
Docker Compose injects environment variables when the container is created, not on every restart.
| You changed | Command | Why |
|---|---|---|
config.yml (teams, metrics, status names) | docker compose restart | File is mounted; the new process re-reads it |
.env (JIRA_TOKEN, etc.) | docker compose up -d --force-recreate | Recreates the container so new env vars apply |
Secret files (JIRA_TOKEN_FILE) | docker compose up -d --force-recreate | Same as env vars |
| Pulled a new image tag | docker compose up -d | Recreates if the image digest changed |
docker compose restart stops and starts the same container with the same environment it had at create time.
A common failure: you fix a Jira token in .env, run restart, and Pulse still sends the old value. up -d --force-recreate fixes it.
Where to put the token
| Approach | After token change |
|---|---|
config.yml (jira.token:) | docker compose restart |
.env (JIRA_TOKEN=) | docker compose up -d --force-recreate |
Compose loads .env via env_file when present. Use JIRA_TOKEN= in .env, or keep the token in config.yml.
Production images run a single stable process (no auto-reload).