SKStacks — Sovereign Infrastructure Configs

Infrastructure-as-code configurations for the SKWorld sovereign stack.

---

Versions

Version	Status	Description
v2/	🟢 Active development	Multi-platform (Swarm + K8s + RKE2), pluggable secret backends
v1/	🟢 Published, one service at a time	Docker Swarm + Ansible, the framework current production clusters run on

See v2/README.md for the full v2 architecture and quick start, or v1/README.md + the v1 service catalog for v1.

---

Framework / instance model (v1 and v2 alike)

This repo is the framework: the Ansible roles/playbooks (v1) or Helm/Kustomize/Terraform (v2) that define each service, with no estate-specific values baked in. A separate, private instance repo pins this framework as a framework/ git submodule at a released tag (skstacks-vMAJOR.MINOR.PATCH), and supplies everything specific to that estate: the inventory, the vault tree with real secrets, and which optional services it deploys. Upgrading an instance means bumping the submodule to a newer tag, not editing framework code in place. See v2/docs/INSTANCE-MODEL.md for the full model (it predates v1's publication but applies the same way).

---

v2 Highlights

• 3 secret backends: vault-file (Ansible) · HashiCorp Vault · CapAuth/PGP sovereign
• 3 platforms: Docker Swarm · Kubernetes · RKE2 (Rancher, CIS-hardened)
• 4 CI/CD targets: Forgejo Actions · GitHub Actions · GitLab CI · ArgoCD GitOps
• Sanitized public templates — no real secrets, all CHANGEME_* placeholders

---

Standalone Services

Directory	Service	Purpose
coturn/	coturn TURN/STUN server	WebRTC NAT traversal relay for turn.skworld.io

---

coturn — Sovereign TURN Server

STUN/TURN server for WebRTC ICE negotiation. Used by SKComm's WebRTC transport and SKChat voice/data channels as the NAT traversal fallback when direct P2P fails.

Domain: turn.skworld.io

Architecture

WebRTC Peer A                coturn                WebRTC Peer B
     │                          │                         │
     │── STUN binding req ──────→                         │
     │←── mapped address ────────                         │
     │                          │                         │
     │  (direct ICE fails)       │                         │
     │── TURN Allocate ──────────→                         │
     │←── relay address ─────────                         │
     │── TURN CreatePermission ──→ (for Peer B's IP)       │
     │                          │                         │
     │══ encrypted DTLS-SRTP through relay ════════════════│

For Tailscale-connected peers, the Tailscale 100.x IP is used as a host ICE candidate and Tailscale DERP handles relay — coturn is only needed for non-tailnet peers.

Quick Setup

1. Install coturn:

# Debian/Ubuntu
sudo apt install coturn

# Arch/Manjaro
sudo pacman -S coturn

2. Generate a shared secret:

openssl rand -hex 32
# → copy this into turnserver.conf static-auth-secret AND
#   into ~/.skcomm/config.yml transports.webrtc.settings.turn_secret
#   (or set SKCOMM_TURN_SECRET env var)

3. Deploy the config:

sudo cp coturn/turnserver.conf /etc/coturn/turnserver.conf
# Edit: set static-auth-secret, uncomment external-ip=YOUR_PUBLIC_IP

4. Set up TLS (recommended):

certbot certonly --standalone -d turn.skworld.io
# Then uncomment the cert/pkey lines in turnserver.conf

5. Open firewall ports:

ufw allow 3478/udp    # STUN/TURN
ufw allow 3478/tcp    # TURN over TCP
ufw allow 5349/tcp    # TURN over TLS
ufw allow 49152:65535/udp  # UDP relay range

6. Start and enable:

sudo systemctl enable --now coturn
sudo systemctl status coturn

Configuration Summary

Setting	Value
STUN/TURN port	3478 (UDP + TCP)
TLS TURN port	5349
UDP relay range	49152–65535
Realm	turn.skworld.io
Auth	HMAC-SHA1 time-limited credentials
Credential TTL	86400s (24h)
Private IP relay	Denied (SSRF protection)

Client Integration (SKComm)

# ~/.skcomm/config.yml
transports:
  webrtc:
    enabled: true
    priority: 1
    settings:
      turn_server: "turn:turn.skworld.io:3478"
      turn_secret: "${SKCOMM_TURN_SECRET}"   # same secret as static-auth-secret

The SKComm WebRTC transport generates HMAC-SHA1 time-limited credentials automatically:

# credential = HMAC-SHA1(secret, f"{expiry}:{username}")
# username    = f"{expiry}:{agent_name}"

Testing

# Test STUN binding (should return your public IP)
stun turn.skworld.io

# Test TURN allocation (requires valid credentials)
turnutils_uclient -u "<expiry>:<username>" -w "<credential>" turn.skworld.io

# Check logs
journalctl -u coturn -f
tail -f /var/log/coturn/turnserver.log

---

License

AGPL-3.0-or-later. Part of the smilinTux sovereign stack.