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
fix(deploy): make docker-compose.yml frontend-only (backend runs on host)
Juan Denis31330a09be21
diff --git a/backend/Dockerfile b/backend/Dockerfileindex bb9d3e20..c8986ce9 100644--- a/backend/Dockerfile+++ b/backend/Dockerfile@@ -1,4 +1,9 @@# Backend Dockerfile for ServerKit+#+# NOTE: A containerized backend CANNOT manage the host (no host Docker daemon,+# nginx, systemctl, or real /var/serverkit/apps). The canonical deployment runs+# the backend on the host via systemd (see install.sh + docker-compose.yml,+# which is frontend-only). This image is only for local/dev or all-in-one demos.FROM python:3.11-slim-bookworm# Set environment variables@@ -42,11 +47,14 @@ RUN pip install --no-cache-dir -r requirements.txt \# Copy application codeCOPY . .-# Create non-root user and set permissions+# Create non-root user and set permissions. /var/serverkit must be owned by+# appuser too, otherwise the (dev/demo) backend cannot create app directories+# under /var/serverkit/apps and fails with EACCES.RUN useradd --create-home appuser \&& chown -R appuser:appuser /app \&& chown -R appuser:appuser /app/instance \&& chown -R appuser:appuser /etc/serverkit \+ && chown -R appuser:appuser /var/serverkit \&& chown -R appuser:appuser /var/quarantine \&& chown -R appuser:appuser /var/backups/serverkitdiff --git a/docker-compose.yml b/docker-compose.ymlindex c5b4b8c8..08b13fd5 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -1,50 +1,26 @@# ============================================-# ServerKit Docker Compose+# ServerKit Docker Compose (canonical deployment)# ============================================-# Runs both backend and frontend in Docker.-# Note: System management features (PHP install,-# firewall, etc.) won't work in Docker.+# 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.#-# Usage:-# docker compose up --build -d+# 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.#-# Access:-# Frontend: http://localhost:3847-# Backend: http://localhost:5849+# Install (sets up the host backend + this frontend): ./serverkit install+# Frontend only: docker compose 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+# header notes, cannot manage the host.# ============================================services:- backend:- build:- context: ./backend- dockerfile: Dockerfile- container_name: serverkit-backend- environment:- - FLASK_ENV=development- - SECRET_KEY=dev-secret-key-not-for-production- - JWT_SECRET_KEY=dev-jwt-key-not-for-production- - DATABASE_URL=sqlite:////app/instance/serverkit.db- - CORS_ORIGINS=http://localhost,http://localhost:3847,http://localhost:41921- - SERVERKIT_BACKEND_PORT=5000- ports:- - "5849:5000"- volumes:- - serverkit-data:/app/instance- - serverkit-config:/etc/serverkit- networks:- - serverkit-network- restart: unless-stopped- healthcheck:- test: ["CMD-SHELL", "curl -f http://localhost:$${SERVERKIT_BACKEND_PORT:-5000}/api/v1/system/health"]- interval: 10s- timeout: 5s- retries: 3- logging:- driver: "json-file"- options:- max-size: "10m"- max-file: "3"-frontend:build:context: ./frontend@@ -52,9 +28,12 @@ services:container_name: serverkit-frontendports:- "3847:80"- depends_on:- backend:- condition: service_healthy+ # Resolve `backend` (used by frontend/nginx.conf) to the host, where the+ # ServerKit backend listens on :5000 under systemd.+ extra_hosts:+ - "backend:host-gateway"+ # install.sh builds the SPA to ./frontend/dist on the host; serve that build+ # directly so a rebuild doesn't require rebuilding the image.volumes:- ./frontend/dist:/usr/share/nginx/html:ronetworks:@@ -75,9 +54,3 @@ networks:serverkit-network:driver: bridgename: serverkit-network--volumes:- serverkit-data:- name: serverkit-data- serverkit-config:- name: serverkit-configdiff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.mdindex 7548d916..142d465a 100644--- a/docs/DEPLOYMENT.md+++ b/docs/DEPLOYMENT.md@@ -2,6 +2,25 @@Complete guide for deploying ServerKit on Ubuntu servers.+## Deployment model (important)++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:++- 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.+## Quick Install (Ubuntu)```bash@@ -208,12 +227,16 @@ 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.+```bash-# Build containers-docker compose build+# Build + start the frontend container+docker compose up -d --build-# Start services-docker compose up -d+# Start the host backend (installed by ./serverkit install)+sudo systemctl start serverkit# Verifyserverkit status@@ -256,12 +279,17 @@ sudo systemctl status serverkit| `SSL_PORT` | HTTPS port | `443` || `FLASK_ENV` | Environment mode | `production` |-### Docker Volumes+### Host data locations++The backend runs on the host, so its data lives on the host filesystem (not in+Docker volumes):-| Volume | Purpose |-|--------|---------|-| `serverkit-data` | Database and application data |-| `nginx/ssl` | SSL certificates |+| Path | Purpose |+|------|---------|+| `/opt/serverkit/backend/instance/serverkit.db` | SQLite database (default) |+| `/var/serverkit/apps/` | Managed app directories (one per app) |+| `/etc/serverkit/` | Config (templates, ssl-mode, install state) |+| `/var/backups/serverkit/` | Backups |## Common Tasksdiff --git a/frontend/nginx.conf b/frontend/nginx.confindex 5f65cb51..0cbf93fe 100644--- a/frontend/nginx.conf+++ b/frontend/nginx.conf@@ -23,7 +23,9 @@ server {try_files $uri $uri/ /index.html;}- # Proxy API requests to backend (running on host, not in Docker)+ # Proxy API requests to the backend, which runs on the HOST (systemd), not+ # in Docker. `backend` resolves to the host via the compose `extra_hosts:+ # ["backend:host-gateway"]` alias (see docker-compose.yml).location /api {proxy_pass http://backend:5000;proxy_http_version 1.1;diff --git a/scripts/test/test_install.sh b/scripts/test/test_install.shindex a9a953cf..a6c4a419 100644--- a/scripts/test/test_install.sh+++ b/scripts/test/test_install.sh@@ -290,6 +290,25 @@ elseok "choose_pkg_manager halts cleanly when no package manager is found"fi+# --------------------------------------------------------------------------+# T12 — the canonical docker-compose.yml is frontend-only. The backend manages+# the host (creates /var/serverkit/apps/*, drives host Docker, reloads nginx),+# which a container cannot do — a backend container fails app creation with+# `Permission denied: /var/serverkit/apps/...` and has no host docker.sock.+# Guard against re-adding a `backend` compose service (the regression that+# broke WordPress/app creation).+# --------------------------------------------------------------------------+compose="$REPO_DIR/docker-compose.yml"+if grep -Eq '^[[:space:]]{2}backend:' "$compose"; then+ bad "docker-compose.yml defines a 'backend' service — the backend must run on the host, not in a container"+elif ! grep -Eq '^[[:space:]]{2}frontend:' "$compose"; then+ bad "docker-compose.yml is missing the 'frontend' service"+elif ! grep -q 'backend:host-gateway' "$compose"; then+ bad "docker-compose.yml frontend is missing the 'backend:host-gateway' alias to reach the host backend"+else+ ok "docker-compose.yml is frontend-only and routes /api to the host backend (backend:host-gateway)"+fi+# --------------------------------------------------------------------------printf '\n%d passed, %d failed, %d skipped\n\n' "$PASS" "$FAIL" "$SKIP"[ "$FAIL" -eq 0 ]