This repository provides a framework and guide for deploying K3s and Element Server Suite (ESS) in disconnected or airgapped environments with cross-platform support for Linux (AMD64/ARM64), Windows (WSL2), and macOS (ARM64).

We utilize Hauler by Rancher Government to collect, package, and distribute assets. Hauler simplifies the airgap process by representing assets as content and collections, allowing users to easily fetch, store, package, and distribute with declarative manifests or the command line.

Review the comprehensive K3s + ESS Quickstart Guide!

High Level Workflow:

Collection -> Across the Airgap -> Distribution

Detailed Workflow:

fetch -> validate -> save -> | <airgap> | -> load -> validate -> distribute

• K3s: Lightweight, certified Kubernetes distribution perfect for edge and airgap scenarios
• ESS: Complete Matrix communication stack (Synapse, Element Web, Element Admin, MAS, Matrix RTC)
• Cross-Platform: Support for Linux, Windows (WSL2), and macOS (Docker Desktop/Rancher Desktop)
• Airgap-First: Designed for disconnected environments with offline installation support

• hauler/k3s - provides the content manifest for K3s (Lightweight Kubernetes)
  • currently supports: K3S: v1.33.5
  • platforms: linux/amd64, linux/arm64 (Windows/macOS use Linux binaries via WSL2/containers)
• hauler/ess-helm - provides the content manifest for Element Server Suite
  • currently supports: ESS Helm Chart: v25.11.0
  • includes: Synapse, Element Web, Element Admin, MAS, Matrix RTC, PostgreSQL, HAProxy
• hauler/helm - provides the content manifest for Helm
  • currently supports: Helm: v3.19.0

Note: This repository focuses on K3s + ESS deployments for airgapped Matrix communication infrastructure.

This repository includes a GitHub Action workflow that automatically builds and releases airgapped image stores and OS dependencies.

📖 Documentation:

• Quick Start Guide - Get started in 5 minutes
• Workflow Documentation - Detailed workflow information
• Secrets Configuration - Configure Cloudflare R2 uploads

Quick Release Process:

git tag v1.0.0 && git push origin v1.0.0

Then download from Releases and follow the K3s + ESS Quickstart Guide.

This repository includes comprehensive testing workflows for airgapped deployments to ensure all assets are available locally.

📖 Testing Documentation:

• Airgap Testing Guide - Complete CI testing workflow documentation
• Local Testing Guide - Local K3s testing with fast iteration
• Quick Reference - Common commands and troubleshooting

Key Features:

• ✅ GitHub Actions - Automated testing on K3d cluster
• ✅ Local Testing - Run airgap tests locally with real K3s
• ✅ Network monitoring to detect external access
• ✅ Image source verification
• ✅ OS package repository validation
• ✅ Iterative improvement workflow
• ✅ PR comments with test results overview

Run CI Test:

gh workflow run test-airgap.yaml

Run Local Test:

sudo .github/workflows/scripts/local-airgap-test.sh

Both tests validate that K3s and ESS can be deployed completely from local sources without internet access. Use the local test for faster iteration during development.

This repository uses Renovate to automatically track and update component versions:

• ESS Helm Chart - Automatically detects new releases and updates image versions
• K3s - Tracks new Kubernetes versions
• Helm - Monitors Helm binary releases
• Hauler - Watches for new Hauler versions

📖 Documentation:

• Renovate Setup Guide - Complete automation documentation

Key Features:

• ✅ Automatic PRs - Renovate creates PRs for new versions every weekend
• ✅ Smart ESS Updates - When ESS Helm Chart bumps, automatically:
  • Deploys the new version to a K3d cluster
  • Extracts actual image versions from the deployment
  • Updates the Hauler manifest with correct images
  • Commits changes back to the PR
• ✅ Version Sync - Updates versions across multiple files consistently

View Renovate Status:

# Check for pending dependency updates
gh pr list --label dependencies

# https://github.com/hauler-dev/hauler
curl -sfL https://get.hauler.dev | bash

# date = $(date +"%m%d%Y")