Deploy Docker Compose apps to your own Linux VPS with one command, from your laptop or CI. tug adds image delivery, rollbacks, scheduled backups, HTTPS and encrypted secrets, so one small server can run a whole stack and a few servers can run a larger one.
npm install -g @wpelevator/tug # or run it with npx @wpelevator/tug
tug lint # check compose.yaml offline, no server neededcompose.yaml: ok
Then install control and an agent on your VPS, and deploy:
tug setup root@203.0.113.5
tug node add root@203.0.113.5 --name app1
tug deployYou need Node.js 22.18 or newer on your computer and root SSH access to a Linux server. tug can install Docker on Debian, Ubuntu, Fedora and RHEL-compatible servers. Deploy your first service walks through each step.
tug is for people who run Compose apps (Node.js, Laravel, Ruby, WordPress and the like) on one or a few VPSes and want deploys, rollbacks, backups and HTTPS in one tool, with one control server that they back up. Your Compose file stays a Compose file: x-tug is a standard Compose extension that plain Docker Compose ignores. tug is open source under the MIT license.
Managed ingress balances HTTP requests across serving replicas with round robin. Cross-node service names do not balance traffic, and tug does not automatically reschedule services or replace a failed server. Node-to-node traffic uses your own private network (Tailscale, a VPC, a LAN), so you own its firewalling and encryption.
- You need Kubernetes-style scheduling, autoscaling, distributed storage, database failover, automatic rescheduling across a cluster or servers provisioned through a provider's API. See the Docker Swarm comparison.
- Your workloads are not Compose and Docker, or you need to roll back the host itself.
tug rollbackreverts deployments, not host packages or kernel settings. - You run several servers with no private network between them. Management traffic works where inbound connections don't, but node-to-node service traffic needs a VPC, LAN or VPN.
- You need to hide secrets from people who can deploy. A
deploycredential can read secret values withexecor through deployed code.inspectredacts environment values, but not a secret you put incommandorlabels.
| Need | What tug does | Details |
|---|---|---|
| Get images to servers | Builds your images on control (or on your machine with tug deploy --build-local) and sends them over connections the agents already make. Or push to any HTTPS registry and declare image:, and control pins the tag to a digest before deploying. A failed build leaves the nodes untouched. |
Control plane |
| Serve HTTPS | Managed Caddy serves a hostname with tls: auto, gets the certificate and renews it. DNS must point at the server and ports 80 and 443 must be reachable. |
Ingress |
| Back up and restore | Scheduled restic backups of volumes and databases to S3-compatible storage. tug restore run db brings one back. Control backs itself up every night. |
Backups |
| Keep secrets out of git | tug secret set keeps them encrypted on control and delivers each only to the nodes whose services use it. Every ${NAME} in your Compose file comes from control, never from the shell or .env of whoever runs the deploy. |
Where values come from |
| Roll back | tug rollback returns to a previous deployment, and a top-level x-tug: { rollback: auto } does it when a node reports the new version unhealthy. It cannot undo database writes or schema changes. |
Health checks |
| Update without a restart | x-tug: { rollout: { strategy: rolling } } starts the new revision beside the old one and switches ingress once it is healthy. It needs ingress, a tug health check and one published port. The default recreate restarts the container and can interrupt traffic. |
Rolling rollouts |
| Give CI one scoped credential | One credential limited by role (read, deploy or admin), and for deploy by project. |
Access control |
| Read logs and open shells | tug logs, tug exec, tug run (for example the wp CLI), tug ps and tug status go through the control plane. SSH is only for installing and managing nodes. |
CLI |
| Catch config errors early | tug lint checks your x-tug config offline, and the same schema ships as JSON Schema for editor autocomplete. |
Compose extensions |
| Know what runs | Published images are pinned to a digest, built images get an immutable tag, and every deployment records who made it. | Access control |
| Add a server | tug node add bootstraps a fresh node. Agents only dial out to control, so a node can sit behind a firewall that allows nothing inbound. |
Nodes |
This WordPress example pins the app, the database and the database volume to app1. Placement can be omitted with one node, but explicit placement keeps the database on its chosen server when you add more nodes. Enable ingress with tug node ingress app1, point the hostname's DNS at the VPS, allow public ports 80 and 443, and replace the hostname with yours.
# yaml-language-server: $schema=https://unpkg.com/@wpelevator/tug/x-tug.schema.json
services:
db:
image: mariadb:11.4.8
volumes:
- db-data:/var/lib/mysql
environment:
MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
x-tug:
placement:
nodes:
- app1
health:
type: tcp
port: 3306
wordpress:
image: wordpress:6.8.3-apache
depends_on:
- db
environment:
WORDPRESS_DB_HOST: db
WORDPRESS_DB_USER: root
WORDPRESS_DB_PASSWORD: ${DB_ROOT_PASSWORD}
ports:
- "8080:80"
x-tug:
placement:
nodes:
- app1
health:
type: http
port: 80
path: /wp-includes/version.php
ingress:
host: blog.example.com
port: 80
tls: auto
volumes:
db-data:
x-tug:
placement:
nodes:
- app1tug secret set DB_ROOT_PASSWORD
tug deploy
tug status
tug logs wordpress --followtug status shows what runs where and anything failing. The named volume holds data on app1 and is not copied to another node, so back it up and restore or move its data deliberately if you replace the server. The examples have complete apps, with scheduled backups, for several stacks, and every x-tug key is in Compose extensions.
| I want to | Run |
|---|---|
| Deploy, or undo a deploy | tug deploy, tug rollback |
| See what is running and what failed | tug status, tug events, tug ps |
| Read logs or open a shell | tug logs <service>, tug exec <service> sh |
| Run a one-off command | tug run <service> -- wp cache flush |
| Add or replace a server | tug node add, tug node replace <name> |
| Upgrade control and nodes | tug upgrade |
| Manage secrets and variables | tug secret set, tug secret import .env, tug var set, tug deploy --dry-run |
| Back up now, or restore | tug backup run, tug restore run <target> |
| Give CI a deploy key | tug credential create ci --role deploy |
| Check that everything is healthy | tug doctor |
Project commands sit at the top level and the rest read tug <subject> <verb>. Every command and flag is in the CLI reference.
tug CLI / CI
|
| mTLS: deploy, status, logs, exec
v
+--------------------------------+ +--------------------------------+
| VPS app1 | | VPS app2 (optional) |
| | | |
| Control plane | | |
| API, SQLite, image builds | | |
| | | |
| Agent --> Docker Engine | | Agent --> Docker Engine |
| | | | | |
| +-- service A | | +-- service C |
| +-- database | | +-- service D |
| +-- more... | | +-- more... |
| (zero or more services) | | (zero or more services) |
| | | |
| Local volumes, optional Caddy | | Local volumes, optional Caddy |
+--------------------------------+ +--------------------------------+
| |
+------- private workload network --------+
Each agent connects to the control plane over mTLS. Services are
placed on either node; local volumes stay on their node. app1 can
run alone. SSH installs control and agents; normal operations use
the control API.
tug deploy reads your Compose file on your machine and sends it to the control plane. Control stores it as an immutable desired state, builds application images when needed and pins published images to digests. Each agent fetches the work for its node, applies it through the Docker Engine API, runs the health checks and reports back. Control marks the deployment done when every node reports it serving. tug reads Compose files with its own reader, so nodes need only Docker Engine and Docker Compose is not needed anywhere.
Control serves mutual TLS on one port (8443). Every operator, CI job and node authenticates with a certificate from a private CA created at install, so the control address can be a bare IP and can change later. Do not terminate TLS in front of it. Architecture covers every flow, and the security audit covers the trust boundaries.
Control readiness monitoring uses an authenticated GET /api/v1/readyz with a read credential; it checks database reads, overdue writer work and whether control needs a restart after restore. Project-filtered Prometheus metrics are at /api/v1/metrics; optional signed webhooks report actionable state changes. See Observability for setup and limits.
The documentation index lists every page by task. The ones you will reach for first:
- Start: Deploy your first service, then the examples
- Run it for real: Production checklist, Backups, Upgrades, Troubleshooting
- Look it up: CLI, Compose extensions, Configuration, Access control
- Contribute: Development, Testing, Releases, and the design records
npm install
npm test
npm run lintDevelopment covers the integration tests, the Docker image and the test VPS setup.
tug is released under the MIT License.