docs: improve documentation pages [skip ci]
Diff
README.md | 6 +-
docs/content/building-from-source.md | 4 +-
docs/content/configuration/config-file.md | 83 ++++++++++++++++++++----------
docs/content/download-and-install.md | 2 +-
docs/content/download-and-install.tmpl.md | 2 +-
docs/content/features/compression-static.md | 2 +-
docs/content/features/security-headers.md | 4 +-
docs/content/index.md | 9 +--
docs/content/platforms-architectures.md | 2 +-
src/lib.rs | 2 +-
src/settings/file.rs | 2 +-
tests/toml/config.toml | 4 +-
12 files changed, 75 insertions(+), 47 deletions(-)
@@ -34,7 +34,7 @@ Written on top of [Hyper](https://github.com/hyperium/hyper) and [Tokio](https:/
It's cross-platform and available for `Linux`, `macOS`, `Windows` and `FreeBSD` (`x86`/`x86_64`, `ARM`/`ARM64`) and `Docker`.
## Features
@@ -51,7 +51,7 @@ It's cross-platform and available for `Linux`, `macOS`, `Windows` and `FreeBSD`
- [Security headers](https://web.dev/security-headers/) for HTTP/2 by default.
- [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) responses.
- Lightweight and configurable logging via [tracing](https://github.com/tokio-rs/tracing) crate.
- A Customizable number of worker threads.
- Customizable number of blocking and worker threads.
- Optional directory listing.
- [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) support.
- Basic HTTP Authentication.
@@ -63,7 +63,7 @@ It's cross-platform and available for `Linux`, `macOS`, `Windows` and `FreeBSD`
- HTTP to HTTPS redirect.
- Support for serving pre-compressed (Gzip/Brotli/Zstd) files.
- Custom URL rewrites and redirects via glob patterns.
- First-class [Docker](https://docs.docker.com/get-started/overview/) support. [Scratch](https://hub.docker.com/_/scratch) and latest [Alpine Linux](https://hub.docker.com/_/alpine) Docker images.
- First-class [Docker](https://docs.docker.com/get-started/overview/) support. [Scratch](https://hub.docker.com/_/scratch), latest [Alpine Linux](https://hub.docker.com/_/alpine) and [Debian](https://hub.docker.com/_/alpine) Docker images.
- Ability to accept a socket listener as a file descriptor for sandboxing and on-demand applications (e.g [systemd](http://0pointer.de/blog/projects/socket-activation.html)).
- Cross-platform. Pre-compiled binaries for Linux, macOS, Windows, FreeBSD and Android (`x86`,`x86_64`,`ARM`,`ARM64`).
@@ -62,10 +62,10 @@ If you want to cross-compile SWS then consider using [Zig](https://github.com/zi
Let's say, you want to cross-compile SWS from macOS to Linux. Then follow these steps.
1. Add the necessary toolchain, for example: `rustup target add x86_64-unknown-linux-gnu` or using `rustup target add x86_64-unknown-linux-musl` if a statically-linked binary is wanted.
1. Add the necessary toolchain, for example just type: `rustup target add x86_64-unknown-linux-gnu` or `rustup target add x86_64-unknown-linux-musl` if a statically-linked binary is wanted.
2. Install the latest [Zig](https://github.com/ziglang/zig) version via `brew install zig`
3. Install [cargo-zigbuild](https://github.com/rust-cross/cargo-zigbuild) via `cargo install cargo-zigbuild`
4. Finally, just build SWS as follows:
4. Finally, build SWS as follows:
```sh
# dynamically-linked binary
cargo zigbuild --verbose --release --target=x86_64-unknown-linux-gnu
@@ -31,27 +31,28 @@ page50x = "./public/50x.html"
#### HTTP/2 + TLS
http2 = false
# http2-tls-cert = "some.cert"
# http2-tls-key = "some.key"
http2-tls-cert = ""
http2-tls-key = ""
https-redirect = false
https-redirect-host = "localhost"
https-redirect-from-port = 80
https-redirect-from-hosts = "localhost"
#### Security headers
security-headers = true
#### CORS
cors-allow-origins = ""
cors-allow-headers = ""
#### CORS & Security headers
# security-headers = true
# cors-allow-origins = ""
#### Directory listing
directory-listing = false
#### Directory listing sorting code
directory-listing-order = 6
directory-listing-order = 1
#### Directory listing content format ("html" or "json")
#### Directory listing content format
directory-listing-format = "html"
#### Basich Authentication
basic-auth = ""
#### Basic Authentication
# basic-auth = ""
#### File descriptor binding
# fd = ""
@@ -63,7 +64,7 @@ threads-multiplier = 1
grace-period = 0
#### Page fallback for 404s
# page-fallback = "some_page.html"
# page-fallback = ""
#### Log request Remote Address if available
log-remote-address = false
@@ -72,26 +73,58 @@ log-remote-address = false
redirect-trailing-slash = true
#### Check for existing pre-compressed files
compression-static = false
#### Ignore hidden files/directories (dotfiles)
ignore-hidden-files = false
compression-static = true
### Windows Only
#### Windows Service support.
#### NOTE: this doesn't create a Windows Service per se,
#### instead, it just tells SWS to run in a Windows Service context,
#### so it's necessary to install the SWS Windows Service first
#### using the `static-web-server.exe -w config.toml install` command.
#### More details on https://static-web-server.net/features/windows-service/
#### Run the web server as a Windows Service
# windows-service = false
[advanced]
#### ....
#### HTTP Headers customization (examples only)
#### a. Oneline version
# [[advanced.headers]]
# source = "**/*.{js,css}"
# headers = { Access-Control-Allow-Origin = "*" }
#### b. Multiline version
# [[advanced.headers]]
# source = "/index.html"
# [advanced.headers.headers]
# Cache-Control = "public, max-age=36000"
# Content-Security-Policy = "frame-ancestors 'self'"
# Strict-Transport-Security = "max-age=63072000; includeSubDomains; preload"
#### c. Multiline version with explicit key (dotted)
# [[advanced.headers]]
# source = "**/*.{jpg,jpeg,png,ico,gif}"
# headers.Strict-Transport-Security = "max-age=63072000; includeSubDomains; preload"
### URL Redirects (examples only)
# [[advanced.redirects]]
# source = "**/*.{jpg,jpeg}"
# destination = "/images/generic1.png"
# kind = 301
# [[advanced.redirects]]
# source = "/index.html"
# destination = "https://static-web-server.net"
# kind = 302
### URL Rewrites (examples only)
# [[advanced.rewrites]]
# source = "**/*.{png,ico,gif}"
# destination = "/assets/favicon.ico"
# [[advanced.rewrites]]
# source = "**/*.{jpg,jpeg}"
# destination = "/images/sws.png"
```
### General options
@@ -13,7 +13,7 @@ Latest **v2.19.0** release `2023-06-16` ([changelog](https://github.com/static-w
See also [the release history](https://github.com/static-web-server/static-web-server/releases) on GitHub.
!!! info "Docker"
If you are working with Docker containers then check out [the Docker page](https://static-web-server.net/features/docker/).
If you are working with Docker containers then check out [the Docker feature page](https://static-web-server.net/features/docker/).
## Installation methods
@@ -13,7 +13,7 @@ Latest **{{RELEASE_VERSION}}** release `{{RELEASE_DATE}}` ([changelog](https://g
See also [the release history](https://github.com/static-web-server/static-web-server/releases) on GitHub.
!!! info "Docker"
If you are working with Docker containers then check out [the Docker page](https://static-web-server.net/features/docker/).
If you are working with Docker containers then check out [the Docker feature page](https://static-web-server.net/features/docker/).
## Installation methods
@@ -2,7 +2,7 @@
**`SWS`** provides support to serve pre-compressed [`Gzip`](https://datatracker.ietf.org/doc/html/rfc1952), [`Brotli`](https://www.ietf.org/rfc/rfc7932.txt) and [`Zstandard` (zstd)](https://datatracker.ietf.org/doc/html/rfc8878) files directly from the disk.
SWS can look up existing pre-compressed file variants (`.gz`, `.br` or `zst`) on disk and serve them directly.
SWS can look up existing pre-compressed file variants (`.gz`, `.br` or `.zst`) on disk and serve them directly.
The feature is disabled by default and can be controlled by the boolean `--compression-static` option or the equivalent [SERVER_COMPRESSION_STATIC](./../configuration/environment-variables.md#server_compression_static) env.
@@ -6,10 +6,6 @@ When the [HTTP/2](../features/http2-tls.md) feature is activated *security heade
This feature is disabled by default on HTTP/1 and can be controlled by the boolean `--security-headers` option or the equivalent [SERVER_SECURITY_HEADERS](./../configuration/environment-variables.md#server_security_headers) env.
!!! info "Not enabled by default when using TOML config file"
This is an issue reported on [static-web-server#210](https://github.com/static-web-server/static-web-server/issues/210).
The workaround is just to enable the `security-header` explicitly along with the `tls` feature. More details on the [issue #210 comment](https://github.com/static-web-server/static-web-server/issues/210#issuecomment-1572686507).
!!! tip "Customize HTTP headers"
If you want to customize HTTP headers on demand then have a look at the [Custom HTTP Headers](custom-http-headers.md) section.
@@ -1,4 +1,4 @@
<div>
<div style="overflow: hidden; clear: both;">
<div align="center" class="sws-logo">
<a href="https://static-web-server.net" title="static-web-server website">
<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100" viewBox="0 0 53.505 53.505"><path d="M161.49 84.99a.664.664 0 0 0-.38.149c-.081.07-.498.613-.927 1.207l-.778 1.079-.232.014c-.56.032-.46.11-1.354-1.054-.445-.58-.873-1.104-.95-1.165a.909.909 0 0 0-.345-.15c-.174-.03-.234-.02-.41.072a.873.873 0 0 0-.292.246c-.047.077-.327.672-.623 1.323-.594 1.309-.516 1.213-1.068 1.308l-.23.04-1.003-.874c-.552-.48-1.081-.914-1.177-.964-.327-.17-.8-.009-.946.321-.036.083-.198.719-.36 1.414-.163.695-.317 1.29-.345 1.324-.027.033-.188.12-.358.192l-.31.132-1.224-.707c-1.162-.67-1.239-.707-1.473-.697a.68.68 0 0 0-.403.12c-.273.193-.313.385-.354 1.719-.021.667-.042 1.285-.047 1.374-.008.14-.047.185-.317.362l-.309.203-1.296-.438c-1.449-.49-1.628-.519-1.883-.3-.084.073-.193.21-.243.306-.105.204-.102.244.172 1.87.104.612.183 1.136.176 1.164-.007.027-.122.159-.256.292l-.243.243-1.328-.172c-.73-.094-1.415-.16-1.52-.148a.717.717 0 0 0-.612.773c.011.105.232.756.49 1.446l.468 1.254-.18.292c-.1.16-.202.303-.227.316-.025.013-.553.054-1.173.093-1.646.103-1.685.109-1.86.258-.082.07-.19.207-.242.305-.157.3-.088.467.72 1.765l.722 1.161-.128.348c-.112.305-.147.354-.282.393-.084.025-.682.186-1.327.358-1.29.344-1.467.426-1.593.736a.677.677 0 0 0-.025.42c.044.23.097.296 1.014 1.275l.967 1.032-.058.332c-.033.182-.08.358-.106.392-.026.034-.571.32-1.211.636-.64.316-1.223.619-1.295.673-.275.208-.334.696-.117.974.059.076.606.498 1.216.937l1.108.8.008.274c.005.151.005.324 0 .383-.007.079-.277.312-1.042.9-.567.437-1.084.846-1.148.91a.876.876 0 0 0-.173.34c-.05.192-.046.252.024.415.045.105.146.24.223.302.078.061.687.358 1.353.66.899.408 1.22.576 1.244.652.018.056.058.224.088.372l.055.27-.897 1.03c-.494.566-.93 1.101-.971 1.189-.148.32.02.782.336.921.082.037.718.2 1.413.362.696.162 1.292.316 1.324.343.033.027.12.189.193.359l.132.309-.708 1.226c-.67 1.161-.706 1.238-.697 1.471.007.18.04.29.12.403.194.274.385.313 1.72.355.667.02 1.285.041 1.373.046.14.008.186.048.364.32l.203.309-.436 1.289c-.24.708-.44 1.361-.444 1.45-.01.218.052.365.221.525.29.273.31.273 1.713.05.693-.11 1.324-.219 1.402-.24.126-.034.169-.01.41.23l.27.268-.172 1.328c-.095.73-.16 1.413-.148 1.518.045.37.401.653.772.613.105-.01.756-.231 1.446-.49l1.255-.469.292.181c.16.1.302.202.315.227.013.025.055.553.094 1.174.102 1.645.108 1.684.258 1.859.07.082.207.19.305.242.299.156.467.088 1.766-.72l1.163-.721.352.13c.194.07.355.14.355.154.025.215.715 2.625.789 2.753a.795.795 0 0 0 .295.274c.163.083.235.09.449.048.244-.05.295-.09 1.286-1.019l1.033-.967.331.059c.182.032.359.079.393.105.034.026.32.571.636 1.211.316.64.62 1.223.673 1.295.217.288.714.336.994.097.082-.07.499-.613.927-1.206l.777-1.08.305-.019c.167-.01.343-.014.39-.006.047.008.448.488.891 1.067.444.579.846 1.088.893 1.133a.952.952 0 0 0 .288.147c.252.083.345.072.578-.068.221-.132.256-.196.91-1.64.268-.595.524-1.096.568-1.114.044-.018.215-.056.381-.083l.301-.05 1.004.873c.551.481 1.08.915 1.176.965.327.169.8.009.945-.321.037-.083.2-.719.362-1.414.162-.695.317-1.291.344-1.324.027-.033.188-.12.358-.192l.31-.133 1.225.707c1.161.67 1.238.707 1.471.698a.678.678 0 0 0 .403-.12c.275-.195.315-.385.355-1.72.02-.666.041-1.285.046-1.373.008-.14.049-.185.32-.364l.31-.203 1.294.439c1.448.491 1.626.52 1.882.3.084-.073.193-.21.243-.306.106-.204.102-.244-.172-1.87-.104-.612-.183-1.136-.176-1.163.007-.027.122-.16.255-.293l.243-.242 1.33.171c.73.094 1.414.161 1.519.148a.717.717 0 0 0 .612-.772c-.01-.105-.231-.756-.49-1.446l-.469-1.255.181-.292c.1-.16.202-.302.227-.315.025-.013.553-.055 1.174-.094 1.645-.103 1.684-.108 1.859-.257.082-.07.19-.208.242-.306.157-.3.088-.466-.72-1.764l-.722-1.162.128-.347c.112-.305.147-.354.282-.394.085-.025.681-.186 1.326-.358 1.29-.344 1.468-.426 1.594-.736a.676.676 0 0 0 .025-.42c-.044-.229-.096-.295-1.014-1.274l-.967-1.033.058-.33c.033-.183.08-.36.106-.393.026-.033.57-.318 1.208-.634.639-.315 1.221-.619 1.295-.674.29-.219.34-.715.1-.996-.07-.082-.613-.5-1.207-.927l-.054-.04-.55-1.873c.17-.139.347-.282.566-.45.579-.443 1.095-.854 1.148-.914a.957.957 0 0 0 .15-.326c.048-.186.044-.247-.026-.41a.905.905 0 0 0-.223-.3c-.078-.062-.685-.358-1.35-.66-.665-.301-1.223-.584-1.241-.628a2.895 2.895 0 0 1-.083-.38l-.05-.3.874-1.003c.48-.552.914-1.082.964-1.178.17-.328.009-.8-.324-.947-.085-.037-.72-.2-1.414-.362-.694-.162-1.288-.316-1.321-.342-.03-.025-.104-.164-.172-.316l-.12-.407.675-1.17c.67-1.162.706-1.238.697-1.472-.007-.178-.04-.29-.12-.403-.193-.273-.385-.313-1.72-.354-.666-.021-1.284-.042-1.372-.047-.14-.008-.186-.048-.365-.32l-.203-.309.44-1.295c.49-1.447.52-1.626.299-1.881a1.235 1.235 0 0 0-.306-.243c-.204-.106-.243-.102-1.869.172-.613.103-1.137.183-1.164.176-.027-.007-.159-.122-.292-.256l-.243-.242.172-1.33c.094-.73.16-1.414.147-1.519a.717.717 0 0 0-.772-.613c-.105.012-.756.232-1.446.49l-1.255.47-.292-.181c-.16-.1-.301-.202-.314-.227-.013-.025-.056-.554-.094-1.174-.103-1.645-.108-1.685-.258-1.86a1.236 1.236 0 0 0-.306-.242c-.299-.156-.467-.087-1.765.72l-1.16.723-.354-.13c-.195-.072-.357-.14-.357-.152-.025-.218-.715-2.63-.788-2.756a.802.802 0 0 0-.295-.274c-.163-.083-.235-.09-.449-.048-.244.05-.296.09-1.287 1.018l-1.033.968-.33-.059c-.183-.032-.36-.08-.394-.105-.034-.026-.32-.571-.635-1.211-.316-.64-.62-1.223-.674-1.295-.135-.18-.38-.266-.614-.247zm-.697 7.073.23.007c.772.027 2.37.305 3.543.618 1.461.39 2.871.954 4.201 1.67l-15.344 16.098 19.624-3.681-6.154 7.367 12.21-1.083c-.164 2.326-.664 4.402-1.554 6.473-.565 1.316-1.393 2.779-2.134 3.768l-.21.28-1.853-.083c-1.285-.056-1.935-.065-2.115-.028-.517.103-.958.5-1.118 1.001-.06.19-.101.723-.153 2.007-.038.961-.074 1.806-.08 1.877-.008.105-.077.168-.38.352-1.565.945-3.403 1.693-5.481 2.23-.636.163-3.37.523-4.096.538-2.105.044-4.413-.275-6.32-.874-.48-.15-.564-.193-.598-.3-.022-.068-.25-.884-.508-1.811-.342-1.232-.505-1.75-.607-1.92a1.507 1.507 0 0 0-1.317-.72c-.184.006-.814.162-2.052.51l-1.788.5-.267-.224c-.946-.794-2.086-2.03-2.935-3.183-1.563-2.121-2.609-4.365-3.314-7.108-.272-1.06-.592-3.89-.538-4.759.009-.152.061-.192 1.583-1.198 1.691-1.117 1.847-1.25 2.014-1.72.073-.205.08-.325.044-.657l-.046-.406-1.082-1.63-1.082-1.629.108-.264a23.32 23.32 0 0 1 .919-1.88 19.752 19.752 0 0 1 10.462-8.984c.31-.114.663-.235.782-.267l.219-.059 1.5 1.185c1.713 1.353 1.825 1.416 2.433 1.346.607-.07.703-.157 2.064-1.865z" transform="translate(-132.667 -84.987)"/></svg>
@@ -28,7 +28,6 @@
The [`v1.19.4`](https://github.com/static-web-server/static-web-server/releases/tag/v1.19.4) was the last version of the 1.x series and will be no longer supported.<br>
So we encourage users to migrate to v2 which has similar and additional features as well as significant performance and security improvements. Follow [the v2 migration steps](./migration.md).
## Overview
**Static Web Server** (or **`SWS`** abbreviated) is a tiny and fast production-ready web server suitable to serve static web files or assets.
@@ -39,7 +38,7 @@ Written on top of [Hyper](https://github.com/hyperium/hyper) and [Tokio](https:/
It's cross-platform and available for `Linux`, `macOS`, `Windows` and `FreeBSD` (`x86`/`x86_64`, `ARM`/`ARM64`) and `Docker`.
## Features
@@ -56,7 +55,7 @@ It's cross-platform and available for `Linux`, `macOS`, `Windows` and `FreeBSD`
- [Security headers](https://web.dev/security-headers/) for HTTP/2 by default.
- [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) responses.
- Lightweight and configurable logging via [tracing](https://github.com/tokio-rs/tracing) crate.
- A Customizable number of worker threads.
- Customizable number of blocking and worker threads.
- Optional directory listing.
- [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) support.
- Basic HTTP Authentication.
@@ -68,7 +67,7 @@ It's cross-platform and available for `Linux`, `macOS`, `Windows` and `FreeBSD`
- HTTP to HTTPS redirect.
- Support for serving pre-compressed (Gzip/Brotli/Zstd) files.
- Custom URL rewrites and redirects via glob patterns.
- First-class [Docker](https://docs.docker.com/get-started/overview/) support. [Scratch](https://hub.docker.com/_/scratch) and latest [Alpine Linux](https://hub.docker.com/_/alpine) Docker images.
- First-class [Docker](https://docs.docker.com/get-started/overview/) support. [Scratch](https://hub.docker.com/_/scratch), latest [Alpine Linux](https://hub.docker.com/_/alpine) and [Debian](https://hub.docker.com/_/alpine) Docker images.
- Ability to accept a socket listener as a file descriptor for sandboxing and on-demand applications (e.g [systemd](http://0pointer.de/blog/projects/socket-activation.html)).
- Cross-platform. Pre-compiled binaries for Linux, macOS, Windows, FreeBSD and Android (`x86`,`x86_64`,`ARM`,`ARM64`).
@@ -3,7 +3,7 @@
Currently, only the following platforms/architectures are supported.
!!! tip "Docker tip"
For Docker images supported list see [Docker OS/Arch](/features/docker/#osarch).
For the list of Docker images supported see [Docker OS/Arch](/features/docker/#osarch) page.
## Linux
@@ -35,7 +35,7 @@
@@ -186,7 +186,7 @@ pub struct General {
#[cfg_attr(docsrs, doc(cfg(feature = "directory-listing")))]
pub directory_listing_format: Option<DirListFmt>,
#[cfg(feature = "basic-auth")]
#[cfg_attr(docsrs, doc(cfg(feature = "basic-auth")))]
pub basic_auth: Option<String>,
@@ -40,7 +40,7 @@ directory-listing-order = 1
directory-listing-format = "json"
basic-auth = ""
@@ -63,7 +63,7 @@ log-remote-address = false
redirect-trailing-slash = true
compression-static = true
compression-static = false
