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.

fix(deploy): make docker-compose.yml frontend-only (backend runs on host)

Juan Denis31330a09be21
diff --git a/backend/Dockerfile b/backend/Dockerfile
index 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 code
COPY . .
-# 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/serverkit
diff --git a/docker-compose.yml b/docker-compose.yml
index 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-frontend
ports:
- "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:ro
networks:
@@ -75,9 +54,3 @@ networks:
serverkit-network:
driver: bridge
name: serverkit-network
-
-volumes:
- serverkit-data:
- name: serverkit-data
- serverkit-config:
- name: serverkit-config
diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
index 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
# Verify
serverkit 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 Tasks
diff --git a/frontend/nginx.conf b/frontend/nginx.conf
index 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.sh
index a9a953cf..a6c4a419 100644
--- a/scripts/test/test_install.sh
+++ b/scripts/test/test_install.sh
@@ -290,6 +290,25 @@ else
ok "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 ]