tdio/fss-proxy

•Updated 6 months ago

Nginx-based image serving static frontend assets and proxying API requests to backend services

Image

3.9K

tdio/fss-proxy repository overview

⁠tdio/fss-proxy

fss-proxy is a Docker image for serving frontend assets with Nginx and forwarding API traffic to backend services. It is designed for frontend deployments, local integration environments, and derived images that want a ready-made static site + reverse proxy runtime.

⁠What It Does

Serves files from /var/www
Supports SPA fallback to index.html
Proxies /api/, /svc/, or custom routes to upstream services
Supports multiple upstream backends
Supports HTTPS with mounted certs or optional auto-issued certs
Can be used directly or as a base image for frontend bundles

⁠Quick Start

Run the image with a local frontend build mounted into /var/www:

docker run --rm \
  --name fss-proxy \
  --network host \
  -v "$PWD/dist:/var/www" \
  -e FSS_PORT=8080 \
  -e FSS_UPSTREAM=127.0.0.1:8709 \
  tdio/fss-proxy:latest

Then open http://127.0.0.1:8080.

⁠Common Setups

⁠Static site with backend API proxy

docker run --rm \
  --name app \
  --network host \
  -v "$PWD/dist:/var/www" \
  -e FSS_PORT=8080 \
  -e FSS_SPA=1 \
  -e FSS_UPSTREAM=192.168.0.10:8709 \
  tdio/fss-proxy:latest

This serves the frontend from /var/www and forwards /api/ requests to 192.168.0.10:8709.

⁠Multiple backend upstreams

docker run --rm \
  --name app \
  --network host \
  -v "$PWD/dist:/var/www" \
  -e FSS_PORT=8080 \
  -e FSS_UPSTREAM=192.168.0.10:8709,192.168.0.11:8709 \
  tdio/fss-proxy:latest

⁠Custom proxy routes

docker run --rm \
  --name app \
  --network host \
  -v "$PWD/dist:/var/www" \
  -e FSS_SPA=0 \
  -e 'FSS_PROXY=[{"path":"/trace","target":"http://192.168.1.199:12800"},{"path":"/api/device","target":"http://192.168.1.20:12801/v1/device/$rewrite_path"}]' \
  tdio/fss-proxy:latest

⁠Environment Variables

⁠Core runtime

Variable	Default	What it does
`FSS_PORT`	`80`	HTTP listen port
`FSS_SERVER_NAME`	unset	Nginx `server_name`
`FSS_SPA`	`1`	Enables SPA fallback to `/index.html`
`FSS_CONTEXT_PATH`	`/`	Mounts the app under a prefix such as `/abc/`
`FSS_QUIET_LOGS`	unset / false	Reduces entrypoint logging

⁠Backend routing

Variable	Default	What it does
`FSS_UPSTREAM`	`127.0.0.1:8709`	Comma-separated upstream backend servers
`FSS_API_BASE`	`/api/`	Prefix routed to the default backend upstream
`FSS_SVC_PREFIX`	`/svc/`	Additional prefix routed to the default backend upstream
`FSS_REWRITE_API`	`1`	Rewrites `FSS_API_BASE` before proxying
`FSS_PROXY`	unset	JSON array of custom proxy route definitions
`FSS_PROXY_SET_HOST`	`true`	Forwards the original `Host` header to upstreams

⁠HTTPS and security

Variable	Default	What it does
`FSS_SSL_PORT`	unset	Enables HTTPS listener
`FSS_FORCE_SSL`	`0`	Redirects HTTP requests to HTTPS
`FSS_SSL_ISSUER_ENABLE`	`false`	Enables automatic certificate fetch
`FSS_SSL_ISSUER_SERVER`	built-in URL template	Certificate issuer endpoint
`FSS_SSL_ISSUER_IPADDR`	auto-detected	IP used for certificate requests
`FSS_SSL_ISSUER_DOMAIN`	unset	DNS names used for certificate requests
`FSS_FIX_HTTPS_COOKIE`	`true`	Adds secure SameSite handling for proxied cookies
`FSS_VALID_REFERERS`	unset	Enables `valid_referers` checks
`FSS_HEADERS_CSP`	built-in value	Sets the `Content-Security-Policy` header
`FSS_HEADERS_XSS_PROTECTION`	`1; mode=block`	Sets the `X-XSS-Protection` header

⁠DNS and config loading

Variable	Default	What it does
`FSS_LOCAL_RESOLVERS_DISABLED`	`false`	Disables automatic resolver generation
`FSS_LOCAL_RESOLVERS`	derived from `/etc/resolv.conf`	Explicit DNS resolvers for Nginx
`FSS_LOAD_ENV`	unset	Enables loading environment variables from a file
`FSS_ENV_FILE`	`/.env`	Env file path used when env loading is enabled

⁠`FSS_PROXY` Format

Use FSS_PROXY for one-off paths that should go to a specific target instead of the default upstream.

type ProxyEntry = {
  path: string
  target: string
  cors?: boolean
  rewrite?: boolean
}

Example:

export FSS_PROXY='[
  {"path":"/trace","target":"http://192.168.1.199:12800"},
  {"path":"/api/device","target":"http://192.168.1.20:12801/v1/device/$rewrite_path"}
]'

When rewrite is not set to false, the route path is stripped before proxying.

⁠Use as a Base Image

fss-proxy supports ONBUILD arguments so frontend bundles can be baked into a derived image.

FROM tdio/fss-proxy:latest

ADD --chown=nginx:nginx ./dist.tgz /var/www/

Build example:

docker build \
  -t cmp-ui:2.4.1 \
  --build-arg BUILD_VERSION=2.4.1 \
  --build-arg BUILD_GIT_HEAD=10a3720f8de3fc7e0c2cbb6d16a9e2a72d603401 \
  -f ./Dockerfile.test .

Supported ONBUILD args:

ARG BUILD_VERBOSE=false
ARG BUILD_GIT_HEAD
ARG BUILD_VERSION
ARG BUILD_ADD_DIST=true

⁠Documentation

docs/README.md⁠: documentation index
docs/User_Guide.md⁠: deployment, configuration, and troubleshooting
docs/architecture/README.md⁠: architecture docs entry
docs/architecture/Project_Architecture_Blueprint.md⁠: full architecture blueprint

Tag summary

Recent tags

Content type