Complete Guide to Installing Huginn: Self-Hosted Automation Platform

Introduction#

Huginn is a powerful open-source automation platform that works like IFTTT but gives you complete control over your data and workflows. By hosting it yourself using Docker, you can create custom automation agents for tasks like monitoring websites, sending notifications, and processing data without sharing your information with third-party services.

Prerequisites#

Software You Need#

• Docker Engine version 24.0 or newer
• Docker Compose version 2.20 or newer
• Linux Server (Ubuntu 22.04 LTS recommended)

Hardware Requirements#

• Minimum Setup: 2 CPU cores, 4GB RAM, 20GB storage
• Better Performance: 4 CPU cores, 8GB RAM, 50GB SSD storage

Network Settings#

• You'll need port 3000 open for Huginn's web interface
• A domain name pointing to your server (like huginn.yourdomain.com)

User Permissions#

• A non-root user with sudo privileges
• Your user added to the Docker group

Basic Installation (Stop Here for Minimal Setup)#

Step 1: Create Directory Structure#

mkdir -p ~/docker_data/huginn/{data,config,logs}
chmod -R 775 ~/docker_data/huginn

This creates folders to store Huginn's data permanently.

Step 2: Create Docker Compose File#

nano ~/docker_data/huginn/docker-compose.yml

Copy and paste this configuration:

version: '3'

services:
  huginn:
    image: huginn/huginn:latest
    container_name: huginn
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - HUGINN_DATABASE_NAME=huginn
      - HUGINN_DATABASE_USERNAME=huginn
      - HUGINN_DATABASE_PASSWORD=huginnpassword
      - INVITATION_CODE=welcome
    volumes:
      - ~/docker_data/huginn/data:/var/lib/mysql
      - ~/docker_data/huginn/config:/app/config
      - ~/docker_data/huginn/logs:/app/log

This sets up a basic Huginn container with MySQL database.

Step 3: Start Huginn#

cd ~/docker_data/huginn
docker compose up -d

This starts Huginn in the background. The first launch might take a few minutes.

Step 4: Check if Huginn is Running#

docker ps | grep huginn

You should see the huginn container running.

Step 5: Access Huginn#

Open your web browser and go to:

http://your-server-ip:3000

Sign in with these default credentials:

• Username: admin
• Password: password

Important: Change your password immediately by clicking on your username in the top right corner and selecting "Account".

Advanced Setup (Continue for Production Environment)#

Integrating with Traefik for Secure Access#

Step 1: Create a Network for Traefik#

docker network create proxy

This creates a shared network for Traefik and Huginn.

Step 2: Update Docker Compose with Traefik Labels#

Replace your docker-compose.yml with:

version: '3'

services:
  huginn:
    image: huginn/huginn:latest
    container_name: huginn
    restart: unless-stopped
    environment:
      - HUGINN_DATABASE_NAME=huginn
      - HUGINN_DATABASE_USERNAME=huginn
      - HUGINN_DATABASE_PASSWORD=huginnpassword
      - INVITATION_CODE=welcome
    volumes:
      - ~/docker_data/huginn/data:/var/lib/mysql
      - ~/docker_data/huginn/config:/app/config
      - ~/docker_data/huginn/logs:/app/log
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.huginn.rule=Host(`huginn.yourdomain.com`)"
      - "traefik.http.routers.huginn.entrypoints=websecure"
      - "traefik.http.routers.huginn.tls=true"
      - "traefik.http.services.huginn.loadbalancer.server.port=3000"

networks:
  proxy:
    external: true

Remember to change huginn.yourdomain.com to your actual domain.

Step 3: Restart Huginn with New Configuration#

cd ~/docker_data/huginn
docker compose down
docker compose up -d

This applies the new configuration with Traefik integration.

Security Hardening#

Update Default Credentials#

docker exec -it huginn rails runner "User.first.update(password: 'your-secure-password')"

This changes the default admin password. Replace 'your-secure-password' with a strong password.

Restrict Network Access#

sudo ufw allow proto tcp from 192.168.1.0/24 to any port 3000
sudo ufw deny 3000

This allows access only from your local network. Change 192.168.1.0/24 to match your network.

Data Management#

Setting Up Automatic Backups#

Step 1: Create a Backup Script#

nano ~/docker_data/huginn/backup.sh

Copy and paste:

#!/bin/bash
BACKUP_DIR=~/docker_data/huginn/backups
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
mkdir -p $BACKUP_DIR
docker exec huginn mysqldump -u root huginn > $BACKUP_DIR/huginn_$TIMESTAMP.sql
tar -czvf $BACKUP_DIR/huginn_config_$TIMESTAMP.tar.gz ~/docker_data/huginn/config
echo "Backup completed: $BACKUP_DIR/huginn_$TIMESTAMP.sql"

Step 2: Make the Script Executable#

chmod +x ~/docker_data/huginn/backup.sh

Step 3: Schedule Daily Backups#

(crontab -l ; echo "0 2 * * * ~/docker_data/huginn/backup.sh") | crontab -

This sets up a backup job to run every day at 2 AM.

Common Issues and Solutions#

Problem: Database Connection Errors#

If you see "Could not connect to database" errors:

docker restart huginn

Wait 30 seconds and try accessing Huginn again.

Problem: Permission Errors on Data Directory#

If Huginn can't write to data directories:

sudo chown -R 1001:1001 ~/docker_data/huginn

This fixes ownership issues with the data directories.

Problem: Email Not Sending#

To configure email for notifications:

nano ~/docker_data/huginn/docker-compose.yml

Add these environment variables:

environment:
  - SMTP_DOMAIN=yourdomain.com
  - [email protected]
  - SMTP_PASSWORD=your_email_password
  - SMTP_SERVER=smtp.yourdomain.com
  - SMTP_PORT=587
  - SMTP_AUTHENTICATION=plain
  - SMTP_ENABLE_STARTTLS_AUTO=true

Then restart Huginn:

docker compose down
docker compose up -d

Upgrading Huginn#

Step 1: Pull Latest Image#

cd ~/docker_data/huginn
docker compose pull

This downloads the latest Huginn version.

Step 2: Apply the Update#

docker compose down
docker compose up -d

This restarts Huginn with the new version.

Step 3: Run Database Migrations#

docker exec huginn bundle exec rake db:migrate

This updates the database structure if needed.

Monitoring Your Huginn Installation#

Check Container Logs#

docker logs -f huginn

Press Ctrl+C to exit the log view.

Check Container Health#

docker inspect --format="{{.State.Health.Status}}" huginn

This shows if the container is healthy.

Creating Your First Agent#

1. Log in to Huginn
2. Click "Agents" in the top menu
3. Click "New Agent" button
4. Select "Website Agent" from the dropdown
5. Fill in the required fields:
   • Name: "Website Monitor"
   • Schedule: "every_15m" (checks every 15 minutes)
   • URL: the website you want to monitor
   • Type: "html"
   • Extract: Add what data you want to extract
6. Click "Save" to create your agent

Conclusion#

You now have a working Huginn installation that you can use to create powerful automation workflows. Start with simple agents and gradually build more complex scenarios as you become familiar with the system.

For more advanced configurations and agent examples, visit the official Huginn documentation at https://github.com/huginn/huginn/wiki