Skip to content
dockmesh

Migrate from SSH / Ansible

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 | 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. Hosts → Add host 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://get.dockmesh.dev/agent | bash -s -- \
      --server https://dockmesh.example.com \
      --token {{ dockmesh_enrollment_token }}
  args:
    creates: /usr/local/bin/dockmesh-agent

Generate enrollment tokens via the dockmesh API (so you can script it):

Terminal window
curl -H "Authorization: Bearer $DOCKMESH_TOKEN" \
  -X POST https://dockmesh.example.com/api/v1/hosts/enroll-tokens \
  -d '{"host_name":"web-01","tags":["prod","web"]}' | jq -r .token

Pass each token to Ansible as a per-host var.

Step 3 — Keep using Git + Ansible if you want

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

dockmesh stack directories look like:

/opt/dockmesh/stacks/
├── prod-01/
│   ├── web/compose.yaml
│   └── api/compose.yaml
└── prod-02/
    └── db/compose.yaml

Point your existing Ansible playbook at these paths:

- name: Sync compose files
  synchronize:
    src: stacks/
    dest: /opt/dockmesh/stacks/{{ inventory_hostname }}/

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”