Skip to content
Klutch.sh Docs

Deploying Mistborn

Introduction

Mistborn is a comprehensive self-hosted security platform that bundles essential privacy and security services into a single, manageable deployment. It combines WireGuard VPN, Pi-hole ad-blocking, firewall management, and additional services to create a secure gateway for personal or organizational use.

The platform provides a web-based control panel for managing all integrated services, making it accessible to users without deep networking expertise. Mistborn handles the complexity of configuring secure communications, DNS filtering, and network protection behind an intuitive interface.

Key highlights of Mistborn:

  • WireGuard VPN: Modern, fast VPN protocol for secure remote access
  • Pi-hole Integration: Network-wide ad blocking and tracking protection
  • Firewall Management: Simplified iptables configuration through web UI
  • DNS-over-HTTPS: Encrypted DNS queries for privacy
  • Secure Gateway: Single point of entry for all self-hosted services
  • User Management: Create and manage VPN users with individual keys
  • Mobile Support: QR code configuration for WireGuard mobile apps
  • Service Proxying: Securely expose services only through VPN
  • Automatic Updates: Keep security components current
  • Web Dashboard: Central management for all features
  • Open Source: Fully auditable security implementation

This guide covers deploying Mistborn on Klutch.sh, configuring VPN access, and managing the integrated security services.

Why Deploy Mistborn on Klutch.sh

Deploying Mistborn on Klutch.sh provides key advantages:

Simplified Deployment: Klutch.sh handles the Docker deployment complexity. Push to GitHub, and your secure gateway deploys automatically.

Persistent Storage: Attach volumes for VPN configurations, user data, and Pi-hole blocklists that persist across updates.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure access to the management dashboard.

Scalable Resources: Allocate CPU and memory based on connected clients and DNS query volume.

GitHub Integration: Connect your repository for automatic deployments and updates.

Environment Variable Management: Securely store admin credentials and configuration secrets.

Always-On Availability: Your secure gateway remains accessible 24/7 for VPN connections.

Prerequisites

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

  • A Klutch.sh account
  • A GitHub account with a repository for your configuration
  • Basic familiarity with Docker and networking concepts
  • Understanding of VPN and firewall principles
  • (Optional) A custom domain for your Mistborn instance

Understanding Mistborn Architecture

Mistborn integrates several components:

Mistborn Core: The main orchestration service managing all components.

WireGuard: Modern VPN protocol providing secure tunnels for remote access.

Pi-hole: DNS sinkhole that blocks ads and trackers at the network level.

Traefik: Reverse proxy handling routing and SSL termination.

PostgreSQL: Database storing user accounts and configuration.

Redis: Caching layer for performance optimization.

Preparing Your Repository

Repository Structure

mistborn-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile:

FROM cybertechniques/mistborn:latest


# Set environment variables
ENV MISTBORN_ADMIN_EMAIL=${MISTBORN_ADMIN_EMAIL}
ENV MISTBORN_ADMIN_PASSWORD=${MISTBORN_ADMIN_PASSWORD}
ENV MISTBORN_HOST=${MISTBORN_HOST}
ENV MISTBORN_DNS_PRIMARY=${MISTBORN_DNS_PRIMARY:-1.1.1.1}
ENV MISTBORN_DNS_SECONDARY=${MISTBORN_DNS_SECONDARY:-8.8.8.8}


# Create data directories
RUN mkdir -p /opt/mistborn/data /opt/mistborn/wireguard


# Expose ports
# 80/443 - Web interface
# 51820 - WireGuard VPN
# 53 - DNS (Pi-hole)
EXPOSE 80 443 51820/udp 53/tcp 53/udp


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

Environment Variables Reference

VariableRequiredDefaultDescription
MISTBORN_ADMIN_EMAILYes-Admin account email
MISTBORN_ADMIN_PASSWORDYes-Admin account password
MISTBORN_HOSTYes-Public hostname for the server
MISTBORN_DNS_PRIMARYNo1.1.1.1Upstream DNS server
MISTBORN_DNS_SECONDARYNo8.8.8.8Backup DNS server
WIREGUARD_PORTNo51820WireGuard VPN port

Deploying Mistborn on Klutch.sh

    Generate Secure Admin Password

    Create a strong admin password:

    Terminal window
    openssl rand -base64 24

    Push Your Repository to GitHub

    Terminal window
    git init
    git add Dockerfile .dockerignore README.md
    git commit -m "Initial Mistborn deployment"
    git remote add origin https://github.com/yourusername/mistborn-deploy.git
    git push -u origin main

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a project named “mistborn” or “secure-gateway”.

    Create a New App

    Create a new app and connect your GitHub repository.

    Configure HTTP Traffic

    In deployment settings:

    • Select HTTP as the traffic type
    • Set the internal port to 80 or 443
    • Note: UDP port 51820 is needed for WireGuard VPN

    Set Environment Variables

    Configure your environment:

    VariableValue
    MISTBORN_ADMIN_EMAILYour admin email
    MISTBORN_ADMIN_PASSWORDYour secure password
    MISTBORN_HOSTyour-app-name.klutch.sh
    MISTBORN_DNS_PRIMARY1.1.1.1
    MISTBORN_DNS_SECONDARY8.8.8.8

    Attach Persistent Volumes

    Add volumes for persistent data:

    Mount PathRecommended SizePurpose
    /opt/mistborn/data5 GBApplication data and database
    /opt/mistborn/wireguard1 GBWireGuard configurations
    /etc/pihole1 GBPi-hole configuration

    Deploy Your Application

    Click Deploy to build and launch Mistborn.

    Access Dashboard

    Navigate to https://your-app-name.klutch.sh and log in with your admin credentials.

Configuring WireGuard VPN

Creating VPN Users

  1. Log into the Mistborn dashboard
  2. Navigate to WireGuard section
  3. Click Add Client
  4. Enter client name (e.g., “laptop”, “phone”)
  5. Download configuration file or scan QR code

Client Configuration

For desktop clients:

  1. Install WireGuard client
  2. Import the downloaded .conf file
  3. Connect to the VPN

For mobile devices:

  1. Install WireGuard app (iOS/Android)
  2. Scan the QR code from dashboard
  3. Enable the VPN connection

VPN Settings

Configure VPN behavior:

  • Allowed IPs: Networks accessible through VPN
  • DNS: Use Pi-hole for DNS filtering
  • Persistent Keepalive: Maintain connections through NAT

Pi-hole Ad Blocking

Accessing Pi-hole

Pi-hole admin panel is available through the Mistborn dashboard or directly at /admin.

Blocklist Management

Configure ad blocking:

  1. Navigate to Settings > Blocklists
  2. Add custom blocklists or use defaults
  3. Update gravity database

DNS Configuration

Point devices to use Pi-hole:

  • Through VPN: Automatic when connected
  • Local network: Set Pi-hole as DNS server

Query Analytics

Monitor DNS activity:

  • View query logs
  • See blocked domains
  • Identify top clients

Firewall Management

Understanding Mistborn Firewall

Mistborn provides simplified firewall management:

  • Default Deny: Block all incoming by default
  • VPN Access: Allow traffic through WireGuard
  • Service Rules: Selectively expose services

Creating Firewall Rules

  1. Navigate to Firewall section
  2. Click Add Rule
  3. Configure source, destination, and action
  4. Apply changes

Best Practices

  • Only expose necessary ports
  • Use VPN for service access when possible
  • Regularly review active rules

Service Integration

Adding Services Behind VPN

Protect self-hosted services:

  1. Deploy service on internal network
  2. Configure routing through Mistborn
  3. Access only via VPN connection

DNS-Based Routing

Use internal DNS for service discovery:

  • Configure custom DNS records in Pi-hole
  • Access services by name through VPN

Troubleshooting

VPN Connection Issues

  • Verify UDP port 51820 is accessible
  • Check client configuration matches server
  • Ensure keys are correctly paired

DNS Not Working

  • Verify Pi-hole is running
  • Check upstream DNS servers
  • Review blocklist conflicts

Dashboard Inaccessible

  • Check container health status
  • Verify port mappings
  • Review application logs

Performance Issues

  • Monitor resource usage
  • Check connected client count
  • Review DNS query volume

Additional Resources

Conclusion

Mistborn on Klutch.sh provides a comprehensive security platform combining VPN access, ad blocking, and firewall management in one deployment. The integrated approach simplifies securing your digital life while the web dashboard makes management accessible. Whether protecting personal browsing or securing organizational access to self-hosted services, Mistborn delivers the tools needed for robust network security.