# README
staticsrv
The command line tool for hosting a directory as a website.
Quick Start: Docker
The easiest way to get started with this tool is to include the docker image in your repository.
# The "latest" tag contains the last released version of this binary.
FROM sverigestelevision/staticsrv:latest
# The docker work directory is /srv/www everything will by default get hosted by staticsrv.
COPY ./build .
NOTE: If you got other compilation steps for your website before you can host the static artifacts, we recommend using multi stage docker builds using staticsrv in the last stage.
Usage
To host your current directory simply type staticsrv.
$ staticsrv
Serve a specific location
In most circumstances you probably want to host a directory you're currently not in. Simply use the path to the directory.
$ staticsrv ./build
More usage information
You can always get the tool's help page by providing the -h flag.
$ staticsrv -h
# Usage: staticsrv [OPTIONS] [DIR]
# Configuration Options:
# -addr string
# network interface to expose for serving the website (default "0.0.0.0:8080")
# -config-variables string
# comma separated list of environment variables to expose in /config.json
# -disable-config-variables
# disables the /config.json endpoint
# -disable-health-checks
# disables the /readyz and /livez endpoints
# -enable-fallback-to-index
# enables serving of fallback file (index.html) for any missing file
# -enable-metrics
# enable scraping application metrics
# -enable-access-log
# enable access log to see all requests to your server to stderr
# -metrics-addr string
# network interface to expose for serving prometheus metrics (default "0.0.0.0:9090")
# -metrics-path string
# http path where prometheus metrics are exported (default "/metrics")
# -timeout-idle int
# the maximum amount of time to wait for the next request (default 60)
# -timeout-read int
# the maximum duration for reading the entire request (default 5)
# -timeout-write int
# the maximum duration before timing out writes of the response (default 5)
# -version
# print the current version number of staticsrv
Features
Liveness and readiness endpoints for kubernetes
In a world of container clouds, it's important to have probe endpoints available. Try them out using curl.
$ curl -k http://localhost:8080/readyz
# ok
$ curl -k http://localhost:8080/livez
# ok
The check endpoints are enabled by default, but can be disabled.
$ staticsrv -disable-health-checks
Fallback to index file
If you're running a front-end framework like React, it might be a good idea to make sure all routes except existing static assets all route to the index file.
$ staticsrv -enable-fallback-to-index
Serving configuration variables
Depending on your environment, you might want to provision configuration variables to your web front-end javascript.
The webserver, by default, serves a json file on the path /config.json. You can configure what environment variables should be exposed in the response, passing a comma separated list to -config-variables.
$ staticsrv -config-variables="ENV_VAR_ONE,ENV_VAR_TWO"
If you hit the configuration endpoint, you should receive a response like this, including your specified variables, wether or not they're set.
{
"ENV_VAR_ONE": "Foo",
"ENV_VAR_TWO": "Bar"
}
To disable webserver from serving the /config.json file.
$ staticsrv -disable-config-variables
Export prometheus metrics
Application metrics can be exported for a prometheus collector to scrape over http. This might be good if you want insight in how the staticsrv runtime is impacting your cluster for high volume applications. Go runtime metrics are as the time of writing not well documented, but you can read the source code for the collector library for pointers.
$ staticsrv -enable-metrics
By default prometheus metrics can be scraped through http on /metrics on port 9090, but can be configured.
$ staticsrv -enable-metrics -metrics-addr :2112 -metrics-path /stats
Metrics Exposed
Here's a table with all the metrics that are exposed by the server through the metrics endpoint. We also expose some metrics for the Go process using the Go prometheus library.
| name | type | labels | description |
|---|---|---|---|
staticsrv_http_requests_total | Counter | method, status | Total amount of requests made to the server process |
staticsrv_http_requests_duration_seconds | Histogram | Request time in seconds (with fractions) | |
staticsrv_http_requests_size_bytes | Histogram | Request size in bytes |
Request access log
You might want to enable access logs if you want to perform analysis on requests to your site. When enabling the access log the log output will post to stderr using the logfmt format.
$ staticsrv -enable-access-log
method=GET duration=7.48875ms size=624B size_bytes=624 status=200 path="/" time=1634312038387629000
method=GET duration=129.875µs size=406B size_bytes=406 status=200 path="/index.css" time=1634312038433253000
method=GET duration=117.666µs size=367B size_bytes=367 status=200 path="/index.js" time=1634312038434145000
method=GET duration=153.416µs size=624B size_bytes=624 status=200 path="/" time=1634312038600024000
Installing
From source
The tool is built with Go 1.17, but any version down to Go 1.11 should work just fine to build. To install to go bin path, just run go install in this repo and make sure your go bin directory is set in your path.
$ go install
Dependencies
This project is not without dependencies, below we detail the intent of our dependencies and provide links to their source.
- We use the official prometheus go client to provide endpoints for prometheus to scrape metrics from the web server. The dependency is also licensed under
Apache 2.0.
Release process
- Create an annotated tag and push Github Actions publishes a new image on Docker Hub, once a new tag like "v*.*.*" (e.g. v0.3.0) is created.
git tag -s -a v${version} -m "v${version}"
git push origin v${version}
- Create a new release on github, according to the instruction. Preferably use Auto-generate release notes for the notes so we don't forget any changes.
Primary Maintainers
Changelog
v0.3.0
- Fix: Set timeout values for HTTP requsts.
- Chore: update OS for build-container.
v0.2.1
- Fix: Handle unhandled errors when writing responses.
v0.2.0
- Feature: Added request metrics to prometheus export
- Feature: Added request access logs that can be enabled with a flag to the server
v0.1.1
- Fix: We were still exposing 9090 in the docker image using ONBUILD.
v0.1.0
- Do not enable metrics by default within the docker image. This is a breaking change for people relying on the docker image to expose metrics as is.