Skip to content
RunWisp

From docker-compose

RunWisp can run the services in an existing compose file. Each compose service becomes a RunWisp service with run history, logs, restarts, and notifications. The containers still run under Docker, and RunWisp never edits the compose file.

Point RunWisp at the compose file

Section titled “Point RunWisp at the compose file”

Run runwisp in the directory with your docker-compose.yml. It detects the file and offers to create a runwisp.toml that imports it:

[compose.myapp]
file = "./docker-compose.yml"

The alias (myapp) comes from the directory name. Open the Web UI at http://localhost:9477; each compose service is listed as a RunWisp service.

You can also write this block yourself and start the daemon with runwisp daemon. RunWisp calls the docker compose CLI, so Docker and the Compose plugin must be installed.

Stop the compose stack

Section titled “Stop the compose stack”

RunWisp starts its own containers with docker compose run. If the stack is also running from docker compose up, every service runs twice and published ports clash. Stop it first:

Terminal window
docker compose down

How the pieces map

Section titled “How the pieces map”
docker-compose RunWisp
a service a RunWisp service named myapp.<service> (name_format)
restart: ignored; RunWisp restarts on failure by default (restart)
stop_grace_period graceful_stop
profiles profiles
images, networks, volumes, ports used as they are
depends_on not started for you; import those services too, or set with_deps

Common changes

Section titled “Common changes”

Per-service settings go in a sub-table named after the compose service.

Restart after every exit, not only failures:

[compose.myapp.api]
restart = "always"

Get notified on failure (see Notifications):

[compose.myapp.api]
notify = ["slack-prod"]

Run four copies of a worker. Each gets RUNWISP_INSTANCE_INDEX (0 to 3):

[compose.myapp.worker]
instances = 4

Import only some services, or leave some out:

[compose.myapp]
services = ["api", "worker"]   # only these
# services = ["-db"]           # everything except db

Run a compose service on a schedule, in a fresh container each time:

[tasks.nightly-backup]
cron            = "0 3 * * *"
compose_file    = "./docker-compose.yml"
compose_service = "backup"

What needs a human

Section titled “What needs a human”
  • restart: policies. RunWisp ignores them. Set restart per service if the default (restart on failure) isn’t what you want.
  • Docker access. The user running RunWisp needs access to the Docker daemon. If RunWisp runs in a container, see Docker tasks.

Learn more

Section titled “Learn more”