Merge pull request #74 from outis1one/claude/zealous-feynman-odDrh

Claude/zealous feynman od drh
2026-06-08 15:08:33 -04:00
parent 95ac16efbd 551c254b89
commit 6d2ffaac4a
19 changed files with 10065 additions and 8 deletions
@@ -66,8 +66,8 @@ Update them any time with `sudo ./setup.sh configure`.
 | Group | Services |
 |-------|---------|
 | `base` | `net-tools`, `ncdu`, `git`, `curl`, `wget`, `htop`, `tree`, `zip`/`unzip`, `ca-certificates`, `gnupg`, `jq`, `rsync`; `glow` (terminal markdown reader, Charm apt repo) |
-| `homelab` | `caddy`, `crowdsec`, `authelia`, `homeassistant` |
-| `utilities` | `actualbudget`, `ddclient`, `filebrowser`, `fmd`, `gatus`, `magicmirror`, `mail-archiver`, `mealie`, `meshcentral`, `ntfy`, `portainer`, `rustdesk`, `syncthing`, `traccar`, `unifi`, `uptimekuma`, `vaultwarden`, `watchyourlan`, `watchtower`, `wg-easy` |
+| `homelab` | `caddy`, `crowdsec`, `authelia`, `homeassistant`, `asterisk` |
+| `utilities` | `actualbudget`, `ddclient`, `filebrowser`, `fmd`, `gatus`, `magicmirror`, `mail-archiver`, `mattermost`, `mealie`, `meshcentral`, `nextcloud`, `ntfy`, `onlyoffice`, `portainer`, `rustdesk`, `syncthing`, `traccar`, `unifi`, `uptimekuma`, `vaultwarden`, `watchyourlan`, `watchtower`, `wg-easy` |
 | `media` | `arm`, `audiobookshelf`, `emby`, `immich`, `jellyfin`, `lyrion` |
 | `cameras` | `frigate`, `frigate-audio`, `frigate-notify`, `sky-cam` |
 | `gaming` | `js99er`, `minecraft`, `wolf`, `wolf-pair` |
@@ -297,10 +297,16 @@ configure_caddy_for_service() {

    echo ""
    echo "Enter the full domain for $SERVICE_NAME:"
-    echo "  Examples: $DEFAULT_SUBDOMAIN.example.com, $DEFAULT_SUBDOMAIN.yourdomain.com"
+    local _default_domain=""
+    if [ -n "$SITE_DOMAIN" ] && [ "$SITE_DOMAIN" != "example.com" ]; then
+        _default_domain="$DEFAULT_SUBDOMAIN.$SITE_DOMAIN"
+        echo "  Default: $_default_domain"
+    else
+        echo "  Examples: $DEFAULT_SUBDOMAIN.example.com, $DEFAULT_SUBDOMAIN.yourdomain.com"
+    fi
    echo ""
    local SERVICE_DOMAIN=""
-    prompt_text "Domain:" "" SERVICE_DOMAIN
+    prompt_text "Domain [${_default_domain:-required}]:" "$_default_domain" SERVICE_DOMAIN
    if [ -z "$SERVICE_DOMAIN" ]; then
        echo "  ⚠ No domain provided, skipping Caddy configuration."; return 0
    fi
@@ -0,0 +1,507 @@
+#!/bin/bash
+# services/asterisk.sh — Easy Asterisk PBX with self-hosted coturn TURN server.
+# Part of the modular post-install system (sourced by setup.sh).
+#
+# Based on https://github.com/outis1one/easy-asterisk
+# Source files vendored in vendor/easy-asterisk/
+# Personal/home-lab use only. Not for commercial or emergency services.
+#
+# Can also be run standalone on any machine:
+#   sudo bash asterisk.sh
+# (Docker must already be installed when run standalone)
+
+# ── Standalone bootstrap ──────────────────────────────────────────────────────
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    [[ "$(id -u)" == "0" ]] || { echo "Run with sudo: sudo bash $0"; exit 1; }
+
+    _SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    _COMMON="$_SELF_DIR/../lib/common.sh"
+
+    if [[ -f "$_COMMON" ]]; then
+        # shellcheck source=../lib/common.sh
+        source "$_COMMON"
+    else
+        log_info()    { echo -e "\033[0;34m[INFO]\033[0m $*"; }
+        log_success() { echo -e "\033[0;32m[OK]\033[0m $*"; }
+        log_warning() { echo -e "\033[1;33m[WARN]\033[0m $*"; }
+        log_error()   { echo -e "\033[0;31m[ERROR]\033[0m $*" >&2; }
+
+        require_docker() {
+            command -v docker &>/dev/null || {
+                log_error "Docker not found. Install it first:"
+                log_error "  curl -fsSL https://get.docker.com | sudo sh"
+                return 1
+            }
+            docker compose version &>/dev/null || {
+                log_error "Docker Compose plugin missing:"
+                log_error "  sudo apt-get install -y docker-compose-plugin"
+                return 1
+            }
+        }
+
+        ensure_docker_dir_ownership() {
+            chown -R "$ACTUAL_USER:$ACTUAL_USER" "$@" 2>/dev/null || true
+        }
+
+        prompt_text() {
+            local _q="$1" _def="$2" _var="$3" _r
+            [[ "${UNATTENDED:-false}" == "true" ]] && { eval "$_var='$_def'"; return; }
+            read -r -p "  $_q " _r
+            eval "$_var='${_r:-$_def}'"
+        }
+
+        prompt_yn() {
+            local _q="$1" _def="$2" _var="$3" _r
+            [[ "${UNATTENDED:-false}" == "true" ]] && { eval "$_var='$_def'"; return; }
+            read -r -p "  $_q " _r
+            eval "$_var='${_r:-$_def}'"
+        }
+
+        configure_caddy_for_service() {
+            local _name="$1" _upstream="$2" _subdomain="$3" _extra="${4:-}"
+            local _caddy_dir="$DOCKER_DIR/caddy"
+            local _caddyfile="$_caddy_dir/Caddyfile"
+
+            if [[ ! -d "$_caddy_dir" ]]; then
+                log_info "Access $_name directly on port ${_upstream##*:}."
+                return 0
+            fi
+
+            echo ""
+            local _do_caddy=""
+            read -r -p "  Configure Caddy reverse proxy for $_name? [y/N]: " _do_caddy
+            [[ "${_do_caddy,,}" == "y" ]] || {
+                log_info "Skipping — access at: http://localhost:${_upstream##*:}"
+                return 0
+            }
+
+            local _domain=""
+            read -r -p "  Domain (e.g. ${_subdomain}.${SITE_DOMAIN:-example.com}): " _domain
+            [[ -n "$_domain" ]] || { log_warning "No domain entered — skipping Caddy."; return 0; }
+
+            if [[ -f "$_caddyfile" ]]; then
+                local _bk="$_caddy_dir/Caddyfile.backup.$(date +%Y%m%d-%H%M%S)"
+                cp "$_caddyfile" "$_bk"
+                log_info "Backed up Caddyfile to $(basename "$_bk")"
+            else
+                touch "$_caddyfile"
+            fi
+
+            if grep -q "^${_domain}" "$_caddyfile" 2>/dev/null; then
+                log_warning "$_domain already in Caddyfile"
+                local _ow=""
+                read -r -p "  Overwrite? [y/N]: " _ow
+                [[ "${_ow,,}" == "y" ]] || { log_info "Keeping existing entry."; return 0; }
+                sed -i "/^${_domain}/,/^}/d" "$_caddyfile"
+            fi
+
+            cat >> "$_caddyfile" << CBLOCK
+
+# $_name
+$_domain {
+    reverse_proxy $_upstream
+
+    header {
+        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
+        X-Content-Type-Options "nosniff"
+        X-Frame-Options "SAMEORIGIN"
+        Referrer-Policy "strict-origin-when-cross-origin"
+    }
+
+    log {
+        output file /var/log/caddy/${_domain}.log
+        format json
+    }
+${_extra}
+}
+CBLOCK
+
+            log_success "Added $_domain to Caddyfile"
+            docker exec caddy caddy fmt --overwrite /etc/caddy/Caddyfile 2>/dev/null || true
+            if docker exec caddy caddy reload --config /etc/caddy/Caddyfile 2>/dev/null; then
+                log_success "$_name accessible at: https://$_domain"
+            else
+                log_warning "Reload failed — check: docker logs caddy"
+                log_info "Manual reload: docker exec caddy caddy reload --config /etc/caddy/Caddyfile"
+            fi
+        }
+
+        write_readme() {
+            local _dir="$1"; shift
+            mkdir -p "$_dir"
+            cat > "$_dir/README.md"
+        }
+    fi
+
+    ACTUAL_USER="${ACTUAL_USER:-${SUDO_USER:-$USER}}"
+    ACTUAL_HOME="$(getent passwd "$ACTUAL_USER" 2>/dev/null | cut -d: -f6 || echo "${HOME:-/root}")"
+    DOCKER_DIR="${DOCKER_DIR:-$ACTUAL_HOME/docker}"
+    DRY_RUN="${DRY_RUN:-false}"
+    UNATTENDED="${UNATTENDED:-false}"
+    SITE_TZ="${SITE_TZ:-$(cat /etc/timezone 2>/dev/null || echo UTC)}"
+    SITE_DOMAIN="${SITE_DOMAIN:-example.com}"
+    SITE_CADDY_NET="${SITE_CADDY_NET:-caddy_net}"
+
+    register_service() { :; }
+    _RUN_STANDALONE=1
+fi
+# ─────────────────────────────────────────────────────────────────────────────
+
+register_service asterisk homelab "Easy Asterisk PBX + coturn TURN server (home intercom/VoIP)" 5061
+
+install_asterisk() {
+    require_docker || return 1
+    log_info "Installing Easy Asterisk PBX..."
+
+    local EA_DIR="$DOCKER_DIR/asterisk"
+
+    # Locate vendored source files (works when sourced by setup.sh or run standalone)
+    local _script_dir
+    _script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)" \
+        || _script_dir="$(dirname "$(realpath "$0" 2>/dev/null || echo "$0")")"
+    local VENDOR_DIR="$_script_dir/../vendor/easy-asterisk"
+    VENDOR_DIR="$(cd "$VENDOR_DIR" 2>/dev/null && pwd)" || VENDOR_DIR=""
+
+    if [[ -z "$VENDOR_DIR" || ! -f "$VENDOR_DIR/easy-asterisk-v0.10.0.sh" ]]; then
+        log_warning "Vendored easy-asterisk files not found at $VENDOR_DIR"
+        log_warning "Expected: vendor/easy-asterisk/ alongside services/ directory"
+        log_error "Cannot install — run from the ubuntu-post-install repo root."
+        return 1
+    fi
+
+    if [ "$DRY_RUN" = true ]; then
+        echo "[DRY-RUN] Would create $EA_DIR"
+        echo "[DRY-RUN] Would copy vendored easy-asterisk files (Dockerfile, scripts, entrypoints)"
+        echo "[DRY-RUN] Would write docker-compose.yml, .env"
+        echo "[DRY-RUN] Would open UFW ports for SIP/RTP/TURN"
+        return 0
+    fi
+
+    mkdir -p "$EA_DIR/docker" "$EA_DIR/scripts"
+    ensure_docker_dir_ownership "$EA_DIR"
+    cd "$EA_DIR" || return 1
+
+    # ── Copy vendored source files ────────────────────────────────────────────
+    log_info "Copying Easy Asterisk source files from vendor/..."
+
+    cp "$VENDOR_DIR/easy-asterisk-v0.10.0.sh"        "$EA_DIR/easy-asterisk.sh"
+    cp "$VENDOR_DIR/Dockerfile"                        "$EA_DIR/Dockerfile"
+    cp "$VENDOR_DIR/docker/entrypoint.sh"              "$EA_DIR/docker/entrypoint.sh"
+    cp "$VENDOR_DIR/docker/coturn-entrypoint.sh"       "$EA_DIR/docker/coturn-entrypoint.sh"
+    cp "$VENDOR_DIR/scripts/vpn-diagnostics.sh"        "$EA_DIR/scripts/vpn-diagnostics.sh"
+    cp "$VENDOR_DIR/scripts/dns-whitelist.sh"          "$EA_DIR/scripts/dns-whitelist.sh"
+
+    chmod 750 "$EA_DIR/easy-asterisk.sh"
+    chmod 755 "$EA_DIR/docker/entrypoint.sh" "$EA_DIR/docker/coturn-entrypoint.sh"
+    chmod 755 "$EA_DIR/scripts/vpn-diagnostics.sh" "$EA_DIR/scripts/dns-whitelist.sh"
+
+    log_success "Source files copied"
+
+    # The Dockerfile COPYs easy-asterisk-v0.10.0.sh (the versioned name).
+    # We keep easy-asterisk.sh as the canonical name and make a real copy
+    # with the versioned filename so Docker COPY works reliably (no symlinks).
+    cp "$EA_DIR/easy-asterisk.sh" "$EA_DIR/easy-asterisk-v0.10.0.sh"
+
+    # ── FQDN setup ────────────────────────────────────────────────────────────
+    echo ""
+    echo "  Easy Asterisk can run in two modes:"
+    echo ""
+    echo "  LAN/VPN — UDP transport, no TLS, no TURN."
+    echo "            Simple setup for devices on your local network or WireGuard/Tailscale."
+    echo ""
+    echo "  FQDN    — TLS + SRTP + coturn TURN relay."
+    echo "            Works from anywhere: LAN, cellular, hotel WiFi, Proton VPN."
+    echo "            Requires a domain name pointing to this server's public IP."
+    echo ""
+
+    local DOMAIN_NAME=""
+    prompt_text "FQDN for this server (e.g. asterisk.${SITE_DOMAIN:-example.com}) [blank for LAN-only]:" "" DOMAIN_NAME
+
+    local LAN_ONLY=false
+    if [[ -z "$DOMAIN_NAME" ]]; then
+        LAN_ONLY=true
+        log_info "LAN/VPN-only mode — TLS and TURN disabled."
+    else
+        log_info "FQDN mode: $DOMAIN_NAME"
+        echo ""
+        echo "  Required router port forwards:"
+        printf "    %-22s %s\n" "5061/tcp"        "SIP TLS signaling"
+        printf "    %-22s %s\n" "3478/udp+tcp"    "STUN/TURN (NAT traversal)"
+        printf "    %-22s %s\n" "10000-20000/udp" "RTP media (Asterisk)"
+        printf "    %-22s %s\n" "49152-49252/udp" "TURN relay range (coturn)"
+        echo ""
+    fi
+
+    # ── Generate TURN password ────────────────────────────────────────────────
+    local TURN_PASSWORD
+    TURN_PASSWORD="$(openssl rand -base64 18 2>/dev/null | tr -dc 'a-zA-Z0-9' | head -c 24 \
+        || tr -dc 'A-Za-z0-9' </dev/urandom | head -c 24)"
+
+    # ── docker-compose.yml ────────────────────────────────────────────────────
+    # Uses the real upstream Dockerfile (FROM ubuntu:24.04 + full Asterisk install)
+    # with host networking for RTP/NAT, and the custom coturn entrypoint.
+    cat > docker-compose.yml << 'COMPOSE_EOF'
+# Easy Asterisk — managed by ubuntu-post-install
+# Manage: docker exec -it easy-asterisk easy-asterisk
+# Source: https://github.com/outis1one/easy-asterisk
+
+services:
+
+  asterisk:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: easy-asterisk
+    # Host networking: required for RTP (10000-20000/udp) and proper NAT detection.
+    # SIP clients connect directly to the host IP; Caddy is only used for the web admin.
+    network_mode: host
+    depends_on:
+      coturn:
+        condition: service_started
+    volumes:
+      - asterisk-config:/etc/asterisk
+      - easy-asterisk-config:/etc/easy-asterisk
+      - asterisk-logs:/var/log/asterisk
+      - asterisk-spool:/var/spool/asterisk
+      - asterisk-lib:/var/lib/asterisk
+      # Bind-mount the management script so updates don't require a rebuild
+      - ./easy-asterisk.sh:/usr/local/bin/easy-asterisk:ro
+    environment:
+      - DOMAIN_NAME=${DOMAIN_NAME}
+      - ENABLE_TLS=${ENABLE_TLS:-y}
+      - PUBLIC_IP=${PUBLIC_IP:-}
+      - LOCAL_CIDR=${LOCAL_CIDR:-}
+      - HAS_VLANS=${HAS_VLANS:-n}
+      - VLAN_SUBNETS=${VLAN_SUBNETS:-}
+      - TURN_ENABLED=${TURN_ENABLED:-y}
+      - TURN_SERVER=${TURN_SERVER}
+      - TURN_USERNAME=${TURN_USERNAME:-easyasterisk}
+      - TURN_PASSWORD=${TURN_PASSWORD}
+      - RTP_START=${RTP_START:-10000}
+      - RTP_END=${RTP_END:-20000}
+      - WEB_ADMIN_PORT=${WEB_ADMIN_PORT:-8080}
+      - WEB_ADMIN_AUTH_DISABLED=${WEB_ADMIN_AUTH_DISABLED:-false}
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "asterisk", "-rx", "core show version"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+
+  coturn:
+    image: coturn/coturn:latest
+    container_name: easy-asterisk-coturn
+    network_mode: host
+    user: root
+    entrypoint: ["/coturn-entrypoint.sh"]
+    volumes:
+      - ./docker/coturn-entrypoint.sh:/coturn-entrypoint.sh:ro
+    environment:
+      - PUBLIC_IP=${PUBLIC_IP:-}
+    command:
+      - -n
+      - --listening-port=${TURN_PORT:-3478}
+      - --listening-ip=0.0.0.0
+      - --fingerprint
+      - --lt-cred-mech
+      - --user=${TURN_USERNAME:-easyasterisk}:${TURN_PASSWORD}
+      - --realm=${DOMAIN_NAME:-localhost}
+      - --min-port=${TURN_RELAY_MIN:-49152}
+      - --max-port=${TURN_RELAY_MAX:-49252}
+      - --no-tls
+      - --no-dtls
+      - --no-cli
+      - --no-multicast-peers
+      - --log-file=stdout
+    restart: unless-stopped
+
+volumes:
+  asterisk-config:
+  easy-asterisk-config:
+  asterisk-logs:
+  asterisk-spool:
+  asterisk-lib:
+COMPOSE_EOF
+
+    # ── .env ─────────────────────────────────────────────────────────────────
+    cat > .env << ENV
+# Easy Asterisk — environment configuration
+# Edit and restart: docker compose down && docker compose up -d
+
+# FQDN pointing to this server's public IP (required for remote/TLS mode)
+DOMAIN_NAME=$DOMAIN_NAME
+
+# Public IP — leave empty to auto-detect
+PUBLIC_IP=
+
+# TLS — always 'y' for remote access, 'n' for LAN-only
+ENABLE_TLS=$( [[ "$LAN_ONLY" == "true" ]] && echo "n" || echo "y" )
+
+# Local network CIDR — auto-detected if empty
+LOCAL_CIDR=
+
+# Additional subnets for site-to-site VPNs (WireGuard/Tailscale mesh, NOT client-side)
+HAS_VLANS=n
+VLAN_SUBNETS=
+
+# TURN/STUN credentials — must match in both Asterisk and coturn
+# Regenerate: openssl rand -base64 18 | tr -dc 'a-zA-Z0-9' | head -c 24
+TURN_USERNAME=easyasterisk
+TURN_PASSWORD=$TURN_PASSWORD
+
+# TURN server address — auto-set based on FQDN or LAN mode above
+# LAN-only: leave empty (coturn not used). FQDN mode: domain:port
+TURN_SERVER=$( [[ "$LAN_ONLY" == "true" ]] && echo "" || echo "${DOMAIN_NAME}:3478" )
+
+# TURN port (change to 3479 if 3478 conflicts with UniFi controller or Mattermost)
+TURN_PORT=3478
+
+# TURN relay port range — forward this range on your router
+TURN_RELAY_MIN=49152
+TURN_RELAY_MAX=49252
+
+# RTP media port range — forward this range on your router
+RTP_START=10000
+RTP_END=20000
+
+# Web admin interface
+WEB_ADMIN_PORT=8080
+WEB_ADMIN_AUTH_DISABLED=false
+ENV
+
+    chmod 600 .env
+    chown "$ACTUAL_USER:$ACTUAL_USER" .env
+
+    # ── UFW firewall rules ────────────────────────────────────────────────────
+    if command -v ufw >/dev/null 2>&1 && ufw status 2>/dev/null | grep -q "Status: active"; then
+        log_info "Opening UFW ports for Asterisk..."
+        ufw allow 5060/udp  comment "Asterisk SIP UDP"         >/dev/null
+        ufw allow 5060/tcp  comment "Asterisk SIP TCP"         >/dev/null
+        ufw allow 5061/tcp  comment "Asterisk SIP TLS"         >/dev/null
+        ufw allow 8080/tcp  comment "Asterisk web admin"       >/dev/null
+        ufw allow 8088/tcp  comment "Asterisk HTTP provision"  >/dev/null
+        ufw allow 8089/tcp  comment "Asterisk HTTPS provision" >/dev/null
+        ufw allow 3478/udp  comment "coturn STUN/TURN UDP"     >/dev/null
+        ufw allow 3478/tcp  comment "coturn STUN/TURN TCP"     >/dev/null
+        ufw allow 10000:20000/udp comment "Asterisk RTP media"  >/dev/null
+        ufw allow 49152:49252/udp comment "coturn TURN relay"   >/dev/null
+        log_success "UFW rules added"
+    else
+        log_info "UFW not active — open these ports manually if needed:"
+        log_info "  5060/udp+tcp, 5061/tcp"
+        log_info "  8080/tcp (web admin), 8088/tcp, 8089/tcp (provisioning)"
+        log_info "  3478/udp+tcp (STUN/TURN)"
+        log_info "  10000-20000/udp (RTP), 49152-49252/udp (TURN relay)"
+    fi
+
+    chown -R "$ACTUAL_USER:$ACTUAL_USER" "$EA_DIR"
+
+    # ── Caddy for web admin (with optional Authelia SSO) ──────────────────────
+    # The web admin has no built-in auth; let Authelia gate it if available.
+    local EA_EXTRA_BLOCK=""
+    if [ -d "$DOCKER_DIR/authelia" ]; then
+        local _use_auth=""
+        prompt_yn "Protect Asterisk web admin with Authelia SSO? (y/n):" "y" _use_auth
+        if [[ "$_use_auth" =~ ^[Yy]$ ]]; then
+            EA_EXTRA_BLOCK="    import authelia"
+            # Tell Asterisk's web admin to skip its own auth — Authelia handles it
+            sed -i "s/^WEB_ADMIN_AUTH_DISABLED=.*/WEB_ADMIN_AUTH_DISABLED=true/" "$EA_DIR/.env"
+            log_info "WEB_ADMIN_AUTH_DISABLED=true set (Authelia will handle authentication)"
+        fi
+    fi
+    configure_caddy_for_service "Asterisk Web Admin" "localhost:8080" "asterisk" "$EA_EXTRA_BLOCK"
+
+    # ── README ────────────────────────────────────────────────────────────────
+    write_readme "$EA_DIR" << MD
+# Easy Asterisk PBX
+
+Home intercom / VoIP system built on Asterisk with self-hosted coturn TURN server.
+Personal/home-lab use only. Source: https://github.com/outis1one/easy-asterisk
+
+## Access
+- Web admin:  http://localhost:8080/clients
+- FQDN:       $( [[ -n "$DOMAIN_NAME" ]] && echo "$DOMAIN_NAME" || echo "(LAN-only — no domain)" )
+
+## Management
+\`\`\`bash
+# Interactive management menu (add devices, provisioning, diagnostics)
+docker exec -it easy-asterisk easy-asterisk
+
+# VPN diagnostics
+docker exec -it easy-asterisk vpn-diagnostics
+
+# DNS whitelist check
+docker exec -it easy-asterisk dns-whitelist
+\`\`\`
+
+## Adding devices
+Run the management menu → Device Management → Add device.
+Each device gets a SIP extension, password, and setup instructions
+for Linphone (remote provisioning) or Baresip (manual).
+
+## Connection modes
+- **LAN/VPN**: UDP, no encryption — local network or WireGuard/Tailscale
+- **FQDN**: TLS + SRTP + coturn TURN relay — works from anywhere
+
+## Caddy and phone calls
+Asterisk uses **host networking** — SIP signaling and RTP media connect
+directly to the server, completely bypassing Caddy. Do NOT put SIP ports
+behind a reverse proxy (Contact header rewriting will break registration).
+
+Caddy only handles the **web admin** (port 8080) for HTTPS browser access.
+
+The **provisioning server** (ports 8088/8089) is Asterisk's built-in HTTP
+server for Linphone XML config delivery. Access it directly by IP/domain,
+not through Caddy — SIP clients fetch it at startup before registering.
+
+## Router port forwards (FQDN mode)
+| Port | Protocol | Service |
+|------|----------|---------|
+| 5061 | TCP | SIP TLS signaling |
+| 3478 | UDP+TCP | STUN/TURN |
+| 10000-20000 | UDP | RTP media |
+| 49152-49252 | UDP | TURN relay |
+| 8088 | TCP | Provisioning (Linphone XML) — optional |
+
+## TURN credentials (for SIP clients behind strict NAT)
+- Server:   \${DOMAIN_NAME}:3478
+- Username: easyasterisk
+- Password: (see .env → TURN_PASSWORD)
+
+## Manage
+\`\`\`bash
+cd $EA_DIR
+docker compose up -d                                      # start
+docker compose down                                       # stop
+docker compose logs -f                                    # logs
+docker compose pull                                       # update coturn image
+docker compose build --pull && docker compose up -d      # rebuild Asterisk image
+\`\`\`
+MD
+
+    # ── Build and start ───────────────────────────────────────────────────────
+    echo ""
+    local START_EA=""
+    prompt_yn "Build and start Easy Asterisk now? (y/n):" "y" START_EA
+    if [[ "$START_EA" =~ ^[Yy]$ ]]; then
+        log_info "Building Asterisk image (first build takes a few minutes)..."
+        if docker compose build --pull 2>&1 | tail -5; then
+            if docker compose up -d; then
+                log_success "Easy Asterisk started"
+                echo ""
+                echo "  Web admin:   http://localhost:8080/clients"
+                echo "  Management:  docker exec -it easy-asterisk easy-asterisk"
+                echo ""
+                log_info "Next: add your first device via the management menu."
+            else
+                log_warning "Start failed — check: docker compose logs"
+            fi
+        else
+            log_warning "Build failed — check output above"
+        fi
+    fi
+    echo ""
+}
+
+# Run immediately when executed directly (deferred until after function definition)
+[[ "${_RUN_STANDALONE:-0}" == 1 ]] && install_asterisk
@@ -242,6 +242,25 @@ HA_CONFIG
        configure_caddy_for_service "Home Assistant" "homeassistant:8123" "home"
    fi

+    write_readme "$HOMEASSISTANT_DIR" << MD
+# Home Assistant
+
+Home automation hub. Built-in auth — no Authelia needed.
+
+## Access
+- URL: http://localhost:8123
+- First run: create your admin account through the onboarding wizard
+
+## Manage
+\`\`\`bash
+cd $HOMEASSISTANT_DIR
+docker compose up -d                          # start
+docker compose down                           # stop
+docker compose logs -f                        # logs
+docker compose pull && docker compose up -d   # update
+\`\`\`
+MD
+
    local START_HA=""
    prompt_yn "Start Home Assistant now? (y/n):" "y" START_HA
    if [ "$START_HA" = "y" ] || [ "$START_HA" = "Y" ]; then
@@ -420,7 +420,13 @@ COMPOSE
    log_success "js99er configured at $JS99ER_DIR"

    # ── 5. Reverse proxy (no-ops if Caddy isn't installed locally) ───────────
-    configure_caddy_for_service "js99er" "js99er:80" "js99er"
+    local JS99ER_EXTRA_BLOCK=""
+    if [ -d "$DOCKER_DIR/authelia" ]; then
+        local _use_auth=""
+        prompt_yn "Protect js99er with Authelia SSO? (y/n):" "y" _use_auth
+        [[ "$_use_auth" =~ ^[Yy]$ ]] && JS99ER_EXTRA_BLOCK="    import authelia"
+    fi
+    configure_caddy_for_service "js99er" "js99er:80" "js99er" "$JS99ER_EXTRA_BLOCK"

    # ── 6. Build & start ─────────────────────────────────────────────────────
    local START_JS99ER=""
@@ -442,7 +448,24 @@ COMPOSE
        fi
    fi

-    # ── 7. Access summary ────────────────────────────────────────────────────
+    write_readme "$JS99ER_DIR" << MD
+# js99er — TI-99/4A Emulator
+
+Browser-based TI-99/4A emulator. No built-in auth — protect with Authelia if exposing externally.
+
+## Access
+- URL: http://localhost:${JS99ER_PORT}
+- Online (no install): https://js99er.net
+
+## Manage
+\`\`\`bash
+cd $JS99ER_DIR
+docker compose up -d --build               # start (or rebuild)
+docker compose down                        # stop
+docker compose logs -f                     # logs
+\`\`\`
+MD
+
    echo ""
    echo "  Access at:  http://localhost:${JS99ER_PORT}"
    echo "  If you set a domain above, it is also reachable via that domain (HTTPS)."
@@ -283,7 +283,15 @@ MM_COMPOSE
        log_success "MagicMirror instance $i configured at $MM_DIR (port $MM_PORT)"

        # Offer Caddy only for first instance
-        [ "$i" -eq 1 ] && configure_caddy_for_service "MagicMirror" "magicmirror-${MM_PORT}:8080" "mirror"
+        if [ "$i" -eq 1 ]; then
+            local MM_EXTRA_BLOCK=""
+            if [ -d "$DOCKER_DIR/authelia" ]; then
+                local _use_auth=""
+                prompt_yn "Protect MagicMirror with Authelia SSO? (y/n):" "y" _use_auth
+                [[ "$_use_auth" =~ ^[Yy]$ ]] && MM_EXTRA_BLOCK="    import authelia"
+            fi
+            configure_caddy_for_service "MagicMirror" "magicmirror-${MM_PORT}:8080" "mirror" "$MM_EXTRA_BLOCK"
+        fi

        local START_MM=""
        prompt_yn "Start instance $i now? (y/n):" "y" START_MM
@@ -0,0 +1,442 @@
+#!/bin/bash
+# services/mattermost.sh — Team messaging with voice/video calls (Mattermost + coturn).
+# Part of the modular post-install system (sourced by setup.sh).
+#
+# Mattermost Team Edition with PostgreSQL and a dedicated coturn TURN server
+# (port 3479 — distinct from Easy Asterisk's coturn on 3478).
+#
+# Can also be run standalone on any machine:
+#   sudo bash mattermost.sh
+# (Docker must already be installed when run standalone)
+
+# ── Standalone bootstrap ──────────────────────────────────────────────────────
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    [[ "$(id -u)" == "0" ]] || { echo "Run with sudo: sudo bash $0"; exit 1; }
+
+    _SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    _COMMON="$_SELF_DIR/../lib/common.sh"
+
+    if [[ -f "$_COMMON" ]]; then
+        # shellcheck source=../lib/common.sh
+        source "$_COMMON"
+    else
+        log_info()    { echo -e "\033[0;34m[INFO]\033[0m $*"; }
+        log_success() { echo -e "\033[0;32m[OK]\033[0m $*"; }
+        log_warning() { echo -e "\033[1;33m[WARN]\033[0m $*"; }
+        log_error()   { echo -e "\033[0;31m[ERROR]\033[0m $*" >&2; }
+
+        require_docker() {
+            command -v docker &>/dev/null || {
+                log_error "Docker not found. Install it first:"
+                log_error "  curl -fsSL https://get.docker.com | sudo sh"
+                return 1
+            }
+            docker compose version &>/dev/null || {
+                log_error "Docker Compose plugin missing:"
+                log_error "  sudo apt-get install -y docker-compose-plugin"
+                return 1
+            }
+        }
+
+        generate_password() {
+            local _len="${1:-32}"
+            tr -dc 'A-Za-z0-9' </dev/urandom | head -c "$_len"
+        }
+
+        ensure_docker_dir_ownership() {
+            chown -R "$ACTUAL_USER:$ACTUAL_USER" "$@" 2>/dev/null || true
+        }
+
+        prompt_text() {
+            local _q="$1" _def="$2" _var="$3" _r
+            [[ "${UNATTENDED:-false}" == "true" ]] && { eval "$_var='$_def'"; return; }
+            read -r -p "  $_q " _r
+            eval "$_var='${_r:-$_def}'"
+        }
+
+        prompt_yn() {
+            local _q="$1" _def="$2" _var="$3" _r
+            [[ "${UNATTENDED:-false}" == "true" ]] && { eval "$_var='$_def'"; return; }
+            read -r -p "  $_q " _r
+            eval "$_var='${_r:-$_def}'"
+        }
+
+        configure_caddy_for_service() {
+            local _name="$1" _upstream="$2" _subdomain="$3" _extra="${4:-}"
+            local _caddy_dir="$DOCKER_DIR/caddy"
+            local _caddyfile="$_caddy_dir/Caddyfile"
+
+            if [[ ! -d "$_caddy_dir" ]]; then
+                log_info "Access $_name directly on port ${_upstream##*:}."
+                return 0
+            fi
+
+            echo ""
+            local _do_caddy=""
+            read -r -p "  Configure Caddy reverse proxy for $_name? [y/N]: " _do_caddy
+            [[ "${_do_caddy,,}" == "y" ]] || {
+                log_info "Skipping — access at: http://localhost:${_upstream##*:}"
+                return 0
+            }
+
+            local _domain=""
+            read -r -p "  Domain (e.g. ${_subdomain}.${SITE_DOMAIN:-example.com}): " _domain
+            [[ -n "$_domain" ]] || { log_warning "No domain entered — skipping Caddy."; return 0; }
+
+            if [[ -f "$_caddyfile" ]]; then
+                local _bk="$_caddy_dir/Caddyfile.backup.$(date +%Y%m%d-%H%M%S)"
+                cp "$_caddyfile" "$_bk"
+                log_info "Backed up Caddyfile to $(basename "$_bk")"
+            else
+                touch "$_caddyfile"
+            fi
+
+            if grep -q "^${_domain}" "$_caddyfile" 2>/dev/null; then
+                log_warning "$_domain already in Caddyfile"
+                local _ow=""
+                read -r -p "  Overwrite? [y/N]: " _ow
+                [[ "${_ow,,}" == "y" ]] || { log_info "Keeping existing entry."; return 0; }
+                sed -i "/^${_domain}/,/^}/d" "$_caddyfile"
+            fi
+
+            cat >> "$_caddyfile" << CBLOCK
+
+# $_name
+$_domain {
+    reverse_proxy $_upstream
+
+    header {
+        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
+        X-Content-Type-Options "nosniff"
+        X-Frame-Options "SAMEORIGIN"
+        Referrer-Policy "strict-origin-when-cross-origin"
+    }
+
+    log {
+        output file /var/log/caddy/${_domain}.log
+        format json
+    }
+${_extra}
+}
+CBLOCK
+
+            log_success "Added $_domain to Caddyfile"
+            docker exec caddy caddy fmt --overwrite /etc/caddy/Caddyfile 2>/dev/null || true
+            if docker exec caddy caddy reload --config /etc/caddy/Caddyfile 2>/dev/null; then
+                log_success "$_name accessible at: https://$_domain"
+            else
+                log_warning "Reload failed — check: docker logs caddy"
+                log_info "Manual reload: docker exec caddy caddy reload --config /etc/caddy/Caddyfile"
+            fi
+        }
+
+        write_readme() {
+            local _dir="$1"; shift
+            mkdir -p "$_dir"
+            cat > "$_dir/README.md"
+        }
+    fi
+
+    ACTUAL_USER="${ACTUAL_USER:-${SUDO_USER:-$USER}}"
+    ACTUAL_HOME="$(getent passwd "$ACTUAL_USER" 2>/dev/null | cut -d: -f6 || echo "${HOME:-/root}")"
+    DOCKER_DIR="${DOCKER_DIR:-$ACTUAL_HOME/docker}"
+    DRY_RUN="${DRY_RUN:-false}"
+    UNATTENDED="${UNATTENDED:-false}"
+    SITE_TZ="${SITE_TZ:-$(cat /etc/timezone 2>/dev/null || echo UTC)}"
+    SITE_DOMAIN="${SITE_DOMAIN:-example.com}"
+    SITE_CADDY_NET="${SITE_CADDY_NET:-caddy_net}"
+
+    register_service() { :; }
+    _RUN_STANDALONE=1
+fi
+# ─────────────────────────────────────────────────────────────────────────────
+
+register_service mattermost utilities "Team messaging with voice/video calls (Mattermost + coturn)" 8065
+
+install_mattermost() {
+    require_docker || return 1
+    log_info "Installing Mattermost Team Edition..."
+
+    local DIR="$DOCKER_DIR/mattermost"
+
+    if [ "$DRY_RUN" = true ]; then
+        echo "[DRY-RUN] Would create $DIR with subdirectories: data logs config plugins db"
+        echo "[DRY-RUN] Would generate DB password, MM secret key, and TURN secret"
+        echo "[DRY-RUN] Would write docker-compose.yml and .env"
+        echo "[DRY-RUN] Would open UFW ports: 3479/udp+tcp, 49153-49352/udp"
+        echo "[DRY-RUN] Would configure Caddy reverse proxy for Mattermost"
+        return 0
+    fi
+
+    # ── Create directory structure ────────────────────────────────────────────
+    mkdir -p "$DIR"/{data,logs,config,plugins,db}
+    # Mattermost runs as UID 2000 inside the container
+    chown -R 2000:2000 "$DIR/data" "$DIR/logs" "$DIR/config" "$DIR/plugins"
+    ensure_docker_dir_ownership "$DIR/db"
+    ensure_docker_dir_ownership "$DIR"
+    cd "$DIR" || return 1
+
+    # ── Generate secrets ──────────────────────────────────────────────────────
+    local DB_PASS MM_SECRET TURN_SECRET
+    DB_PASS="$(generate_password 32)"
+    MM_SECRET="$(generate_password 48)"
+    TURN_SECRET="$(openssl rand -hex 32 2>/dev/null || generate_password 32)"
+
+    # ── Site URL ──────────────────────────────────────────────────────────────
+    local SITE_URL="http://localhost:8065"
+    if [[ -n "$SITE_DOMAIN" && "$SITE_DOMAIN" != "example.com" ]]; then
+        SITE_URL="https://chat.${SITE_DOMAIN}"
+    fi
+    local CONFIGURED_SITEURL=""
+    prompt_text "Mattermost site URL [${SITE_URL}]:" "$SITE_URL" CONFIGURED_SITEURL
+    [[ -n "$CONFIGURED_SITEURL" ]] && SITE_URL="$CONFIGURED_SITEURL"
+
+    # ── docker-compose.yml ────────────────────────────────────────────────────
+    cat > docker-compose.yml << COMPOSE
+# Mattermost Team Edition — generated by ubuntu-post-install
+# Manage: docker compose up -d / down / logs -f
+# Admin setup: \${MATTERMOST_SITE_URL}/signup_user_complete
+
+name: mattermost
+
+services:
+
+  db:
+    image: postgres:15-alpine
+    container_name: mattermost-db
+    restart: unless-stopped
+    security_opt:
+      - no-new-privileges:true
+    pids_limit: 100
+    volumes:
+      - ./db:/var/lib/postgresql/data
+    environment:
+      - POSTGRES_USER=mattermost
+      - POSTGRES_PASSWORD=\${DB_PASS}
+      - POSTGRES_DB=mattermost
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U mattermost"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  mattermost:
+    image: mattermost/mattermost-team-edition:latest
+    container_name: mattermost
+    restart: unless-stopped
+    security_opt:
+      - no-new-privileges:true
+    pids_limit: 200
+    depends_on:
+      db:
+        condition: service_healthy
+    ports:
+      - "8065:8065"
+      - "8443:8443/udp"   # Calls plugin RTC server (WebRTC direct path)
+    volumes:
+      - ./data:/mattermost/data
+      - ./logs:/mattermost/logs
+      - ./config:/mattermost/config
+      - ./plugins:/mattermost/plugins
+    environment:
+      - MM_SQLSETTINGS_DRIVERNAME=postgres
+      - MM_SQLSETTINGS_DATASOURCE=postgres://mattermost:\${DB_PASS}@db:5432/mattermost?sslmode=disable
+      - MM_SERVICESETTINGS_SITEURL=\${MATTERMOST_SITE_URL}
+      - MM_PLUGINSETTINGS_ENABLEUPLOADS=true
+      - MM_SERVICESETTINGS_ENABLELOCALMODE=true
+      - TZ=\${TZ}
+    networks:
+      - default
+      - caddy_net
+
+  coturn:
+    image: coturn/coturn:latest
+    container_name: mattermost-coturn
+    restart: unless-stopped
+    network_mode: host
+    command:
+      - -n
+      - --listening-port=3479
+      - --tls-listening-port=5350
+      - --listening-ip=0.0.0.0
+      - --fingerprint
+      - --use-auth-secret
+      - --static-auth-secret=\${TURN_SECRET}
+      - --realm=\${TURN_REALM}
+      - --min-port=49153
+      - --max-port=49352
+      - --no-tls
+      - --no-dtls
+      - --no-cli
+      - --no-multicast-peers
+      - --log-file=stdout
+
+networks:
+  default:
+  caddy_net:
+    external: true
+    name: \${CADDY_NET:-caddy_net}
+COMPOSE
+
+    # ── .env ──────────────────────────────────────────────────────────────────
+    cat > .env << ENV
+# Mattermost — environment configuration
+# Edit and restart: docker compose down && docker compose up -d
+
+# PostgreSQL password (do not change after first start without migrating data)
+DB_PASS=$DB_PASS
+
+# Mattermost secret key (used for signing session tokens)
+MM_SECRET=$MM_SECRET
+
+# Site URL — must match the public URL clients use to access Mattermost
+MATTERMOST_SITE_URL=$SITE_URL
+
+# Timezone
+TZ=$SITE_TZ
+
+# TURN server shared secret for Mattermost Calls plugin
+# Generate a new one: openssl rand -hex 32
+TURN_SECRET=$TURN_SECRET
+
+# TURN realm (typically your domain)
+TURN_REALM=${SITE_DOMAIN:-localhost}
+
+# Caddy network name
+CADDY_NET=$SITE_CADDY_NET
+ENV
+
+    chmod 600 .env
+    chown "$ACTUAL_USER:$ACTUAL_USER" .env
+
+    # ── UFW firewall rules ─────────────────────────────────────────────────────
+    echo ""
+    log_info "Firewall — Mattermost coturn uses port 3479 (avoiding conflict with Easy Asterisk on 3478)."
+    if command -v ufw >/dev/null 2>&1 && ufw status 2>/dev/null | grep -q "Status: active"; then
+        log_info "Opening UFW ports for Mattermost..."
+        ufw allow 8443/udp  comment "Mattermost Calls RTC server"  >/dev/null
+        ufw allow 3479/udp  comment "Mattermost coturn STUN/TURN"  >/dev/null
+        ufw allow 3479/tcp  comment "Mattermost coturn STUN/TURN"  >/dev/null
+        ufw allow 49153:49352/udp comment "Mattermost coturn relay" >/dev/null
+        log_success "UFW rules added"
+    else
+        log_info "UFW not active — add these rules manually if needed:"
+        echo "    ufw allow 8443/udp  # Mattermost Calls RTC"
+        echo "    ufw allow 3479/udp && ufw allow 3479/tcp  # coturn STUN/TURN"
+        echo "    ufw allow 49153:49352/udp  # coturn relay"
+    fi
+
+    # ── Router port-forward instructions ──────────────────────────────────────
+    echo ""
+    echo "  ┌─────────────────────────────────────────────────────────────────┐"
+    echo "  │  Router port-forwards needed for Mattermost Calls (external)   │"
+    echo "  ├──────────────────┬──────────┬──────────────────────────────────┤"
+    echo "  │  Port(s)         │ Protocol │ Service                          │"
+    echo "  ├──────────────────┼──────────┼──────────────────────────────────┤"
+    echo "  │  8443            │ UDP      │ Calls plugin RTC (direct WebRTC) │"
+    echo "  │  3479            │ UDP+TCP  │ coturn STUN/TURN                 │"
+    echo "  │  49153–49352     │ UDP      │ coturn relay range               │"
+    echo "  └──────────────────┴──────────┴──────────────────────────────────┘"
+    echo ""
+    echo "  ⚠  WebRTC (Calls) requires HTTPS. Calls will not work if Mattermost"
+    echo "     is accessed over plain HTTP. Configure Caddy with a domain below."
+    echo ""
+
+    ensure_docker_dir_ownership "$DIR"
+
+    # ── Caddy reverse proxy ───────────────────────────────────────────────────
+    # SITEURL is already set from SITE_DOMAIN above. configure_caddy_for_service
+    # will pre-fill the domain prompt with chat.$SITE_DOMAIN.
+    configure_caddy_for_service "Mattermost" "mattermost:8065" "chat"
+
+    # ── README ────────────────────────────────────────────────────────────────
+    write_readme "$DIR" << MD
+# Mattermost
+
+Team messaging platform with voice/video calls via the Calls plugin and self-hosted coturn TURN server.
+
+## Access
+- Direct:  http://localhost:8065
+- Via Caddy: see your configured domain (e.g. https://chat.${SITE_DOMAIN:-example.com})
+
+## Initial admin setup
+Visit: \`${SITE_URL}/signup_user_complete\`
+
+The first user to sign up becomes the System Admin.
+
+## Calls plugin (voice/video)
+The Mattermost Calls plugin provides voice/video channels.
+**WebRTC requires HTTPS** — calls will not work over plain HTTP.
+
+### Enable the plugin
+1. Go to **System Console → Plugins → Plugin Management**
+2. Enable the **Calls** plugin (pre-installed in Team Edition)
+
+### Configure ICE / TURN server
+1. Go to **System Console → Plugins → Calls**
+2. Set **RTC Server Address**: your server's public IP or domain
+3. Set **TURN server URL**: \`turn:<your-server-or-ip>:3479\`
+4. Set **TURN credentials type**: Static credentials (auth secret)
+5. Set **TURN static auth secret**: (see \`TURN_SECRET\` in \`$DIR/.env\`)
+6. Save and test a call in a channel
+
+Direct WebRTC (port 8443/UDP) is tried first; coturn relay is the fallback
+for clients behind strict NAT (cellular, hotel WiFi, Proton VPN, etc.).
+
+## Router port-forwards (for external calls)
+| Port(s)      | Protocol | Service                         |
+|--------------|-----------|---------------------------------|
+| 8443         | UDP       | Calls plugin RTC (direct path)  |
+| 3479         | UDP+TCP   | coturn STUN/TURN                |
+| 49153–49352  | UDP       | coturn relay range              |
+
+## Manage
+\`\`\`bash
+cd $DIR
+docker compose up -d                         # start
+docker compose down                          # stop
+docker compose logs -f                       # all logs
+docker compose logs -f mattermost            # app logs only
+docker compose logs -f coturn                # TURN server logs
+docker compose pull && docker compose up -d  # update images
+\`\`\`
+
+## Backup
+Important paths to back up:
+- \`$DIR/data/\`    — uploaded files and attachments
+- \`$DIR/config/\`  — server configuration
+- \`$DIR/plugins/\` — installed plugins
+- \`$DIR/db/\`      — PostgreSQL data directory
+- \`$DIR/.env\`     — secrets and configuration
+
+## Configuration
+Main config file: \`$DIR/config/config.json\` (created on first start).
+Environment variables in \`.env\` override config.json values.
+After editing .env: \`docker compose down && docker compose up -d\`
+MD
+
+    # ── Start ──────────────────────────────────────────────────────────────────
+    echo ""
+    local START=""
+    prompt_yn "Start Mattermost now? (y/n):" "y" START
+    if [[ "$START" =~ ^[Yy]$ ]]; then
+        log_info "Pulling images and starting Mattermost (first start may take a minute)..."
+        if docker compose pull 2>&1 | tail -3 && docker compose up -d; then
+            log_success "Mattermost started"
+            echo ""
+            echo "  App:         http://localhost:8065"
+            echo "  Admin setup: ${SITE_URL}/signup_user_complete"
+            echo ""
+            log_info "Enable the Calls plugin and configure TURN at:"
+            log_info "  System Console → Plugins → Calls"
+            log_info "  TURN URL:    turn:<your-public-ip>:3479"
+            log_info "  TURN secret: (see $DIR/.env → TURN_SECRET)"
+        else
+            log_warning "Start failed — check: docker compose logs"
+        fi
+    fi
+    echo ""
+}
+
+# Run immediately when executed directly (deferred until after function definition)
+[[ "${_RUN_STANDALONE:-0}" == 1 ]] && install_mattermost
@@ -2489,6 +2489,25 @@ NETEOF
    echo "  Run:  sudo ./setup.sh backup"
    echo ""

+    write_readme "$MC_DIR" << MD
+# Minecraft — ${MC_NAME}
+
+## Manage
+\`\`\`bash
+cd $MC_DIR
+docker compose up -d --build   # start (builds image on first run)
+docker compose down            # stop
+docker compose logs -f         # logs
+docker compose pull && docker compose up -d --build  # update
+\`\`\`
+
+## Backups
+World data lives in \`./data\` — covered by Kopia/Borg if installed.
+\`\`\`bash
+sudo ./setup.sh backup
+\`\`\`
+MD
+
    # ── Optional: start server and run pre-gen now ──────────────────────────────
    local START_MC=""
    prompt_yn "Start the Minecraft server now? (first build takes a few minutes) (y/n) [y]:" "y" START_MC
@@ -0,0 +1,362 @@
+#!/bin/bash
+# services/nextcloud.sh — Self-hosted cloud storage with SMB/local file access (Nextcloud).
+# Part of the modular post-install system (sourced by setup.sh).
+#
+# Uses a custom Dockerfile (nextcloud:apache + smbclient) so SMB external storage
+# works without AIO.  All data uses bind mounts under ~/docker/nextcloud/ so that
+# Kopia/Borg backup scripts cover everything automatically.
+#
+# Can also be run standalone on any machine:
+#   sudo bash nextcloud.sh
+# (Docker must already be installed when run standalone)
+
+# ── Standalone bootstrap ──────────────────────────────────────────────────────
+# Detected when the script is executed directly rather than sourced by setup.sh.
+# Sets up helpers and globals, then defers execution until after the function
+# definition at the bottom of this file.
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    [[ "$(id -u)" == "0" ]] || { echo "Run with sudo: sudo bash $0"; exit 1; }
+
+    _SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    _COMMON="$_SELF_DIR/../lib/common.sh"
+
+    if [[ -f "$_COMMON" ]]; then
+        # Full repo present — use the real helpers (picks up ~/docker/.config too)
+        # shellcheck source=../lib/common.sh
+        source "$_COMMON"
+    else
+        # One-off copy — inline minimal stubs
+        log_info()    { echo -e "\033[0;34m[INFO]\033[0m $*"; }
+        log_success() { echo -e "\033[0;32m[OK]\033[0m $*"; }
+        log_warning() { echo -e "\033[1;33m[WARN]\033[0m $*"; }
+        log_error()   { echo -e "\033[0;31m[ERROR]\033[0m $*" >&2; }
+
+        require_docker() {
+            command -v docker &>/dev/null || {
+                log_error "Docker not found. Install it first:"
+                log_error "  curl -fsSL https://get.docker.com | sudo sh"
+                return 1
+            }
+            docker compose version &>/dev/null || {
+                log_error "Docker Compose plugin missing:"
+                log_error "  sudo apt-get install -y docker-compose-plugin"
+                return 1
+            }
+        }
+
+        ensure_docker_dir_ownership() {
+            chown -R "$ACTUAL_USER:$ACTUAL_USER" "$@" 2>/dev/null || true
+        }
+
+        generate_password() {
+            local _len="${1:-32}"
+            tr -dc 'A-Za-z0-9' < /dev/urandom | head -c "$_len"
+        }
+
+        # Match common.sh's eval-based pattern so local vars in install_* are set correctly
+        prompt_text() {
+            local _q="$1" _def="$2" _var="$3" _r
+            [[ "${UNATTENDED:-false}" == "true" ]] && { eval "$_var='$_def'"; return; }
+            read -r -p "  $_q " _r
+            eval "$_var='${_r:-$_def}'"
+        }
+
+        prompt_yn() {
+            local _q="$1" _def="$2" _var="$3" _r
+            [[ "${UNATTENDED:-false}" == "true" ]] && { eval "$_var='$_def'"; return; }
+            read -r -p "  $_q " _r
+            eval "$_var='${_r:-$_def}'"
+        }
+
+        configure_caddy_for_service() {
+            local _name="$1" _upstream="$2" _subdomain="$3" _extra="${4:-}"
+            local _caddy_dir="$DOCKER_DIR/caddy"
+            local _caddyfile="$_caddy_dir/Caddyfile"
+
+            if [[ ! -d "$_caddy_dir" ]]; then
+                log_info "Access $_name directly on port 8080."
+                return 0
+            fi
+
+            echo ""
+            local _do_caddy=""
+            read -r -p "  Configure Caddy reverse proxy for $_name? [y/N]: " _do_caddy
+            [[ "${_do_caddy,,}" == "y" ]] || {
+                log_info "Skipping — access at: http://localhost:8080"
+                return 0
+            }
+
+            local _domain=""
+            read -r -p "  Domain (e.g. ${_subdomain}.${SITE_DOMAIN:-example.com}): " _domain
+            [[ -n "$_domain" ]] || { log_warning "No domain entered — skipping Caddy."; return 0; }
+
+            # Back up before touching
+            if [[ -f "$_caddyfile" ]]; then
+                local _bk="$_caddy_dir/Caddyfile.backup.$(date +%Y%m%d-%H%M%S)"
+                cp "$_caddyfile" "$_bk"
+                log_info "Backed up Caddyfile to $(basename "$_bk")"
+            else
+                touch "$_caddyfile"
+            fi
+
+            # Remove existing block for this domain if present
+            if grep -q "^${_domain}" "$_caddyfile" 2>/dev/null; then
+                log_warning "$_domain already in Caddyfile"
+                local _ow=""
+                read -r -p "  Overwrite? [y/N]: " _ow
+                [[ "${_ow,,}" == "y" ]] || { log_info "Keeping existing entry."; return 0; }
+                sed -i "/^${_domain}/,/^}/d" "$_caddyfile"
+            fi
+
+            cat >> "$_caddyfile" << CBLOCK
+
+# $_name
+$_domain {
+    reverse_proxy $_upstream
+
+    header {
+        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
+        X-Content-Type-Options "nosniff"
+        X-Frame-Options "SAMEORIGIN"
+        Referrer-Policy "strict-origin-when-cross-origin"
+    }
+
+    log {
+        output file /var/log/caddy/${_domain}.log
+        format json
+    }
+${_extra}
+}
+CBLOCK
+
+            log_success "Added $_domain to Caddyfile"
+            docker exec caddy caddy fmt --overwrite /etc/caddy/Caddyfile 2>/dev/null || true
+            if docker exec caddy caddy reload --config /etc/caddy/Caddyfile 2>/dev/null; then
+                log_success "$_name accessible at: https://$_domain"
+            else
+                log_warning "Reload failed — check: docker logs caddy"
+                log_info "Manual reload: docker exec caddy caddy reload --config /etc/caddy/Caddyfile"
+            fi
+        }
+
+        write_readme() {
+            local _dir="$1"; shift
+            mkdir -p "$_dir"
+            cat > "$_dir/README.md"
+        }
+    fi
+
+    # Globals — ACTUAL_USER/ACTUAL_HOME must come before DOCKER_DIR
+    # ($HOME under sudo is /root, not the real user's home)
+    ACTUAL_USER="${ACTUAL_USER:-${SUDO_USER:-$USER}}"
+    ACTUAL_HOME="$(getent passwd "$ACTUAL_USER" 2>/dev/null | cut -d: -f6 || echo "${HOME:-/root}")"
+    DOCKER_DIR="${DOCKER_DIR:-$ACTUAL_HOME/docker}"
+    DRY_RUN="${DRY_RUN:-false}"
+    UNATTENDED="${UNATTENDED:-false}"
+    SITE_TZ="${SITE_TZ:-$(cat /etc/timezone 2>/dev/null || echo UTC)}"
+    SITE_DOMAIN="${SITE_DOMAIN:-example.com}"
+    SITE_CADDY_NET="${SITE_CADDY_NET:-caddy_net}"
+
+    register_service() { :; }   # no-op — no wizard to register into
+    _RUN_STANDALONE=1
+fi
+# ─────────────────────────────────────────────────────────────────────────────
+
+register_service nextcloud utilities "Self-hosted cloud storage with SMB/local file access (Nextcloud)" 8080
+
+install_nextcloud() {
+    require_docker || return 1
+    log_info "Installing Nextcloud..."
+    local DIR="$DOCKER_DIR/nextcloud"
+
+    if [ "$DRY_RUN" = true ]; then
+        echo "[DRY-RUN] Would create $DIR with:"
+        echo "[DRY-RUN]   Dockerfile (nextcloud:apache + smbclient)"
+        echo "[DRY-RUN]   docker-compose.yml (nextcloud + mariadb:10.11)"
+        echo "[DRY-RUN]   .env with generated DB and admin passwords"
+        echo "[DRY-RUN]   Bind-mount directories: html/ db/ config/ custom_apps/"
+        echo "[DRY-RUN] Would expose Nextcloud on port 8080"
+        echo "[DRY-RUN] Would enable files_external app via occ after deploy"
+        return 0
+    fi
+
+    mkdir -p "$DIR/html" "$DIR/db" "$DIR/config" "$DIR/custom_apps"
+    ensure_docker_dir_ownership "$DIR"
+    cd "$DIR" || return 1
+
+    local DB_PASS NC_ADMIN_PASS TZ_VAL
+    DB_PASS=$(generate_password 32)
+    NC_ADMIN_PASS=$(generate_password 24)
+    TZ_VAL="${SITE_TZ:-$(cat /etc/timezone 2>/dev/null || echo UTC)}"
+
+    # ── Dockerfile — adds SMB support to the official apache image ────────────
+    cat > Dockerfile << 'DOCKERFILE'
+FROM nextcloud:apache
+
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends procps smbclient \
+ && rm -rf /var/lib/apt/lists/*
+DOCKERFILE
+
+    # ── docker-compose.yml — single-quoted EOF prevents variable expansion ────
+    cat > docker-compose.yml << 'EOF'
+name: nextcloud
+
+services:
+  nextcloud:
+    build: .
+    container_name: nextcloud
+    hostname: nextcloud
+    restart: unless-stopped
+    env_file: .env
+    depends_on:
+      - db
+    volumes:
+      - ./html:/var/www/html
+      - ./config:/var/www/html/config
+      - ./custom_apps:/var/www/html/custom_apps
+    ports:
+      - "8080:80"
+    networks:
+      - caddy_net
+
+  db:
+    image: mariadb:10.11
+    container_name: nextcloud-db
+    hostname: nextcloud-db
+    restart: unless-stopped
+    env_file: .env
+    volumes:
+      - ./db:/var/lib/mysql
+    networks:
+      - caddy_net
+
+networks:
+  caddy_net:
+    external: true
+    name: ${CADDY_NET:-caddy_net}
+EOF
+
+    # ── .env — actual variable values (NOT inside the compose heredoc) ────────
+    cat > .env << NC_ENV
+# ── Timezone & network ────────────────────────────────────────────────────────
+TZ=$TZ_VAL
+CADDY_NET=$SITE_CADDY_NET
+
+# ── MariaDB ───────────────────────────────────────────────────────────────────
+MYSQL_ROOT_PASSWORD=$DB_PASS
+MYSQL_DATABASE=nextcloud
+MYSQL_USER=nextcloud
+MYSQL_PASSWORD=$DB_PASS
+MARIADB_AUTO_UPGRADE=1
+
+# ── Nextcloud bootstrap ───────────────────────────────────────────────────────
+# These are used only on the very first startup to create the admin account
+# and wire up the database.  They are ignored on subsequent startups.
+NEXTCLOUD_ADMIN_USER=admin
+NEXTCLOUD_ADMIN_PASSWORD=$NC_ADMIN_PASS
+NEXTCLOUD_DB_TYPE=mysql
+MYSQL_HOST=db
+NC_ENV
+
+    chmod 600 .env
+    chown -R "$ACTUAL_USER:$ACTUAL_USER" "$DIR"
+    log_success "Nextcloud configured at $DIR"
+
+    configure_caddy_for_service "Nextcloud" "nextcloud:80" "cloud"
+
+    write_readme "$DIR" << MD
+# Nextcloud
+
+Self-hosted cloud storage — files, contacts, calendar, notes, and more.
+SMB/local external storage is enabled via a custom Docker image (nextcloud:apache + smbclient).
+
+## Access
+- URL: http://localhost:8080
+- Admin user: \`admin\`
+- Admin password: see \`NEXTCLOUD_ADMIN_PASSWORD\` in \`.env\`
+
+## Directory layout (all bind-mounted — covered by Kopia/Borg backups)
+\`\`\`
+$DIR/
+  html/         # Nextcloud web root (PHP app + uploaded files)
+  config/       # config.php and other Nextcloud config files
+  custom_apps/  # manually installed apps not shipped with Nextcloud
+  db/           # MariaDB data directory
+  Dockerfile    # custom image definition (adds smbclient)
+  docker-compose.yml
+  .env          # secrets — chmod 600
+\`\`\`
+
+## External Storage (SMB / local paths)
+The \`files_external\` app is enabled automatically during setup.
+Add mounts in the Nextcloud web UI:
+**Admin → Administration → External Storage**
+
+Supported backends: Local, SMB/CIFS, FTP, S3, WebDAV, and more.
+
+## Manage
+\`\`\`bash
+cd $DIR
+docker compose up -d                                      # start
+docker compose down                                       # stop
+docker compose logs -f                                    # logs
+docker compose build --pull && docker compose up -d      # rebuild image + update
+docker exec --user www-data nextcloud php occ list        # occ CLI
+\`\`\`
+
+## Backup note
+All data lives under \`$DIR/\` as bind mounts.
+Include this directory in your Kopia/Borg backup policy.
+Run \`docker compose down\` before a cold backup of \`db/\` for consistency,
+or use \`mysqldump\` for a hot backup:
+\`\`\`bash
+docker exec nextcloud-db mysqldump -u nextcloud -p\$MYSQL_PASSWORD nextcloud > nextcloud_db.sql
+\`\`\`
+MD
+
+    local START_NC=""
+    prompt_yn "Start Nextcloud now? (y/n):" "y" START_NC
+    if [ "$START_NC" = "y" ] || [ "$START_NC" = "Y" ]; then
+        docker compose up -d \
+            && log_success "Nextcloud started — first boot may take 1-2 minutes" \
+            || { log_warning "Start failed — check: docker compose logs"; return 1; }
+
+        # Wait for Nextcloud to finish first-boot initialisation before running occ
+        log_info "Waiting for Nextcloud to finish initialising (up to 90 s)..."
+        local _waited=0
+        until docker exec --user www-data nextcloud php occ status --output=json 2>/dev/null \
+              | grep -q '"installed":true'; do
+            sleep 5
+            _waited=$(( _waited + 5 ))
+            if (( _waited >= 90 )); then
+                log_warning "Nextcloud did not finish initialising within 90 s."
+                log_warning "Run the occ command manually once the container is ready:"
+                log_warning "  docker exec --user www-data nextcloud php occ app:enable files_external"
+                break
+            fi
+        done
+
+        if (( _waited < 90 )); then
+            if docker exec --user www-data nextcloud php occ app:enable files_external; then
+                log_success "External Storage app enabled"
+            else
+                log_warning "Could not enable files_external — run manually:"
+                log_warning "  docker exec --user www-data nextcloud php occ app:enable files_external"
+            fi
+        fi
+    fi
+
+    echo ""
+    echo "  URL:            http://localhost:8080"
+    echo "  Admin user:     admin"
+    echo "  Admin password: $NC_ADMIN_PASS"
+    echo "  (Credentials also saved to $DIR/.env)"
+    echo ""
+    echo "  To add SMB or local external storage:"
+    echo "    Nextcloud → Admin → Administration → External Storage"
+    echo ""
+}
+
+# Run immediately when executed directly (deferred until after function definition)
+[[ "${_RUN_STANDALONE:-0}" == 1 ]] && install_nextcloud
@@ -0,0 +1,358 @@
+#!/bin/bash
+# services/onlyoffice.sh — Self-hosted OnlyOffice Document Server.
+# Part of the modular post-install system (sourced by setup.sh).
+#
+# Can also be run standalone on any machine:
+#   sudo bash onlyoffice.sh
+# (Docker must already be installed when run standalone)
+
+# ── Standalone bootstrap ──────────────────────────────────────────────────────
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    [[ "$(id -u)" == "0" ]] || { echo "Run with sudo: sudo bash $0"; exit 1; }
+
+    _SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    _COMMON="$_SELF_DIR/../lib/common.sh"
+
+    if [[ -f "$_COMMON" ]]; then
+        # shellcheck source=../lib/common.sh
+        source "$_COMMON"
+    else
+        log_info()    { echo -e "\033[0;34m[INFO]\033[0m $*"; }
+        log_success() { echo -e "\033[0;32m[OK]\033[0m $*"; }
+        log_warning() { echo -e "\033[1;33m[WARN]\033[0m $*"; }
+        log_error()   { echo -e "\033[0;31m[ERROR]\033[0m $*" >&2; }
+
+        require_docker() {
+            command -v docker &>/dev/null || {
+                log_error "Docker not found. Install it first:"
+                log_error "  curl -fsSL https://get.docker.com | sudo sh"
+                return 1
+            }
+            docker compose version &>/dev/null || {
+                log_error "Docker Compose plugin missing:"
+                log_error "  sudo apt-get install -y docker-compose-plugin"
+                return 1
+            }
+        }
+
+        ensure_docker_dir_ownership() {
+            chown -R "$ACTUAL_USER:$ACTUAL_USER" "$@" 2>/dev/null || true
+        }
+
+        prompt_text() {
+            local _q="$1" _def="$2" _var="$3" _r
+            [[ "${UNATTENDED:-false}" == "true" ]] && { eval "$_var='$_def'"; return; }
+            read -r -p "  $_q " _r
+            eval "$_var='${_r:-$_def}'"
+        }
+
+        prompt_yn() {
+            local _q="$1" _def="$2" _var="$3" _r
+            [[ "${UNATTENDED:-false}" == "true" ]] && { eval "$_var='$_def'"; return; }
+            read -r -p "  $_q " _r
+            eval "$_var='${_r:-$_def}'"
+        }
+
+        configure_caddy_for_service() {
+            local _name="$1" _upstream="$2" _subdomain="$3" _extra="${4:-}"
+            local _caddy_dir="$DOCKER_DIR/caddy"
+            local _caddyfile="$_caddy_dir/Caddyfile"
+
+            if [[ ! -d "$_caddy_dir" ]]; then
+                log_info "Access $_name directly on port ${_upstream##*:}."
+                return 0
+            fi
+
+            echo ""
+            local _do_caddy=""
+            read -r -p "  Configure Caddy reverse proxy for $_name? [y/N]: " _do_caddy
+            [[ "${_do_caddy,,}" == "y" ]] || {
+                log_info "Skipping — access at: http://localhost:${_upstream##*:}"
+                return 0
+            }
+
+            local _domain=""
+            read -r -p "  Domain (e.g. ${_subdomain}.${SITE_DOMAIN:-example.com}): " _domain
+            [[ -n "$_domain" ]] || { log_warning "No domain entered — skipping Caddy."; return 0; }
+
+            if [[ -f "$_caddyfile" ]]; then
+                local _bk="$_caddy_dir/Caddyfile.backup.$(date +%Y%m%d-%H%M%S)"
+                cp "$_caddyfile" "$_bk"
+                log_info "Backed up Caddyfile to $(basename "$_bk")"
+            else
+                touch "$_caddyfile"
+            fi
+
+            if grep -q "^${_domain}" "$_caddyfile" 2>/dev/null; then
+                log_warning "$_domain already in Caddyfile"
+                local _ow=""
+                read -r -p "  Overwrite? [y/N]: " _ow
+                [[ "${_ow,,}" == "y" ]] || { log_info "Keeping existing entry."; return 0; }
+                sed -i "/^${_domain}/,/^}/d" "$_caddyfile"
+            fi
+
+            cat >> "$_caddyfile" << CBLOCK
+
+# $_name
+$_domain {
+    reverse_proxy $_upstream
+
+    header {
+        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
+        X-Content-Type-Options "nosniff"
+        X-Frame-Options "SAMEORIGIN"
+        Referrer-Policy "strict-origin-when-cross-origin"
+    }
+
+    log {
+        output file /var/log/caddy/${_domain}.log
+        format json
+    }
+${_extra}
+}
+CBLOCK
+
+            log_success "Added $_domain to Caddyfile"
+            docker exec caddy caddy fmt --overwrite /etc/caddy/Caddyfile 2>/dev/null || true
+            if docker exec caddy caddy reload --config /etc/caddy/Caddyfile 2>/dev/null; then
+                log_success "$_name accessible at: https://$_domain"
+            else
+                log_warning "Reload failed — check: docker logs caddy"
+                log_info "Manual reload: docker exec caddy caddy reload --config /etc/caddy/Caddyfile"
+            fi
+        }
+
+        write_readme() {
+            local _dir="$1"; shift
+            mkdir -p "$_dir"
+            cat > "$_dir/README.md"
+        }
+
+        generate_password() {
+            local len="${1:-32}"
+            tr -dc 'A-Za-z0-9' </dev/urandom | head -c "$len"
+        }
+    fi
+
+    ACTUAL_USER="${ACTUAL_USER:-${SUDO_USER:-$USER}}"
+    ACTUAL_HOME="$(getent passwd "$ACTUAL_USER" 2>/dev/null | cut -d: -f6 || echo "${HOME:-/root}")"
+    DOCKER_DIR="${DOCKER_DIR:-$ACTUAL_HOME/docker}"
+    DRY_RUN="${DRY_RUN:-false}"
+    UNATTENDED="${UNATTENDED:-false}"
+    SITE_TZ="${SITE_TZ:-$(cat /etc/timezone 2>/dev/null || echo UTC)}"
+    SITE_DOMAIN="${SITE_DOMAIN:-example.com}"
+    SITE_CADDY_NET="${SITE_CADDY_NET:-caddy_net}"
+
+    register_service() { :; }
+    _RUN_STANDALONE=1
+fi
+# ─────────────────────────────────────────────────────────────────────────────
+
+register_service onlyoffice utilities "Self-hosted OnlyOffice Document Server (Nextcloud/FileBrowser)" 8082
+
+# ── Ensure yq v4 is installed ─────────────────────────────────────────────────
+_ensure_yq() {
+    if command -v yq &>/dev/null; then
+        local major
+        major=$(yq --version 2>&1 | grep -oP '(?<=v)\d+' | head -1 || echo 0)
+        [[ "$major" -ge 4 ]] && return 0
+        log_info "yq found but version < 4 — reinstalling..."
+    else
+        log_info "yq not found — installing..."
+    fi
+    local arch
+    arch=$(uname -m)
+    local yq_bin="yq_linux_amd64"
+    [[ "$arch" == "aarch64" || "$arch" == "arm64" ]] && yq_bin="yq_linux_arm64"
+    if wget -qO /usr/local/bin/yq \
+        "https://github.com/mikefarah/yq/releases/latest/download/${yq_bin}" \
+        && chmod +x /usr/local/bin/yq; then
+        log_success "yq installed ($(yq --version 2>&1 | head -1))"
+    else
+        log_warning "Could not install yq — FileBrowser config.yaml will need manual update"
+        return 1
+    fi
+}
+
+# ── Wire OnlyOffice into Nextcloud ────────────────────────────────────────────
+_wire_nextcloud() {
+    local jwt_secret="$1"
+    local nc_dir="$DOCKER_DIR/nextcloud"
+
+    [[ -d "$nc_dir" ]] || return 0
+
+    log_info "Nextcloud detected — wiring OnlyOffice integration..."
+
+    if ! docker ps --format '{{.Names}}' 2>/dev/null | grep -q "^nextcloud$"; then
+        log_warning "Nextcloud container not running — skipping occ wiring."
+        log_info "  Start Nextcloud and re-run: sudo bash $0"
+        return 0
+    fi
+
+    docker exec --user www-data nextcloud php occ app:enable onlyoffice \
+        && log_success "OnlyOffice app enabled in Nextcloud" \
+        || log_warning "app:enable failed — may already be enabled"
+    docker exec --user www-data nextcloud php occ \
+        config:app:set onlyoffice DocumentServerUrl \
+        --value "http://onlyoffice:80/" \
+        && log_success "DocumentServerUrl → http://onlyoffice:80/" \
+        || log_warning "Could not set DocumentServerUrl"
+    docker exec --user www-data nextcloud php occ \
+        config:app:set onlyoffice jwt_secret \
+        --value "$jwt_secret" \
+        && log_success "jwt_secret set" \
+        || log_warning "Could not set jwt_secret"
+    docker exec --user www-data nextcloud php occ \
+        config:app:set onlyoffice jwt_header \
+        --value "AuthorizationJwt" \
+        && log_success "jwt_header set" \
+        || log_warning "Could not set jwt_header"
+}
+
+# ── Wire OnlyOffice into FileBrowser Quantum ──────────────────────────────────
+_wire_filebrowser() {
+    local fb_config="$DOCKER_DIR/filebrowser/data/config.yaml"
+
+    [[ -f "$fb_config" ]] || return 0
+
+    log_info "FileBrowser Quantum detected — updating config.yaml..."
+
+    if ! _ensure_yq; then
+        log_info "Set officeServer manually in $fb_config:"
+        log_info "  officeServer: \"http://onlyoffice:80/\""
+        return 0
+    fi
+
+    yq e -i '.officeServer = "http://onlyoffice:80/"' "$fb_config" \
+        && log_success "FileBrowser config.yaml: officeServer → http://onlyoffice:80/" \
+        || log_warning "yq failed — set officeServer manually in $fb_config"
+
+    if docker ps --format '{{.Names}}' 2>/dev/null | grep -q "^filebrowser$"; then
+        docker restart filebrowser >/dev/null 2>&1 \
+            && log_info "FileBrowser restarted to pick up config change" \
+            || log_warning "Could not restart FileBrowser container"
+    fi
+}
+
+install_onlyoffice() {
+    require_docker || return 1
+    log_info "Installing OnlyOffice Document Server..."
+
+    local DIR="$DOCKER_DIR/onlyoffice"
+
+    if [ "$DRY_RUN" = true ]; then
+        echo "[DRY-RUN] Would create $DIR with docker-compose.yml and .env"
+        echo "[DRY-RUN] Would deploy onlyoffice/documentserver:latest on port 8082"
+        echo "[DRY-RUN] Would install yq if missing"
+        echo "[DRY-RUN] Would wire OnlyOffice into Nextcloud (if running)"
+        echo "[DRY-RUN] Would wire OnlyOffice into FileBrowser Quantum (if present)"
+        return 0
+    fi
+
+    # Always install yq — needed for FBQ config patching
+    _ensure_yq || true
+
+    mkdir -p "$DIR"
+    ensure_docker_dir_ownership "$DIR"
+    cd "$DIR" || return 1
+
+    # Generate JWT secret (or read existing one so re-runs don't rotate it)
+    local JWT_SECRET=""
+    if [[ -f "$DIR/.env" ]]; then
+        JWT_SECRET=$(grep "^JWT_SECRET=" "$DIR/.env" 2>/dev/null | cut -d= -f2-)
+    fi
+    [[ -z "$JWT_SECRET" ]] && JWT_SECRET="$(generate_password 32)"
+
+    cat > docker-compose.yml << 'OO_COMPOSE'
+name: onlyoffice
+
+services:
+  onlyoffice:
+    image: onlyoffice/documentserver:latest
+    container_name: onlyoffice
+    hostname: onlyoffice
+    restart: unless-stopped
+    env_file: .env
+    ports:
+      - "8082:80"
+    networks:
+      - caddy_net
+
+networks:
+  caddy_net:
+    external: true
+    name: ${CADDY_NET:-caddy_net}
+OO_COMPOSE
+
+    cat > .env << OO_ENV
+# OnlyOffice Document Server — environment
+CADDY_NET=$SITE_CADDY_NET
+
+# JWT authentication — keep JWT_SECRET private
+# If you rotate it, update Nextcloud (occ config:app:set onlyoffice jwt_secret)
+# and any other integration that uses this server
+JWT_ENABLED=true
+JWT_SECRET=$JWT_SECRET
+JWT_HEADER=AuthorizationJwt
+OO_ENV
+
+    chmod 600 .env
+    chown -R "$ACTUAL_USER:$ACTUAL_USER" "$DIR"
+
+    configure_caddy_for_service "OnlyOffice" "onlyoffice:80" "office"
+
+    local START=""
+    prompt_yn "Start OnlyOffice now? (y/n):" "y" START
+    if [[ "$START" =~ ^[Yy]$ ]]; then
+        docker compose up -d \
+            && log_success "OnlyOffice started" \
+            || log_warning "Start failed — check: docker compose logs"
+    fi
+
+    # Wire into integrations every run (idempotent)
+    echo ""
+    _wire_nextcloud "$JWT_SECRET"
+    _wire_filebrowser
+
+    write_readme "$DIR" << MD
+# OnlyOffice Document Server
+
+Self-hosted collaborative editing for DOCX, XLSX, PPTX, and ODT files.
+Integrates with Nextcloud and FileBrowser Quantum.
+Port: 8082 (internal 80)
+
+## JWT Secret
+Stored in \`.env\` (chmod 600). If you rotate it:
+1. Update \`JWT_SECRET\` in \`.env\`
+2. Re-run the installer to re-wire all integrations:  \`sudo bash services/onlyoffice.sh\`
+
+## Verify integrations
+\`\`\`bash
+# Nextcloud
+docker exec --user www-data nextcloud php occ config:app:get onlyoffice DocumentServerUrl
+docker exec --user www-data nextcloud php occ config:app:get onlyoffice jwt_secret
+
+# FileBrowser Quantum
+grep officeServer ~/docker/filebrowser/data/config.yaml
+\`\`\`
+
+## Manage
+\`\`\`bash
+cd $DIR
+docker compose up -d                          # start
+docker compose down                           # stop
+docker compose logs -f                        # logs
+docker compose pull && docker compose up -d   # update
+\`\`\`
+MD
+
+    log_success "OnlyOffice installed at $DIR"
+    echo ""
+    echo "  Port:       http://localhost:8082"
+    echo "  JWT Secret: $JWT_SECRET"
+    echo "  (Secret also saved to $DIR/.env)"
+    echo ""
+}
+
+# Run immediately when executed directly (deferred until after function definition)
+[[ "${_RUN_STANDALONE:-0}" == 1 ]] && install_onlyoffice
@@ -399,7 +399,13 @@ COMPOSE
    fi

    # ── 5. Caddy (optional) ───────────────────────────────────────────────────
-    configure_caddy_for_service "wolf-pair" "$WOLFPAIR_PORT" "wolf-pair"
+    local WOLFPAIR_EXTRA_BLOCK=""
+    if [ -d "$DOCKER_DIR/authelia" ]; then
+        local _use_auth=""
+        prompt_yn "Protect wolf-pair with Authelia SSO? (y/n):" "y" _use_auth
+        [[ "$_use_auth" =~ ^[Yy]$ ]] && WOLFPAIR_EXTRA_BLOCK="    import authelia"
+    fi
+    configure_caddy_for_service "wolf-pair" "$WOLFPAIR_PORT" "wolf-pair" "$WOLFPAIR_EXTRA_BLOCK"

    # ── 6. README ─────────────────────────────────────────────────────────────
    write_readme "$WOLFPAIR_DIR" << 'MD'
@@ -927,6 +927,61 @@ PYEOF
    echo "  Set up automatic backups with the backup module:"
    echo "       sudo ./setup.sh backup"
    echo ""
+    # Wolf's web UI (pair/manage) has no built-in auth — protect with Authelia if available
+    local WOLF_EXTRA_BLOCK=""
+    if [ -d "$DOCKER_DIR/authelia" ]; then
+        local _use_auth=""
+        prompt_yn "Protect Wolf web UI with Authelia SSO? (y/n):" "y" _use_auth
+        [[ "$_use_auth" =~ ^[Yy]$ ]] && WOLF_EXTRA_BLOCK="    import authelia"
+    fi
+    configure_caddy_for_service "Wolf" "wolf:47990" "wolf" "$WOLF_EXTRA_BLOCK"
+
+    write_readme "$WOLF_DIR" << MD
+# Wolf — Cloud Gaming (Games-on-Whales)
+
+Stream games to any Moonlight client over your LAN or Tailscale VPN.
+
+## Pair a new client
+1. Open Moonlight on the client device
+2. Add host: this server's IP
+3. Run the pin command on the server:
+\`\`\`bash
+cd $WOLF_DIR && ./manage.sh pin
+\`\`\`
+
+## Manage
+\`\`\`bash
+cd $WOLF_DIR
+./manage.sh start        # start Wolf
+./manage.sh stop         # stop
+./manage.sh restart      # restart
+./manage.sh logs         # live logs
+./manage.sh status       # container status
+./manage.sh update       # pull latest image and restart
+./manage.sh add-apps     # add game launchers
+\`\`\`
+
+## Ports (open on firewall / router)
+| Port(s) | Protocol | Use |
+|---------|----------|-----|
+| 47984–47990 | TCP | Moonlight control |
+| 48010 | TCP | RTSP |
+| 47998–48000 | UDP | RTP video/audio/control |
+
+## Backup
+\`\`\`bash
+sudo ./setup.sh backup   # covers /etc/wolf saves and ES-DE settings
+\`\`\`
+MD
+
+    local START_WOLF=""
+    prompt_yn "Start Wolf now? (y/n):" "y" START_WOLF
+    if [[ "$START_WOLF" =~ ^[Yy]$ ]]; then
+        docker compose up -d \
+            && log_success "Wolf started — pair Moonlight to this server's IP" \
+            || log_warning "Start failed — check: docker compose logs"
+    fi
+
    log_success "Done. Pair Moonlight and play."
 }

@@ -0,0 +1,99 @@
+# ================================================================
+# Easy Asterisk - Environment Configuration
+#
+# Setup:
+#   1. cp .env.example .env
+#   2. Set DOMAIN_NAME (the only required setting)
+#   3. docker compose up -d
+#   4. docker exec -it easy-asterisk easy-asterisk
+#
+# Port forwarding required on your router:
+#   5061/tcp        → SIP TLS signaling
+#   3478/udp+tcp    → STUN/TURN (NAT traversal + media relay)
+#                     (change with TURN_PORT if 3478 is taken)
+#   10000-20000/udp → RTP media (or your custom range below)
+#
+# How it works:
+#   - All SIP clients connect to DOMAIN_NAME:5061 (TLS)
+#   - coturn handles NAT traversal (STUN) and media relay (TURN)
+#   - Works from any network: LAN, cellular, Proton VPN, hotel WiFi
+#   - Set TURN_PASSWORD below (generate one: openssl rand -base64 18)
+# ================================================================
+
+# ── Domain Name (REQUIRED) ────────────────────────────────────
+# The FQDN that points to this server's public IP.
+# This is what SIP clients use to connect.
+# Example: asterisk.yourdomain.com
+DOMAIN_NAME=
+
+# ── Public IP ─────────────────────────────────────────────────
+# Your server's public IP address.
+# Leave empty to auto-detect (uses ifconfig.me).
+# Set manually if auto-detection fails (e.g., behind double NAT).
+PUBLIC_IP=
+
+# ── TLS ───────────────────────────────────────────────────────
+# Always "y" for remote access. Self-signed certs are auto-generated.
+# For trusted certs (no client warnings), mount your Let's Encrypt
+# certs into /etc/asterisk/certs/ via docker compose volumes.
+ENABLE_TLS=y
+
+# ── Local Network ─────────────────────────────────────────────
+# Your LAN CIDR. Auto-detected if empty.
+# Example: 192.168.1.0/24
+LOCAL_CIDR=
+
+# ── Additional Subnets (optional) ─────────────────────────────
+# Only needed for site-to-site VPNs or VLANs where the server
+# has a direct route to client IPs (e.g., WireGuard, Tailscale).
+#
+# NOT needed for client-side VPNs (Proton, NordVPN, etc.)
+# - Those clients appear with random public IPs
+# - TURN handles media relay for them automatically
+#
+# Examples:
+#   WireGuard:    VLAN_SUBNETS=10.8.0.0/24
+#   Tailscale:    VLAN_SUBNETS=100.64.0.0/10
+#   Multiple:     VLAN_SUBNETS=10.8.0.0/24 10.10.0.0/24
+HAS_VLANS=n
+VLAN_SUBNETS=
+
+# ── TURN/STUN Settings ──────────────────────────────────────
+# Used by coturn for TURN relay authentication.
+# If empty, defaults to "changeme" — set a real password for security.
+# Generate one with:  openssl rand -base64 18
+#
+# These credentials are for coturn only. SIP clients that need TURN
+# relay (behind strict NAT) must configure the same credentials in
+# their SIP app settings.
+TURN_USERNAME=easyasterisk
+TURN_PASSWORD=
+
+# ── TURN/STUN Port ──────────────────────────────────────────
+# Default: 3478 (standard STUN/TURN port)
+# Change if 3478 is already in use (e.g., UniFi controller uses 3478/udp).
+# Common alternative: 3479
+TURN_PORT=3478
+
+# ── TURN Relay Port Range ─────────────────────────────────────
+# Ports coturn uses for media relay. Forward this range on your router.
+# Default is 100 ports (enough for ~50 simultaneous relayed calls).
+# Most calls use direct paths; TURN relay is the fallback.
+TURN_RELAY_MIN=49152
+TURN_RELAY_MAX=49252
+
+# ── RTP Port Range ────────────────────────────────────────────
+# Asterisk's own RTP media ports. Forward this range on your router.
+# Default: 10000-20000 (10,000 ports)
+# For constrained environments: 10000-10200
+RTP_START=10000
+RTP_END=20000
+
+# ── Web Admin ─────────────────────────────────────────────────
+# HTTP management interface. Access via browser at:
+#   http://your-server:8080/clients
+#
+# For HTTPS: put this behind Caddy or nginx reverse proxy,
+# then set WEB_ADMIN_AUTH_DISABLED=true (let the proxy handle auth).
+WEB_ADMIN_PORT=8080
+WEB_ADMIN_AUTH_DISABLED=false
@@ -0,0 +1,103 @@
+# ================================================================
+# Easy Asterisk - Docker Container
+# Asterisk PBX with web admin and optional STUN support
+#
+# Usage:
+#   docker compose up -d                    # Asterisk only
+#   docker compose --profile stun up -d     # Asterisk + self-hosted STUN
+#   docker exec -it easy-asterisk easy-asterisk  # Interactive management
+#   docker exec -it easy-asterisk vpn-diagnostics # VPN diagnostics
+#   docker exec -it easy-asterisk dns-whitelist   # DNS whitelist check
+# ================================================================
+
+FROM ubuntu:24.04
+
+ENV DEBIAN_FRONTEND=noninteractive
+ENV LANG=C.UTF-8
+
+# Install Asterisk and all dependencies (matches install_asterisk_packages)
+RUN echo "exit 101" > /usr/sbin/policy-rc.d && chmod +x /usr/sbin/policy-rc.d && \
+    apt-get update && \
+    apt-get install -y --no-install-recommends \
+        asterisk \
+        asterisk-core-sounds-en-gsm \
+        asterisk-modules \
+        ca-certificates \
+        openssl \
+        curl \
+        wget \
+        tcpdump \
+        sngrep \
+        python3 \
+        iproute2 \
+        net-tools \
+        dnsutils \
+        iputils-ping \
+        procps \
+        lsof \
+    && rm -rf /var/lib/apt/lists/* \
+    && rm -f /usr/sbin/policy-rc.d \
+    && ldconfig \
+    && update-ca-certificates 2>/dev/null || true
+
+# NOTE: Opus transcoding (codec_opus.so) is NOT available on Ubuntu 24.04 due to
+# a packaging bug (Launchpad #2044135). The Digium precompiled binary is ABI-incompatible.
+# Opus pass-through (phone-to-phone) still works via res_format_attr_opus.so from
+# asterisk-modules. Only Opus<->ulaw transcoding is missing, which is rarely needed
+# since modern SIP phones all support the same codecs natively.
+
+# Create required directories
+RUN mkdir -p \
+    /etc/easy-asterisk \
+    /etc/asterisk/certs \
+    /var/lib/asterisk/static-http \
+    /var/log/asterisk \
+    /var/spool/asterisk \
+    /var/run/asterisk \
+    && chown -R asterisk:asterisk \
+        /etc/asterisk \
+        /var/lib/asterisk \
+        /var/log/asterisk \
+        /var/spool/asterisk \
+        /var/run/asterisk
+
+# Docker detection marker (used by is_docker() in the script)
+RUN touch /.dockerenv
+
+# Copy the main management script
+COPY easy-asterisk-v0.10.0.sh /usr/local/bin/easy-asterisk
+RUN chmod +x /usr/local/bin/easy-asterisk
+
+# Copy diagnostic and utility scripts
+COPY scripts/vpn-diagnostics.sh /usr/local/bin/vpn-diagnostics
+COPY scripts/dns-whitelist.sh /usr/local/bin/dns-whitelist
+RUN chmod +x /usr/local/bin/vpn-diagnostics /usr/local/bin/dns-whitelist
+
+# Copy entrypoint
+COPY docker/entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+# SIP signaling
+EXPOSE 5060/udp
+EXPOSE 5060/tcp
+EXPOSE 5061/tcp
+
+# Web admin + provisioning
+EXPOSE 8080/tcp
+EXPOSE 8088/tcp
+EXPOSE 8089/tcp
+
+# STUN (if running coturn in same container; default 3478, configurable via TURN_PORT)
+EXPOSE 3478/udp
+
+# RTP media range (use --network host in production for full range)
+# Docker port-mapping 10000 ports is impractical; host networking recommended
+EXPOSE 10000-10100/udp
+
+# Persistent data
+VOLUME ["/etc/asterisk", "/etc/easy-asterisk", "/var/log/asterisk"]
+
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+    CMD asterisk -rx "core show version" >/dev/null 2>&1 || exit 1
+
+ENTRYPOINT ["/entrypoint.sh"]
@@ -0,0 +1,26 @@
+#!/bin/sh
+# ================================================================
+# Robust coturn entrypoint
+#
+# The coturn/coturn Docker image's native entrypoint uses:
+#   exec $(eval "echo $@")
+# which is fragile — if DETECT_EXTERNAL_IP's DNS lookup returns empty,
+# the eval produces an empty token → "ERROR: CONFIG: Unknown argument:"
+#
+# This wrapper reuses the image's detect-external-ip script but avoids
+# the eval word-splitting issue. If detection fails, we simply omit
+# --external-ip rather than passing a blank argument.
+# ================================================================
+
+# Use explicit PUBLIC_IP if provided, otherwise auto-detect
+if [ -z "$PUBLIC_IP" ]; then
+    PUBLIC_IP=$(detect-external-ip 2>/dev/null || true)
+fi
+
+# Only add --external-ip if we actually have an IP
+EXTERNAL_IP_ARG=""
+if [ -n "$PUBLIC_IP" ]; then
+    EXTERNAL_IP_ARG="--external-ip=$PUBLIC_IP"
+fi
+
+exec turnserver "$@" $EXTERNAL_IP_ARG
@@ -0,0 +1,449 @@
+#!/bin/bash
+# ================================================================
+# Easy Asterisk Docker Entrypoint
+#
+# Fully automated:
+#   - Detects public IP
+#   - Generates TURN credentials if not provided
+#   - Configures Asterisk with FQDN, TLS, ICE, STUN, TURN
+#   - Starts web admin + Asterisk
+# ================================================================
+
+set -e
+
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+log_info() { echo -e "${GREEN}[entrypoint]${NC} $1"; }
+log_warn() { echo -e "${YELLOW}[entrypoint]${NC} $1"; }
+log_error() { echo -e "${RED}[entrypoint]${NC} $1"; }
+
+CONFIG_DIR="/etc/easy-asterisk"
+CONFIG_FILE="${CONFIG_DIR}/config"
+WEB_ADMIN_SCRIPT="/usr/local/bin/easy-asterisk-webadmin"
+
+# ── Helper: generate random password ─────────────────────────
+gen_password() {
+    openssl rand -base64 18 | tr -dc 'a-zA-Z0-9' | head -c 24
+}
+
+# ── 1. Ensure asterisk user exists ───────────────────────────
+if ! id asterisk >/dev/null 2>&1; then
+    useradd -r -s /bin/false -d /var/lib/asterisk asterisk 2>/dev/null || true
+fi
+
+# ── 2. Detect public IP ──────────────────────────────────────
+PUBLIC_IP="${PUBLIC_IP:-}"
+if [[ -z "$PUBLIC_IP" ]]; then
+    log_info "Auto-detecting public IP..."
+    PUBLIC_IP=$(curl -s -4 --connect-timeout 5 ifconfig.me 2>/dev/null || true)
+    if [[ -z "$PUBLIC_IP" ]]; then
+        PUBLIC_IP=$(curl -s -4 --connect-timeout 5 icanhazip.com 2>/dev/null || true)
+    fi
+    if [[ -z "$PUBLIC_IP" ]]; then
+        PUBLIC_IP=$(curl -s -4 --connect-timeout 5 api.ipify.org 2>/dev/null || true)
+    fi
+fi
+
+if [[ -n "$PUBLIC_IP" ]]; then
+    log_info "Public IP: ${PUBLIC_IP}"
+else
+    log_warn "Could not detect public IP. Set PUBLIC_IP in .env"
+fi
+
+# ── 3. TURN credentials ─────────────────────────────────────────
+# The password MUST match what coturn was started with. In Docker, both
+# read from the same env-var / .env file, so we use the value as-is.
+# Auto-generating a different password here would create a mismatch
+# (coturn is already running with ITS copy of the env-var).
+TURN_USERNAME="${TURN_USERNAME:-easyasterisk}"
+TURN_PASSWORD="${TURN_PASSWORD:-changeme}"
+if [[ "${TURN_PASSWORD}" == "changeme" ]]; then
+    log_warn "TURN password is the default 'changeme' — set TURN_PASSWORD in .env for better security"
+fi
+
+# ── 4. Detect local network ──────────────────────────────────
+local_ip=$(hostname -I 2>/dev/null | awk '{print $1}')
+raw_cidr=$(ip -o -f inet addr show 2>/dev/null | awk '/scope global/ {print $4}' | head -1)
+default_cidr="$raw_cidr"
+if [[ "$raw_cidr" =~ \.([0-9]+)/([0-9]+)$ ]]; then
+    default_cidr="${raw_cidr%.*}.0/${BASH_REMATCH[2]}"
+fi
+
+# ── 5. Generate self-signed certs ──────────────────────────────
+# Regenerate if missing OR if existing cert lacks SANs (modern TLS clients require them)
+regen_cert=false
+if [[ ! -f /etc/asterisk/certs/server.crt ]]; then
+    regen_cert=true
+elif ! openssl x509 -in /etc/asterisk/certs/server.crt -noout -ext subjectAltName 2>/dev/null | grep -q "DNS:"; then
+    log_info "Existing TLS cert lacks SANs — regenerating for mobile phone compatibility"
+    regen_cert=true
+fi
+
+if $regen_cert; then
+    log_info "Generating self-signed TLS certificate..."
+    mkdir -p /etc/asterisk/certs
+    cn="${DOMAIN_NAME:-asterisk-local}"
+    # Include Subject Alternative Names — required by modern TLS clients (iOS/Android SIP apps)
+    openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
+        -keyout /etc/asterisk/certs/server.key \
+        -out /etc/asterisk/certs/server.crt \
+        -subj "/CN=${cn}" \
+        -addext "subjectAltName=DNS:${cn}${PUBLIC_IP:+,IP:${PUBLIC_IP}}" \
+        2>/dev/null
+    chown asterisk:asterisk /etc/asterisk/certs/server.*
+    chmod 644 /etc/asterisk/certs/server.crt
+    chmod 600 /etc/asterisk/certs/server.key
+fi
+
+# ── 6. Write config file ─────────────────────────────────────
+mkdir -p "$CONFIG_DIR"
+
+# Determine TURN/STUN server address
+turn_server="${TURN_SERVER:-${DOMAIN_NAME:-$local_ip}:${TURN_PORT:-3478}}"
+
+cat > "$CONFIG_FILE" << EOF
+# Easy Asterisk Configuration (Docker) - $(date)
+KIOSK_USER=""
+KIOSK_UID=""
+KIOSK_EXTENSION=""
+KIOSK_NAME=""
+SIP_PASSWORD=""
+ASTERISK_HOST="${DOMAIN_NAME:-$local_ip}"
+DOMAIN_NAME="${DOMAIN_NAME:-}"
+ENABLE_TLS="${ENABLE_TLS:-y}"
+HAS_VLANS="${HAS_VLANS:-n}"
+VLAN_SUBNETS="${VLAN_SUBNETS:-}"
+CERT_PATH=""
+KEY_PATH=""
+INSTALLED_SERVER="y"
+INSTALLED_CLIENT="n"
+CURRENT_PUBLIC_IP="${PUBLIC_IP}"
+PTT_DEVICE=""
+PTT_KEYCODE=""
+LOCAL_CIDR="${LOCAL_CIDR:-$default_cidr}"
+WEB_ADMIN_PORT="${WEB_ADMIN_PORT:-8080}"
+WEB_ADMIN_AUTH_DISABLED="${WEB_ADMIN_AUTH_DISABLED:-false}"
+VPN_ICE_ENABLED="y"
+CUSTOM_STUN_SERVER="${turn_server}"
+TURN_ENABLED="y"
+TURN_SERVER="${turn_server}"
+TURN_USERNAME="${TURN_USERNAME}"
+TURN_PASSWORD="${TURN_PASSWORD}"
+EOF
+chmod 644 "$CONFIG_FILE"
+
+# ── 7. Initialize categories & rooms if missing ──────────────
+CATEGORIES_FILE="${CONFIG_DIR}/categories.conf"
+if [[ ! -f "$CATEGORIES_FILE" ]]; then
+    log_info "Creating default device categories..."
+    cat > "$CATEGORIES_FILE" << 'EOF'
+kiosks|Kiosks|yes|Fixed wall-mount tablets & intercoms
+mobile|Mobile|no|Phones & tablets (ring normally)
+custom|Custom|no|Custom configuration
+EOF
+fi
+
+ROOMS_FILE="${CONFIG_DIR}/rooms.conf"
+if [[ ! -f "$ROOMS_FILE" ]]; then
+    cat > "$ROOMS_FILE" << 'EOF'
+# ext|name|members|timeout|type
+EOF
+fi
+
+# ── 8. Generate Asterisk configs ─────────────────────────────
+
+# Build local_net entries
+all_local_nets="local_net=${LOCAL_CIDR:-$default_cidr}"
+if [[ "${HAS_VLANS:-n}" == "y" && -n "${VLAN_SUBNETS:-}" ]]; then
+    for subnet in $VLAN_SUBNETS; do
+        all_local_nets="${all_local_nets}
+local_net=${subnet}"
+    done
+fi
+
+# NAT settings - always include external addresses for FQDN mode
+nat_settings=""
+if [[ -n "$PUBLIC_IP" ]]; then
+    nat_settings="external_media_address=${PUBLIC_IP}
+external_signaling_address=${PUBLIC_IP}
+${all_local_nets}"
+else
+    nat_settings="${all_local_nets}"
+fi
+
+# ── pjsip.conf (only if empty/missing - preserves existing devices) ──
+if [[ ! -f /etc/asterisk/pjsip.conf ]] || [[ ! -s /etc/asterisk/pjsip.conf ]]; then
+    log_info "Generating PJSIP configuration..."
+    cat > /etc/asterisk/pjsip.conf << EOF
+; Easy Asterisk (Docker) - FQDN: ${DOMAIN_NAME:-none}
+[global]
+type=global
+user_agent=EasyAsterisk
+
+[transport-udp]
+type=transport
+protocol=udp
+bind=0.0.0.0:5060
+; Server IP: ${local_ip} | Public IP: ${PUBLIC_IP:-unknown}
+${nat_settings}
+
+[transport-tcp]
+type=transport
+protocol=tcp
+bind=0.0.0.0:5060
+; Server IP: ${local_ip} | Public IP: ${PUBLIC_IP:-unknown}
+${nat_settings}
+
+[transport-tls]
+type=transport
+protocol=tls
+bind=0.0.0.0:5061
+; Server IP: ${local_ip} | Public IP: ${PUBLIC_IP:-unknown}
+cert_file=/etc/asterisk/certs/server.crt
+priv_key_file=/etc/asterisk/certs/server.key
+; ca_list_file not set — only needed for verify_client=yes (client cert auth)
+method=tlsv1_2
+${nat_settings}
+
+EOF
+    chown asterisk:asterisk /etc/asterisk/pjsip.conf
+else
+    # Update NAT settings in existing pjsip.conf transports if public IP changed
+    if [[ -n "$PUBLIC_IP" ]]; then
+        current_ext=$(grep "^external_media_address=" /etc/asterisk/pjsip.conf 2>/dev/null | head -1 | cut -d= -f2)
+        if [[ "$current_ext" != "$PUBLIC_IP" && -n "$current_ext" ]]; then
+            log_info "Updating public IP in pjsip.conf: ${current_ext} -> ${PUBLIC_IP}"
+            sed -i "s|external_media_address=.*|external_media_address=${PUBLIC_IP}|g" /etc/asterisk/pjsip.conf
+            sed -i "s|external_signaling_address=.*|external_signaling_address=${PUBLIC_IP}|g" /etc/asterisk/pjsip.conf
+        fi
+    fi
+fi
+
+# ── Sanitize pjsip.conf: remove endpoint-only options from aor sections ──
+if [[ -f /etc/asterisk/pjsip.conf ]]; then
+    # Options that are only valid in [endpoint] sections, not in [aor] sections
+    endpoint_only_opts="direct_media|rtp_symmetric|force_rport|rewrite_contact|rtp_keepalive|rtp_timeout|rtp_timeout_hold|ice_support|context|disallow|allow|auth|aors|callerid|media_encryption|transport"
+    current_type=""
+    needs_fix=false
+    while IFS= read -r line; do
+        if [[ "$line" =~ ^type=(.*) ]]; then
+            current_type="${BASH_REMATCH[1]}"
+        fi
+        if [[ "$current_type" == "aor" ]] && echo "$line" | grep -qE "^(${endpoint_only_opts})="; then
+            needs_fix=true
+            break
+        fi
+    done < /etc/asterisk/pjsip.conf
+
+    if $needs_fix; then
+        log_info "Sanitizing pjsip.conf (removing misplaced options from aor sections)..."
+        awk -v opts="$endpoint_only_opts" '
+        BEGIN { split(opts, arr, "|"); for (i in arr) bad[arr[i]]=1 }
+        /^type=/ { current_type = substr($0, 6) }
+        {
+            if (current_type == "aor") {
+                split($0, kv, "=")
+                if (kv[1] in bad) next
+            }
+            print
+        }
+        ' /etc/asterisk/pjsip.conf > /tmp/pjsip_sanitized.conf
+        mv /tmp/pjsip_sanitized.conf /etc/asterisk/pjsip.conf
+        chown asterisk:asterisk /etc/asterisk/pjsip.conf
+    fi
+fi
+
+# ── Ensure transport-tls exists in pjsip.conf (upgrade / migration path) ──
+# If pjsip.conf was preserved from a pre-TLS config or a non-Docker install it
+# will have no [transport-tls] section.  Asterisk starts without TLS silently,
+# and mobile devices cannot register.  Inject the section when it is absent.
+if [[ -f /etc/asterisk/pjsip.conf ]] && ! grep -q "^\[transport-tls\]" /etc/asterisk/pjsip.conf; then
+    log_info "transport-tls missing from pjsip.conf — adding TLS transport (required for mobile registration)..."
+    cat >> /etc/asterisk/pjsip.conf << EOF
+
+[transport-tls]
+type=transport
+protocol=tls
+bind=0.0.0.0:5061
+cert_file=/etc/asterisk/certs/server.crt
+priv_key_file=/etc/asterisk/certs/server.key
+; ca_list_file not set — only needed for verify_client=yes (client cert auth)
+method=tlsv1_2
+${nat_settings}
+
+EOF
+    chown asterisk:asterisk /etc/asterisk/pjsip.conf
+fi
+
+# ── rtp.conf (always regenerated) ──
+# ICE is enabled so Asterisk participates in ICE negotiation with clients.
+# stunaddr/turnaddr are NOT set here because:
+#   - Asterisk already knows its public IP via external_media_address in pjsip.conf
+#   - Its RTP ports are port-forwarded, so host candidates are sufficient
+#   - Setting stunaddr/turnaddr causes STUN/TURN gather timeouts (~27s per call)
+#     when the STUN/TURN server is unreachable or misconfigured
+# coturn is for SIP CLIENTS behind strict NAT — they configure TURN in their
+# own app settings, independently of Asterisk's rtp.conf.
+log_info "Configuring RTP with ICE support..."
+cat > /etc/asterisk/rtp.conf << EOF
+[general]
+rtpstart=${RTP_START:-10000}
+rtpend=${RTP_END:-20000}
+strictrtp=yes
+icesupport=yes
+EOF
+chown asterisk:asterisk /etc/asterisk/rtp.conf
+
+# ── extensions.conf (only if missing) ──
+if [[ ! -f /etc/asterisk/extensions.conf ]] || [[ ! -s /etc/asterisk/extensions.conf ]]; then
+    log_info "Generating dialplan..."
+    cat > /etc/asterisk/extensions.conf << 'EOF'
+[general]
+static=yes
+writeprotect=no
+[default]
+exten => _X.,1,Hangup()
+[intercom]
+EOF
+    chown asterisk:asterisk /etc/asterisk/extensions.conf
+fi
+
+# ── Other core configs (only if missing) ──
+if [[ ! -f /etc/asterisk/asterisk.conf ]]; then
+    cat > /etc/asterisk/asterisk.conf << 'EOF'
+[directories]
+[options]
+runuser = asterisk
+rungroup = asterisk
+EOF
+fi
+
+# ── logger.conf (always regenerated - ensures security logging is on) ──
+cat > /etc/asterisk/logger.conf << 'EOF'
+[general]
+[logfiles]
+; security level captures TLS handshake failures and auth issues
+console => notice,warning,error,security
+EOF
+
+# ── modules.conf (always regenerated - ensures chan_sip stays disabled) ──
+cat > /etc/asterisk/modules.conf << 'EOF'
+[modules]
+autoload=yes
+noload => chan_sip.so
+noload => chan_iax2.so
+; Opus transcoding unavailable on Ubuntu 24.04 (bug #2044135)
+; Opus pass-through still works via res_format_attr_opus.so
+noload => codec_opus.so
+noload => format_ogg_opus.so
+load => res_pjsip.so
+load => res_pjsip_session.so
+load => res_pjsip_logger.so
+load => chan_pjsip.so
+load => codec_ulaw.so
+load => codec_alaw.so
+load => codec_g722.so
+load => res_rtp_asterisk.so
+load => app_dial.so
+load => app_page.so
+load => pbx_config.so
+EOF
+
+# ── Remove incompatible Digium codec_opus if present on volume ──
+# The Digium binary is ABI-incompatible with Ubuntu 24.04's Asterisk and crashes it
+MODULES_DIR=$(find /usr/lib -type d -name modules -path "*/asterisk/*" 2>/dev/null | head -1)
+if [[ -n "$MODULES_DIR" ]]; then
+    for bad_module in codec_opus.so format_ogg_opus.so; do
+        if [[ -f "$MODULES_DIR/$bad_module" ]] && ! dpkg -S "$MODULES_DIR/$bad_module" >/dev/null 2>&1; then
+            log_warn "Removing incompatible $bad_module (not from Ubuntu package)"
+            rm -f "$MODULES_DIR/$bad_module"
+        fi
+    done
+fi
+
+# ── 9. Fix permissions ───────────────────────────────────────
+chown -R asterisk:asterisk /etc/asterisk /var/lib/asterisk /var/log/asterisk /var/spool/asterisk /var/run/asterisk 2>/dev/null || true
+
+# ── 10. Start Web Admin in background ─────────────────────────
+# The web admin script is generated by the 'easy-asterisk' management tool.
+# On first run: docker exec -it easy-asterisk easy-asterisk → Web Admin menu → Start
+if [[ -f "$WEB_ADMIN_SCRIPT" ]]; then
+    log_info "Starting Web Admin on port ${WEB_ADMIN_PORT:-8080}..."
+    WEBADMIN_PORT="${WEB_ADMIN_PORT:-8080}" \
+    WEBADMIN_AUTH_DISABLED="${WEB_ADMIN_AUTH_DISABLED:-false}" \
+    python3 "$WEB_ADMIN_SCRIPT" &
+fi
+
+# ── 11. Signal handling for clean shutdown ────────────────────
+cleanup() {
+    log_info "Shutting down..."
+    pkill -f "easy-asterisk-webadmin" 2>/dev/null || true
+    asterisk -rx "core stop now" 2>/dev/null || true
+    exit 0
+}
+trap cleanup SIGTERM SIGINT
+
+# ── 12. Start Asterisk ───────────────────────────────────────
+log_info "Starting Asterisk PBX..."
+echo ""
+
+# Start Asterisk in the background, then print management info once ready
+asterisk -f -U asterisk -G asterisk &
+ASTERISK_PID=$!
+
+# Wait for Asterisk to be ready (up to 60 seconds)
+for i in $(seq 1 60); do
+    if asterisk -rx "core show version" >/dev/null 2>&1; then
+        break
+    fi
+    sleep 1
+done
+
+# Verify PJSIP transports are listening
+tls_ok=false
+udp_ok=false
+if asterisk -rx "pjsip show transports" 2>/dev/null | grep -q "transport-tls"; then
+    tls_ok=true
+fi
+if asterisk -rx "pjsip show transports" 2>/dev/null | grep -q "transport-udp"; then
+    udp_ok=true
+fi
+
+# Check if port 5061 is actually bound
+tls_listen=""
+if command -v ss &>/dev/null; then
+    tls_listen=$(ss -tlnp 2>/dev/null | grep ":5061 " || true)
+elif command -v netstat &>/dev/null; then
+    tls_listen=$(netstat -tlnp 2>/dev/null | grep ":5061 " || true)
+fi
+
+echo ""
+echo -e "${CYAN}══════════════════════════════════════════════════════════════${NC}"
+echo -e "${CYAN}  Easy Asterisk (Docker)${NC}"
+echo -e "${CYAN}══════════════════════════════════════════════════════════════${NC}"
+echo -e "  FQDN:         ${GREEN}${DOMAIN_NAME:-not set}${NC}"
+echo -e "  Public IP:    ${GREEN}${PUBLIC_IP:-unknown}${NC}"
+echo -e "  TURN/STUN:    ${GREEN}${turn_server}${NC}"
+if $tls_ok && [[ -n "$tls_listen" ]]; then
+    echo -e "  TLS:          ${GREEN}Enabled (port 5061)${NC}"
+elif $tls_ok; then
+    echo -e "  TLS:          ${YELLOW}Transport loaded but port 5061 not bound — check certs${NC}"
+else
+    echo -e "  TLS:          ${RED}NOT LOADED — check Asterisk logs${NC}"
+fi
+echo -e "  ICE:          ${GREEN}Enabled${NC}"
+echo -e "${CYAN}──────────────────────────────────────────────────────────────${NC}"
+echo -e "  SIP clients connect to: ${GREEN}${DOMAIN_NAME:-$local_ip}:5061${NC} (TLS)"
+echo -e "  Web Admin:    ${GREEN}http://${local_ip}:${WEB_ADMIN_PORT:-8080}/clients${NC}"
+echo -e "${CYAN}──────────────────────────────────────────────────────────────${NC}"
+echo -e "  Management:   ${YELLOW}docker exec -it easy-asterisk easy-asterisk${NC}"
+echo -e "  Diagnostics:  docker exec -it easy-asterisk vpn-diagnostics"
+echo -e "${CYAN}══════════════════════════════════════════════════════════════${NC}"
+echo ""
+
+# Wait for Asterisk process (keeps container running)
+wait $ASTERISK_PID
@@ -0,0 +1,280 @@
+#!/bin/bash
+# ================================================================
+# DNS Whitelist Checker for Easy Asterisk
+#
+# Checks which domains need to be whitelisted when DNS filtering
+# is active on the server, caller, or receiver networks.
+#
+# Usage: dns-whitelist [--check] [--sipnetic] [--linphone]
+# ================================================================
+
+set -e
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+BOLD='\033[1m'
+NC='\033[0m'
+
+CONFIG_FILE="/etc/easy-asterisk/config"
+CHECK_MODE=false
+SHOW_SIPNETIC=false
+SHOW_LINPHONE=false
+SHOW_ALL=true
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --check) CHECK_MODE=true; shift ;;
+        --sipnetic) SHOW_SIPNETIC=true; SHOW_ALL=false; shift ;;
+        --linphone) SHOW_LINPHONE=true; SHOW_ALL=false; shift ;;
+        --help|-h)
+            echo "Usage: dns-whitelist [OPTIONS]"
+            echo ""
+            echo "Options:"
+            echo "  --check       Test reachability of each domain"
+            echo "  --sipnetic    Show Sipnetic-specific domains"
+            echo "  --linphone    Show Linphone-specific domains"
+            echo "  --help        Show this help"
+            exit 0
+            ;;
+        *) shift ;;
+    esac
+done
+
+print_header() {
+    echo ""
+    echo -e "${CYAN}╔══════════════════════════════════════════════════════════╗${NC}"
+    echo -e "${CYAN}  $1${NC}"
+    echo -e "${CYAN}╚══════════════════════════════════════════════════════════╝${NC}"
+    echo ""
+}
+
+check_dns() {
+    local domain="$1"
+    local port="$2"
+    local proto="${3:-tcp}"
+
+    if $CHECK_MODE; then
+        # DNS resolution test
+        if nslookup "$domain" >/dev/null 2>&1; then
+            echo -e "    ${GREEN}✓ DNS resolves${NC}"
+        else
+            echo -e "    ${RED}✗ DNS BLOCKED - add to whitelist${NC}"
+            return 1
+        fi
+
+        # Connectivity test
+        if [[ "$proto" == "udp" ]]; then
+            # UDP - just check DNS resolution (can't reliably test UDP connectivity)
+            echo -e "    ${CYAN}→ UDP port ${port} (cannot test remotely)${NC}"
+        else
+            if curl -s --connect-timeout 5 "https://${domain}" >/dev/null 2>&1 || \
+               curl -s --connect-timeout 5 "http://${domain}" >/dev/null 2>&1; then
+                echo -e "    ${GREEN}✓ Reachable${NC}"
+            else
+                echo -e "    ${YELLOW}! Connection failed (may be expected)${NC}"
+            fi
+        fi
+    fi
+}
+
+# Load config if available
+source "$CONFIG_FILE" 2>/dev/null || true
+
+print_header "DNS Whitelist for Easy Asterisk"
+
+echo -e "${BOLD}Your Setup:${NC}"
+if [[ -n "$DOMAIN_NAME" ]]; then
+    echo -e "  Mode: FQDN/Internet (${DOMAIN_NAME})"
+else
+    echo -e "  Mode: LAN/VPN (no domain configured)"
+fi
+echo ""
+
+# ══════════════════════════════════════════════════════════════
+# SECTION 1: ASTERISK SERVER DOMAINS
+# ══════════════════════════════════════════════════════════════
+if $SHOW_ALL; then
+    echo -e "${BOLD}━━━ 1. ASTERISK SERVER (whitelist on server's DNS filter) ━━━${NC}"
+    echo ""
+
+    echo -e "${BOLD}Required for LAN/VPN mode:${NC}"
+    echo -e "  ${GREEN}None${NC} - Asterisk needs no internet after installation"
+    echo -e "  SIP operates over direct IP connections, no DNS involved"
+    echo ""
+
+    echo -e "${BOLD}Required for FQDN/Internet mode only:${NC}"
+    echo ""
+
+    echo -e "  ${CYAN}ifconfig.me${NC} (HTTPS 443)"
+    echo -e "    Purpose: Auto-detect public IP for NAT settings"
+    echo -e "    When: Only during config regeneration"
+    check_dns "ifconfig.me" "443"
+    echo ""
+
+    echo -e "  ${CYAN}icanhazip.com${NC} (HTTPS 443)"
+    echo -e "    Purpose: Fallback public IP detection"
+    check_dns "icanhazip.com" "443"
+    echo ""
+
+    echo -e "${BOLD}Required if ICE/STUN enabled:${NC}"
+    echo ""
+
+    # Check what STUN server is configured
+    stun_server=""
+    if [[ -f /etc/asterisk/rtp.conf ]]; then
+        stun_server=$(grep "^stunaddr=" /etc/asterisk/rtp.conf 2>/dev/null | cut -d= -f2)
+    fi
+
+    if [[ -n "$stun_server" ]]; then
+        stun_host=$(echo "$stun_server" | cut -d: -f1)
+        stun_port=$(echo "$stun_server" | cut -d: -f2)
+        stun_port="${stun_port:-3478}"
+        echo -e "  ${CYAN}${stun_host}${NC} (UDP ${stun_port})"
+        echo -e "    Purpose: STUN NAT discovery"
+        echo -e "    ${YELLOW}Tip: Use self-hosted coturn to avoid this dependency${NC}"
+        check_dns "$stun_host" "$stun_port" "udp"
+    else
+        echo -e "  ${GREEN}No external STUN server configured${NC}"
+        echo -e "  To use self-hosted: docker compose --profile stun up -d"
+    fi
+    echo ""
+
+    echo -e "${BOLD}Required for package updates only:${NC}"
+    echo ""
+    echo -e "  ${CYAN}archive.ubuntu.com${NC} / ${CYAN}security.ubuntu.com${NC} (HTTPS 443)"
+    echo -e "    Purpose: apt package updates"
+    echo -e "    When: Only during install/update (not runtime)"
+    echo ""
+
+    echo -e "${BOLD}Required for TLS certificates:${NC}"
+    echo ""
+    echo -e "  ${CYAN}acme-v02.api.letsencrypt.org${NC} (HTTPS 443)"
+    echo -e "    Purpose: Let's Encrypt certificate issuance"
+    echo -e "    When: Only if using Let's Encrypt / Certbot / Caddy"
+    if $CHECK_MODE; then
+        check_dns "acme-v02.api.letsencrypt.org" "443"
+    fi
+    echo ""
+fi
+
+# ══════════════════════════════════════════════════════════════
+# SECTION 2: SIPNETIC (Mobile Client) DOMAINS
+# ══════════════════════════════════════════════════════════════
+if $SHOW_ALL || $SHOW_SIPNETIC; then
+    echo -e "${BOLD}━━━ 2. SIPNETIC CLIENT (whitelist on caller/receiver DNS) ━━━${NC}"
+    echo ""
+
+    echo -e "${BOLD}Required for SIP calls:${NC}"
+    echo -e "  ${GREEN}None${NC} - Configure Sipnetic with the server's IP address directly"
+    echo -e "  SIP registration and calls use IP:port, not DNS"
+    echo ""
+
+    echo -e "${BOLD}Sipnetic app domains (for app functionality):${NC}"
+    echo ""
+    echo -e "  ${CYAN}onesip.io${NC} / ${CYAN}api.onesip.io${NC}"
+    echo -e "    Purpose: Sipnetic account/licensing (free tier works offline)"
+    echo -e "    Required: Only for initial setup or account sync"
+    if $CHECK_MODE; then
+        check_dns "onesip.io" "443"
+    fi
+    echo ""
+
+    echo -e "  ${CYAN}play.google.com${NC} / ${CYAN}apps.apple.com${NC}"
+    echo -e "    Purpose: App updates"
+    echo -e "    Required: Only for installing/updating the app"
+    echo ""
+
+    echo -e "${BOLD}If STUN configured in Sipnetic:${NC}"
+    echo ""
+    echo -e "  The STUN server domain configured in Sipnetic's settings"
+    echo -e "  needs to resolve on the mobile device's network."
+    echo ""
+    echo -e "  ${YELLOW}Recommendation: Use the Asterisk server's VPN IP as STUN${NC}"
+    echo -e "  ${YELLOW}server (if running self-hosted coturn), avoiding DNS entirely.${NC}"
+    echo ""
+
+    echo -e "${BOLD}Sipnetic Configuration for DNS-Filtered Networks:${NC}"
+    echo ""
+    echo -e "  Server:     ${CYAN}<server-vpn-ip>${NC} (not a hostname)"
+    echo -e "  Port:       ${CYAN}5060${NC} (UDP, LAN/VPN mode)"
+    echo -e "  Transport:  ${CYAN}UDP${NC}"
+    echo -e "  STUN:       ${CYAN}<server-vpn-ip>:3478${NC} (if self-hosted coturn)"
+    echo -e "              or leave blank if VPN provides direct routing"
+    echo ""
+fi
+
+# ══════════════════════════════════════════════════════════════
+# SECTION 3: LINPHONE (Mobile Client) DOMAINS
+# ══════════════════════════════════════════════════════════════
+if $SHOW_ALL || $SHOW_LINPHONE; then
+    echo -e "${BOLD}━━━ 3. LINPHONE CLIENT (whitelist on caller/receiver DNS) ━━━${NC}"
+    echo ""
+
+    echo -e "${BOLD}Required for SIP calls:${NC}"
+    echo -e "  ${GREEN}None${NC} - Same as Sipnetic, configure with server IP directly"
+    echo ""
+
+    echo -e "${BOLD}Linphone app domains:${NC}"
+    echo ""
+    echo -e "  ${CYAN}linphone.org${NC} / ${CYAN}sip.linphone.org${NC}"
+    echo -e "    Purpose: Default Linphone SIP proxy (NOT needed for Easy Asterisk)"
+    echo -e "    Required: ${GREEN}No${NC} - We use our own Asterisk server"
+    echo ""
+    echo -e "  ${CYAN}subscribe.linphone.org${NC}"
+    echo -e "    Purpose: Push notifications (may be needed for background calls)"
+    echo -e "    Required: Only if you need calls to ring when app is backgrounded"
+    echo ""
+
+    echo -e "${BOLD}For remote provisioning:${NC}"
+    echo ""
+    echo -e "  If using Easy Asterisk's HTTP provisioning:"
+    echo -e "  The phone must reach ${CYAN}http://<server-ip>:8088/static/linphone.xml${NC}"
+    echo -e "  This is an IP address, so no DNS whitelist needed."
+    echo ""
+fi
+
+# ══════════════════════════════════════════════════════════════
+# SECTION 4: SUMMARY
+# ══════════════════════════════════════════════════════════════
+if $SHOW_ALL; then
+    print_header "Quick Reference - Minimum DNS Whitelist"
+
+    echo -e "${BOLD}For LAN/VPN mode (no internet calling):${NC}"
+    echo ""
+    echo -e "  Server DNS filter:  ${GREEN}No domains needed${NC}"
+    echo -e "  Client DNS filter:  ${GREEN}No domains needed${NC}"
+    echo -e "  (Configure everything by IP address)"
+    echo ""
+
+    echo -e "${BOLD}For LAN/VPN + self-hosted STUN (coturn):${NC}"
+    echo ""
+    echo -e "  Server DNS filter:  ${GREEN}No domains needed${NC}"
+    echo -e "  Client DNS filter:  ${GREEN}No domains needed${NC}"
+    echo -e "  (STUN server reached by VPN IP, not hostname)"
+    echo ""
+
+    echo -e "${BOLD}For LAN/VPN + Google STUN:${NC}"
+    echo ""
+    echo -e "  Server DNS filter:  ${YELLOW}stun.l.google.com${NC}"
+    echo -e "  Client DNS filter:  ${YELLOW}stun.l.google.com${NC} (if also set in Sipnetic)"
+    echo ""
+
+    echo -e "${BOLD}For FQDN/Internet mode:${NC}"
+    echo ""
+    echo -e "  Server DNS filter:  ${YELLOW}ifconfig.me, icanhazip.com, stun.l.google.com${NC}"
+    echo -e "                      ${YELLOW}acme-v02.api.letsencrypt.org${NC} (if using LE certs)"
+    echo -e "  Client DNS filter:  ${YELLOW}Your domain name (${DOMAIN_NAME:-yourdomain.com})${NC}"
+    echo ""
+
+    print_header "Recommendation for DNS-Filtered Environments"
+
+    echo -e "  ${GREEN}Use LAN/VPN mode + self-hosted coturn (STUN-only)${NC}"
+    echo -e "  ${GREEN}= Zero external DNS dependencies${NC}"
+    echo ""
+    echo -e "  Setup: docker compose --profile stun up -d"
+    echo -e "  Then configure STUN as your server's VPN IP:3478"
+    echo -e "  No hostnames, no DNS, everything by IP."
+    echo ""
+fi
@@ -0,0 +1,366 @@
+#!/bin/bash
+# ================================================================
+# VPN Diagnostics for Easy Asterisk
+#
+# Tests whether your third-party VPN setup needs STUN/TURN
+# and validates connectivity between Asterisk and VPN clients.
+#
+# Usage: vpn-diagnostics [--auto] [--client-ip <ip>]
+# ================================================================
+
+set -e
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+BOLD='\033[1m'
+NC='\033[0m'
+
+CONFIG_FILE="/etc/easy-asterisk/config"
+RESULTS=()
+WARNINGS=()
+CLIENT_IP=""
+AUTO_MODE=false
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --auto) AUTO_MODE=true; shift ;;
+        --client-ip) CLIENT_IP="$2"; shift 2 ;;
+        --help|-h)
+            echo "Usage: vpn-diagnostics [OPTIONS]"
+            echo ""
+            echo "Options:"
+            echo "  --auto              Non-interactive mode"
+            echo "  --client-ip <ip>    Test connectivity to specific VPN client"
+            echo "  --help              Show this help"
+            exit 0
+            ;;
+        *) shift ;;
+    esac
+done
+
+print_header() {
+    echo ""
+    echo -e "${CYAN}╔══════════════════════════════════════════════════════════╗${NC}"
+    echo -e "${CYAN}  $1${NC}"
+    echo -e "${CYAN}╚══════════════════════════════════════════════════════════╝${NC}"
+    echo ""
+}
+
+pass() { echo -e "  ${GREEN}✓${NC} $1"; RESULTS+=("PASS: $1"); }
+fail() { echo -e "  ${RED}✗${NC} $1"; RESULTS+=("FAIL: $1"); }
+warn() { echo -e "  ${YELLOW}!${NC} $1"; WARNINGS+=("$1"); }
+info() { echo -e "  ${CYAN}→${NC} $1"; }
+
+# ── Test 1: Detect network interfaces ────────────────────────
+print_header "VPN Diagnostics for Easy Asterisk"
+
+echo -e "${BOLD}1. Network Interface Detection${NC}"
+echo ""
+
+# Detect primary LAN interface
+primary_ip=$(hostname -I | awk '{print $1}')
+info "Primary IP: ${primary_ip}"
+
+# Detect VPN interfaces (tun, tap, wg, tailscale, utun, ppp)
+vpn_found=false
+vpn_ips=()
+vpn_ifaces=()
+
+while IFS= read -r line; do
+    iface=$(echo "$line" | awk '{print $2}' | tr -d ':')
+    ip_addr=$(echo "$line" | awk '{print $4}' | cut -d'/' -f1)
+
+    # Check for VPN interface patterns
+    if [[ "$iface" =~ ^(tun|tap|wg|tailscale|utun|ppp|nordlynx|proton|mullvad) ]] || \
+       [[ "$ip_addr" =~ ^(10\.|172\.(1[6-9]|2[0-9]|3[01])\.|100\.64\.|100\.96\.|100\.100\.) ]]; then
+        vpn_found=true
+        vpn_ips+=("$ip_addr")
+        vpn_ifaces+=("$iface")
+        pass "VPN interface detected: ${iface} (${ip_addr})"
+    fi
+done < <(ip -o -f inet addr show scope global 2>/dev/null)
+
+if ! $vpn_found; then
+    warn "No VPN interface detected on server"
+    info "If your VPN runs on the router (not this server), that's expected"
+    info "The VPN subnet should be added via VLAN/VPN subnet configuration"
+fi
+
+# ── Test 2: Check Asterisk PJSIP transport configuration ─────
+echo ""
+echo -e "${BOLD}2. Asterisk Transport Configuration${NC}"
+echo ""
+
+if [[ -f /etc/asterisk/pjsip.conf ]]; then
+    # Check local_net entries
+    local_nets=$(grep "^local_net=" /etc/asterisk/pjsip.conf 2>/dev/null | sort -u)
+    if [[ -n "$local_nets" ]]; then
+        while IFS= read -r net; do
+            info "Transport local_net: ${net#local_net=}"
+        done <<< "$local_nets"
+
+        # Check if VPN subnets are included
+        for vpn_ip in "${vpn_ips[@]}"; do
+            vpn_subnet=$(echo "$vpn_ip" | sed 's/\.[0-9]*$/.0\/24/')
+            if echo "$local_nets" | grep -q "$vpn_subnet"; then
+                pass "VPN subnet ${vpn_subnet} included in transport"
+            else
+                fail "VPN subnet ${vpn_subnet} NOT in transport local_net"
+                warn "Add via: Server Settings → Configure VLAN/VPN Subnets"
+            fi
+        done
+    else
+        warn "No local_net entries found in transport (basic LAN mode)"
+    fi
+
+    # Check transport types
+    if grep -q "transport=transport-udp" /etc/asterisk/pjsip.conf; then
+        pass "UDP transport configured for LAN/VPN devices"
+    fi
+    if grep -q "transport=transport-tls" /etc/asterisk/pjsip.conf; then
+        pass "TLS transport configured for FQDN devices"
+    fi
+else
+    fail "pjsip.conf not found"
+fi
+
+# ── Test 2b: TLS Certificate & Port Checks ────────────────────
+echo ""
+echo -e "${BOLD}2b. TLS / Certificate Status${NC}"
+echo ""
+
+# Check if port 5061 is actually listening
+if command -v ss &>/dev/null; then
+    tls_listen=$(ss -tlnp 2>/dev/null | grep ":5061 " || true)
+elif command -v netstat &>/dev/null; then
+    tls_listen=$(netstat -tlnp 2>/dev/null | grep ":5061 " || true)
+else
+    tls_listen=""
+fi
+
+if [[ -n "$tls_listen" ]]; then
+    pass "Port 5061 (TLS) is listening"
+else
+    fail "Port 5061 (TLS) is NOT listening"
+    warn "Asterisk TLS transport failed to start — check certs and logs"
+fi
+
+# Check TLS cert
+cert_file="/etc/asterisk/certs/server.crt"
+if [[ -f "$cert_file" ]]; then
+    pass "TLS certificate exists: $cert_file"
+
+    # Check cert CN/SAN
+    cert_cn=$(openssl x509 -in "$cert_file" -noout -subject 2>/dev/null | sed 's/.*CN *= *//')
+    cert_san=$(openssl x509 -in "$cert_file" -noout -ext subjectAltName 2>/dev/null | grep -oP 'DNS:\K[^,]+' || true)
+    cert_expiry=$(openssl x509 -in "$cert_file" -noout -enddate 2>/dev/null | cut -d= -f2)
+
+    info "Cert CN: ${cert_cn:-unknown}"
+    if [[ -n "$cert_san" ]]; then
+        pass "Cert has SAN (Subject Alt Name): ${cert_san}"
+    else
+        fail "Cert has NO SAN — modern phones (iOS/Android) will reject it"
+        warn "Delete /etc/asterisk/certs/server.crt and restart to regenerate with SANs"
+    fi
+    info "Cert expires: ${cert_expiry:-unknown}"
+
+    # Check if cert is self-signed
+    issuer=$(openssl x509 -in "$cert_file" -noout -issuer 2>/dev/null | sed 's/.*CN *= *//')
+    if [[ "$issuer" == "$cert_cn" ]]; then
+        warn "Cert is SELF-SIGNED — phones must be set to accept self-signed certs"
+        info "In your SIP app: disable TLS certificate verification / allow self-signed"
+    fi
+
+    # Verify PJSIP transport loaded it
+    if command -v asterisk &>/dev/null; then
+        transport_status=$(asterisk -rx "pjsip show transports" 2>/dev/null || true)
+        if echo "$transport_status" | grep -q "transport-tls"; then
+            pass "PJSIP TLS transport is loaded"
+        else
+            fail "PJSIP TLS transport NOT loaded — cert may be invalid"
+        fi
+    fi
+else
+    fail "TLS certificate not found at $cert_file"
+fi
+
+# ── Test 3: Check RTP and ICE/STUN configuration ─────────────
+echo ""
+echo -e "${BOLD}3. RTP / ICE / STUN Configuration${NC}"
+echo ""
+
+if [[ -f /etc/asterisk/rtp.conf ]]; then
+    rtp_start=$(grep "^rtpstart=" /etc/asterisk/rtp.conf | cut -d= -f2)
+    rtp_end=$(grep "^rtpend=" /etc/asterisk/rtp.conf | cut -d= -f2)
+    info "RTP port range: ${rtp_start:-10000}-${rtp_end:-20000}"
+
+    if grep -q "^icesupport=yes" /etc/asterisk/rtp.conf; then
+        pass "ICE support enabled"
+        stun_addr=$(grep "^stunaddr=" /etc/asterisk/rtp.conf | cut -d= -f2)
+        if [[ -n "$stun_addr" ]]; then
+            info "STUN server: ${stun_addr}"
+
+            # Test STUN server reachability
+            stun_host=$(echo "$stun_addr" | cut -d: -f1)
+            stun_port=$(echo "$stun_addr" | cut -d: -f2)
+            stun_port="${stun_port:-3478}"
+
+            if command -v nslookup &>/dev/null && nslookup "$stun_host" >/dev/null 2>&1; then
+                pass "STUN server DNS resolves: ${stun_host}"
+            else
+                fail "Cannot resolve STUN server: ${stun_host}"
+                warn "Add ${stun_host} to DNS whitelist"
+            fi
+        fi
+    else
+        info "ICE support disabled (standard for LAN/VPN mode)"
+        warn "If audio fails over VPN, enable ICE via: Server Settings → VPN STUN/ICE"
+    fi
+else
+    warn "rtp.conf not found"
+fi
+
+# ── Test 4: Check endpoint ICE settings ───────────────────────
+echo ""
+echo -e "${BOLD}4. Per-Device ICE Configuration${NC}"
+echo ""
+
+if [[ -f /etc/asterisk/pjsip.conf ]]; then
+    device_count=$(grep -c "^; === Device:" /etc/asterisk/pjsip.conf 2>/dev/null || echo 0)
+    ice_device_count=$(grep -c "^ice_support=yes" /etc/asterisk/pjsip.conf 2>/dev/null || echo 0)
+    info "Total devices: ${device_count}"
+    info "Devices with ICE: ${ice_device_count}"
+
+    if [[ "$device_count" -gt 0 && "$ice_device_count" -eq 0 ]]; then
+        warn "No devices have ICE enabled"
+        info "For third-party VPNs with NAT, enable ICE via VPN STUN/ICE menu"
+    fi
+fi
+
+# ── Test 5: VPN client connectivity ──────────────────────────
+echo ""
+echo -e "${BOLD}5. VPN Client Connectivity${NC}"
+echo ""
+
+if [[ -z "$CLIENT_IP" ]] && ! $AUTO_MODE; then
+    echo "  Enter a VPN client IP to test connectivity (or press Enter to skip):"
+    read -p "  Client VPN IP: " CLIENT_IP
+fi
+
+if [[ -n "$CLIENT_IP" ]]; then
+    # Ping test
+    if ping -c 2 -W 3 "$CLIENT_IP" >/dev/null 2>&1; then
+        pass "Ping to ${CLIENT_IP} succeeded"
+    else
+        fail "Ping to ${CLIENT_IP} failed"
+        warn "VPN routing issue - client may not be reachable"
+    fi
+
+    # SIP port test (UDP 5060)
+    if command -v nc &>/dev/null; then
+        if nc -z -u -w 3 "$CLIENT_IP" 5060 2>/dev/null; then
+            pass "UDP 5060 reachable on ${CLIENT_IP}"
+        else
+            info "UDP 5060 probe inconclusive (normal for filtered VPNs)"
+        fi
+    fi
+else
+    info "Skipping client connectivity test (no IP provided)"
+fi
+
+# ── Test 6: NAT type detection ───────────────────────────────
+echo ""
+echo -e "${BOLD}6. NAT Type Analysis${NC}"
+echo ""
+
+# Check if server is behind NAT
+if [[ -n "$primary_ip" ]]; then
+    public_ip=$(curl -s -4 --connect-timeout 5 ifconfig.me 2>/dev/null || echo "")
+    if [[ -n "$public_ip" ]]; then
+        if [[ "$primary_ip" == "$public_ip" ]]; then
+            pass "Server has public IP (no NAT)"
+        else
+            info "Server behind NAT: ${primary_ip} → ${public_ip}"
+            info "This is normal for VPN setups where traffic stays on VPN"
+        fi
+    else
+        info "Cannot detect public IP (DNS filtering or no internet)"
+        info "Not needed for LAN/VPN mode"
+    fi
+fi
+
+# ── Test 7: Asterisk registration status ─────────────────────
+echo ""
+echo -e "${BOLD}7. Asterisk Registration Status${NC}"
+echo ""
+
+if command -v asterisk &>/dev/null; then
+    reg_output=$(asterisk -rx "pjsip show endpoints" 2>/dev/null || echo "")
+    if [[ -n "$reg_output" ]]; then
+        online_count=$(echo "$reg_output" | grep -c "Avail" 2>/dev/null || echo 0)
+        offline_count=$(echo "$reg_output" | grep -c "Unavail" 2>/dev/null || echo 0)
+        info "Endpoints online: ${online_count}"
+        info "Endpoints offline: ${offline_count}"
+
+        if [[ "$offline_count" -gt 0 ]]; then
+            warn "Some endpoints are offline - check VPN connectivity"
+            echo "$reg_output" | grep "Unavail" | while IFS= read -r line; do
+                info "  Offline: $line"
+            done
+        fi
+    else
+        info "Asterisk not running or no endpoints configured"
+    fi
+else
+    info "Asterisk CLI not available"
+fi
+
+# ── Summary ──────────────────────────────────────────────────
+print_header "Diagnostic Summary"
+
+fail_count=0
+pass_count=0
+for result in "${RESULTS[@]}"; do
+    if [[ "$result" == FAIL* ]]; then
+        ((fail_count++))
+    elif [[ "$result" == PASS* ]]; then
+        ((pass_count++))
+    fi
+done
+
+echo -e "  Passed: ${GREEN}${pass_count}${NC}"
+echo -e "  Failed: ${RED}${fail_count}${NC}"
+echo -e "  Warnings: ${YELLOW}${#WARNINGS[@]}${NC}"
+
+if [[ ${#WARNINGS[@]} -gt 0 ]]; then
+    echo ""
+    echo -e "${BOLD}Recommendations:${NC}"
+    for w in "${WARNINGS[@]}"; do
+        echo -e "  ${YELLOW}→${NC} $w"
+    done
+fi
+
+# ── STUN Recommendation ─────────────────────────────────────
+echo ""
+echo -e "${BOLD}Do you need STUN?${NC}"
+echo ""
+
+if $vpn_found; then
+    echo -e "  VPN detected on this server."
+    echo -e "  ${GREEN}If your VPN provides direct routing (both sides get VPN IPs),${NC}"
+    echo -e "  ${GREEN}STUN is likely NOT needed.${NC}"
+    echo ""
+    echo -e "  ${YELLOW}If audio works one-way or not at all, enable STUN:${NC}"
+    echo -e "    1. docker compose --profile stun up -d  (self-hosted STUN)"
+    echo -e "    2. Or via easy-asterisk: Server Settings → VPN STUN/ICE"
+else
+    echo -e "  No VPN interface found on server."
+    echo -e "  ${YELLOW}If VPN runs on router/firewall:${NC}"
+    echo -e "    - Add VPN subnet via: Server Settings → VLAN/VPN Subnets"
+    echo -e "    - If audio still fails, enable STUN for NAT traversal"
+fi
+
+echo ""