Skip to content
dockmesh

From SSH or Ansible to Dockmesh — Docker Fleet at Scale

Many self-hosters and small teams manage Docker via ssh host "docker compose pull && up" or an Ansible playbook. This works but doesn’t scale past a handful of hosts. This guide walks through adopting dockmesh without abandoning your existing workflow immediately.

Your current setup probably looks like

Section titled “Your current setup probably looks like”
  • A Git repo with docker-compose.yml files per service
  • Deploy via SSH loops or ansible-playbook deploy.yml
  • Secrets in .env files (possibly encrypted with SOPS or Ansible Vault)
  • Logs accessed via ssh + docker logs

dockmesh doesn’t fight any of this. It reads the same compose files and gives you a UI on top.

Step 1 — Install dockmesh on your “control” machine

Section titled “Step 1 — Install dockmesh on your “control” machine”

Whichever host you usually SSH from (or a dedicated VM), install dockmesh:

Terminal window
curl -fsSL https://get.dockmesh.dev | sudo bash

This becomes your new control plane. Your workstation, CI, or Ansible bastion keeps working — dockmesh doesn’t force you to stop using them.

Step 2 — Enroll each target host

Section titled “Step 2 — Enroll each target host”

For each host in your Ansible inventory:

  1. Agents → New agent in dockmesh UI
  2. Copy the agent install command
  3. Paste into the host over SSH (or run via Ansible — see below)

Via Ansible

Section titled “Via Ansible”
roles/dockmesh-agent/tasks/main.yml
- name: Install dockmesh agent
  shell: |
    curl -fsSL "https://dockmesh.example.com/install/agent.sh?token={{ dockmesh_enrollment_token }}" \
      | sudo bash
  args:
    creates: /usr/local/bin/dockmesh-agent

Generate enrollment tokens via the dockmesh CLI (or the equivalent REST endpoint) so you can script it. Easiest: run on the dockmesh server itself, one token per host you want to enrol:

Terminal window
ssh dockmesh-server "sudo dockmesh enroll create --name web-01"
# prints the token + the ready-to-paste install command

Pass each token to Ansible as a per-host var. After the agent comes online, set its tags from the dockmesh UI (Hosts → host detail → edit tags) — the create-time flow only takes a name today.

Step 3 — Keep using Git + Ansible if you want

Section titled “Step 3 — Keep using Git + Ansible if you want”

dockmesh’s stack tree is host-neutral on disk — one directory per stack, no host subdir. The host a stack is currently deployed on lives in the database:

/var/lib/dockmesh/stacks/
├── web/compose.yaml
├── api/compose.yaml
└── db/compose.yaml

Point your existing Ansible playbook at the central dockmesh server (not each agent — agents only ever pull compose content from the server during deploy):

- name: Sync compose files onto the dockmesh server
  hosts: dockmesh-server
  tasks:
    - synchronize:
        src: stacks/
        dest: /var/lib/dockmesh/stacks/

When files change, dockmesh detects the change (inotify) and marks the stack as “changes pending”. You then deploy via UI, or automate it:

- name: Trigger deploy
  uri:
    url: "https://dockmesh.example.com/api/v1/stacks/{{ item }}/deploy"
    method: POST
    headers:
      Authorization: "Bearer {{ dockmesh_token }}"
  loop:
    - web
    - api

Your Ansible flow changes from “run compose” to “sync files + call API”. Slightly more layers, but you get the UI + audit log + RBAC on top.

Step 4 — Alternative: pure UI mode

Section titled “Step 4 — Alternative: pure UI mode”

If you’re tired of Ansible for Docker management:

  1. Use dockmesh’s Git integration (Stacks → New stack → Git) — dockmesh pulls compose files directly from your Git repo
  2. Commits auto-trigger deploys (via webhook from GitHub/GitLab)
  3. Delete the Ansible Docker role — dockmesh handles it

You keep Ansible for OS-level config (firewall, system packages, users), drop it for application deployment.

Step 5 — Secrets

Section titled “Step 5 — Secrets”

If you use SOPS or Ansible Vault:

  • Keep using them — dockmesh doesn’t care how you produce the final .env file, as long as it’s on disk when deploy runs
  • Ansible’s decrypt-then-sync flow works identically with dockmesh’s stack directories

Or migrate to dockmesh’s encrypted env vars:

  • Environment → Import accepts .env files
  • Stored encrypted at rest in the dockmesh DB
  • No more Ansible Vault passphrase management in CI

Migration can be gradual — per-stack.

Step 6 — Logs and exec

Section titled “Step 6 — Logs and exec”

You’ve been doing ssh host "docker logs container". Now:

  • Containers → [container] → Logs in the UI — live streaming
  • Containers → [container] → Terminal — browser-based exec

Faster than SSH + docker exec, and you get logs retained and searchable.

Benefits over pure SSH/Ansible

Section titled “Benefits over pure SSH/Ansible”
  • Audit log — who deployed what, when, from where
  • RBAC — not everyone needs root SSH to deploy a compose change
  • SSO — log into the UI via company IdP
  • Alerts — get paged when something’s wrong, not when SSH reveals it
  • Backups — automated, not a cron + rsync hack
  • No SSH key management — the dockmesh API token flow is simpler

What you keep

Section titled “What you keep”
  • Your compose files — untouched, on disk, same Git workflow
  • Ansible for OS-level provisioning
  • ssh for break-glass / emergency debugging
  • Full control — dockmesh doesn’t lock anything behind UI-only flows

See also

Section titled “See also”