docs: minor pages improvements [skip ci]
Diff
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(-)
@@ -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 <https://joseluisq.net>
A blazing fast and asynchronous web server for static files-serving.
@@ -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.<br>
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.<br>
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.
@@ -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
@@ -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:
@@ -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)
@@ -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 <kbd>CTRL + C</kbd>. 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.
@@ -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
@@ -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.
@@ -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.
@@ -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.
@@ -9,7 +9,7 @@
<h1 align="center">Static Web Server</h1>
<h4 align="center">
A blazing fast and asynchronous web server for static files-serving ⚡
A blazing fast and asynchronous web server for static files serving ⚡
</h4>
<div align="center">
@@ -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.
!!! 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`).
@@ -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
