Skip to content
dpl

Serve commands

dpl serve is the long-running process for one base directory.

Terminal window
DPL_BASE=/opt/dpl dpl serve

In production, run it with systemd.

What serve does

Section titled “What serve does”

dpl serve:

  • holds state/serve.pid as a PID file and lock
  • starts containers for deployed runtime units
  • restarts ready units with backoff if they exit
  • runs app timers when they are due
  • re-reads deploy state and starts newly deployed units when a deploy command sends it SIGHUP

Deploy commands do not act as supervisors. They update state and notify dpl serve.

Liveness comes from podman (podman ps plus a podman events watcher), not from child processes. dpl serve launches each container with a detached dpl start and tracks it by inspecting the container, so it can be restarted or upgraded independently of the containers it supervises.

Restarting serve does not stop apps

Section titled “Restarting serve does not stop apps”

Stopping or restarting dpl serve leaves the supervised containers running. A dpl serve restart (for example, to deploy a new dpl binary) is zero-downtime: on startup serve adopts the containers that are already running and resumes supervising them.

This is why the systemd unit uses KillMode=process - only the serve process is signalled on stop, never the containers in its cgroup.

To stop everything, use dpl down.

Tearing down: dpl down

Section titled “Tearing down: dpl down”
Terminal window
DPL_BASE=/opt/dpl dpl down

dpl down is the global teardown:

  • if dpl serve is running, it sends SIGTERM and waits briefly for serve to stop supervising (serve drops its PID file on exit), so a container is not respawned mid-teardown
  • it then stops and removes every supervised container

Deploy state is left intact (the supervised flag stays set), so restarting dpl serve - for example systemctl start dpl - brings the containers back. To remove a single unit instead of everything, use dpl undeploy <name>.

systemd example

Section titled “systemd example”
[Unit]
Description=dpl service
Wants=network-online.target
After=network-online.target


[Service]
Type=simple
Environment="DPL_BASE=/opt/dpl"
ExecStart=/usr/local/bin/dpl serve
ExecReload=/bin/kill -s HUP $MAINPID
KillMode=process
TimeoutStopSec=300
Restart=always
RestartSec=5


[Install]
WantedBy=multi-user.target

One daemon per base directory

Section titled “One daemon per base directory”

Run one dpl serve process for each DPL_BASE.

If another instance is already running for the same base directory, the PID lock stops the second daemon from starting.