From e674940b67b739cff02e75bc80d74e9b9f762f81 Mon Sep 17 00:00:00 2001 From: Jose Quintana Date: Wed, 3 Aug 2022 23:37:24 +0200 Subject: [PATCH] docs: minor pages improvements [skip ci] --- docs/content/configuration/command-line-arguments.md | 2 +- docs/content/features/basic-authentication.md | 8 ++++---- docs/content/features/cache-control-headers.md | 3 ++- docs/content/features/directory-listing.md | 4 ++-- docs/content/features/docker.md | 6 +++--- docs/content/features/graceful-shutdown.md | 4 ++-- docs/content/features/security-headers.md | 3 ++- docs/content/features/windows-service.md | 4 ++-- docs/content/features/worker-threads.md | 4 ++-- docs/content/getting-started.md | 6 +++--- docs/content/index.md | 30 +++++++++++++++--------------- docs/content/platforms-architectures.md | 2 +- 12 files changed, 39 insertions(+), 37 deletions(-) diff --git a/docs/content/configuration/command-line-arguments.md b/docs/content/configuration/command-line-arguments.md index ffb3e56..3fd7634 100644 --- a/docs/content/configuration/command-line-arguments.md +++ b/docs/content/configuration/command-line-arguments.md @@ -10,7 +10,7 @@ The server can be configured via the following command-line arguments. ``` $ static-web-server -h -static-web-server 2.9.0 +static-web-server 2.10.0 Jose Quintana A blazing fast and asynchronous web server for static files-serving. diff --git a/docs/content/features/basic-authentication.md b/docs/content/features/basic-authentication.md index 3f4c2a2..8ebb7ea 100644 --- a/docs/content/features/basic-authentication.md +++ b/docs/content/features/basic-authentication.md @@ -1,19 +1,19 @@ # Basic HTTP Authentication -**`SWS`** provides ['Basic' HTTP Authentication Scheme](https://datatracker.ietf.org/doc/html/rfc7617) using a `user:password` pair. +**`SWS`** provides ['Basic' HTTP Authentication Scheme](https://datatracker.ietf.org/doc/html/rfc7617) using an `user:password` pair. This feature is disabled by default and can be controlled by the string `--basic-auth` option or the equivalent [SERVER_BASIC_AUTH](./../configuration/environment-variables.md#server_basic_auth) env. The format to use is the following: -> `username:encrypted-password` +> `username:encrypted_password` Both are separated by a `:` (punctuation mark) character. !!! info "Password Encryption" Only the password must be encoded using the [`BCrypt`](https://en.wikipedia.org/wiki/Bcrypt) password-hashing function. -As an example, we will use the [Apache `htpasswd`](https://httpd.apache.org/docs/2.4/programs/htpasswd.html) tool to generate the `username:encrypted-password` pair. +As an example, we will use the [Apache `htpasswd`](https://httpd.apache.org/docs/2.4/programs/htpasswd.html) tool to generate the `username:encrypted_password` pair. ```sh htpasswd -nBC10 "username" @@ -30,7 +30,7 @@ htpasswd -nBC10 "username" Using a higher value is more secure but slower. The default value is `5` and the possible values are ranging from `4` to `17`. !!! tip "Docker Compose Advice" - If you are using `SERVER_BASIC_AUTH` env via a `docker-compose.yml` file don't forget to replace a single `$` (dollar sign) with a `$$` (double-dollar sign) when you want individual `$` dollar signs in your configuration to be treated by Docker as literals.
+ If you are using `SERVER_BASIC_AUTH` env via a `docker-compose.yml` file don't forget to replace the single `$` (dollar sign) with a `$$` (double-dollar sign) if you want those individual `$` dollar signs in your configuration to be treated by Docker as literals.
More details at [Docker Compose file: variable substitution](https://docs.docker.com/compose/compose-file/compose-file-v2/#variable-substitution) Finally, assign the credentials and run the server. diff --git a/docs/content/features/cache-control-headers.md b/docs/content/features/cache-control-headers.md index 43877d4..50608de 100644 --- a/docs/content/features/cache-control-headers.md +++ b/docs/content/features/cache-control-headers.md @@ -4,7 +4,8 @@ This feature is enabled by default and can be controlled by the boolean `-e, --cache-control-headers` option or the equivalent [SERVER_CACHE_CONTROL_HEADERS](./../configuration/environment-variables.md#server_cache_control_headers) env. -**Note:** If you want to customize HTTP headers on demand then have a look at the [Custom HTTP Headers](custom-http-headers.md) section. +!!! 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. ## Cache-Control Max-Age diff --git a/docs/content/features/directory-listing.md b/docs/content/features/directory-listing.md index 9db30ea..76635ce 100644 --- a/docs/content/features/directory-listing.md +++ b/docs/content/features/directory-listing.md @@ -50,9 +50,9 @@ Below are the possible number code values for sorting or ordering which are grou - `6`: Unordered -!!! info "Tips" +!!! tip "Tips" - The `--directory-listing-order` option depends on `--directory-listing` to be enabled. - - Use the query `?sort=NUMBER` to customize the sorting. E.g `https://localhost/?sort=5` (sort by size in descending order) + - Use the query `?sort=NUMBER` to customize the sorting via the URI. E.g `https://localhost/?sort=5` (sort by size in descending order) Example: diff --git a/docs/content/features/docker.md b/docs/content/features/docker.md index ee2ecf0..1233456 100644 --- a/docs/content/features/docker.md +++ b/docs/content/features/docker.md @@ -18,9 +18,9 @@ View all images on [Docker Hub](https://hub.docker.com/r/joseluisq/static-web-se To give the server a quick try just run the following commands. -!!! info "Tips" - - [Server CLI arguments](/configuration/command-line-arguments/) can be provided directly to the container or omitted as shown below. - - It can specify a Docker volume like `-v $HOME/my-public-dir:/public` to overwrite the default root directory. +!!! tip "Tips" + - [The SWS CLI arguments](/configuration/command-line-arguments/) can be provided directly to the container or omitted as shown below. + - A Docker volume like `-v $HOME/my-public-dir:/public` can be specified to overwrite the default root directory. Run the scratch Docker image (just the binary) diff --git a/docs/content/features/graceful-shutdown.md b/docs/content/features/graceful-shutdown.md index 0ea6b1a..ca973b7 100644 --- a/docs/content/features/graceful-shutdown.md +++ b/docs/content/features/graceful-shutdown.md @@ -4,7 +4,7 @@ It means that when a `SIGTERM` [termination signal](https://www.gnu.org/software/libc/manual/html_node/Termination-Signals.html) is caught the server will stop receiving more requests immediately but in turn, it will continue processing all existing requests until they are completed (or closed). -!!! info "Notes" +!!! tip "Tips" - In **BSD/Unix-like** systems, SWS will start the graceful shutdown process when a `SIGTERM`, `SIGINT` or `SIGQUIT` [termination signal](https://www.gnu.org/software/libc/manual/html_node/Termination-Signals.html) is caught. - In **Windows** systems otherwise, SWS will start the graceful shutdown process right after a CTRL + C. This is used to abort the current task. @@ -12,7 +12,7 @@ It means that when a `SIGTERM` [termination signal](https://www.gnu.org/software Sometimes one wants to control the graceful shutdown process for different reasons. For example during [Kubernetes rollouts](https://github.com/joseluisq/static-web-server/issues/79). -In these situations, SWS allows delaying the graceful shutdown process right after a `SIGTERM` providing a grace period of seconds. +In these situations, SWS allows delaying the graceful shutdown process right after a `SIGTERM` providing a *grace period* in seconds. The feature is disabled by default and can be controlled by the numeric `-q, --grace-period` option or its equivalent [SERVER_GRACE_PERIOD](./../configuration/environment-variables.md#server_grace_period) env. diff --git a/docs/content/features/security-headers.md b/docs/content/features/security-headers.md index 5e8ba4b..f56585e 100644 --- a/docs/content/features/security-headers.md +++ b/docs/content/features/security-headers.md @@ -6,7 +6,8 @@ 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. -**Note:** If you want to customize HTTP headers on demand then have a look at the [Custom HTTP Headers](custom-http-headers.md) section. +!!! 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. ## Headers included diff --git a/docs/content/features/windows-service.md b/docs/content/features/windows-service.md index 31f0f0c..fe9f93b 100644 --- a/docs/content/features/windows-service.md +++ b/docs/content/features/windows-service.md @@ -1,6 +1,6 @@ # Windows Service -**`SWS`** can be also executed in a [Windows Service](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2003/cc783643(v=ws.10)) context. +**`SWS`** can be also executed in a [Windows Service](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2003/cc783643(v=ws.10)) context. Therefore it also provides a subcommand to *install* SWS as a Windows Service. This feature is disabled by default and can be controlled by the boolean `-s, --windows-service` option or the equivalent [SERVER_WINDOWS_SERVICE](./../configuration/environment-variables.md#server_windows_service) env. @@ -9,7 +9,7 @@ This feature is disabled by default and can be controlled by the boolean `-s, -- ## Important Notes -- This is a Windows platform-specific feature. +- This is an obvious Windows platform-specific feature. - The SWS Windows Service option (`windows-service`) doesn't create a Windows Service per se. It just tells SWS to run in a Windows Service context. So it's necessary to [install the SWS Windows Service](#install-the-service) first. - Enabling the `windows-service` option via the [configuration file](../configuration/config-file.md) is unnecessary if you use the [install subcommand](#install-the-service) to create the service since it already enables it during the service installation. - However, you can enable the `windows-service` option for example if you plan to create your own Windows Service and use SWS with it. diff --git a/docs/content/features/worker-threads.md b/docs/content/features/worker-threads.md index dd48472..da02959 100644 --- a/docs/content/features/worker-threads.md +++ b/docs/content/features/worker-threads.md @@ -18,11 +18,11 @@ The formula used is the following: **For example:** If there are `4` available CPUs and the `--threads-multiplier` is `8` then the total of *worker threads* to use will be `32`. -!!! Info "Info" +!!! tip "Tip" When the `--threads-multiplier` input value is `0` or `1` then one thread per core is used (default value). !!! warn "Warn" - Number of worker threads result should be a number between `1` and `32,768` though it is advised to keep this value on the smaller side. See [Tokio ` worker_threads` API](https://docs.rs/tokio/1.12.0/tokio/runtime/struct.Builder.html#method.worker_threads) for more details. + The number of worker threads result should be a number between `1` and `32,768` though it is advised to keep this value on the smaller side. See [Tokio ` worker_threads` API](https://docs.rs/tokio/1.12.0/tokio/runtime/struct.Builder.html#method.worker_threads) for more details. Below is an example of how to adjust the number of worker threads. diff --git a/docs/content/getting-started.md b/docs/content/getting-started.md index 3885c8d..1750fd0 100644 --- a/docs/content/getting-started.md +++ b/docs/content/getting-started.md @@ -1,6 +1,6 @@ # Getting Started -[Download and install](./download-and-install.md) the binary for your specific platform and then just type +[Download and install](./download-and-install.md) the binary for your specific platform and then type ```sh static-web-server --port 8787 --root ./my-public-dir @@ -15,6 +15,6 @@ docker run --rm -it -p 8787:80 joseluisq/static-web-server:2 !!! info "Docker Tip" You can specify a Docker volume like `-v $HOME/my-public-dir:/public` to overwrite the default root directory. See [Docker examples](features/docker.md). -- Type `static-web-server --help` or go to the [Command-line arguments](./configuration/command-line-arguments.md) section. +- Type `static-web-server --help` or see the [Command-line arguments](./configuration/command-line-arguments.md) section. - See how to configure the server using a [configuration file](configuration/config-file.md). -- Have also a look at [the features](./features/http1.md) section for more advanced examples. +- Have a look at [the features](./features/http1.md) section for more advanced examples. diff --git a/docs/content/index.md b/docs/content/index.md index 52fa70a..2ba5dec 100644 --- a/docs/content/index.md +++ b/docs/content/index.md @@ -9,7 +9,7 @@

Static Web Server

- A blazing fast and asynchronous web server for static files-serving ⚡ + A blazing fast and asynchronous web server for static files serving ⚡

@@ -25,17 +25,17 @@ **Static Web Server** (or **`SWS`** abbreviated) is a very small and fast production-ready web server suitable to serve static web files or assets. -It is focused on **lightness and easy-to-use** principles while keeping [high](https://blog.rust-lang.org/2015/04/10/Fearless-Concurrency.html) performance and safety](https://blog.rust-lang.org/2015/04/10/Fearless-Concurrency.html) powered by [The Rust Programming Language](https://rust-lang.org). +It is focused on **lightness** and **easy-to-use** principles while keeping [high performance and safety](https://blog.rust-lang.org/2015/04/10/Fearless-Concurrency.html) powered by [The Rust Programming Language](https://rust-lang.org). Written on top of [Hyper](https://github.com/hyperium/hyper) and [Tokio](https://github.com/tokio-rs/tokio) runtime. It provides [concurrent and asynchronous networking abilities](https://rust-lang.github.io/async-book/01_getting_started/02_why_async.html) as well as the latest HTTP/1 - HTTP/2 implementations. -It's cross-platform and available for `Linux`, `macOS`, `Windows` and `FreeBSD` (`x86`/`x86_64`, `ARM`/`ARM64`) as well as `Docker`. +It's cross-platform and available for Linux, macOS, Windows and FreeBSD (`x86`,`x86_64`,`ARM`,`ARM64`) as well as Docker. ![static-web-server](https://user-images.githubusercontent.com/1700322/152613820-658f025c-d0a4-46b3-aa6d-bdc7f638ce77.png) !!! tip "Tips" - - If you're looking for `v1` please go to [1.x](https://github.com/joseluisq/static-web-server/tree/1.x) branch. - - If you want to migrate from `v1` to `v2` please take a look at [v2.0.0](https://github.com/joseluisq/static-web-server/releases/tag/v2.0.0) release. + - If you're looking for `v1` please go to [1.x branch](https://github.com/joseluisq/static-web-server/tree/1.x). + - If you want to migrate from `v1` to `v2` please take a look at [v2.0.0](https://github.com/joseluisq/static-web-server/releases/tag/v2.0.0) release notes. ## Features @@ -46,9 +46,9 @@ It's cross-platform and available for `Linux`, `macOS`, `Windows` and `FreeBSD` - Optional GZip, Deflate or Brotli compression for text-based web files only. - Compression on-demand via [Accept-Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) header. - [Partial Content Delivery](https://en.wikipedia.org/wiki/Byte_serving) support for byte-serving of large files. -- Optional [Cache Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) headers for assets. +- Optional [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) headers for assets. - [Termination signal](https://www.gnu.org/software/libc/manual/html_node/Termination-Signals.html) handling with [graceful shutdown](https://cloud.google.com/blog/products/containers-kubernetes/kubernetes-best-practices-terminating-with-grace) ability and grace period. -- [HTTP/2](https://tools.ietf.org/html/rfc7540) + TLS support. +- [HTTP/2](https://tools.ietf.org/html/rfc7540) and TLS support. - [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. @@ -56,13 +56,13 @@ It's cross-platform and available for `Linux`, `macOS`, `Windows` and `FreeBSD` - Optional directory listing. - [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) support. - Basic HTTP Authentication. -- Customizable HTTP Response Headers for specific file requests via glob patterns. -- Fallback pages for 404 errors useful for Single-page applications. -- Run the server as [Windows Service](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2003/cc783643(v=ws.10)). -- Configurable using CLI arguments, environment variables or a file. +- Customizable HTTP response headers for specific file requests via glob patterns. +- Fallback pages for 404 errors, useful for Single-page applications. +- Run the server as a [Windows Service](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2003/cc783643(v=ws.10)). +- Configurable using CLI arguments, environment variables or a TOML file. - Default and custom error pages. -- Custom URL rewrites. -- Custom URL redirects. -- 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 available. +- Custom URL rewrites via glob patterns. +- Custom URL 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. - Ability to accept a socket listener as a file descriptor for use in sandboxing and on-demand applications (E.g [systemd](http://0pointer.de/blog/projects/socket-activation.html)). -- Cross-platform. Binaries available for Linux, macOS, Windows & FreeBSD x86_64 / ARM. +- Cross-platform. Pre-compiled binaries for Linux, macOS, Windows and FreeBSD (`x86`,`x86_64`,`ARM`,`ARM64`). diff --git a/docs/content/platforms-architectures.md b/docs/content/platforms-architectures.md index df50069..a39f1e2 100644 --- a/docs/content/platforms-architectures.md +++ b/docs/content/platforms-architectures.md @@ -2,7 +2,7 @@ Currently, only the following platforms/architectures are supported. -!!! info "Docker" +!!! tip "Docker tip" For Docker images supported list see [Docker OS/Arch](/features/docker/#osarch). ## Linux -- libgit2 1.7.2