Skip to content

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.

feat(deploy): serve panel frontend from host nginx, retire the container

Juan Denisca666297806a
diff --git a/docker-compose.yml b/docker-compose.yml
index 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: ./frontend
dockerfile: Dockerfile
diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
index 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 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 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 + nginx
sudo systemctl start serverkit
+sudo systemctl reload nginx
# Verify
serverkit status
diff --git a/install.sh b/install.sh
index 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_mode
install_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; then
setsebool -P httpd_can_network_connect 1 2>/dev/null || true
fi
+ selinux_label_frontend_dist
good "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 nginx
good "Services started."
diff --git a/nginx/sites-available/serverkit-insecure.conf b/nginx/sites-available/serverkit-insecure.conf
index 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.conf
index 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.sh
index c3db7c73..b642388c 100644
--- a/scripts/test/test_update.sh
+++ b/scripts/test/test_update.sh
@@ -337,6 +337,47 @@ else
ok "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.sh
index 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-reload
systemctl start "$BACKEND_SERVICE" 2>/dev/null || true
wait_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_graceful
good "Services started"