Static Site Serving#

Dokploy serves static sites by generating an nginx:alpine-based Docker image at deploy time. Two build types produce this image via the same shared helper: Static (raw file drop or pre-built output) and Nixpacks (when a publishDirectory is set). Both paths converge on getStaticCommand in packages/server/src/utils/builders/static.ts.

How It Works#

Static Build Type#

getStaticCommand generates a shell script that:

1. Optionally writes a custom nginx.conf into the build directory (see SPA Routing below) 1
2. Writes a .dockerignore (excluding .git, .env, Dockerfile, .dockerignore) 2
3. Generates a Dockerfile that bases on nginx:alpine, sets WORKDIR /usr/share/nginx/html/, copies publishDirectory (defaults to .) into the webroot, and starts nginx with daemon off 3
4. Invokes getDockerCommand with buildType: "dockerfile" to build and deploy the image 4

File creation (nginx.conf, Dockerfile, .dockerignore) is handled by getCreateFileCommand, which base64-encodes content and writes it via shell.

Nixpacks Build Type#

When an application's publishDirectory is set and buildType is Nixpacks, getNixpacksCommand adds an artifact extraction step before handing off to getStaticCommand:

1. --no-error-without-start is passed to nixpacks (no start command needed since nginx will serve the output) 5
2. A temporary container is created from the nixpacks-built image 6
3. Artifacts are copied out of the container at /app/${publishDirectory} to the host filesystem 7
4. The container is removed, then getStaticCommand(application) is called to produce the final nginx image 8

This approach shrinks the final image significantly — from ~600 MB (full nixpacks build image) to ~40 MB (nginx + static files) 9.

The publishDirectory feature was introduced in PR #297.

SPA Routing#

When application.isStaticSpa is true, a custom nginx.conf is injected that adds try_files $uri $uri/ /index.html 10. This prevents 404s on page refresh for client-side routers (React Router, Vue Router, etc.) by falling back all unresolved paths to index.html.

The isStaticSpa flag is a boolean on the application model 11, toggled from the dashboard under Build → Static settings. It was introduced in PR #1931.

Without isStaticSpa, nginx uses its default config (no try_files override), so direct URL access to deep routes returns 404.

Key Files#

Architecture Flow#