Static Web Server

Appearance

Docker ​

SWS has first-class Docker support.

It is provided in three Docker image variants such as Scratch, Alpine and Debian images.

All images are available on Docker Hub and GitHub Container Registry.

OS/Arch ​

All Docker images are Multi-Arch and the following operating systems and architectures are supported.

  • linux/386
  • linux/amd64
  • linux/arm/v6
  • linux/arm/v7
  • linux/arm64
  • linux/ppc64le (Debian only)
  • linux/s390x (Debian only)

`Scratch` and `Alpine` images use statically-linked binaries

Sc ScratchandAlpine` based Docker images use a statically-linked binary that is portable, performant and dependency-free thanks to musl libc, keeping containers as lean as possible.

`Debian` images use dynamically-linked binaries

Debian based Docker images use SWS dynamically-linked binaries, making containers highly optimized, performant and resource-efficient.

Rootless ​

The Debian and Alpine Docker images are rootless by default using a dedicated sws user and group. This reduces the attack surface and improves security.

Remember

Users can still run the containers as root if they explicitly set the user to root when running the container, e.g., using the --user root flag with docker run.

The static-web-server binary and all files under /home/sws (home directory) are owned by the non-root sws user and group.

For convenience, those paths are also available:

  • Home directory: /home/sws
  • Public directory: /home/sws/public
  • Public directory symlink: /var/public -> /home/sws/public

The current working directory is the home directory by default.

Run a container ​

To give the server a quick try just run the following commands.

Tips

The SWS CLI arguments can be provided directly to the container or omitted as shown below. A Docker volume like -v $HOME/my-public-dir:/public can be specified to overwrite the default root directory.

To run SWS, there are several Docker image variants that you can use.

Scratch (just the binary) ​

sh
docker run --rm -it -p 8787:80 joseluisq/static-web-server:2 -g info
# or
docker run --rm -it -p 8787:80 ghcr.io/static-web-server/static-web-server:2 -g info

Alpine ​

sh
docker run --rm -it -p 8787:80 joseluisq/static-web-server:2-alpine -g info
# or
docker run --rm -it -p 8787:80 ghcr.io/static-web-server/static-web-server:2-alpine -g info

Debian ​

sh
docker run --rm -it -p 8787:80 joseluisq/static-web-server:2-debian -g info
# or
docker run --rm -it -p 8787:80 ghcr.io/static-web-server/static-web-server:2-debian -g info

FIPS-validated TLS ​

For deployments that require FIPS 140-validated cryptography (US federal, regulated industries), there are a few Docker image variants available with FIPS-validated TLS via the http2-fips feature. FIPS images use aws-lc-rs in FIPS mode instead of ring as the TLS crypto provider.

Platforms supported by FIPS images are linux/amd64 and linux/arm64 only.

Verify FIPS mode ​

To verify that the image supports FIPS mode, check the output of the following command:

sh
docker run --rm ghcr.io/static-web-server/static-web-server:2-fips -V | grep -i "fips"
# FIPS Mode:
#   Module Version:   AWS-LC-FIPS 3.0.x
#   Crypto Provider:  aws-lc-rs (via aws-lc-fips-sys)

Scratch ​

sh
# Scratch (just the binary)
docker run --rm -it -p 8787:80 joseluisq/static-web-server:2-fips -g info
# or
docker run --rm -it -p 8787:80 ghcr.io/static-web-server/static-web-server:2-fips -g info

Alpine ​

sh
docker run --rm -it -p 8787:80 joseluisq/static-web-server:2-fips-alpine -g info
# or
docker run --rm -it -p 8787:80 ghcr.io/static-web-server/static-web-server:2-fips-alpine -g info

Debian ​

sh
docker run --rm -it -p 8787:80 joseluisq/static-web-server:2-fips-debian -g info
# or
docker run --rm -it -p 8787:80 ghcr.io/static-web-server/static-web-server:2-fips-debian -g info

Development ​

Additionally, we publish development Docker images based on master branch changes.

sh
# Scratch (just the binary)
docker run --rm -it -p 8787:80 ghcr.io/static-web-server/static-web-server:devel -g info
# Debian
docker run --rm -it -p 8787:80 ghcr.io/static-web-server/static-web-server:devel-debian -g info

Dockerfile ​

SWS Docker images can be extended as needed.

Extending the Scratch Docker image (just the binary)

Dockerfile
FROM joseluisq/static-web-server:2
# or
FROM ghcr.io/static-web-server/static-web-server:2
# do stuff...

Or the Alpine

Dockerfile
FROM joseluisq/static-web-server:2-alpine
# or
FROM ghcr.io/static-web-server/static-web-server:2-alpine
# do stuff...

Or the Debian

Dockerfile
FROM joseluisq/static-web-server:2-debian
# or
FROM ghcr.io/static-web-server/static-web-server:2-debian
# do stuff...

Docker Compose ​

Example using Docker Compose.

yaml
version: '3.3'

services:
  website:
    image: joseluisq/static-web-server:2-alpine
    container_name: 'website'
    ports:
      - 80:80
    restart: unless-stopped
    environment:
      # Note: those envs are customizable but also optional
      - SERVER_ROOT=/var/public
      - SERVER_CONFIG_FILE=/etc/sws.toml
    volumes:
      - ./public:/var/public
      - ./sws.toml:/etc/sws.toml

Traefik Proxy ​

Example using Docker Swarm and Traefik Proxy.

  1. Create an external traefik_net Docker attachable network for Traefik:
    • docker network create --driver=overlay --attachable traefik_net
  2. Map a host directory like /var/www/website to the service container or create an external website_data Docker volume if you prefer:
    • docker volume create website_data
yaml
version: '3.3'

services:
  traefik:
    image: 'traefik:v2.11'
    command:
      #- "--log.level=DEBUG"
      - '--api.insecure=true'
      - '--providers.docker=true'
      - '--providers.docker.exposedbydefault=false'
      - '--entrypoints.web.address=:80'
    ports:
      - '80:80'
      - '8080:8080'
    volumes:
      - '/var/run/docker.sock:/var/run/docker.sock:ro'

  website:
    image: joseluisq/static-web-server:2
    environment:
      # Note: those envs are customizable but also optional
      - SERVER_ROOT=/public
    volumes:
      - /var/www/website:/public
      # Or use an existing Docker volume
      # - website_data:/public
    labels:
      - 'traefik.enable=true'
      - 'traefik.docker.network=traefik_net'
      - 'traefik.http.routers.website.entrypoints=web'
      - 'traefik.http.routers.website.rule=Host(`website.localhost`)'
      - 'traefik.http.routers.website.priority=1'
      - 'traefik.http.services.website.loadbalancer.server.port=80'
    networks:
      - traefik_net

# volumes:
#   website_data:
#     external: true

networks:
  traefik_net:
    external: true

Kubernetes ​

Example using Kubernetes pod with liveness probe.

yaml
apiVersion: v1
kind: Pod
metadata:
  name: website
spec:
  containers:
    - name: sws
      image: ghcr.io/static-web-server/static-web-server
      command:
        - static-web-server
        - --root=/public
        - --health
      ports:
        - containerPort: 80
      livenessProbe:
        httpGet:
          path: /health
          port: http

TrueCharts ​

The TrueCharts Community also provides a ready-to-use Static Web Server Helm-Chart that you can easily deploy in your Kubernetes.