Skip to content
Klutch.sh Docs

Deploying Static Web Server

Introduction

Static Web Server (SWS) is a blazing fast, lightweight static file server written in Rust. Designed for serving static websites, single-page applications, and file downloads, SWS provides an efficient alternative to heavyweight web servers when you only need to serve static content.

With its tiny memory footprint and high performance, Static Web Server is perfect for serving documentation sites, landing pages, built frontend applications, and any content that doesn’t require server-side processing.

Key highlights of Static Web Server:

  • Blazing Fast: Written in Rust for maximum performance
  • Lightweight: Minimal memory and CPU usage
  • Easy Configuration: Simple command-line and TOML configuration
  • Gzip/Brotli Compression: Automatic response compression
  • Cache Control: Configurable caching headers
  • Directory Listing: Optional file browser
  • CORS Support: Configurable cross-origin settings
  • Security Headers: Security best practices built-in
  • Custom Error Pages: Configurable 404 and error pages
  • SPA Support: Fallback routing for single-page apps
  • Health Check Endpoint: Built-in health checks
  • Docker Ready: Small, efficient container image
  • Open Source: MIT/Apache-2.0 dual licensed

This guide walks through deploying Static Web Server on Klutch.sh using Docker for efficient static content hosting.

Why Deploy Static Web Server on Klutch.sh

Deploying Static Web Server on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh handles the container deployment automatically.

HTTPS by Default: Secure content delivery with automatic SSL.

Low Resource Usage: SWS runs efficiently on minimal resources.

GitHub Integration: Deploy your static site directly from GitHub.

Custom Domains: Serve your site from a custom domain.

Fast Performance: Rust-based server delivers content quickly.

Perfect for Static Sites: Ideal for documentation, landing pages, SPAs.

Prerequisites

Before deploying Static Web Server on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your static content
  • Static files to serve (HTML, CSS, JS, images, etc.)
  • Basic familiarity with Docker
  • (Optional) A custom domain

Deploying Static Web Server on Klutch.sh

    Create a GitHub Repository

    Create a repository containing your static files.

    Create Your Dockerfile

    Create a Dockerfile in your repository:

    FROM joseluisq/static-web-server:2
    

    # Copy your static files
    COPY ./public /public
    

    # Set environment variables
    ENV SERVER_ROOT=/public
    ENV SERVER_PORT=8787
    ENV SERVER_LOG_LEVEL=info
    

    EXPOSE 8787
    

    HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
      CMD wget --no-verbose --tries=1 --spider http://localhost:8787/health || exit 1

    Organize Your Static Files

    Structure your public directory:

    public/
    ├── index.html
    ├── css/
    │   └── style.css
    ├── js/
    │   └── app.js
    ├── images/
    │   └── logo.png
    ├── 404.html
    └── favicon.ico

    Push Your Repository to GitHub

    Commit and push your Dockerfile and static files.

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project.

    Create a New App

    Within your project, create a new app and connect your GitHub repository.

    Configure HTTP Traffic

    In the deployment settings:

    • Select HTTP as the traffic type
    • Set the internal port to 8787

    Set Environment Variables (Optional)

    Configure optional environment variables:

    VariableValue
    SERVER_COMPRESSIONtrue
    SERVER_COMPRESSION_LEVELdefault
    SERVER_DIRECTORY_LISTINGfalse
    SERVER_CACHE_CONTROL_HEADERStrue

    Deploy Your Application

    Click Deploy to build and start Static Web Server.

    Access Your Site

    Once deployment completes, access your static site at https://your-app-name.klutch.sh.

Configuration Options

Environment Variables

VariableDescriptionDefault
SERVER_ROOTRoot directory for files/public
SERVER_PORTListen port80
SERVER_HOSTListen address0.0.0.0
SERVER_COMPRESSIONEnable compressiontrue
SERVER_DIRECTORY_LISTINGEnable file browserfalse
SERVER_CACHE_CONTROL_HEADERSAdd cache headerstrue
SERVER_LOG_LEVELLog verbosityerror

TOML Configuration

For advanced configuration, create config.toml:

[general]
host = "0.0.0.0"
port = 8787
root = "/public"
log-level = "info"


[general.compression]
gzip = true
brotli = true


[general.directory-listing]
order = 1
format = "html"


[general.cache-control-headers]
max-age = 86400


[general.security-headers]
enabled = true


[general.fallback-page]
enabled = true
file = "/index.html"

Using Config File

Update Dockerfile to use config:

FROM joseluisq/static-web-server:2


COPY ./config.toml /config.toml
COPY ./public /public


ENV SERVER_CONFIG_FILE=/config.toml


EXPOSE 8787

Single-Page Application (SPA) Support

Fallback Routing

For SPAs like React, Vue, or Angular:

FROM joseluisq/static-web-server:2


COPY ./dist /public


ENV SERVER_ROOT=/public
ENV SERVER_PORT=8787
ENV SERVER_FALLBACK_PAGE=/index.html


EXPOSE 8787

This ensures all routes fall back to index.html for client-side routing.

SPA Build Integration

For a complete SPA workflow:

# Build stage
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build


# Production stage
FROM joseluisq/static-web-server:2


COPY --from=builder /app/dist /public


ENV SERVER_ROOT=/public
ENV SERVER_PORT=8787
ENV SERVER_FALLBACK_PAGE=/index.html
ENV SERVER_COMPRESSION=true


EXPOSE 8787

Documentation Sites

Serving Documentation

Perfect for VitePress, Docusaurus, MkDocs output:

FROM joseluisq/static-web-server:2


COPY ./docs/.vitepress/dist /public


ENV SERVER_ROOT=/public
ENV SERVER_PORT=8787
ENV SERVER_COMPRESSION=true


EXPOSE 8787

Directory Listing for Downloads

For file download directories:

FROM joseluisq/static-web-server:2


COPY ./downloads /public


ENV SERVER_ROOT=/public
ENV SERVER_DIRECTORY_LISTING=true
ENV SERVER_DIRECTORY_LISTING_ORDER=1
ENV SERVER_DIRECTORY_LISTING_FORMAT=html


EXPOSE 8787

Performance Tuning

Compression

Enable compression for faster delivery:

OptionDescription
gzipTraditional compression, wide support
brotliBetter compression, modern browsers

Cache Headers

Configure caching for better performance:

[general.cache-control-headers]
max-age = 31536000  # 1 year for static assets

Small Docker Image

The SWS image is only about 10MB, making deployments fast.

Security Features

Security Headers

Built-in security headers:

  • X-Content-Type-Options: nosniff
  • X-Frame-Options: DENY
  • X-XSS-Protection: 1; mode=block

CORS Configuration

Enable CORS for API-like usage:

[general.cors]
enabled = true
origins = ["https://example.com"]
methods = ["GET", "HEAD", "OPTIONS"]

Custom Error Pages

404 Page

Create a custom 404 page:

  1. Add 404.html to your public directory
  2. The server automatically serves it for missing files

Custom Error Configuration

[general.page404]
file = "/custom-404.html"

Troubleshooting

Files Not Found

  • Verify files are in the correct directory
  • Check SERVER_ROOT path
  • Review file permissions

Compression Not Working

  • Verify SERVER_COMPRESSION is enabled
  • Check that client accepts compression
  • Some file types are already compressed (images)

SPA Routes Not Working

  • Enable SERVER_FALLBACK_PAGE
  • Set to /index.html
  • Verify the fallback file exists

Additional Resources

Conclusion

Deploying Static Web Server on Klutch.sh gives you a fast, efficient way to serve static content. Whether you’re hosting a documentation site, landing page, or single-page application, SWS delivers with minimal resource usage and maximum performance. With its simple configuration and built-in features like compression and security headers, you can focus on your content rather than server configuration.