Deploy Ansible with Dokploy

Dokploy is an open-source server management platform that simplifies deploying Docker Compose applications on your VPS. While Ansible is a CLI-based automation tool rather than a web service, running it in a Docker container via Dokploy provides a persistent, reproducible environment for executing playbooks and managing infrastructure.

This guide walks you through deploying an Ansible control node container with persistent playbook storage, SSH key management, and Ansible Semaphore as a web UI for managing and scheduling automation tasks.

Prerequisites

• A VPS with at least 1 vCPU, 1 GB RAM, and 5 GB storage
• Dokploy installed and running on your server (installation docs)
• A domain name (e.g., ansible.yourdomain.com) with DNS A record pointing to your server's IP (for the Semaphore web UI)
• SSH keys for connecting to target hosts

Docker Compose Configuration

Create a new Compose project in Dokploy and paste the following configuration:

version: "3.8"

services:
  semaphore:
    image: semaphoreui/semaphore:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - SEMAPHORE_DB_DIALECT=bolt
      - SEMAPHORE_ADMIN=${SEMAPHORE_ADMIN_USER}
      - SEMAPHORE_ADMIN_PASSWORD=${SEMAPHORE_ADMIN_PASSWORD}
      - SEMAPHORE_ADMIN_NAME=Admin
      - SEMAPHORE_ADMIN_EMAIL=${SEMAPHORE_ADMIN_EMAIL}
      - SEMAPHORE_ACCESS_KEY_ENCRYPTION=${SEMAPHORE_ENCRYPTION_KEY}
    volumes:
      - ../files/ansible-semaphore:/etc/semaphore
      - ../files/ansible-playbooks:/home/semaphore/playbooks
      - ../files/ansible-ssh:/home/semaphore/.ssh
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://localhost:3000/api/ping || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3

Note: Ansible Semaphore provides a web-based UI for managing Ansible playbooks, inventories, and SSH keys. It includes a built-in Ansible runtime, so you don't need a separate Ansible container. Semaphore uses BoltDB by default for simplicity — for production with multiple users, switch to PostgreSQL or MySQL by adjusting the SEMAPHORE_DB_DIALECT and adding a database service.

Environment Variables

Set these in Dokploy's Environment tab for your compose project:

Variable	Purpose	Example
SEMAPHORE_ADMIN_USER	Admin username for Semaphore UI	admin
SEMAPHORE_ADMIN_PASSWORD	Admin password for Semaphore UI	a-strong-random-password
SEMAPHORE_ADMIN_EMAIL	Admin email address	admin@yourdomain.com
SEMAPHORE_ENCRYPTION_KEY	Encryption key for stored credentials (32+ chars)	a-long-random-encryption-key

In Dokploy, environment variables are set via the Environment editor in the project settings. Do not create a .env file manually — Dokploy manages this for you. The encryption key protects SSH keys and passwords stored in Semaphore — keep it safe and consistent across redeployments.

Volumes & Data Persistence

This setup uses Dokploy's ../files convention for bind-mounted volumes:

• ../files/ansible-semaphore — Semaphore configuration and BoltDB database
• ../files/ansible-playbooks — Your Ansible playbooks, roles, and inventories
• ../files/ansible-ssh — SSH keys for connecting to managed hosts

The ../files path is relative to the compose file inside Dokploy's project directory. This ensures your data persists across redeployments. Avoid using absolute paths (e.g., /opt/ansible) because Dokploy may clean them during redeployment.

If you need S3 backup support, consider using named Docker volumes instead. Named volumes can be backed up with Dokploy's built-in backup features.

Domain & SSL Setup

1. In your Dokploy project, navigate to the Domains tab
2. Click Add Domain and enter your domain (e.g., ansible.yourdomain.com)
3. Set the container port to 3000
4. Enable HTTPS — Dokploy automatically provisions a Let's Encrypt SSL certificate
5. Save and wait for the certificate to be issued (usually under a minute)

Dokploy's built-in Traefik reverse proxy handles TLS termination and routes traffic to the Semaphore container.

Verifying the Deployment

1. In Dokploy, go to your project's Deployments tab and click Deploy
2. Watch the build logs — the Semaphore container should start and initialize
3. Check the Logs tab for the semaphore service. Look for: Listening on 0.0.0.0:3000
4. Open https://ansible.yourdomain.com in your browser — you should see the Semaphore login page
5. Log in with your admin credentials, then add a project, key store entry (SSH key), inventory, and repository to run your first playbook

Troubleshooting

Semaphore UI shows "500 Internal Server Error" This usually indicates a database initialization issue. Check the Semaphore logs for specific errors. Ensure the ../files/ansible-semaphore volume is writable. Delete the BoltDB file and restart to reinitialize if the database is corrupted.

SSH connections to target hosts fail Verify that your SSH private key is correctly added via the Semaphore Key Store UI. The key must be in OpenSSH format. Ensure target hosts have the corresponding public key in their authorized_keys file. Test connectivity by adding a simple ping playbook first.

Playbooks not found after redeployment Ensure playbooks are stored in the ../files/ansible-playbooks volume. In Semaphore, configure your repository to point to the local path /home/semaphore/playbooks or use a Git repository URL for version-controlled playbooks.

SSL certificate not issuing Ensure your domain's DNS A record points to your server's IP and has propagated. Dokploy uses Let's Encrypt HTTP-01 challenges, so port 80 must be accessible. Check Traefik logs in Dokploy for certificate-related errors.

---

Learn more about Ansible in our complete overview.

Need a VPS? Hostinger VPS starts at $4.99/mo — perfect for running Ansible.

---

For more on Docker Compose deployments in Dokploy, see the Dokploy Docker Compose documentation.

App data sourced from selfh.st open-source directory.