Deploying HomelabOS

Introduction

HomelabOS is a comprehensive self-hosted cloud platform that simplifies deploying and managing over 100 popular open-source services. Built with Ansible and Docker, HomelabOS provides a unified framework for running your entire homelab infrastructure with consistent configuration, automatic updates, and integrated service discovery.

The platform abstracts away the complexity of individually configuring each service, providing sensible defaults while allowing deep customization. From media servers to productivity tools, monitoring solutions to development environments, HomelabOS packages everything into a cohesive ecosystem that just works.

Key highlights of HomelabOS:

100+ Integrated Services: Deploy popular applications like Nextcloud, Jellyfin, Gitea, and many more with minimal configuration
Ansible Automation: Infrastructure-as-code approach ensures reproducible deployments
Traefik Integration: Automatic reverse proxy configuration with SSL certificates for all services
Service Discovery: Services automatically discover and integrate with each other
Unified Configuration: Single configuration file controls your entire homelab
Automatic Backups: Built-in backup solutions for all service data
VPN Integration: Optional WireGuard VPN for secure remote access
Authentication: Centralized authentication with Authelia or similar providers
Documentation: Comprehensive docs for every supported service
Active Community: Regular updates and community-contributed services

This guide walks through deploying the HomelabOS management interface on Klutch.sh, enabling you to orchestrate your homelab services from the cloud.

Why Deploy HomelabOS on Klutch.sh

Deploying HomelabOS on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds the HomelabOS management interface without complex configuration.

Persistent Storage: Attach persistent volumes for your HomelabOS configuration and state. Your settings survive container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your HomelabOS dashboard.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Centralized Management: Access your HomelabOS control plane from anywhere with internet access.

Environment Variable Management: Securely store sensitive configuration through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain to your HomelabOS management interface.

Always-On Availability: Your HomelabOS dashboard remains accessible 24/7.

Prerequisites

Before deploying HomelabOS on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your HomelabOS configuration
Basic familiarity with Docker, Ansible, and containerization concepts
Understanding of your homelab architecture and desired services
(Optional) A custom domain for your HomelabOS instance

Understanding HomelabOS Architecture

HomelabOS uses a modular architecture built on proven technologies:

Ansible Playbooks: The core of HomelabOS is a collection of Ansible playbooks that define how each service should be deployed and configured.

Docker Compose: Each service runs in Docker containers, orchestrated through Docker Compose files generated by Ansible.

Traefik Reverse Proxy: All services are exposed through Traefik, which handles routing, load balancing, and automatic SSL certificate provisioning.

Configuration Management: A single YAML configuration file controls which services are enabled and how they’re configured.

Service Roles: Each supported application has an Ansible role that handles its specific deployment requirements.

Preparing Your Repository

To deploy HomelabOS on Klutch.sh, create a GitHub repository containing your configuration.

Repository Structure

homelabos-deploy/
├── Dockerfile
├── config.yml
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM python:3.11-slim

# Install dependencies
RUN apt-get update && apt-get install -y \
    git \
    openssh-client \
    && rm -rf /var/lib/apt/lists/*

# Install Ansible and dependencies
RUN pip install ansible docker docker-compose

# Clone HomelabOS
RUN git clone https://gitlab.com/NickBusey/HomelabOS.git /homelabos

WORKDIR /homelabos

# Copy custom configuration
COPY config.yml /homelabos/settings/config.yml

# Set environment variables
ENV ANSIBLE_HOST_KEY_CHECKING=False

# Expose web interface
EXPOSE 8080

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:8080/health || exit 1

CMD ["python", "-m", "http.server", "8080", "--directory", "/homelabos/docs"]

Configuration File

Create a config.yml file with your HomelabOS settings:

# HomelabOS Configuration
homelab:
  # Domain configuration
  domain: example.com

  # Admin email for Let's Encrypt
  admin_email: admin@example.com

  # Timezone
  timezone: America/New_York

  # Enable services
  services:
    jellyfin:
      enabled: true
    nextcloud:
      enabled: true
    gitea:
      enabled: true
    portainer:
      enabled: true

  # Traefik configuration
  traefik:
    enabled: true
    dashboard: true

  # Authentication
  authelia:
    enabled: true

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

Variable	Required	Default	Description
`HOMELAB_DOMAIN`	Yes	-	Primary domain for your homelab
`ADMIN_EMAIL`	Yes	-	Email for SSL certificates and notifications
`TIMEZONE`	No	UTC	Timezone for all services
`ENABLE_VPN`	No	false	Enable WireGuard VPN integration

Deploying HomelabOS on Klutch.sh

Once your repository is prepared, follow these steps to deploy:

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile config.yml .dockerignore README.md
git commit -m "Initial HomelabOS deployment configuration"
git remote add origin https://github.com/yourusername/homelabos-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “homelabos” or “homelab-management”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your HomelabOS Dockerfile.

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 8080

Set Environment Variables

In the environment variables section, add:

Variable	Value
`HOMELAB_DOMAIN`	`example.com`
`ADMIN_EMAIL`	`admin@example.com`
`TIMEZONE`	`America/New_York`

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
`/homelabos/settings`	100 MB	HomelabOS configuration
`/homelabos/data`	1 GB	Service data and state

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

Detect your Dockerfile automatically
Build the container image
Attach the persistent volumes
Start the HomelabOS container
Provision an HTTPS certificate

Access HomelabOS

Once deployment completes, access your HomelabOS instance at https://example-app.klutch.sh.

Initial Setup and Configuration

Enabling Services

After deployment, configure which services to enable:

Edit your config.yml file
Set enabled: true for desired services
Push changes to trigger redeployment
HomelabOS will deploy the enabled services

Available Service Categories

HomelabOS supports services across many categories:

Media:

Jellyfin, Plex, Emby
Sonarr, Radarr, Lidarr
Transmission, qBittorrent

Productivity:

Nextcloud, Seafile
Paperless-ngx
Bookstack, Wiki.js

Development:

Gitea, GitLab
Code-server
Drone CI

Monitoring:

Grafana, Prometheus
Uptime Kuma
Netdata

Infrastructure:

Portainer
Traefik
Pi-hole, AdGuard Home

Authentication Setup

Configure centralized authentication:

Enable Authelia in your configuration
Configure user accounts and groups
Set up two-factor authentication
Apply authentication to protected services

Production Best Practices

Security Recommendations

Strong Passwords: Use unique, strong passwords for all services
Two-Factor Authentication: Enable 2FA through Authelia
Regular Updates: Keep HomelabOS and all services updated
Network Segmentation: Isolate services appropriately
Backup Encryption: Encrypt all backup data

Performance Optimization

Resource Allocation: Monitor and adjust container resources
Service Selection: Enable only services you actively use
Database Optimization: Configure databases for your workload
Caching: Enable caching where available

Backup Strategy

HomelabOS includes backup functionality:

Automated Backups: Configure scheduled backups for all services
Remote Storage: Store backups off-site
Testing: Regularly test backup restoration
Retention: Define backup retention policies

Troubleshooting Common Issues

Services Not Starting

Symptoms: Enabled services don’t appear or start.

Solutions:

Check container logs for specific errors
Verify configuration syntax in config.yml
Ensure required dependencies are enabled
Review resource allocation

Authentication Issues

Symptoms: Cannot log into services or Authelia.

Solutions:

Verify Authelia configuration
Check user account settings
Review authentication logs
Clear browser cookies and cache

SSL Certificate Problems

Symptoms: Certificate errors when accessing services.

Solutions:

Verify domain DNS configuration
Check Traefik logs for certificate errors
Ensure ports 80 and 443 are accessible
Review Let’s Encrypt rate limits

Additional Resources

Conclusion

Deploying HomelabOS on Klutch.sh gives you a powerful platform for managing your entire self-hosted infrastructure. The combination of HomelabOS’s extensive service catalog and Klutch.sh’s deployment simplicity means you can focus on using your services rather than managing infrastructure.

With 100+ integrated services, automated configuration, and built-in features like authentication and backups, HomelabOS transforms homelab management from a complex hobby into a streamlined experience. Whether you’re starting your self-hosting journey or consolidating an existing infrastructure, HomelabOS on Klutch.sh provides the foundation for a reliable, maintainable homelab.