viws

viws

A superlight HTTP fileserver with customizable behavior.

Installation

go get github.com/ViBiOh/viws/cmd/viws

Light version

Light version (without GZIP and Prometheus) is also available, for a smaller binary.

go get github.com/ViBiOh/viws/cmd/viws-light

Features

• Full TLS support
• GZIP Compression
• Prometheus monitoring
• Read-only container
• Serve static content, with Single Page App handling
• HTTP/2 Server push
• Serve environment variables for easier-config

Single Page Application

This mode is useful when you have a router in your javascript framework (e.g. Angular/React/Vue). When a request target a not found file, it returns the index instead of 404. This option also deactivates cache for the index in order to make work the cache-buster for javascript/style files.

curl myWebsite.com/users/vibioh/
=> /index.html

Endpoints

• GET /health: healthcheck of server, respond okStatus (default 204) or 503 during graceDuration when SIGTERM is received
• GET /version: value of VERSION environment variable
• GET /env: values of specified environments variables

Environment variables

Environment variables are exposed as JSON from a single and easy to remember endpoint: /env. You have full control of exposed variables by declaring them on the CLI.

This feature is useful for Single Page Application, you first request /env in order to know the API_URL or CONFIGURATION_TOKEN and then proceed. You reuse the same artifact between pre-production and production, only variables change, in respect of 12factor app

Configuration example

API_URL=https://api.vibioh.fr vibioh/viws --env API_URL

> curl http://localhost:1080/env
{"API_URL":"https://api.vibioh.fr"}

Usage in SPA

// index.js

const response = await fetch("/env");
const config = await response.json();
ReactDOM.render(<App config={config} />, document.getElementById("root"));

Usage

By default, server is listening on the 1080 port and serve content for GET requests from the /www/ directory. It assumes that HTTPS is done, somewhere between browser and server (e.g. CloudFlare, ReverseProxy, Traefik, ...) so it sets HSTS flag by default.

Usage of viws:
  -address string
        [http] Listen address {VIWS_ADDRESS}
  -cert string
        [http] Certificate file {VIWS_CERT}
  -corsCredentials
        [cors] Access-Control-Allow-Credentials {VIWS_CORS_CREDENTIALS}
  -corsExpose string
        [cors] Access-Control-Expose-Headers {VIWS_CORS_EXPOSE}
  -corsHeaders string
        [cors] Access-Control-Allow-Headers {VIWS_CORS_HEADERS} (default "Content-Type")
  -corsMethods string
        [cors] Access-Control-Allow-Methods {VIWS_CORS_METHODS} (default "GET")
  -corsOrigin string
        [cors] Access-Control-Allow-Origin {VIWS_CORS_ORIGIN} (default "*")
  -csp string
        [owasp] Content-Security-Policy {VIWS_CSP} (default "default-src 'self'; base-uri 'self'")
  -directory string
        [viws] Directory to serve {VIWS_DIRECTORY} (default "/www/")
  -env string
        [env] Environments key variables to expose, comma separated {VIWS_ENV}
  -frameOptions string
        [owasp] X-Frame-Options {VIWS_FRAME_OPTIONS} (default "deny")
  -graceDuration string
        [http] Grace duration when SIGTERM received {VIWS_GRACE_DURATION} (default "15s")
  -headers string
        [viws] Custom headers, tilde separated (e.g. content-language:fr~X-UA-Compatible:test) {VIWS_HEADERS}
  -hsts
        [owasp] Indicate Strict Transport Security {VIWS_HSTS} (default true)
  -key string
        [http] Key file {VIWS_KEY}
  -okStatus int
        [http] Healthy HTTP Status code {VIWS_OK_STATUS} (default 204)
  -port uint
        [http] Listen port {VIWS_PORT} (default 1080)
  -prometheusPath string
        [prometheus] Path for exposing metrics {VIWS_PROMETHEUS_PATH} (default "/metrics")
  -push string
        [viws] Paths for HTTP/2 Server Push on index, comma separated {VIWS_PUSH}
  -spa
        [viws] Indicate Single Page Application mode {VIWS_SPA}
  -url string
        [alcotest] URL to check {VIWS_URL}
  -userAgent string
        [alcotest] User-Agent for check {VIWS_USER_AGENT} (default "Alcotest")

Docker

docker run -d --name website \
  -p 1080:1080/tcp \
  -v "$(pwd):/www/:ro" \
  vibioh/viws

We recommend using a Dockerfile to ship your files inside it.

e.g.

FROM vibioh/viws

ENV VERSION 1.2.3-1234abcd
COPY dist/ /www/

Light image

Image with tag :light is also available.

e.g.

FROM vibioh/viws:light

ENV VERSION 1.0.0-1234abcd
COPY dist/ /www/

Compilation

You need Go 1.12+ with go modules enabled in order to compile the project.

make go

License