Operating an environment
The commands that inspect, troubleshoot and change a running environment, grouped by task.
Once an environment is deployed, these commands show what runs on the server, get you into a container, and change services between deploys. This page gives each command's purpose and a typical use. The CLI reference lists every option.
Choosing the environment
Most commands take [<env>] as their first argument:
- you can leave it out when
dockflow.ymlhas a single environment; - a unique prefix is enough (
prodforproduction).
The examples below always name it.
Every command reaches the server the way a deploy does: through the <ENV>_CONNECTION secret, the environment's server: block, or --connection.
See what runs
| Command | Purpose |
|---|---|
status | The current release, each service with its running and desired container counts, the degraded flag and any lock. Without <env>, every environment of dockflow.yml |
ps | The app's containers, with their service, release, state and health; -a adds stopped and one-off containers |
details | Every service of the current release in full: image, routes, ports, networks, mounts, limits, restart policy, and the names (never the values) of its environment variables |
releases | The release history, newest first, with the current one marked; -n limits the count, --stats adds the success rate and durations |
version | The version label the environment runs; without <env>, the CLI's own version |
list envs | The environments of dockflow.yml and the CI tags that select each |
list services | The services of an environment as Dockflow will deploy them, read from your project, without the server |
list images | The app's images on the server; -a lists every image of the server |
dockflow status
dockflow ps production -a
dockflow releases production -n 10 --stats
dockflow list images productionRead logs
logs prints the logs of the containers that serve the environment, for all services or one. When there are several containers, each line is prefixed with its container.
dockflow logs production web -f
dockflow logs production web --since 10m --timestamps
dockflow logs production worker -n all --all-nsets the lines per container: 100 by default, 20 with-f, orall.--alladds the previous release's containers and stopped containers.--picklets you choose one container.--no-prefixremoves the prefix.
Secret values are masked in the output.
With a single argument, logs reads it as the environment. To select a service, name the environment first: dockflow logs production web.
Get inside
| Command | Purpose |
|---|---|
exec | Runs a command in a running container of a service, or opens a shell (bash when the image has it, else sh). -u sets the user, -w the directory, -e a variable, -T disables the terminal for scripts, --pick chooses among several containers |
run | Starts a one-off container with the service's spec and deployed image, without ports or network aliases, and removes it when the command ends. For a console or a one-time script |
cp | Copies a file or directory between your machine and a container, in either direction; the container side is written service:/path |
ssh | Opens a shell on the server, or runs one command there, as the environment's SSH user |
dockflow exec production web
dockflow exec production web -T -- php artisan cache:clear
dockflow run production web -e LOG_LEVEL=debug -- ./manage.py shell
dockflow cp production web:/var/log/app/error.log ./error.log
dockflow cp production ./dump.sql db:/tmp/
dockflow ssh production -- df -hexec, run and ssh exit with the command's own exit code. Their output goes straight to your terminal and is not masked.
Troubleshoot
diagnose looks for the reasons containers don't run and prints one line per problem:
| Problem | What it checks |
|---|---|
oom killed | A container killed for lack of memory |
port in use | A container that could not bind a host port |
exited | A container that stopped, with its exit code |
crash loop | A container restarting, or restarted more than twice |
unhealthy | A failing health check, with the check's last output |
missing containers | A service running fewer containers than it should |
disk space | Less than 2 GiB free, or less than 5% of the disk and less than 10 GiB free, on the filesystem that holds Dockflow's state |
dockflow diagnose productionIt exits with code 0 when it finds nothing, and with code 9 when it finds at least one problem, so a script or a monitor can call it.
attach follows a run in progress, for example a deploy started from CI, or replays a finished one. Without a run ID, it picks the environment's latest run. The ID is in the --json events and in notifications.
dockflow attach production
dockflow attach production 01JBF3K9Q2M8XW4T6Y7Z1N5R0CChange services between deploys
These commands take the environment's lock and change the current release's services. Each records what it did as a new release, shown as (restart), (stop)… in dockflow releases. The next deploy brings the services back to what the Compose file says.
| Command | Purpose |
|---|---|
restart | Restarts services with their rollout strategy: routed services get new containers before the old ones stop, so they restart without downtime. Without a service, every long-running service |
stop | Stops services until the next deploy or restart. Without a service, every long-running service |
scale | Sets a service's replica count until the next deploy. At least 1 (stop stops a service); a stateful service or one with container_name runs once |
destroy | Removes the environment from the server: containers, routes, networks and its state. Volumes stay unless you add --volumes. --only removes some services, unless another service depends on them |
cancel | Asks the run in progress to stop and roll back, then follows it to the end |
dockflow restart production web
dockflow stop production worker
dockflow scale production web 4
dockflow destroy production --only mailer
dockflow cancel productionTo go back to an earlier release, use dockflow rollback, described in releases and rollbacks.
destroy --volumes
dockflow destroy production --volumes deletes the environment's volumes and the data in them. On a terminal it asks you to type the environment's name; without one it requires --yes. Volumes marked external are never deleted.
Lock an environment by hand
A manual lock holds an environment during a maintenance window. Until it is released, every command that takes the lock (deploy, rollback, restart, stop, scale, destroy) is refused with exit code 5. A manual lock never expires.
dockflow lock acquire production -m "database migration"
dockflow lock status production
dockflow lock release productiondockflow deploy --forcedeploys despite a manual lock.lock acquire --forcetakes over someone else's manual lock.statusshows who holds the lock, since when, and why.
Put an environment under maintenance
dockflow maintenance on takes an environment's site offline for visitors without stopping it: every route answers with a maintenance page and the 503 status, which tells search engines the outage is temporary. Use it to fix an incident, run a migration by hand, or close the site for any other reason.
dockflow maintenance on production
dockflow maintenance on production --page maintenance.html --allow 203.0.113.7
dockflow maintenance off production- The services keep running:
exec,logsandrunwork as usual. --allowlets your own address through, to check the app before opening it again.- A deploy during the maintenance keeps the page up; only
offtakes it down. dockflow statusshows the maintenance mode.
The manual lock and the maintenance mode are independent: the lock refuses deploys, the maintenance mode turns visitors away. Use both to freeze an environment entirely.