Static Sites

Railpack can automatically build and set up a server for static sites that require no build steps. The Caddy server is used as the underlying web server.

Detection

Your project will be automatically detected as a static site if any of these conditions are met:

• A Staticfile configuration file exists in the root directory
• An index.html file exists in the root directory
• A public directory exists
• The RAILPACK_STATIC_FILE_ROOT environment variable is set

Root Directory Resolution

The provider determines the root directory in this order:

1. RAILPACK_STATIC_FILE_ROOT environment variable if set
2. root directory specified in Staticfile if present
3. public directory if it exists
4. Current directory (.) if index.html exists in root

Configuration

Staticfile

You can configure static file serving with a Staticfile in your project root:

# root directory to serve
root: dist

# enable SPA routing: fall back to index.html for unmatched routes
index_fallback: true

index_fallback defaults to false. Enable it for single-page applications (React, Vue, Angular, etc.) where the frontend router handles all routes and the server should always serve index.html for unmatched paths.

Config Variables

Variable	Description	Example
RAILPACK_STATIC_FILE_ROOT	Override the root directory	public

Custom Caddyfile

Railpack uses a custom Caddyfile that is used to serve the static files. You can overwrite this file with your own Caddyfile at the root of your project.