Huginn is a self-hosted automation tool that empowers users to create agents for tasks like web scraping, notifications, and data monitoring, all via customizable workflows. Designed to give full control over data and functionality, Huginn is an excellent choice for developers and tech-savvy users seeking a highly flexible, privacy-focused alternative to third-party automation services. In this guide, we’ll walk through installing Huginn, setting up a reverse proxy, managing logs, creating backups, updating the app, and leveraging its unique features.
Installing Huginn
📦 Docker/Docker Compose Setup
Docker provides a simple way to deploy Huginn. Below is a docker-compose.yml file for Huginn, complete with port mappings, persistent volumes, and environment variables.
version: "3.8"
services:
huginn:
image: huginn/huginn
container_name: huginn
ports:
- "3000:3000"
environment:
- APP_SECRET_TOKEN=your_secret_token
- DB_NAME=huginn_production
- DB_USER=huginn
- DB_PASSWORD=your_db_password
- DB_HOST=mysql
volumes:
- huginn_data:/var/lib/huginn
depends_on:
- mysql
mysql:
image: mysql:5.7
container_name: huginn_mysql
environment:
- MYSQL_ROOT_PASSWORD=your_root_password
- MYSQL_DATABASE=huginn_production
- MYSQL_USER=huginn
- MYSQL_PASSWORD=your_db_password
volumes:
- mysql_data:/var/lib/mysql
volumes:
huginn_data:
mysql_data:
To deploy Huginn, run the following commands:
docker-compose up -d
docker-compose ps
This will spin up Huginn and its MySQL database. You can access Huginn at http://<server-ip>:3000.
🚀 Manual Installation
For users who prefer manual installation on a Linux server, here are the steps:
sudo apt update && sudo apt upgrade -y
sudo apt install -y git nodejs npm ruby mysql-server libmysqlclient-dev libssl-dev zlib1g-dev
## Clone the Huginn repository
git clone https://github.com/huginn/huginn.git
cd huginn
## Install Ruby dependencies via Bundler
gem install bundler
bundle install --deployment --without development test
## Configure the database
cp .env.example .env
nano .env # Configure database and application secrets
## Set up the database
bundle exec rake db:create
bundle exec rake db:migrate
## Start the Huginn server
bundle exec foreman start
Huginn will now be accessible on http://<server-ip>:3000.
Configuring Nginx as a Reverse Proxy
🌐 Nginx Configuration
Set up Nginx to route traffic to Huginn:
sudo nano /etc/nginx/sites-available/huginn
Add the following server block:
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
Enable the configuration and restart Nginx:
sudo ln -s /etc/nginx/sites-available/huginn /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
🔒 SSL/TLS Setup
Secure your Huginn instance with Let’s Encrypt:
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com
sudo systemctl reload nginx
Logging and Debugging Huginn
🗃️ Enabling Debug Logs
Enable detailed logging in Huginn to assist with debugging:
nano .env
Set the log level to debug:
RAILS_LOG_LEVEL=debug
Save and restart Huginn:
docker-compose restart # For Docker users
bundle exec foreman start # For manual installations
📄 Viewing Logs
Access Huginn logs:
-
Docker:
docker logs -f huginn -
Manual:
tail -f log/production.log
🛠️ Troubleshooting Common Issues
Look for common errors such as database connection issues (ActiveRecord::ConnectionNotEstablished) or missing environment variables. Correct configurations in .env and restart the app.
Backup and Restore
🗂️ File-Based Backups
Back up Huginn configuration files and workflows:
tar -cvzf huginn_backup.tar.gz /path/to/huginn
🔄 Database Backups
Export the database:
mysqldump -u huginn -p huginn_production > huginn_db_backup.sql
Restore the database:
mysql -u huginn -p huginn_production < huginn_db_backup.sql
📅 Automated Backup Scripts
Create a backup script and schedule it using cron:
#!/bin/bash
tar -cvzf /backup/huginn_$(date +%F).tar.gz /path/to/huginn
mysqldump -u huginn -p'your_db_password' huginn_production > /backup/huginn_db_$(date +%F).sql
Add the script to cron:
crontab -e
0 2 * * * /backup/huginn_backup.sh
Updating and Upgrading Huginn
⬆️ Updating Docker Images
Update Huginn’s Docker setup:
docker-compose pull
docker-compose down
docker-compose up -d
🛠️ Manual Updates
For manual installations:
cd huginn
git pull origin master
bundle install --deployment --without development test
bundle exec rake db:migrate
bundle exec foreman start
🔍 Checking for Updates
Monitor the Huginn GitHub repository for announcements and updates.
Leveraging Huginn’s Unique Features
🔧 Enabling APIs
If you want to use Huginn’s API capabilities, create an API user:
bundle exec rails console
user = User.create!(email: '[email protected]', password: 'securepassword', confirmed_at: Time.now, admin: true)
puts "Your API key is: #{user.authentication_token}"
Use the API to trigger or configure agents:
curl -X POST -H "Authorization: Token your_api_key" -H "Content-Type: application/json" \
-d '{"agent": {"name": "Web Scraper", "type": "Agents::WebsiteAgent", "options": {...}}}' \
http://your-domain.com/users/1/agents
🌟 Advanced Configurations
To connect Huginn with third-party systems, add Webhooks or RSS feeds to agents. For example, configure a webhook agent to trigger workflows:
{
"expected_receive_period_in_days": 2,
"webhook_url": "https://your-domain.com/users/1/webhooks/trigger",
"content_type": "application/json"
}
Wrapping Up
This guide has covered the essentials of deploying, configuring, and managing Huginn for self-hosting. Whether you're using it to automate tasks, monitor data, or integrate third-party services, Huginn offers unparalleled flexibility and control. Start experimenting with agents and workflows to unlock its full potential!
