8.3 KiB
Installation Guide
This guide provides detailed instructions for setting up buun-stack - a Kubernetes development environment accessible from anywhere via the internet.
Prerequisites
Linux Machine
A Linux PC with the following requirements:
- Docker support
- SSH daemon configured for remote access
- Passwordless sudo execution (required for k3sup)
- Low power consumption recommended for 24/7 operation
Cloud Services
- Domain Registrar: For registering and managing domain names
- DNS Provider: DNS managed by Cloudflare (for tunnel setup)
- Container Registry: For storing container images (optional)
Local Development Machine
- Linux or macOS preferred
- mise installed
Setting Up the Linux Machine
Basic Configuration
- Install Linux with Docker support
- Configure SSH daemon for remote access
- Set up passwordless sudo execution
Arch Linux Specific Configuration
For Arch Linux users, configure sshd to support keyboard-interactive authentication with PAM:
Create /etc/ssh/sshd_config.d/10-pamauth.conf:
KbdInteractiveAuthentication yes
AuthenticationMethods publickey keyboard-interactive:pam
Restart the sshd service:
sudo systemctl restart sshd
Create sudoers file for your account (replace buun with your username):
/etc/sudoers.d/buun:
buun ALL=(ALL:ALL) NOPASSWD: ALL
Installing Required Tools
Clone the Repository
git clone https://github.com/buun-ch/buun-stack
cd buun-stack
Install mise
Follow the Getting Started guide to install mise.
Install Project Tools
mise install
mise ls -l # Verify installed tools
This installs the following tools:
- gomplate: Template engine for configuration files
- gum: Interactive CLI for user input
- helm: Kubernetes package manager
- just: Task runner for installation commands
- kubelogin: kubectl authentication plugin
- vault: HashiCorp Vault CLI client
Creating the Kubernetes Cluster
Generate Configuration
just env::setup # Creates .env.local with your configuration
This interactive command collects:
- SSH hostname for local access
- External domain names for services
- Keycloak realm name
- Other configuration options
Deploy k3s Cluster
just k8s::install
kubectl get nodes # Verify cluster status
The installation uses k3sup to deploy k3s on the remote machine and automatically configures kubeconfig on your local machine.
Configuring Cloudflare Tunnel
Create the Tunnel
- Navigate to Cloudflare Dashboard > Zero Trust > Network > Tunnels
- Click "+ Create a tunnel"
- Select "Cloudflared"
- Enter tunnel name
- Click "Save tunnel"
Install cloudflared
Debian/Red Hat
Follow the instructions displayed in the Cloudflare dashboard.
Arch Linux
paru cloudflared
Create the systemd unit file:
sudo systemctl edit --force --full cloudflared.service
Add the following content (replace <TOKEN VALUE> with your token):
[Unit]
Description=Cloudflare Tunnel
After=network.target
[Service]
TimeoutStartSec=0
Type=notify
ExecStart=/usr/bin/cloudflared tunnel --loglevel debug --logfile /var/log/cloudflared/cloudflared.log run --token <TOKEN VALUE>
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=multi-user.target
Enable and start the service:
sudo systemctl enable cloudflared
sudo systemctl start cloudflared
Configure Public Hostnames
In the Cloudflare tunnel configuration, add these public hostnames:
ssh.yourdomain.com→ SSH localhost:22vault.yourdomain.com→ HTTPS localhost:443 (No TLS Verify)auth.yourdomain.com→ HTTPS localhost:443 (No TLS Verify)k8s.yourdomain.com→ HTTPS localhost:6443 (No TLS Verify)
Note: Enable "No TLS Verify" for HTTPS services as they use self-signed certificates internally.
Configure SSH Access
macOS
Install cloudflared:
brew install cloudflared
Configure SSH in ~/.ssh/config:
Host yourdomain
Hostname ssh.yourdomain.com
ProxyCommand /opt/homebrew/bin/cloudflared access ssh --hostname %h
Test connection:
ssh yourdomain
Installing Core Components
Longhorn - Distributed Storage
Longhorn provides distributed block storage with support for PersistentVolumes and NFS exports.
Prerequisites for Longhorn
Install open-iscsi on the Linux machine:
# Arch Linux
sudo pacman -S open-iscsi
sudo systemctl enable iscsid
sudo systemctl start iscsid
# Ubuntu/Debian
sudo apt-get install open-iscsi
sudo systemctl enable iscsid
sudo systemctl start iscsid
If you use NFS volumes, install nfs-utils/nfs-common:
# Arch Linux
sudo pacman -S nfs-utils
# Ubuntu/Debian
sudo apt-get install nfs-common
Install Longhorn
just longhorn::install
HashiCorp Vault - Secrets Management (Optional but Recommended)
Vault provides centralized secrets management for the entire cluster. While optional, its installation is recommended as it enhances security and simplifies credential management.
When you install Vault, the External Secrets Operator is also deployed. This operator synchronizes secrets from Vault to Kubernetes Secrets, allowing your applications to seamlessly access credentials and sensitive data stored in Vault through standard Kubernetes Secret resources.
just vault::install
Important: Store the displayed root token securely. You'll need it for initial configuration.
PostgreSQL - Database Cluster
PostgreSQL provides database services for Keycloak and applications.
just postgres::install
Keycloak - Identity Management
Keycloak provides identity and access management with OIDC/OAuth2 support.
just keycloak::install
Configuring OIDC Authentication
Create Keycloak Realm
just keycloak::create-realm
The default realm name is buunstack. To change it, edit .env.local:
KEYCLOAK_REALM=your-realm
Configure Vault OIDC Integration
just vault::setup-oidc-auth
This enables Vault authentication via Keycloak OIDC.
Create Initial User
just keycloak::create-user
Follow the prompts to create username and password.
Enable Kubernetes OIDC Authentication
just k8s::setup-oidc-auth
This creates a new kubectl context with OIDC authentication. If your original context is minipc1, the OIDC context will be minipc1-oidc.
Testing the Setup
Verify OIDC Authentication
kubectl config use-context minipc1-oidc
kubectl get nodes
Test Pod Operations
Create test resources:
kubectl apply -f debug/debug-pod.yaml
kubectl apply -f debug/debug-svc.yaml
Test kubectl exec:
kubectl exec debug-pod -it -- sh
# Inside the pod:
uname -a
ps x
exit
Test port forwarding:
kubectl port-forward svc/debug-service 8080:8080
# In another terminal:
curl localhost:8080
Test Vault OIDC
export VAULT_ADDR=https://vault.yourdomain.com
vault login -method=oidc
vault kv get -mount=secret -field=password postgres/admin
Troubleshooting
Check Pod Logs
kubectl logs -n <namespace> <pod-name>
Check Service Status
kubectl get pods -A
kubectl get svc -A
Reset OIDC Configuration
If OIDC authentication fails:
- Check Keycloak is running:
kubectl get pods -n keycloak - Verify realm exists: Browse to
https://auth.yourdomain.com - Re-run OIDC setup:
just k8s::setup-oidc-auth
Connection Issues
If unable to connect via Cloudflare Tunnel:
- Check tunnel status in Cloudflare dashboard
- Verify cloudflared service:
sudo systemctl status cloudflared - Check DNS resolution:
nslookup k8s.yourdomain.com
Next Steps
- Create custom recipes in
custom.justfor your workflows - Deploy applications using Helm charts
- Set up CI/CD pipelines
- Configure monitoring and observability