Skip to content
Klutch.sh Docs

Deploying Self Host Blocks

Introduction

Self Host Blocks (SHB) is a modular, NixOS-based framework for building self-hosted infrastructure using composable building blocks. It provides pre-configured NixOS modules for popular self-hosted applications, making it easy to deploy secure, reproducible systems with features like automatic SSL certificates, SSO integration, and backup management built-in.

The project aims to reduce the complexity of self-hosting by providing opinionated but flexible configurations that follow security best practices. Each “block” represents a service or feature that can be combined with others to create a complete self-hosting solution.

Key highlights of Self Host Blocks:

  • Declarative Configuration: Define your entire infrastructure as code with NixOS
  • Modular Design: Mix and match service blocks to build your stack
  • Built-in SSO: Integrated authentication using LDAP/OIDC across services
  • Automatic SSL: Integrated Let’s Encrypt certificate management
  • Backup Integration: Built-in backup support with Borgmatic
  • Reverse Proxy: Pre-configured Nginx with security headers
  • Database Management: Automated PostgreSQL/MariaDB provisioning
  • Security Hardening: Security best practices applied by default
  • 100% Open Source: Licensed under GPL-3.0

This guide explains how to leverage Self Host Blocks concepts when deploying containerized services on Klutch.sh.

Why Use Self Host Blocks Patterns on Klutch.sh

While Self Host Blocks is primarily designed for NixOS systems, its architectural patterns and service configurations can inform Docker-based deployments:

Service Composition: Learn from SHB’s modular approach to combine services effectively.

Security Defaults: Apply SHB’s security recommendations to your Docker deployments.

Configuration Patterns: Use SHB’s configuration examples as templates for environment variables.

SSO Integration: Implement authentication patterns similar to SHB’s LDAP/OIDC setup.

Prerequisites

Before implementing Self Host Blocks patterns on Klutch.sh:

  • A Klutch.sh account
  • A GitHub account for your configuration repositories
  • Basic familiarity with Docker and containerization concepts
  • Understanding of reverse proxy and SSO concepts

Available Service Blocks

Self Host Blocks provides configurations for many popular services. Here are Docker equivalents you can deploy on Klutch.sh:

Authentication Block

Deploy an identity provider like Authentik or Keycloak for centralized SSO.

Media Block

Deploy media servers:

Monitoring Block

Deploy monitoring solutions:

Implementing SHB Patterns

Pattern 1: Service with SSO

FROM your-service:latest


# Configure OIDC authentication
ENV OIDC_ISSUER=${OIDC_ISSUER}
ENV OIDC_CLIENT_ID=${OIDC_CLIENT_ID}
ENV OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}


EXPOSE 8080

Pattern 2: Service with Database

FROM your-service:latest


# Database configuration following SHB patterns
ENV DB_TYPE=postgresql
ENV DB_HOST=${DB_HOST}
ENV DB_PORT=5432
ENV DB_NAME=${DB_NAME}
ENV DB_USER=${DB_USER}
ENV DB_PASSWORD=${DB_PASSWORD}


EXPOSE 8080

Pattern 3: Service with Backup Integration

Structure your volumes for easy backup:

Mount PathPurpose
/dataApplication data (backup target)
/configConfiguration files (backup target)
/cacheTemporary data (exclude from backup)

Deploying SHB-Inspired Services on Klutch.sh

    Plan Your Service Stack

    Review Self Host Blocks documentation to understand service dependencies and recommended configurations.

    Create Service Repositories

    Create a GitHub repository for each service with appropriate Dockerfile and configuration.

    Deploy Authentication First

    If using SSO, deploy your identity provider (Authentik, Keycloak) before other services.

    Deploy Core Services

    Deploy databases and other shared infrastructure services.

    Deploy Application Services

    Deploy your application services with SSO and database connections configured.

    Configure Environment Variables

    Set environment variables following SHB’s recommended patterns:

    CategoryVariables
    DatabaseDB_HOST, DB_USER, DB_PASSWORD
    SSOOIDC_ISSUER, OIDC_CLIENT_ID
    GeneralTZ, PUID, PGID

    Attach Persistent Volumes

    Mount persistent storage following SHB’s data organization patterns.

Security Best Practices from SHB

HTTP Headers

Configure security headers in your applications:

  • X-Frame-Options: DENY
  • X-Content-Type-Options: nosniff
  • X-XSS-Protection: 1; mode=block
  • Referrer-Policy: strict-origin-when-cross-origin

Secret Management

  • Never commit secrets to repositories
  • Use Klutch.sh environment variables for sensitive data
  • Rotate secrets periodically

Network Isolation

  • Separate public-facing and internal services
  • Use private networks for database connections

Additional Resources

Conclusion

While Self Host Blocks is designed for NixOS, its modular architecture and security-focused patterns provide valuable guidance for any self-hosting deployment. By applying SHB’s principles to your Docker-based Klutch.sh deployments, you can build a well-organized, secure self-hosted infrastructure using industry best practices.