Skip to content
Klutch.sh Docs

Deploying a Huginn App

Introduction

Huginn is an open-source system for building agents that monitor, fetch, and act on data across the web. Deploying Huginn with a Dockerfile on Klutch.sh gives you reproducible builds, managed secrets, and persistent storage for queues and uploaded assets—all from klutch.sh/app. This guide covers installation, repository prep, Dockerfile configuration, deployment steps, Nixpacks overrides, and production best practices.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository containing your Huginn code (GitHub is the only supported git source)
  • Docker and Ruby familiarity (Huginn uses Ruby on Rails, Node for assets, and MySQL/PostgreSQL)
  • Database connection details (MySQL or PostgreSQL)
  • Redis credentials if you enable background job queues

Architecture and ports

  • Huginn runs over HTTP; set the internal container port to 3000.
  • If you deploy MySQL/PostgreSQL or Redis on Klutch.sh, run them as separate TCP apps. Expose TCP apps on port 8000 and connect internally on their native ports (3306/5432/6379).
  • Persistent storage is recommended for uploaded files and long-lived data caches.

Repository layout

huginn/
├── app/                  # Rails app code
├── config/               # Rails configs
├── db/                   # Migrations
├── log/                  # Rails logs (use volume or external logging)
├── public/               # Static files
├── tmp/                  # Cache and pids (can be ephemeral)
├── vendor/               # Optional vendored assets
├── Dockerfile            # Must be in repo root for auto-detection
├── Gemfile
├── Gemfile.lock
└── package.json          # Frontend assets

Keep secrets out of Git; store them in Klutch.sh environment variables.

Local installation and starter commands

Install dependencies locally before pushing to GitHub:

Terminal window
bundle install
yarn install --frozen-lockfile
bundle exec rake db:setup
bundle exec rails assets:precompile

For local convenience, create a start.sh script that also works with Nixpacks:

#!/usr/bin/env bash
set -euo pipefail
bundle exec rake db:migrate
exec bundle exec rails server -b 0.0.0.0 -p 3000

Make it executable with chmod +x start.sh.

Dockerfile for Huginn (production-ready)

Place this Dockerfile at the repository root so Klutch.sh auto-detects it (no Docker toggle in the UI):

FROM ruby:3.2-slim AS base
ENV RAILS_ENV=production NODE_ENV=production APP_HOME=/app
WORKDIR $APP_HOME


# System deps
RUN apt-get update && apt-get install -y \
    build-essential nodejs npm git libpq-dev libmysqlclient-dev curl && \
    npm install -g yarn && \
    rm -rf /var/lib/apt/lists/*


# Install Ruby gems
COPY Gemfile Gemfile.lock ./
RUN bundle config set without 'development test' && bundle install --jobs 4 --retry 3


# Install JS deps and build assets
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* ./
RUN yarn install --frozen-lockfile || npm install --omit=dev


# Copy app source
COPY . .


# Precompile assets
RUN bundle exec rake assets:precompile


# Runtime image
FROM ruby:3.2-slim
ENV RAILS_ENV=production NODE_ENV=production APP_HOME=/app PORT=3000
WORKDIR $APP_HOME


# System deps for runtime
RUN apt-get update && apt-get install -y nodejs npm libpq-dev libmysqlclient-dev && \
    rm -rf /var/lib/apt/lists/*


COPY --from=base /app /app


# Ensure a non-root user if desired (optional)
# RUN useradd -m huginn && chown -R huginn:huginn /app
# USER huginn


EXPOSE 3000
CMD ["bundle", "exec", "rails", "server", "-b", "0.0.0.0", "-p", "3000"]

Notes:

  • Install either libpq-dev or libmysqlclient-dev depending on your database. The example includes both for flexibility.
  • If using Redis for background jobs, configure the environment variables below and ensure the redis client gem is included.

Environment variables (Klutch.sh)

Set these in the Klutch.sh app settings (Secrets tab) before deploying:

  • RAILS_ENV=production
  • PORT=3000
  • APP_BASE_URL=https://example-app.klutch.sh
  • DATABASE_URL=postgres://<user>:<password>@<host>:<port>/<db> (or mysql://)
  • SECRET_KEY_BASE=<generate secure value>
  • RAILS_SERVE_STATIC_FILES=true
  • RAILS_LOG_TO_STDOUT=true
  • REDIS_URL=redis://<user>:<password>@<host>:<port>/0 (if using Redis)
  • SMTP_ADDRESS, SMTP_USER, SMTP_PASSWORD (if sending email)

If you deploy without a Dockerfile and want Nixpacks overrides:

  • NIXPACKS_BUILD_CMD=yarn install --frozen-lockfile && bundle install --without development test && bundle exec rake assets:precompile
  • NIXPACKS_START_CMD=./start.sh
  • NIXPACKS_RUBY_VERSION=3.2

These keep Huginn compatible with the Nixpacks build path when no Dockerfile is present.

Attach persistent volumes

Add mount paths and sizes in Klutch.sh (names are not needed):

  • /app/public/system — for file uploads and user attachments.
  • /app/log — optional if you need on-disk logs; otherwise ship to an external sink.
  • /app/tmp — optional cache for performance; safe to keep ephemeral if not required.

Ensure these paths remain writable inside the container.

Deploy Huginn on Klutch.sh (Dockerfile workflow)

  1. Push your repository with the Dockerfile at the root to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Connect your GitHub repository; Klutch.sh automatically detects the Dockerfile (no manual Docker option).
  4. Choose HTTP traffic for Huginn.
  5. Set the internal port to 3000.
  6. Add the environment variables listed above (database, secrets, Redis/SMTP if needed).
  7. Attach persistent volumes for /app/public/system (and /app/log or /app/tmp if you want them persisted) with sizes that match your storage needs.
  8. Deploy. Your app will be available at https://example-app.klutch.sh; map a custom domain if desired.

For databases or Redis hosted on Klutch.sh, create separate TCP apps, expose them on port 8000, and point DATABASE_URL or REDIS_URL to those endpoints (internal ports 3306/5432/6379 respectively).

Health checks and production tips

  • Add a lightweight health endpoint (for example, /health) that verifies DB connectivity.
  • Keep SECRET_KEY_BASE secure and rotate it as part of credential management.
  • Back up your database regularly; do not rely on container filesystems for durability.
  • Pin Ruby and Node versions (via NIXPACKS_RUBY_VERSION or Docker base image) for consistent builds.
  • Monitor volume usage and increase sizes before they fill.

Huginn on Klutch.sh combines reproducible Docker builds with managed secrets, persistent volumes, and flexible HTTP/TCP traffic options. With the Dockerfile at the repo root and ports set to 3000 for the app (8000 externally for TCP databases and queues), you can run autonomous agents reliably without extra YAML or workflow overhead.