How to Set Up Huginn with MariaDB on Docker

In this guide, we’ll walk through the process of setting up Huginn, a powerful open-source system for automating tasks and managing workflows, using Docker. We’ll use MariaDB as the backend database and go over how to configure it with simple environment variables.

Prerequisites

Before we start, you’ll need:

• Docker and Docker Compose installed on your server.
• A basic understanding of Docker Compose and containerized applications.
• A server or machine running a Linux or macOS-based operating system.

If you’re on macOS, you will need to install the uuid command line tool through Homebrew. You can do so with the following command:

brew install ossp-uuid

We’ll use the uuid command to generate unique passwords for MariaDB and Huginn.

Step 1: Create a Docker Compose File

We’ll begin by creating a docker-compose.yml file to define our Huginn and MariaDB services. This configuration will simplify the setup and enable us to easily start and manage the services.

Here’s the complete docker-compose.yml:

services:
  mariadb:
    image: mariadb:latest
    environment:
      MARIADB_ROOT_PASSWORD: ${MARIADB_ROOT_PASSWORD}
      MARIADB_USER: huginn
      MARIADB_PASSWORD: ${MARIADB_PASSWORD}
      MARIADB_DATABASE: huginn
    volumes:
      - mariadb_data:/var/lib/mysql
    networks:
      - huginn_network
    restart: always
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      start_period: 10s
      interval: 10s
      timeout: 5s
      retries: 3
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

  huginn:
    image: ghcr.io/huginn/huginn  # Updated to the new GitHub Container Registry
    ports:
      - "3000:3000"
    environment:
      HUGINN_DATABASE_NAME: ${MARIADB_DATABASE}
      HUGINN_DATABASE_USERNAME: ${MARIADB_USER}
      HUGINN_DATABASE_PASSWORD: ${MARIADB_PASSWORD}
      DATABASE_HOST: mariadb   # Add this line to specify the MariaDB container hostname
    depends_on:
      mariadb:
        condition: service_healthy
    networks:
      - huginn_network
    restart: always
    healthcheck:
test: ["CMD", "sh", "-c", "curl -s http://localhost:3000 | grep -q 'Your agents are standing by'"]
      interval: 30s
      retries: 3
      start_period: 30s
      timeout: 10s
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

networks:
  huginn_network:
    driver: bridge

volumes:
  mariadb_data:

Step 2: Set Environment Variables

In this docker-compose.yml file, we reference several environment variables:

• MARIADB_ROOT_PASSWORD: The root password for the MariaDB instance.
• MARIADB_USER: The database user for Huginn (we use huginn as the default).
• MARIADB_PASSWORD: The password for the MARIADB_USER.
• MARIADB_DATABASE: The name of the database for Huginn (also set to huginn).

To simplify this setup, we’ll use uuid to generate two unique passwords. Here’s how you can do it:

# Generate a unique root password
export MARIADB_ROOT_PASSWORD=$(uuid)

# Generate a unique password for the Huginn database user
export MARIADB_PASSWORD=$(uuid)

These commands will generate two unique password strings. The uuid command on macOS might require installation via Homebrew if you don’t have it already:

brew install uuid

Once you’ve generated the passwords, you can either:

1. Add them to an .env file in the same directory as your docker-compose.yml:

   MARIADB_ROOT_PASSWORD=your-root-password
   MARIADB_PASSWORD=your-generated-password
   

2. Or, directly set them through your Docker environment configuration in Portainer.

Step 3: Launch the Containers

Now that the environment variables are set, you can bring up the Huginn and MariaDB services with the following command:

docker-compose up -d

This will download the necessary Docker images (if they aren’t already cached) and start the containers in the background. You can check the status of the containers using:

docker-compose ps

Step 4: Access Huginn

Once the containers are up and running, you should be able to access the Huginn web interface at:

http://localhost:3000

Here, you can log in and start using Huginn to automate tasks and workflows.

Step 5: Set Up Reverse Proxy (Optional)

While this guide doesn’t go into detail about reverse proxy setups, it’s important to note that your Huginn instance should be publicly served behind a reverse proxy for security and ease of access.

We recommend using Traefik as a great option for managing reverse proxies, especially with Docker. Traefik automatically handles container routing, SSL certificates, and more. Configuring Traefik is beyond the scope of this guide, but you can find detailed instructions in the Traefik documentation.

Conclusion

Congratulations! You’ve now set up Huginn and MariaDB using Docker, with a simple and flexible configuration. This setup is perfect for tech enthusiasts who like to self-host web applications at home. With Huginn, you can automate workflows, integrate with external APIs, and much more.

By using healthcheck.sh, you ensure that MariaDB is properly initialized and healthy before Huginn starts, making the setup more resilient and reliable.

Important: Don’t forget to change the default Huginn username and password immediately after logging in.

Additionally, both the Huginn and MariaDB containers now log in JSON format, making it easier to parse and manage logs. The logs are rotated when they exceed 10 MB, with a maximum of 3 files kept.

Feel free to modify this setup to suit your needs, and remember to protect your instance by setting up a reverse proxy like Traefik for secure, production-ready deployment.

Happy self-hosting!