Deploy Huginn with Dokploy

Dokploy is an open-source server management platform that simplifies deploying Docker Compose applications on your VPS. It handles reverse proxy configuration, SSL certificates, and deployment management — making it practical to run Huginn as a system of autonomous agents for web monitoring, data collection, and task automation.

This guide walks you through deploying Huginn with a MySQL database backend, persistent storage, and automatic HTTPS. Huginn agents can monitor websites, send notifications, process data, and chain together to form complex workflows.

Prerequisites

• A VPS with at least 1 vCPU, 2 GB RAM, and 10 GB storage
• Dokploy installed and running on your server (installation docs)
• A domain name (e.g., huginn.yourdomain.com) with DNS A record pointing to your server's IP

Docker Compose Configuration

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

version: "3.8"

services:
  huginn:
    image: ghcr.io/huginn/huginn:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - DOMAIN=${HUGINN_DOMAIN}
      - PORT=3000
      - DATABASE_ADAPTER=mysql2
      - DATABASE_HOST=huginn-db
      - DATABASE_PORT=3306
      - DATABASE_NAME=huginn
      - DATABASE_USERNAME=huginn
      - DATABASE_PASSWORD=${HUGINN_DB_PASSWORD}
      - HUGINN_SEED_USERNAME=${HUGINN_ADMIN_USER:-admin}
      - HUGINN_SEED_PASSWORD=${HUGINN_ADMIN_PASSWORD}
      - HUGINN_SEED_EMAIL=${HUGINN_ADMIN_EMAIL:-admin@yourdomain.com}
      - INVITATION_CODE=${HUGINN_INVITATION_CODE}
      - SMTP_DOMAIN=${HUGINN_DOMAIN}
      - SMTP_SERVER=${SMTP_SERVER:-localhost}
      - SMTP_PORT=${SMTP_PORT:-587}
      - SMTP_USER_NAME=${SMTP_LOGIN}
      - SMTP_PASSWORD=${SMTP_PASSWORD}
    depends_on:
      huginn-db:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:3000 || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 5

  huginn-db:
    image: mysql:8.0
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=${HUGINN_DB_ROOT_PASSWORD}
      - MYSQL_DATABASE=huginn
      - MYSQL_USER=huginn
      - MYSQL_PASSWORD=${HUGINN_DB_PASSWORD}
    volumes:
      - ../files/huginn-db-data:/var/lib/mysql
    healthcheck:
      test: ["CMD-SHELL", "mysqladmin ping -h localhost -u root -p${HUGINN_DB_ROOT_PASSWORD}"]
      interval: 10s
      timeout: 5s
      retries: 5

Note: Huginn seeds the database with a default admin account on first startup using the HUGINN_SEED_* variables. The INVITATION_CODE controls whether new users can sign up — leave it blank to disable registration. SMTP settings are optional but needed for email-based agents and notifications.

Environment Variables

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

Variable	Purpose	Example
HUGINN_DOMAIN	Your Huginn domain	huginn.yourdomain.com
HUGINN_DB_PASSWORD	MySQL database password for Huginn user	a-strong-random-password
HUGINN_DB_ROOT_PASSWORD	MySQL root password	another-strong-password
HUGINN_ADMIN_USER	Initial admin username	admin
HUGINN_ADMIN_PASSWORD	Initial admin password	a-strong-admin-password
HUGINN_ADMIN_EMAIL	Admin email address	admin@yourdomain.com
HUGINN_INVITATION_CODE	Code required for new user signups	my-secret-code
SMTP_SERVER	SMTP server for email agents (optional)	smtp.mailgun.org
SMTP_PORT	SMTP port (optional)	587
SMTP_LOGIN	SMTP username (optional)	huginn@yourdomain.com
SMTP_PASSWORD	SMTP password (optional)	your-smtp-password

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.

Volumes & Data Persistence

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

• ../files/huginn-db-data — MySQL database files containing agents, events, user data, and logs

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/huginn) because Dokploy may clean them during redeployment.

Huginn stores all data (agent configurations, collected events, user accounts) in MySQL, so the database volume is the critical persistence layer.

Domain & SSL Setup

1. In your Dokploy project, navigate to the Domains tab
2. Click Add Domain and enter your domain (e.g., huginn.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 Huginn container.

Verifying the Deployment

1. In Dokploy, go to your project's Deployments tab and click Deploy
2. Watch the build logs — you should see both huginn and huginn-db containers start
3. Check the Logs tab for the huginn service. Look for: database migration messages followed by Listening on http://0.0.0.0:3000
4. Open https://huginn.yourdomain.com in your browser — you should see the Huginn login page
5. Log in with your seed admin credentials
6. Create a test agent (e.g., a Website Agent that monitors a webpage for changes) to verify everything works

Troubleshooting

Huginn shows "502 Bad Gateway" on first startup Huginn takes 1–2 minutes to initialize the database and run migrations on first boot. Wait for the health check to pass. Watch the huginn service logs for migration progress and Listening on messages.

Agents not running or events not being processed Huginn runs agent checks on a schedule (default every few minutes). Check the Agents page for the "Last check" timestamp. Ensure the Huginn container is running continuously — agents only execute when the main process is active.

Email agents not sending notifications Configure the SMTP variables and ensure your VPS allows outbound connections on the SMTP port. Test SMTP settings by creating a simple Email Agent and triggering it manually from the Huginn UI.

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 Huginn in our complete overview.

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

---

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

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