From 21c90db067079dc80ee158114c9cd7097da28253 Mon Sep 17 00:00:00 2001 From: Jose Quintana Date: Fri, 16 Jun 2023 20:43:45 +0200 Subject: [PATCH] docs: improve documentation pages [skip ci] --- 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(-) diff --git a/README.md b/README.md index 291b726..613532c 100644 --- a/README.md +++ b/README.md @@ -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`. -![static-web-server](https://user-images.githubusercontent.com/1700322/152613820-658f025c-d0a4-46b3-aa6d-bdc7f638ce77.png) +![static-web-server running](https://github.com/static-web-server/static-web-server/assets/1700322/102bef12-1f30-4054-a1bc-30c650d4ffa7) ## 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`). diff --git a/docs/content/building-from-source.md b/docs/content/building-from-source.md index 5931b8a..75d6fbd 100644 --- a/docs/content/building-from-source.md +++ b/docs/content/building-from-source.md @@ -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 diff --git a/docs/content/configuration/config-file.md b/docs/content/configuration/config-file.md index 58290a9..fecfe94 100644 --- a/docs/content/configuration/config-file.md +++ b/docs/content/configuration/config-file.md @@ -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 diff --git a/docs/content/download-and-install.md b/docs/content/download-and-install.md index c44370f..9eda226 100644 --- a/docs/content/download-and-install.md +++ b/docs/content/download-and-install.md @@ -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 diff --git a/docs/content/download-and-install.tmpl.md b/docs/content/download-and-install.tmpl.md index eb254ff..28fba3b 100644 --- a/docs/content/download-and-install.tmpl.md +++ b/docs/content/download-and-install.tmpl.md @@ -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 diff --git a/docs/content/features/compression-static.md b/docs/content/features/compression-static.md index 2e6cd3f..d2243c4 100644 --- a/docs/content/features/compression-static.md +++ b/docs/content/features/compression-static.md @@ -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. diff --git a/docs/content/features/security-headers.md b/docs/content/features/security-headers.md index 5907110..c9947e3 100644 --- a/docs/content/features/security-headers.md +++ b/docs/content/features/security-headers.md @@ -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. diff --git a/docs/content/index.md b/docs/content/index.md index 90e08ef..e8dcdd5 100644 --- a/docs/content/index.md +++ b/docs/content/index.md @@ -1,4 +1,4 @@ -
+