How to deploy Huginn on your own server using Docker

Huginn is like IFTTT or Zapier, but free, open source and running on a server you control! It’s a system for building agents that perform automated tasks for you online. Some examples of what you can do:

• Track the weather and get an email when it’s going to rain (or snow) tomorrow (“Don’t forget your umbrella!”).
• Watch for air travel or shopping deals.
• Scrape websites and receive emails when they change.
• Connect to HipChat, Basecamp, Growl, IMAP, JIRA, MQTT, Pushbullet, Pushover, RSS, Slack, StubHub, Twilio, Twitter, to name a few.

In about 5 minutes you’ll have a Huginn website running with Docker, Let’s Encrypt SSL certificates (via Traefik), phpMyAdmin and automatic updates.

If you’ve got your own server already — whether at Bytemark or not — skip the Create a Cloud Server section and run our setup script on your server instead. Make sure you have Docker CE and Docker Compose installed.

If you’re a developer or sysadmin and just looking for the nitty gritty, skip down to the Technical details section.

Create a Cloud Server

1. Login to the Bytemark Panel (or start a free trial).
2. Add a Cloud Server with these settings:
   • Name: Give your server a name (eg, “huginn”)
   • Group: Leave as “default”
   • Resources: 1 Core, 1GiB Memory
     
   • Operating System: Debian 9
   • Discs: 25GiB SSD storage (but increase if you have a lot of data)
   • Backup Schedule: Leave enabled (recommended)
   • Boot options: Select Add script and paste this inside:

? Copy to clipboard

#!/bin/sh
export DEBIAN_FRONTEND=noninteractive
  
# Wait for apt-get to be available.
while ! apt-get -qq check; do sleep 1s; done

# Install docker-ce and docker-compose.
apt-get update
apt-get install -y apt-transport-https ca-certificates curl gnupg2 software-properties-common
curl -fsSL https://download.docker.com/linux/debian/gpg | apt-key add -
add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian `lsb_release -cs` stable"
apt-get update
apt-get install -y docker-ce
curl -fsSL https://github.com/docker/compose/releases/download/1.21.2/docker-compose-`uname -s`-`uname -m` -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose

# Check for security updates every night and install them.
apt-get install -y unattended-upgrades
  
# Retrieve configuration files. Lots of explanatory comments inside!
# If you'd rather inspect and install these files yourself, see:
# https://github.com/BytemarkHosting/configs-huginn-docker
mkdir -p /root/compose
curl -fsSL https://raw.githubusercontent.com/BytemarkHosting/configs-huginn-docker/master/docker-compose.yml -o /root/compose/docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/BytemarkHosting/configs-huginn-docker/master/.env -o /root/compose/.env
curl -fsSL https://raw.githubusercontent.com/BytemarkHosting/configs-huginn-docker/master/traefik.toml -o /root/compose/traefik.toml
curl -fsSL https://raw.githubusercontent.com/BytemarkHosting/configs-huginn-docker/master/php.ini -o /root/compose/php.ini
 
# Traefik needs a file to store SSL/TLS keys and certificates.
touch /root/compose/acme.json
chmod 0600 /root/compose/acme.json
  
# Use the hostname of the server as the main domain.
sed -i -e "s|^TRAEFIK_DOMAINS=.*|TRAEFIK_DOMAINS=`hostname -f`|" /root/compose/.env
sed -i -e "s|^HUGINN_DOMAINS=.*|HUGINN_DOMAINS=`hostname -f`|" /root/compose/.env
sed -i -e "s|^HUGINN_EMAIL=.*|HUGINN_EMAIL=huginn@`hostname -f`|" /root/compose/.env
 
# Fill /root/compose/.env with some randomly generated passwords.
sed -i -e "s|^HUGINN_DB_ROOT_PASSWORD=.*|HUGINN_DB_ROOT_PASSWORD=`cat /dev/urandom | tr -dc '[:alnum:]' | head -c14`|" /root/compose/.env
sed -i -e "s|^HUGINN_DB_PASSWORD=.*|HUGINN_DB_PASSWORD=`cat /dev/urandom | tr -dc '[:alnum:]' | head -c14`|" /root/compose/.env
sed -i -e "s|^HUGINN_ADMIN_PASSWORD=.*|HUGINN_ADMIN_PASSWORD=`cat /dev/urandom | tr -dc '[:alnum:]' | head -c14`|" /root/compose/.env
sed -i -e "s|^HUGINN_INVITATION_CODE=.*|HUGINN_INVITATION_CODE=`cat /dev/urandom | tr -dc '[:alnum:]' | head -c14`|" /root/compose/.env
apt-get install -y apache2-utils
BASIC_AUTH_PASSWORD="`cat /dev/urandom | tr -dc '[:alnum:]' | head -c10`"
BASIC_AUTH="`printf '%s\n' "$BASIC_AUTH_PASSWORD" | tee /root/compose/auth-password.txt | htpasswd -in admin`"
sed -i -e "s|^BASIC_AUTH=.*|BASIC_AUTH=$BASIC_AUTH|" /root/compose/.env
  
# Start our containers.
cd /root/compose
docker-compose up -d

3. Have a cup of tea! Your Huginn server will be ready in about 5 minutes.
4. The Panel will tell you the root password for your server. Save it!
5. Click on the Console button next to your Cloud Server. You’ll know installation has finished when you see a login prompt. You can login with username root.

After installation

Login to your Cloud Server and view the contents of /root/compose/.env:

cat /root/compose/.env

There’s a variable called HUGINN_INVITATION_CODE. Note down the code.

In your browser, navigate to the hostname of your server (eg, http://name.of.server.uk0.bigv.io). If you see a Bad Gateway message, wait a few seconds for the database to initialize and then refresh your page.

Click Signup. You’ll be asked for the code from earlier, an email address, username and password. And now you’re pretty much done!

Refer to the Huginn documentation to configure Huginn with some agents to do your bidding. Read on to Use your own domain, Enable SSL/TLS or Access phpMyAdmin.

Use your own domain

Login to your Cloud Server and open /root/compose/.env in a text editor:

nano /root/compose/.env

Change HUGINN_DOMAINS to your own domain. For example:

HUGINN_DOMAINS=my-brilliant-site.com,www.my-brilliant-site.com

Restart your Docker containers to apply the change:

cd /root/compose
docker-compose down
docker-compose up -d

Enable SSL/TLS

Configure your own domain as per the previous step. All domains you list in HUGINN_DOMAINS must point to your server (via DNS records) for this to work.

Once you’ve done that, Traefik will generate Let’s Encrypt SSL certificates for you automatically! Browse to https://your_domain.com to see if it worked.

If you want to redirect all HTTP traffic to HTTPS (as is recommended these days), open /root/compose/traefik.toml in a text editor and uncomment two lines so that it looks like this:

[entryPoints]
  [entryPoints.http]
  address = ":80"
  # Uncomment the following two lines to redirect HTTP to HTTPS.
    [entryPoints.http.redirect]
    entryPoint = "https"

Open /root/compose/docker-compose.yml in a text editor. Under the huginn: section, uncomment the bottom line so that it looks like this:

      # Uncomment the next line to enable HSTS header.
      - "traefik.frontend.headers.STSSeconds=15768000"

Restart your Docker containers to apply the change:

cd /root/compose
docker-compose down
docker-compose up -d

Access phpMyAdmin

The setup script generated a password and saved it inside /root/auth-password.txt on your server. Look inside to see what the browser authentication password is for the admin user:

cat /root/compose/auth-password.txt

Go to http://name.of.server.uk0.bigv.io/phpmyadmin/ in your browser. The last forward slash is important! Login with username admin and the password above.

You should see the phpMyAdmin login screen. You can find the password for the MySQL root user inside your Docker environment file:

cat /root/compose/.env

Email delivery

The mail container should be sufficient for most people.

If you’re have any trouble with email delivery, you might look into using an email delivery service like SendGrid or MailChimp:

• Refer to your chosen email delivery service to learn what DNS records to set for your domain, and what SMTP settings to use.
• Refer to the bytemark/smtp image documentation for instructions on how to set environment variables with your SMTP settings, username and password.
• Modify your /root/compose/docker-compose.yml file to tell the mail container to use your chosen email delivery service, using the information you’ve learnt above.

Technical details

Inside /root/compose you’ll find all the configuration files, which are taken from our Git repository. Feel free to browse around or adapt those configuration files to your needs.

• Traefik acts as a reverse proxy, listening on ports 80 and 443 and passing web traffic to the appropriate container based on rules you decide (eg, based on the URL). If domains are properly configured, it automatically retrieves Let’s Encrypt SSL certificates for you.
• Watchtower automatically updates your containers to the latest images, such as your Huginn version. This keeps your website secure.
• phpMyAdmin gives you access to view, modify and retrieve your database.
• Our configuration installs a custom php.ini file, as some of PHP’s default settings are too restrictive and tend to cause headaches.
• Our bytemark/smtp image allows your Huginn server to send outgoing emails for notifications and similar.