🐳 Deploy Bumper¶
Manage Bumper with Docker: pull the official image, deploy with Compose or Swarm, build custom images, or run directly.
🔧 Prerequisites¶
TLS certificates
The checked-in docker-compose.yaml and docker-compose-traefik.yaml load
ca.crt, bumper.crt, and bumper.key from $PWD/certs/* as read-only Docker
configs, so the files must exist before you deploy. Create them, then install
certs/ca.crt on the clients:
Key types, SANs, and certificate generation are covered in Certificates.
Environment variables:
Create a .env file with at least the following:
# 'overlay' for Docker Swarm, 'bridge' for plain Docker Compose
NETWORK_MODE=overlay
# required by the Compose file
BUMPER_ANNOUNCE_IP=192.168.0.100 # your server's local IP
Full environment variable reference: Environment Variables
✨ Pull the Official Image¶
See the package on GitHub Container Registry here.
👤 Container User¶
Bumper runs as the unprivileged user bumper (uid/gid 1000). In the
checked-in Compose files, /bumper/data is the writable state volume and
/bumper/certs is provided via read-only Docker configs.
A named volume takes ownership from the image and needs no manual step. The
container starts as root, repairs ownership of writable mounted paths when it
can (capabilities granted by the checked-in Compose files), and then drops to
bumper. If you use a custom writable host directory, ensure it is readable or
writable as needed by uid/gid 1000.
🚀 Docker Swarm Deployment¶
Step 1 - Clone the repository
Step 2 - Initiate Docker in Swarm mode
Step 3 - Start services
Alias
This uses the docker-swarm-compose alias,
which is maintained in the dotfiles repository. Pass the compose file with -f;
setting COMPOSE_FILE is not enough. The final argument is the stack name.
# pulls ghcr.io/mvladislav/bumper, tag from VERSION_BUMPER (default "latest")
docker-swarm-compose deebot
# with a non-default compose file (for example the Traefik variant)
docker-swarm-compose -f docker-compose-traefik.yaml deebot
# or plain Docker Compose: builds the image from this checkout
docker compose up -d
Step 4 - Access the UI
Visit https://ecovacs.net/ in your browser.
🗂️ Extra data files (voices, CodePush)¶
Voice files and CodePush packages are large and are not part of the image or
repository, so they live in the data volume: /bumper/data/voices and
/bumper/data/codepush inside the container (BUMPER_VOICES and
BUMPER_CODEPUSH override the paths). Features explains
what needs them.
The files either live in that volume already or are copied into it:
docker cp ./data/voices/. <container>:/bumper/data/voices/
docker cp ./data/codepush/. <container>:/bumper/data/codepush/
With Swarm the named volume is local to a node, so the files have to exist on the node that runs the task (or be copied into the volume there).
The files are downloaded by the maintainer scripts; see Static Data Update.
🛠 Build a Custom Image¶
Step 1 - Clone the repository (if not already done)
Step 2 - Build
Requires Docker ≥17.09 or Podman.
🎯 Direct Docker Run¶
Step 1 - Create a Docker volume
(Or use a host directory: -v /path/to/data:/bumper/data.)
Step 2 - Run the container
docker run -it \
--mount source=bumper_data,target=/bumper/data \
-v $PWD/certs:/bumper/certs \
-p 443:443 -p 8007:8007 -p 1883:1883 -p 8883:8883 -p 5223:5223 \
--name bumper \
ghcr.io/mvladislav/bumper:latest
- Volumes:
bumper_dataholds Bumper state. Mount a writable host directory at/bumper/certsif you want generated certificates to persist across container recreation; you can also pre-create certificates withscripts/certs/create-cert.sh. Without a persistent writable certs mount, a new container may generate a new CA and clients that trusted the old CA will fail. - Ports: 443 (HTTPS), 8007 (HTTP), 1883 (plain MQTT), 8883 (MQTT over TLS), 5223 (XMPP over TLS)
For advanced Docker parameters (resource limits, secrets, configs), see the Environment Variables.