Skip to content
Klutch.sh Docs

Deploying FreedomBox

Introduction

FreedomBox is a free and open-source personal server operating system that puts privacy, security, and freedom at the forefront of your digital life. Designed as a privacy-focused alternative to centralized cloud services, FreedomBox provides self-hosted solutions for communication, file sharing, VPN access, web hosting, and more—all managed through an intuitive web interface without requiring deep technical expertise.

Built on Debian GNU/Linux, FreedomBox offers a comprehensive suite of applications including chat servers (XMPP), file synchronization (Syncthing), VPN services (OpenVPN, WireGuard), web serving (Apache), blogging platforms, calendar/contacts (DAV servers), and collaborative tools. It’s designed to run on low-power devices like single-board computers but works equally well in containerized environments, making it perfect for deployment on Klutch.sh.

Deploying FreedomBox on Klutch.sh combines the privacy benefits of self-hosting with the convenience of managed infrastructure. You get automatic HTTPS, reliable persistent storage for your data, seamless updates, and professional-grade infrastructure without the complexity of managing physical hardware or bare-metal servers.

This guide walks you through deploying FreedomBox on Klutch.sh using Docker, configuring persistent volumes for your data, setting up networking for various services, and implementing best practices for security and reliability.

Why Deploy FreedomBox on Klutch.sh?

  • Privacy-First Infrastructure: Self-host your data on infrastructure you control
  • Automatic HTTPS: Built-in SSL certificates for secure access to all services
  • Persistent Storage: Reliable volume storage for configurations, user data, and application state
  • Custom Domains: Use your own domain for professional, branded access
  • Easy Updates: Deploy new FreedomBox versions without hardware management
  • Zero Downtime: Update your server without interrupting active services
  • Scalable Resources: Adjust CPU and memory as your usage grows
  • No Hardware Maintenance: Skip the physical server setup and management
  • GitHub Integration: Version-controlled deployments from your repository
  • Professional Infrastructure: Enterprise-grade reliability for personal freedom

Prerequisites

Before you begin, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your deployment
  • Basic understanding of Docker and Linux server administration
  • A domain name (optional, but recommended for production use)

Technical Requirements:

FreedomBox is resource-intensive due to the multiple services it runs. We recommend:

  • Minimum 2GB RAM (4GB recommended for production)
  • At least 10GB persistent storage (20GB+ recommended)
  • Stable internet connection for service access

Understanding FreedomBox Architecture

FreedomBox is built as a complete server environment with multiple layers:

Core Components:

  • Debian Base: Stable Linux foundation with security updates
  • Plinth: Web-based administration interface (FreedomBox’s control panel)
  • SystemD Services: Background services for various applications
  • Apache Web Server: Serves the admin interface and hosted web applications
  • OpenVPN/WireGuard: VPN servers for secure remote access
  • XMPP Server (Ejabberd): Private chat and messaging
  • Syncthing: Decentralized file synchronization
  • Nextcloud: File hosting and collaboration
  • Let’s Encrypt: Automatic SSL certificate management

Key Features:

  • Self-hosted email, chat, and file sharing
  • VPN access for secure browsing
  • Ad blocking and privacy protection
  • Personal wiki and blogging platforms
  • Calendar and contacts synchronization
  • Backup and restore functionality
  • Multi-user support with access controls

When deploying on Klutch.sh, FreedomBox runs in a containerized environment with all these services accessible through Klutch.sh’s networking infrastructure.

Preparing Your Repository

Step 1: Create Project Directory

Create a new directory for your FreedomBox deployment:

Terminal window
mkdir freedombox-deploy
cd freedombox-deploy

Step 2: Create Dockerfile

FreedomBox doesn’t have an official Docker image, but we can build one based on the FreedomBox Debian package. Create a Dockerfile:

FROM debian:bookworm


# Set environment variables
ENV DEBIAN_FRONTEND=noninteractive \
    FREEDOMBOX_SETUP=true


# Install FreedomBox and dependencies
RUN apt-get update && \
    apt-get install -y \
    freedombox \
    sudo \
    systemd \
    systemd-sysv \
    dbus \
    ca-certificates \
    curl \
    wget \
    gnupg \
    apt-transport-https \
    && apt-get clean && \
    rm -rf /var/lib/apt/lists/*


# Create necessary directories
RUN mkdir -p /var/log/freedombox \
    /var/lib/freedombox \
    /etc/freedombox


# Expose ports for FreedomBox services
# 80/443: Web interface and hosted apps
# 1194: OpenVPN
# 51820: WireGuard
# 5222: XMPP client connections
# 5269: XMPP server-to-server
EXPOSE 80 443 1194 51820 5222 5269


# Set up init system for FreedomBox
STOPSIGNAL SIGRTMIN+3


# Start FreedomBox
CMD ["/lib/systemd/systemd"]

Alternative: Lightweight Configuration

For a lighter deployment focused on specific services, use this optimized Dockerfile:

FROM debian:bookworm-slim


ENV DEBIAN_FRONTEND=noninteractive


# Install only essential FreedomBox components
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
    freedombox \
    apache2 \
    python3 \
    python3-pip \
    openssl \
    sudo \
    systemd \
    ca-certificates \
    && apt-get clean && \
    rm -rf /var/lib/apt/lists/*


# Configure Apache for Plinth
RUN a2enmod ssl rewrite proxy proxy_http headers && \
    systemctl enable apache2


# Create data directories
RUN mkdir -p /var/lib/freedombox /var/log/freedombox


EXPOSE 80 443


VOLUME ["/var/lib/freedombox", "/etc/freedombox"]


CMD ["/lib/systemd/systemd"]

Step 3: Create .gitignore

Create a .gitignore file to exclude sensitive data:

# FreedomBox data
/data/
/backups/


# Logs
*.log


# Environment files
.env
.env.local


# System files
.DS_Store
Thumbs.db

Step 4: Create README.md

Document your deployment:

# FreedomBox on Klutch.sh


Self-hosted privacy server deployed on Klutch.sh infrastructure.


## Quick Start


1. Push this repository to GitHub
2. Deploy on Klutch.sh
3. Access your FreedomBox at your assigned URL
4. Complete initial setup wizard


## Services Included


- Web Administration (Plinth)
- VPN Access (OpenVPN/WireGuard)
- File Sync (Syncthing)
- Chat Server (XMPP)
- And more...


## Configuration


See Klutch.sh dashboard for environment variables and volume configuration.

Step 5: Push to GitHub

Initialize git and push your repository:

Terminal window
git init
git add Dockerfile .gitignore README.md
git commit -m "Initial FreedomBox deployment setup"
git branch -M main
git remote add origin https://github.com/your-username/freedombox-deploy.git
git push -u origin main

Deploying on Klutch.sh

Step 1: Create New App

    1. Log in to the Klutch.sh dashboard

    2. Create a new project or select an existing one

    3. Create a new app and configure it:

      • Repository: Select your FreedomBox GitHub repository
      • Branch: Choose the branch to deploy (e.g., main or production)
      • Traffic Type: Select HTTP (FreedomBox web interface runs on HTTP/HTTPS)
      • Internal Port: Set to 80 (FreedomBox’s Apache server listens on port 80)

Step 2: Configure Persistent Volumes

FreedomBox requires persistent storage for configurations, user data, and service state.

    1. In your app settings, navigate to the Volumes section

    2. Add a volume for FreedomBox data:

      • Mount Path: /var/lib/freedombox
      • Size: 10GB minimum (20GB recommended for production)

    3. Add a volume for configuration:

      • Mount Path: /etc/freedombox
      • Size: 2GB

    4. (Optional) Add a volume for logs:

      • Mount Path: /var/log/freedombox
      • Size: 2GB

Step 3: Configure Environment Variables

Set essential environment variables for your FreedomBox deployment:

    1. In your app settings, navigate to the Environment Variables section

    2. Add the following variables:

      Basic Configuration:

      Terminal window
      FREEDOMBOX_DOMAIN=example-app.klutch.sh
      FREEDOMBOX_ADMIN_USER=admin
      FREEDOMBOX_ADMIN_PASSWORD=your-secure-password

      Network Configuration:

      Terminal window
      ENABLE_VPN=true
      ENABLE_TOR=false
      ENABLE_PAGEKIT=true

      Service Configuration:

      Terminal window
      ENABLE_SYNCTHING=true
      ENABLE_XMPP=true
      ENABLE_NEXTCLOUD=false

    3. Mark sensitive values (passwords, keys) as secrets in the dashboard

Step 4: Deploy Your Application

    1. Click Deploy to start the build process

    2. Klutch.sh will:

      • Pull your GitHub repository
      • Detect the Dockerfile automatically
      • Build the FreedomBox container image
      • Deploy it with your configured volumes and environment variables

    3. Monitor the build logs for any errors

    4. Once deployed, your FreedomBox will be available at https://example-app.klutch.sh

Initial Setup

After deployment, complete the FreedomBox initial setup:

Step 1: Access Web Interface

    1. Navigate to https://example-app.klutch.sh in your browser

    2. You’ll be greeted with the FreedomBox Setup Wizard

    3. Accept the terms and conditions

Step 2: Create Admin Account

    1. Create your administrator account:

      • Username: Choose a secure username
      • Password: Use a strong password (minimum 12 characters)
      • Email: Provide your email for notifications

    2. Complete the account creation

Step 3: Configure Domain

    1. In the FreedomBox admin panel, navigate to System → Configure

    2. Set your domain name:

      • Domain: example-app.klutch.sh (or your custom domain)
      • Enable Automatic HTTPS (handled by Klutch.sh)

    3. Save the configuration

Step 4: Enable Services

    1. Navigate to Apps in the FreedomBox interface

    2. Enable the services you want to use:

      • File Synchronization (Syncthing)
      • Chat Server (Ejabberd XMPP)
      • VPN (OpenVPN or WireGuard)
      • Web Publishing
      • Calendar & Contacts

    3. Each service will have its own configuration page

Configuring Services

VPN Access

Set up secure VPN access to your FreedomBox:

    1. Navigate to Apps → OpenVPN or WireGuard

    2. Click Install to set up the VPN service

    3. Create VPN profiles for your devices:

      • Click Add Profile
      • Name the profile (e.g., “Laptop”, “Phone”)
      • Download the configuration file

    4. Import the configuration into your VPN client

    Note: For VPN to work properly through Klutch.sh, you may need to use TCP mode for OpenVPN rather than UDP.

File Synchronization (Syncthing)

Configure decentralized file sync:

    1. Navigate to Apps → Syncthing

    2. Click Install to enable Syncthing

    3. Access Syncthing interface through FreedomBox

    4. Add devices and folders:

      • Click Add Device in Syncthing
      • Enter device ID from your other devices
      • Configure shared folders

    5. Syncthing will sync files across all connected devices

Chat Server (XMPP)

Set up private instant messaging:

    1. Navigate to Apps → XMPP Server (Ejabberd)

    2. Click Install to deploy the chat server

    3. Create user accounts:

      • Navigate to System → Users
      • Add users who can access the chat server
      • Each user gets an XMPP address: username@example-app.klutch.sh

    4. Connect with XMPP clients:

Calendar & Contacts (DAV)

Synchronize calendars and contacts:

    1. Navigate to Apps → Calendar and Addressbook (Radicale)

    2. Click Install to enable DAV services

    3. Configure your devices:

      • CalDAV URL: https://example-app.klutch.sh/radicale/
      • CardDAV URL: https://example-app.klutch.sh/radicale/
      • Username and password from FreedomBox user account

    4. Supported clients:

      • iOS: Native Calendar and Contacts apps
      • Android: DAVx⁵
      • Desktop: Thunderbird, Evolution, GNOME Calendar

Custom Domain Configuration

For production use, configure a custom domain:

Step 1: Configure Domain in Klutch.sh

    1. In the Klutch.sh dashboard, navigate to your app settings

    2. Go to the Domains section

    3. Add your custom domain (e.g., freedombox.yourdomain.com)

    4. Klutch.sh will provide DNS records to configure

Step 2: Update DNS Records

    1. Log in to your domain registrar

    2. Add the DNS records provided by Klutch.sh:

      • CNAME record pointing to your Klutch.sh app
      • Wait for DNS propagation (can take up to 48 hours)

    3. Klutch.sh will automatically provision SSL certificates

Step 3: Update FreedomBox Configuration

    1. Access your FreedomBox admin panel

    2. Navigate to System → Configure

    3. Update the domain name to your custom domain

    4. Save and restart affected services

Security Best Practices

Strong Authentication

    1. Use Strong Passwords:

      • Minimum 16 characters
      • Mix of uppercase, lowercase, numbers, and symbols
      • Use a password manager

    2. Enable Two-Factor Authentication:

      • Navigate to System → Security
      • Enable 2FA for admin accounts
      • Use authenticator apps like Authy or Google Authenticator

    3. Limit User Access:

      • Create separate user accounts for each person
      • Apply principle of least privilege
      • Regularly audit user accounts

Network Security

    1. Firewall Configuration:

      • FreedomBox includes a built-in firewall
      • Navigate to System → Firewall
      • Only open necessary ports
      • Block unnecessary services

    2. VPN for Remote Access:

      • Always use VPN when accessing FreedomBox remotely
      • Avoid exposing admin interface to public internet
      • Use WireGuard for modern, efficient VPN

    3. Regular Updates:

      • Enable automatic security updates in FreedomBox
      • Navigate to System → Updates
      • Check for updates weekly
      • Apply critical patches immediately

Data Protection

    1. Regular Backups:

      • FreedomBox includes backup functionality
      • Navigate to System → Backups
      • Configure automatic backups to external storage
      • Test restore procedures regularly

    2. Encryption:

      • FreedomBox encrypts data at rest
      • Use HTTPS for all web services
      • Enable encryption for file sync

    3. Access Logs:

      • Monitor access logs regularly
      • Navigate to System → Logs
      • Look for suspicious activity
      • Set up alerts for failed login attempts

Performance Optimization

Resource Allocation

    1. CPU and Memory:

      • Monitor resource usage in Klutch.sh dashboard
      • Scale up if services are slow
      • Recommended: 2 vCPU, 4GB RAM for light use
      • Heavy use: 4 vCPU, 8GB RAM

    2. Disable Unused Services:

      • Turn off services you don’t need
      • Each service consumes resources
      • Navigate to Apps and disable unused apps

Storage Management

    1. Monitor Disk Usage:

      • Check storage in System → Storage
      • Set up alerts for low disk space
      • Increase volume size in Klutch.sh if needed

    2. Log Rotation:

      • Configure log rotation to prevent disk fill
      • Navigate to System → Logs
      • Set retention policies

    3. Clean Old Data:

      • Remove old backups
      • Clear cached data periodically
      • Archive old user data

Service-Specific Optimization

    1. Syncthing:

      • Limit sync frequency for large files
      • Use ignore patterns for unnecessary files
      • Configure bandwidth limits

    2. XMPP:

      • Limit message history retention
      • Configure automatic cleanup
      • Disable unused XMPP modules

    3. Web Server:

      • Enable Apache caching modules
      • Compress responses with mod_deflate
      • Optimize static file serving

Backup and Recovery

Creating Backups

    1. Using FreedomBox Backup:

      • Navigate to System → Backups
      • Click Create Backup
      • Select data to include:
        • Configuration files
        • User data
        • Application data
      • Download backup file

    2. Schedule Automatic Backups:

      • Configure backup schedule
      • Choose backup destination (local volume or remote storage)
      • Set retention policy

    3. Volume Snapshots:

      • Use Klutch.sh volume snapshots for additional protection
      • Navigate to Volumes in Klutch.sh dashboard
      • Take snapshots before major changes

Restoring from Backup

    1. Restore FreedomBox Data:

      • Navigate to System → Backups
      • Upload backup file
      • Click Restore
      • Wait for restoration to complete

    2. Restore from Volume Snapshot:

      • In Klutch.sh dashboard, navigate to Volumes
      • Select snapshot to restore
      • Create new volume from snapshot
      • Update app to use restored volume

Monitoring and Maintenance

System Monitoring

    1. FreedomBox Diagnostics:

      • Navigate to System → Diagnostics
      • Check system health
      • Review service status
      • Monitor resource usage

    2. Klutch.sh Metrics:

      • View CPU, memory, and network metrics in dashboard
      • Set up alerts for high resource usage
      • Monitor application logs

    3. Service Health Checks:

      • Verify each service is running correctly
      • Test VPN connectivity
      • Check file sync status
      • Verify chat server availability

Regular Maintenance Tasks

    1. Weekly Tasks:

      • Check for system updates
      • Review access logs
      • Verify backups completed successfully
      • Test critical services

    2. Monthly Tasks:

      • Review user accounts
      • Audit security settings
      • Check disk space usage
      • Update documentation

    3. Quarterly Tasks:

      • Test disaster recovery procedures
      • Review and update access policies
      • Optimize database and storage
      • Security audit

Troubleshooting Common Issues

FreedomBox Won’t Start

    1. Check Container Logs:

      • View logs in Klutch.sh dashboard
      • Look for systemd initialization errors
      • Check for missing dependencies

    2. Verify Volume Mounts:

      • Ensure volumes are properly attached
      • Check mount paths are correct
      • Verify sufficient storage space

    3. Reset Configuration:

      • Delete /etc/freedombox volume contents
      • Redeploy to trigger fresh setup
      • Complete setup wizard again

Service Not Accessible

    1. Check Service Status:

      • Navigate to Apps in FreedomBox
      • Verify service is installed and running
      • Restart service if needed

    2. Verify Network Configuration:

      • Ensure correct internal port (80) configured in Klutch.sh
      • Check firewall settings in FreedomBox
      • Verify domain/URL is correct

    3. SSL/HTTPS Issues:

      • Klutch.sh handles SSL automatically
      • Check certificate status in dashboard
      • Verify domain DNS is correctly configured

VPN Connection Fails

    1. Check VPN Configuration:

      • Verify VPN service is running in FreedomBox
      • Review VPN client configuration file
      • Ensure correct server address

    2. Try TCP Mode:

      • UDP VPN may not work through Klutch.sh HTTP routing
      • Configure OpenVPN to use TCP port 443
      • Update client configuration

    3. Firewall Issues:

      • Check FreedomBox firewall allows VPN traffic
      • Verify Klutch.sh doesn’t block VPN ports
      • Consider using WireGuard instead of OpenVPN

Performance Issues

    1. Resource Constraints:

      • Check CPU and memory usage in Klutch.sh dashboard
      • Scale up resources if maxed out
      • Disable unused services to free resources

    2. Storage Full:

      • Check disk usage in FreedomBox diagnostics
      • Increase volume size in Klutch.sh
      • Clean up old logs and backups

    3. Service Conflicts:

      • Check for services competing for resources
      • Review systemd service logs
      • Restart conflicting services

Backup/Restore Problems

    1. Backup Creation Fails:

      • Check available disk space
      • Verify backup directory permissions
      • Review FreedomBox logs for errors

    2. Restore Incomplete:

      • Ensure backup file is not corrupted
      • Verify sufficient space for restoration
      • Try restoring individual components

    3. Data Inconsistency:

      • Stop services before backup/restore
      • Use FreedomBox maintenance mode
      • Verify data integrity after restore

Production Deployment Checklist

Before going live with FreedomBox:

  • Custom domain configured and DNS propagated
  • SSL/HTTPS working correctly (automatic via Klutch.sh)
  • Admin account created with strong password
  • Two-factor authentication enabled
  • Persistent volumes configured and tested (minimum 10GB)
  • Backup schedule configured and tested
  • Essential services installed and configured
  • VPN access tested from external network
  • User accounts created with appropriate permissions
  • Firewall rules reviewed and configured
  • Service health checks passing
  • Security updates enabled
  • Monitoring and alerts configured
  • Documentation updated with your specific setup
  • Disaster recovery plan documented
  • Team trained on FreedomBox administration

Advanced Configuration

Multi-User Setup

    1. Create User Accounts:

      • Navigate to System → Users
      • Add users with appropriate permissions
      • Set strong passwords or SSH key access
      • Configure user quotas

    2. Access Control:

      • Define which services each user can access
      • Configure application-specific permissions
      • Set up user groups for easier management

    3. User Isolation:

      • Enable separate home directories
      • Configure file sharing permissions
      • Limit resource usage per user

Integration with External Services

    1. External Storage:

      • Mount cloud storage (S3, Google Drive) for backups
      • Configure remote backup destinations
      • Set up cross-region redundancy

    2. LDAP/Active Directory:

      • Integrate with existing directory services
      • Configure LDAP authentication
      • Sync user accounts

    3. Email Server:

      • Configure SMTP for outgoing email
      • Set up email aliases
      • Configure spam filtering

Automation and Scripts

    1. Custom Scripts:

      • Add custom scripts to /usr/local/bin/
      • Create cron jobs for automated tasks
      • Configure systemd timers for scheduled operations

    2. API Integration:

      • Use FreedomBox API for automation
      • Create monitoring scripts
      • Automate user provisioning

    3. Configuration Management:

      • Version control FreedomBox configurations
      • Document custom settings
      • Create reproducible deployments

Migration and Upgrades

Migrating from Existing FreedomBox

    1. Export Data:

      • Create full backup on existing FreedomBox
      • Export user accounts and configurations
      • Download backup files

    2. Deploy on Klutch.sh:

      • Follow deployment steps in this guide
      • Complete initial setup

    3. Import Data:

      • Upload backup to new FreedomBox
      • Restore configuration and data
      • Verify all services working

    4. Update DNS:

      • Point domain to new Klutch.sh deployment
      • Wait for DNS propagation
      • Verify services accessible at new location

Upgrading FreedomBox

    1. Check for Updates:

      • Navigate to System → Updates
      • Review available updates
      • Read release notes

    2. Create Backup:

      • Always backup before upgrading
      • Test backup restoration
      • Take volume snapshot in Klutch.sh

    3. Perform Update:

      • Click Install Updates
      • Wait for update to complete
      • Restart services as needed

    4. Verify System:

      • Check all services still working
      • Review logs for errors
      • Test critical functionality

Resources and Further Reading

Conclusion

Deploying FreedomBox on Klutch.sh brings together the privacy and freedom benefits of self-hosting with the convenience and reliability of managed cloud infrastructure. With automatic HTTPS, persistent storage, easy scaling, and professional-grade reliability, you can run your personal server without the complexity of managing physical hardware.

This guide covered everything from basic deployment to advanced configuration, security hardening, service setup, and troubleshooting. Whether you’re looking to escape centralized cloud services, need secure communication tools, or want complete control over your digital life, FreedomBox on Klutch.sh provides a powerful, privacy-focused solution.

Remember to keep your FreedomBox updated, maintain regular backups, monitor service health, and follow security best practices. For additional help or questions, refer to the resources above or reach out to the FreedomBox and Klutch.sh communities.