ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
feat(deploy): serve panel frontend from host nginx, retire the container
Juan Denisca666297806a
diff --git a/docker-compose.yml b/docker-compose.ymlindex 08b13fd5..021fe422 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -1,19 +1,20 @@# ============================================-# ServerKit Docker Compose (canonical deployment)+# ServerKit Docker Compose (optional legacy frontend container)# ============================================-# ServerKit's backend manages the HOST it runs on — it creates app directories-# under /var/serverkit/apps, drives the host Docker daemon (one container per-# managed app), reloads nginx, and runs systemctl/firewall/PHP-FPM. A backend-# *inside* a container cannot do any of that, so the backend runs directly on-# the host (via systemd `serverkit.service`, installed by install.sh) and this-# compose file builds and serves ONLY the frontend.+# ServerKit runs FULLY OFF DOCKER for the panel itself:+# - the backend runs on the host via systemd `serverkit.service`, and+# - the React frontend is served as static files directly by the host nginx+# from frontend/dist (built by install.sh) — NO container.+# This keeps a ServerKit update from ever touching the workloads: managed apps+# are the only things in Docker, and host nginx (which fronts them) is never+# stopped, only gracefully reloaded.#-# The frontend's nginx proxies /api and /socket.io to the host backend through-# the special `backend:host-gateway` alias (see frontend/nginx.conf), so the-# `backend` upstream resolves to the host regardless of the bridge network.+# The `frontend` service below is retained ONLY as an opt-in escape hatch for+# anyone who specifically wants the panel UI in a container. It sits behind the+# `legacy-frontend` profile, so the default `docker compose up -d` starts+# NOTHING. To use it, also repoint nginx `location /` back at 127.0.0.1:3847:#-# Install (sets up the host backend + this frontend): ./serverkit install-# Frontend only: docker compose up -d --build+# docker compose --profile legacy-frontend up -d --build## Want a quick, throwaway demo with NO host management? Use the single-container# image built from ./Dockerfile instead — it bundles both tiers but, as its@@ -22,6 +23,7 @@services:frontend:+ profiles: ["legacy-frontend"]build:context: ./frontenddockerfile: Dockerfilediff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.mdindex 142d465a..4b47448e 100644--- a/docs/DEPLOYMENT.md+++ b/docs/DEPLOYMENT.md@@ -8,18 +8,28 @@ ServerKit's backend **manages the host it runs on** — it creates appdirectories under `/var/serverkit/apps`, drives the host Docker daemon (onecontainer per managed app), reloads nginx, and runs systemctl/firewall/PHP-FPM.A backend running *inside a container* cannot do any of that. So the canonical-deployment installed by `./serverkit install` (`install.sh`) runs:+deployment installed by `./serverkit install` (`install.sh`) runs **fully off+Docker for the panel itself**:- the **backend on the host** via systemd (`serverkit.service`), and-- **only the frontend in Docker** (`docker-compose.yml` is frontend-only; its- nginx proxies `/api` + `/socket.io` to the host backend via the- `backend:host-gateway` alias).--Do **not** add the backend back into `docker-compose.yml` — a containerized-backend fails app/WordPress creation with `Permission denied:-/var/serverkit/apps/...` and has no access to the host Docker daemon. The-single-container image in `./Dockerfile` exists only for throwaway demos and,-as its header states, cannot manage the host.+- the **frontend as static files served directly by host nginx** from+ `frontend/dist` (built by `install.sh`) — no container. Host nginx serves the+ SPA at `location /` and proxies `/api` + `/socket.io` to the host backend on+ `:5000`.++Docker is therefore used **only for the workloads you host** (one container per+managed app). This is deliberate: a ServerKit update never touches those+containers, and host nginx — which reverse-proxies them — is only ever+*reloaded*, never stopped, so updating the panel causes **zero downtime for+hosted apps**.++Do **not** add the backend into Docker — a containerized backend fails+app/WordPress creation with `Permission denied: /var/serverkit/apps/...` and has+no access to the host Docker daemon. A containerized *frontend* is still+available as an opt-in escape hatch (`docker compose --profile legacy-frontend+up -d`, plus repointing nginx `location /` at `127.0.0.1:3847`) but is not used+by the default install. The single-container image in `./Dockerfile` exists only+for throwaway demos and, as its header states, cannot manage the host.## Quick Install (Ubuntu)@@ -227,16 +237,18 @@ openssl req -x509 -nodes -days 365 -newkey rsa:2048 \### 5. Build and Start-`docker compose` builds and serves only the **frontend** container; the backend-runs on the host under systemd (`serverkit.service`, set up by `./serverkit-install`). See the **Deployment model** note above.+Both panel tiers run on the host: the backend under systemd+(`serverkit.service`) and the frontend as static files served by host nginx from+`frontend/dist`. `./serverkit install` builds the bundle and wires nginx for+you. See the **Deployment model** note above.```bash-# Build + start the frontend container-docker compose up -d --build+# Build the SPA bundle host nginx serves (install.sh does this automatically)+cd frontend && npm ci && npm run build && cd ..-# Start the host backend (installed by ./serverkit install)+# Start the host backend + nginxsudo systemctl start serverkit+sudo systemctl reload nginx# Verifyserverkit statusdiff --git a/install.sh b/install.shindex 1d7970e7..9c34f36b 100644--- a/install.sh+++ b/install.sh@@ -891,16 +891,25 @@ configure_nginx() {cp "$INSTALL_DIR/nginx/sites-available/serverkit-insecure.conf" /etc/nginx/sites-available/cp "$INSTALL_DIR/nginx/sites-available/example.conf.template" /etc/nginx/sites-available/+ # The panel frontend is served as static files by host nginx (no container).+ # The shipped config roots at the default /opt/serverkit; point it at the real+ # install dir when SERVERKIT_DIR was customised.+ apply_frontend_root /etc/nginx/sites-available/serverkit.conf \+ /etc/nginx/sites-available/serverkit-insecure.conf+# Decide whether we can use HTTPS. SSL is best-effort: if certbot fails or# no domain is given, we fall back to plain HTTP rather than forcing the# user to fix DNS/certs before they can use ServerKit.choose_ssl_modeinstall_nginx_config_for_mode- # SELinux: let nginx make upstream connections to the app containers.+ # SELinux: let nginx make upstream connections to the app containers AND read+ # the SPA bundle it now serves from $INSTALL_DIR (default /opt, which is not+ # httpd_sys_content_t by default — without this nginx 403s every panel asset).if { [ "$OS_FAMILY" = "fedora" ] || [ "$OS_FAMILY" = "rhel" ]; } && command -v setsebool &>/dev/null; thensetsebool -P httpd_can_network_connect 1 2>/dev/null || truefi+ selinux_label_frontend_distgood "Nginx configured ($SSL_MODE)."}@@ -965,6 +974,36 @@ install_nginx_config_for_mode() {[ -n "$PANEL_DOMAIN" ] && printf '%s\n' "$PANEL_DOMAIN" > /etc/serverkit/panel-domain}+# Point the static-frontend `root` at the real install dir. The shipped nginx+# config defaults to /opt/serverkit; only a customised SERVERKIT_DIR needs the+# rewrite. update.sh's refresh_config carries the same logic across upgrades.+apply_frontend_root() {+ [ "$INSTALL_DIR" = "/opt/serverkit" ] && return 0+ local f+ for f in "$@"; do+ [ -f "$f" ] && sed -i "s|/opt/serverkit/frontend/dist|$INSTALL_DIR/frontend/dist|g" "$f"+ done+}++# Label the SPA bundle so SELinux-enforcing hosts (Fedora/RHEL) let nginx read+# it. /opt is not httpd_sys_content_t by default, so without this every panel+# asset 403s. Label the *real* slot path (blue/green resolves through a symlink).+# Best-effort: a permissive/disabled box, or one without the tools, just no-ops.+selinux_label_frontend_dist() {+ command -v selinuxenabled &>/dev/null && selinuxenabled 2>/dev/null || return 0+ local real dist+ real="$(readlink -f "$INSTALL_DIR" 2>/dev/null || echo "$INSTALL_DIR")"+ dist="${real}/frontend/dist"+ [ -d "$dist" ] || return 0+ if command -v semanage &>/dev/null && command -v restorecon &>/dev/null; then+ semanage fcontext -a -t httpd_sys_content_t "${dist}(/.*)?" 2>/dev/null \+ || semanage fcontext -m -t httpd_sys_content_t "${dist}(/.*)?" 2>/dev/null || true+ restorecon -R "$dist" 2>/dev/null || true+ elif command -v chcon &>/dev/null; then+ chcon -R -t httpd_sys_content_t "$dist" 2>/dev/null || true+ fi+}+# ---------------------------------------------------------------------------# Server-wide TLS floor — force every HTTPS listener onto TLS 1.2/1.3 with# AEAD-only ciphers, so even the default server and non-ServerKit vhosts can't@@ -1088,20 +1127,11 @@ sync_templates() {launch_services() {phase "Starting Services"- step "Pruning stale Docker networks..."- docker network prune -f 2>/dev/null || true- docker container prune -f 2>/dev/null || true-- step "Building the frontend container..."- cd "$INSTALL_DIR"- docker compose build 2>&1 | tail -5-step "Starting the backend..."systemctl start serverkit- step "Starting the frontend container..."- docker compose up -d 2>&1 | tail -5-+ # The frontend is static files served by host nginx (built into+ # frontend/dist by build_frontend) — no container to build or start.step "Starting nginx..."systemctl start nginxgood "Services started."diff --git a/nginx/sites-available/serverkit-insecure.conf b/nginx/sites-available/serverkit-insecure.confindex 45e561b2..a5a2bad9 100644--- a/nginx/sites-available/serverkit-insecure.conf+++ b/nginx/sites-available/serverkit-insecure.conf@@ -26,14 +26,21 @@ server {root /var/www/certbot;}+ # ServerKit frontend — served directly by host nginx from the built SPA+ # bundle (no container). Path tracks the /opt/serverkit symlink so blue/green+ # updates swap assets atomically; the installer rewrites it for a custom+ # SERVERKIT_DIR.+ root /opt/serverkit/frontend/dist;+ index index.html;++ location /assets/ {+ try_files $uri =404;+ expires 1y;+ add_header Cache-Control "public, immutable";+ }+location / {- proxy_pass http://127.0.0.1:3847;- proxy_http_version 1.1;- proxy_set_header Host $host;- proxy_set_header X-Real-IP $remote_addr;- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;- proxy_set_header X-Forwarded-Proto $scheme;- proxy_set_header X-Forwarded-Host $host;+ try_files $uri $uri/ /index.html;}location /api {diff --git a/nginx/sites-available/serverkit.conf b/nginx/sites-available/serverkit.confindex 1ad8193b..f5c0312a 100644--- a/nginx/sites-available/serverkit.conf+++ b/nginx/sites-available/serverkit.conf@@ -105,19 +105,23 @@ server {add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self'; connect-src 'self' ws: wss:; frame-ancestors 'none'; base-uri 'self'; form-action 'self';" always;# ═══════════════════════════════════════════════════════════════════════════- # Proxy to ServerKit frontend- # NOTE: If your frontend container runs on a different port, change 3847 below.- # The reference nginx/nginx.conf uses 8080; this file preserves the legacy 3847- # port to avoid breaking existing ServerKit installations.+ # ServerKit frontend — served directly by host nginx from the built SPA+ # bundle (no container). The path tracks the /opt/serverkit symlink, so a+ # blue/green update swaps the served assets atomically. The installer rewrites+ # this root when SERVERKIT_DIR is customised.# ═══════════════════════════════════════════════════════════════════════════+ root /opt/serverkit/frontend/dist;+ index index.html;++ # Long-cache the content-hashed build assets; never cache the HTML entrypoint.+ location /assets/ {+ try_files $uri =404;+ expires 1y;+ add_header Cache-Control "public, immutable";+ }+location / {- proxy_pass http://127.0.0.1:3847;- proxy_http_version 1.1;- proxy_set_header Host $host;- proxy_set_header X-Real-IP $remote_addr;- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;- proxy_set_header X-Forwarded-Proto $scheme;- proxy_set_header X-Forwarded-Host $host;+ try_files $uri $uri/ /index.html;}# ═══════════════════════════════════════════════════════════════════════════diff --git a/scripts/test/test_update.sh b/scripts/test/test_update.shindex c3db7c73..b642388c 100644--- a/scripts/test/test_update.sh+++ b/scripts/test/test_update.sh@@ -337,6 +337,47 @@ elseok "update.sh never stops nginx (no 'systemctl stop nginx' anywhere)"fi+# --------------------------------------------------------------------------+# T14 — the panel frontend is served statically from $INSTALL_DIR/frontend/dist.+# refresh_config must repoint the shipped `root` (default /opt/serverkit) at a+# customised SERVERKIT_DIR, or a custom install dir would 404 the whole panel+# after an upgrade.+# --------------------------------------------------------------------------+t="$WORK/t14"+mkdir -p "$t/nginx/sites-available" "$t/nginx/sites-enabled" "$t/target/nginx/sites-available"+printf 'http {\n}\n' > "$t/nginx/nginx.conf"+printf 'server {\n root /opt/serverkit/frontend/dist;\n location / { try_files $uri /index.html; }\n}\n' \+ > "$t/target/nginx/sites-available/serverkit-insecure.conf"+(+ set -Eeuo pipefail+ NGINX_DIR="$t/nginx"; LETSENCRYPT_DIR="$t/le"; SYSTEMD_DIR="$t/sysd"; CONFIG_DIR="$t/cfg"; DRY_RUN=0+ INSTALL_DIR="$WORK/opt/serverkit" # non-default → substitution must fire+ refresh_config "$t/target"+) >/dev/null 2>&1+installed="$t/nginx/sites-available/serverkit-insecure.conf"+if grep -q "root $WORK/opt/serverkit/frontend/dist;" "$installed" \+ && ! grep -q "root /opt/serverkit/frontend/dist;" "$installed"; then+ ok "refresh_config repoints the static-frontend root at a custom SERVERKIT_DIR"+else+ bad "refresh_config did not rewrite the frontend dist root: $(grep -n root "$installed" | tr '\n' ';')"+fi++# --------------------------------------------------------------------------+# T15 — the shipped nginx sites serve the SPA statically (host nginx, no+# container): each must carry a frontend/dist root + a try_files SPA fallback+# and must NOT proxy the retired frontend container on :3847.+# --------------------------------------------------------------------------+SK_ROOT="$SCRIPT_DIR/../.."+for f in serverkit.conf serverkit-insecure.conf; do+ cfg="$SK_ROOT/nginx/sites-available/$f"+ if grep -q 'frontend/dist' "$cfg" && grep -q 'try_files' "$cfg" \+ && ! grep -q '127.0.0.1:3847' "$cfg"; then+ ok "$f serves the SPA statically (dist root + try_files, no :3847 proxy)"+ else+ bad "$f is not a clean static-serve config (still proxying :3847?)"+ fi+done+# --------------------------------------------------------------------------printf '\n%d passed, %d failed, %d skipped\n\n' "$PASS" "$FAIL" "$SKIP"[ "$FAIL" -eq 0 ]diff --git a/scripts/update.sh b/scripts/update.shindex dc2b351f..7633bbf6 100644--- a/scripts/update.sh+++ b/scripts/update.sh@@ -361,6 +361,25 @@ reload_nginx_graceful() {fi}+# Label a slot's SPA bundle for SELinux-enforcing hosts so nginx can read the+# static panel assets it now serves (see install.sh selinux_label_frontend_dist).+# Best-effort and a no-op on permissive/disabled boxes or where the tools are+# absent. Takes the slot's real path (blue/green resolves through a symlink).+selinux_label_dist() {+ local dir="$1"+ [ "$DRY_RUN" = "1" ] && return 0+ command -v selinuxenabled &>/dev/null && selinuxenabled 2>/dev/null || return 0+ local dist="${dir}/frontend/dist"+ [ -d "$dist" ] || return 0+ if command -v semanage &>/dev/null && command -v restorecon &>/dev/null; then+ semanage fcontext -a -t httpd_sys_content_t "${dist}(/.*)?" 2>/dev/null \+ || semanage fcontext -m -t httpd_sys_content_t "${dist}(/.*)?" 2>/dev/null || true+ restorecon -R "$dist" 2>/dev/null || true+ elif command -v chcon &>/dev/null; then+ chcon -R -t httpd_sys_content_t "$dist" 2>/dev/null || true+ fi+}+# Resolve the currently active real directory behind the symlink.active_real_dir() {if [ -L "$INSTALL_DIR" ]; then@@ -768,6 +787,19 @@ refresh_config() {cp "$target/nginx/sites-available/serverkit-insecure.conf" "$NGINX_DIR/sites-available/"fi+ # The panel frontend is served statically by host nginx from+ # $INSTALL_DIR/frontend/dist (the /opt/serverkit symlink). The shipped config+ # roots at the default /opt/serverkit; re-point it when SERVERKIT_DIR differs,+ # exactly as install.sh does, so a custom install dir survives upgrades.+ if [ "$INSTALL_DIR" != "/opt/serverkit" ]; then+ local conf+ for conf in serverkit.conf serverkit-insecure.conf; do+ [ -f "$NGINX_DIR/sites-available/$conf" ] && \+ sed -i "s|/opt/serverkit/frontend/dist|$INSTALL_DIR/frontend/dist|g" \+ "$NGINX_DIR/sites-available/$conf"+ done+ fi+# TLS floor — prefer a reversible conf.d snippet when nginx.conf doesn't# already declare these (a second declaration in the same http{} context is a# "duplicate ssl_protocols" error); otherwise rewrite in place. Mirrors@@ -877,7 +909,8 @@ rollback() {systemctl daemon-reloadsystemctl start "$BACKEND_SERVICE" 2>/dev/null || truewait_for_service "$BACKEND_SERVICE" active 30 || true- cd "$INSTALL_DIR" && docker compose up -d --force-recreate frontend 2>&1 | tail -5+ # Frontend is static (served from the restored slot); just re-label + reload.+ selinux_label_dist "$PREVIOUS_DIR"reload_nginx_graceful# Confirm the restored version actually answers — a rollback that itself@@ -1378,10 +1411,15 @@ PREVIOUS_DIR="$(active_real_dir)"atomic_switch "$NEXT_DIR"# Start services.+#+# The frontend is now static files under the switched-in slot's frontend/dist,+# served directly by host nginx (no container to recreate). The atomic switch+# already swapped the served assets; nginx only needs a graceful config reload.phase "Starting Services"run_or_dry systemctl start "$BACKEND_SERVICE"wait_for_service "$BACKEND_SERVICE" active 30 || warn "Backend did not report active within 30 seconds"-run_in_dir "$INSTALL_DIR" docker compose up -d --force-recreate frontend+# Re-label the now-active slot's bundle for SELinux hosts before nginx serves it.+selinux_label_dist "$NEXT_DIR"# Graceful, zero-downtime config swap — never a stop/start (see reload_nginx_graceful).reload_nginx_gracefulgood "Services started"