mirror of
https://github.com/static-web-server/static-web-server.git
synced 2026-01-24 20:56:50 +00:00
refactor: format check support Markdown files via mdformat (#597)
* chore: format Markdown files with mdformat * chore: switch to mdformat config file * chore: add missing trailing slash * docs: add section about formatting Markdown files
This commit is contained in:
Matthias Schoettle
committed by
GitHub
GitHub
parent
ce3a51c6ac
commit
dd43d06551
5
.github/workflows/devel.project.docs.yml
vendored
5
.github/workflows/devel.project.docs.yml
vendored
@@ -24,6 +24,11 @@ jobs:
|
||||
with:
|
||||
config: ./.github/workflows/config/typos.toml
|
||||
|
||||
- name: Check Markdown formatting
|
||||
run: |
|
||||
pip install uv
|
||||
uvx --python ">=3.13" --with mdformat-mkdocs mdformat --check ./*.md docs/
|
||||
|
||||
- name: Build docs
|
||||
run: |
|
||||
docker compose -f docs/docker-compose.yml run --rm server mkdocs build
|
||||
|
||||
15
.mdformat.toml
Normal file
15
.mdformat.toml
Normal file
@@ -0,0 +1,15 @@
|
||||
# see: https://mdformat.readthedocs.io/en/stable/users/configuration_file.html
|
||||
|
||||
number = true
|
||||
# requires Python 3.13+
|
||||
exclude = [
|
||||
# avoid moving all link definitions to the bottom
|
||||
"CHANGELOG.md",
|
||||
|
||||
# fails validation that rendered HTML is consistent
|
||||
"docs/content/download-and-install*.md"
|
||||
]
|
||||
|
||||
# https://github.com/hukkin/mdformat-gfm#configuration
|
||||
[plugin.tables]
|
||||
compact_tables = true
|
||||
@@ -5,13 +5,13 @@
|
||||
/></a>
|
||||
</div>
|
||||
|
||||
<h1 align="center">Static Web Server</h1>
|
||||
<h1 align="center">Static Web Server</h1>
|
||||
|
||||
<h4 align="center">
|
||||
<h4 align="center">
|
||||
A cross-platform, high-performance and asynchronous web server for static files-serving ⚡
|
||||
</h4>
|
||||
|
||||
<div align="center">
|
||||
<div align="center">
|
||||
<a href="https://github.com/static-web-server/static-web-server/actions/workflows/devel.yml" title="devel ci"><img src="https://github.com/static-web-server/static-web-server/actions/workflows/devel.yml/badge.svg?branch=master"></a>
|
||||
<a href="https://hub.docker.com/r/joseluisq/static-web-server/" title="Docker Image Version (tag latest semver)"><img src="https://img.shields.io/docker/v/joseluisq/static-web-server/2"></a>
|
||||
<a href="https://hub.docker.com/r/joseluisq/static-web-server/tags" title="Docker Image Size (tag)"><img src="https://img.shields.io/docker/image-size/joseluisq/static-web-server/2"></a>
|
||||
@@ -59,7 +59,7 @@ Cross-platform and available for `Linux`, `macOS`, `Windows`, `FreeBSD`, `NetBSD
|
||||
- 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 a [Windows Service](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2003/cc783643(v=ws.10)).
|
||||
- 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.
|
||||
- Built-in HTTP to HTTPS redirect.
|
||||
|
||||
@@ -4,10 +4,10 @@
|
||||
|
||||
The following Static Web Server versions are currently being supported with security updates.
|
||||
|
||||
| Version | Supported |
|
||||
| ------- | ------------------ |
|
||||
| 2.x.x | :white_check_mark: (current stable) |
|
||||
| 1.x.x | :x: (deprecated due to [End of Life](https://github.com/static-web-server/static-web-server/releases/tag/v1.19.4)) |
|
||||
| Version | Supported |
|
||||
| -- | -- |
|
||||
| 2.x.x | :white_check_mark: (current stable) |
|
||||
| 1.x.x | :x: (deprecated due to [End of Life](https://github.com/static-web-server/static-web-server/releases/tag/v1.19.4)) |
|
||||
|
||||
## Report a security issue
|
||||
|
||||
|
||||
@@ -20,7 +20,7 @@ Get-ChildItem . -Filter "*.rs" -Recurse | foreach { rustfmt --check --edition 20
|
||||
|
||||
> **NOTE**: If you are using `rust-analyzer`, you can add the following two lines in your `settings.json` to make sure the features get taken into account when checking the project:
|
||||
>
|
||||
> ```json
|
||||
> "rust-analyzer.cargo.features": ["full"],
|
||||
> "rust-analyzer.check.features": ["full"],
|
||||
> ```
|
||||
> ```json
|
||||
> "rust-analyzer.cargo.features": ["full"],
|
||||
> "rust-analyzer.check.features": ["full"],
|
||||
> ```
|
||||
|
||||
@@ -5,6 +5,7 @@ This leads to **more readable messages** that are easy to follow when looking th
|
||||
But also, we use the git commit messages to **generate the change log**.
|
||||
|
||||
## Commit Message Format
|
||||
|
||||
Each commit message consists of a **header**, a **body** and a **footer**. The header has a special
|
||||
format that includes a **type**, a **scope** and a **subject**:
|
||||
|
||||
@@ -20,46 +21,48 @@ Any line of the commit message cannot be longer 100 characters! This allows the
|
||||
to read on github as well as in various git tools.
|
||||
|
||||
## Type
|
||||
|
||||
Must be one of the following:
|
||||
|
||||
* **feat**: A new feature
|
||||
* **fix**: A bug fix
|
||||
* **docs**: Documentation only changes
|
||||
* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing
|
||||
semi-colons, etc)
|
||||
* **refactor**: A code change that neither fixes a bug or adds a feature
|
||||
* **perf**: A code change that improves performance
|
||||
* **test**: Adding missing tests
|
||||
* **chore**: Changes to the build process or auxiliary tools and libraries such as documentation
|
||||
- **feat**: A new feature
|
||||
- **fix**: A bug fix
|
||||
- **docs**: Documentation only changes
|
||||
- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing
|
||||
semi-colons, etc)
|
||||
- **refactor**: A code change that neither fixes a bug or adds a feature
|
||||
- **perf**: A code change that improves performance
|
||||
- **test**: Adding missing tests
|
||||
- **chore**: Changes to the build process or auxiliary tools and libraries such as documentation
|
||||
generation
|
||||
|
||||
## Scope
|
||||
|
||||
The scope should refer to a **module** in SWS that is being touched. Some examples:
|
||||
|
||||
* server
|
||||
* http1
|
||||
* http2
|
||||
* tls
|
||||
* compression
|
||||
* fs
|
||||
* logger
|
||||
* rewrites
|
||||
* redirects
|
||||
* signals
|
||||
* winservice
|
||||
* handler
|
||||
* response
|
||||
* service
|
||||
* directory_listing
|
||||
* cors
|
||||
- server
|
||||
- http1
|
||||
- http2
|
||||
- tls
|
||||
- compression
|
||||
- fs
|
||||
- logger
|
||||
- rewrites
|
||||
- redirects
|
||||
- signals
|
||||
- winservice
|
||||
- handler
|
||||
- response
|
||||
- service
|
||||
- directory_listing
|
||||
- cors
|
||||
|
||||
## Subject
|
||||
|
||||
The subject contains succinct description of the change:
|
||||
|
||||
* use the imperative, present tense: "change" not "changed" nor "changes"
|
||||
* don't capitalize first letter
|
||||
* no dot (.) at the end
|
||||
- use the imperative, present tense: "change" not "changed" nor "changes"
|
||||
- don't capitalize first letter
|
||||
- no dot (.) at the end
|
||||
|
||||
## Body
|
||||
|
||||
|
||||
@@ -19,6 +19,7 @@ cargo build --release
|
||||
Finally, the release binary should be available at `target/release/static-web-server` or under your toolchain directory chosen.
|
||||
|
||||
!!! info "Don't use the project's `Makefile`"
|
||||
|
||||
Please don't use the project's `Makefile` since it's only intended for development and some on-demand tasks.
|
||||
|
||||
## Cargo features
|
||||
@@ -26,26 +27,26 @@ Finally, the release binary should be available at `target/release/static-web-se
|
||||
When building from the source, all features are enabled by default.
|
||||
However, you can disable just the ones you don't need from the lists below.
|
||||
|
||||
Feature | Description
|
||||
---------|------
|
||||
**Default** |
|
||||
`default` | Activates the default features by omission.
|
||||
`all` | Activates all available features including the `experimental` feature. This is the default feature used when building SWS binaries.
|
||||
`experimental` | Activates all SWS experimental features. Make sure to also provide the required `RUSTFLAGS` if the feature requires so.
|
||||
[**HTTP2/TLS**](./features/http2-tls.md) |
|
||||
`http2` | Activates the HTTP2 and TLS feature.
|
||||
[**Compression**](./features/compression.md) |
|
||||
`compression` | Activates auto-compression and compression static with all supported algorithms.
|
||||
`compression-brotli` | Activates auto-compression/compression static with only the `brotli` algorithm.
|
||||
`compression-deflate` | Activates auto-compression/compression static with only the `deflate` algorithm.
|
||||
`compression-gzip` | Activates auto-compression/compression static with only the `gzip` algorithm.
|
||||
`compression-zstd` | Activates auto-compression/compression static with only the `zstd` algorithm.
|
||||
[**Directory Listing**](./features/directory-listing.md) |
|
||||
`directory-listing` | Activates the directory listing feature.
|
||||
[**Basic Authorization**](./features/basic-authentication.md) |
|
||||
`basic-auth` | Activates the Basic HTTP Authorization Schema feature.
|
||||
[**Fallback Page**](./features/error-pages.md#fallback-page-for-use-with-client-routers) |
|
||||
`fallback-page` | Activates the Fallback Page feature.
|
||||
| Feature | Description |
|
||||
| -- | -- |
|
||||
| **Default** | |
|
||||
| `default` | Activates the default features by omission. |
|
||||
| `all` | Activates all available features including the `experimental` feature. This is the default feature used when building SWS binaries. |
|
||||
| `experimental` | Activates all SWS experimental features. Make sure to also provide the required `RUSTFLAGS` if the feature requires so. |
|
||||
| [**HTTP2/TLS**](./features/http2-tls.md) | |
|
||||
| `http2` | Activates the HTTP2 and TLS feature. |
|
||||
| [**Compression**](./features/compression.md) | |
|
||||
| `compression` | Activates auto-compression and compression static with all supported algorithms. |
|
||||
| `compression-brotli` | Activates auto-compression/compression static with only the `brotli` algorithm. |
|
||||
| `compression-deflate` | Activates auto-compression/compression static with only the `deflate` algorithm. |
|
||||
| `compression-gzip` | Activates auto-compression/compression static with only the `gzip` algorithm. |
|
||||
| `compression-zstd` | Activates auto-compression/compression static with only the `zstd` algorithm. |
|
||||
| [**Directory Listing**](./features/directory-listing.md) | |
|
||||
| `directory-listing` | Activates the directory listing feature. |
|
||||
| [**Basic Authorization**](./features/basic-authentication.md) | |
|
||||
| `basic-auth` | Activates the Basic HTTP Authorization Schema feature. |
|
||||
| [**Fallback Page**](./features/error-pages.md#fallback-page-for-use-with-client-routers) | |
|
||||
| `fallback-page` | Activates the Fallback Page feature. |
|
||||
|
||||
### Disable all default features
|
||||
|
||||
@@ -118,6 +119,7 @@ docker run -it --rm \
|
||||
```
|
||||
|
||||
!!! tip "Output the docs in a different directory"
|
||||
|
||||
If you want to output the docs in a different directory then append the `--site-dir=/new/dir/path/` argument to the *"squidfunk/mkdocs-material"* `build` command and make sure to provide the new directory path.
|
||||
|
||||
### Development server
|
||||
@@ -131,3 +133,14 @@ docker-compose -f docs/docker-compose.yml up
|
||||
```
|
||||
|
||||
Now the server will be available at `localhost:8000`
|
||||
|
||||
## Formatting Markdown files
|
||||
|
||||
This project makes use of [mdformat](https://mdformat.readthedocs.io/en/stable/) to format Markdown files.
|
||||
The CI job `devel-project-docs` checks that all Markdown files are formatted correctly.
|
||||
|
||||
To format documentation changes, you can run `mdformat` manually using [uv](https://docs.astral.sh/uv/getting-started/installation/):
|
||||
|
||||
```sh
|
||||
uvx --python ">=3.13" --with mdformat-mkdocs mdformat ./*.md docs/
|
||||
```
|
||||
|
||||
@@ -3,10 +3,10 @@
|
||||
The server can be configured via the following command-line arguments.
|
||||
|
||||
!!! tip "Remember"
|
||||
|
||||
- Command-line arguments are equivalent to their [environment variables](./environment-variables.md).
|
||||
- Command-line arguments take precedence over their equivalent environment variables.
|
||||
|
||||
|
||||
```
|
||||
$ static-web-server -h
|
||||
A cross-platform, high-performance and asynchronous web server for static files-serving.
|
||||
|
||||
@@ -5,6 +5,7 @@
|
||||
It's disabled by default and can be enabled by passing a _string file path_ via the `-w, --config-file` option or its equivalent [SERVER_CONFIG_FILE](./../configuration/environment-variables.md#server_config_file) env.
|
||||
|
||||
!!! info "The default config file path is checked at startup time"
|
||||
|
||||
If using the default config file path (`./sws.toml`), SWS will attempt to load it at startup time.
|
||||
If it is not found or can not be loaded then SWS will continue using the server defaults.
|
||||
|
||||
@@ -177,6 +178,7 @@ The TOML `[general]` section allows adjusting the current options available via
|
||||
So they are equivalent to each other **except** for the `-w, --config-file` option which is omitted and can not be used for obvious reasons.
|
||||
|
||||
!!! info "Config file-based features are optional"
|
||||
|
||||
All server feature options via the configuration file are optional and can be omitted as needed.
|
||||
|
||||
### Advanced options
|
||||
|
||||
@@ -3,151 +3,200 @@
|
||||
The server can be configured via the following environment variables.
|
||||
|
||||
!!! tip "Remember"
|
||||
|
||||
- Environment variables are equivalent to their command-line arguments.
|
||||
- [Command-line arguments](./command-line-arguments.md) take precedence over their equivalent environment variables.
|
||||
|
||||
### SERVER_HOST
|
||||
|
||||
The address of the host (e.g. 127.0.0.1). Default `[::]`.
|
||||
|
||||
### SERVER_PORT
|
||||
|
||||
The port of the host. Default `80`.
|
||||
|
||||
### SERVER_LISTEN_FD
|
||||
|
||||
Optional file descriptor number (e.g. `0`) to inherit an already-opened TCP listener (instead of using `SERVER_HOST` and/or `SERVER_PORT`). Default empty (disabled).
|
||||
|
||||
### SERVER_ROOT
|
||||
|
||||
Relative or absolute root directory path of static files. Default `./public`.
|
||||
|
||||
### SERVER_CONFIG_FILE
|
||||
|
||||
The Server configuration file path is in TOML format. See [The TOML Configuration File](../configuration/config-file.md).
|
||||
|
||||
### SERVER_GRACE_PERIOD
|
||||
|
||||
Defines a grace period in seconds after a `SIGTERM` signal is caught which will delay the server before shutting it down gracefully. The maximum value is `255` seconds. The default value is `0` (no delay).
|
||||
|
||||
### SERVER_LOG_LEVEL
|
||||
|
||||
Specify a logging level in lowercase. Possible values are `error`, `warn`, `info`, `debug` or `trace`. Default `error`.
|
||||
|
||||
### SERVER_LOG_WITH_ANSI
|
||||
|
||||
Enable or disable ANSI escape codes for colors and other text formatting of the log output.
|
||||
|
||||
### SERVER_LOG_REMOTE_ADDRESS
|
||||
|
||||
Log incoming request information along with its Remote Address (IP) if available using the `info` log level. Default `false`.
|
||||
|
||||
### SERVER_LOG_X_REAL_IP
|
||||
|
||||
Log the X-Real-IP header if available using the `info` log level. Default `false`.
|
||||
|
||||
### SERVER_LOG_FORWARDED_FOR
|
||||
|
||||
Log the X-Forwarded-For header if available using the `info` log level. Default `false`.
|
||||
|
||||
### SERVER_TRUSTED_PROXIES
|
||||
|
||||
A comma separated list of IP addresses to accept the X-Forwarded-For header from. An empty string means trust all IPs. Default `""`
|
||||
|
||||
### SERVER_ERROR_PAGE_404
|
||||
|
||||
HTML file path for 404 errors. If the path is not specified or simply doesn't exist then the server will use a generic HTML error message.
|
||||
If a relative path is used then it will be resolved under the root directory. Default `./404.html`.
|
||||
|
||||
### SERVER_ERROR_PAGE_50X
|
||||
|
||||
HTML file path for 50x errors. If the path is not specified or simply doesn't exist then the server will use a generic HTML error message.
|
||||
If a relative path is used then it will be resolved under the root directory. Default `./50x.html`
|
||||
|
||||
### SERVER_FALLBACK_PAGE
|
||||
|
||||
A HTML file path (not relative to the root) used for `GET` requests when the requested path doesn't exist. The fallback page is served with a `200` status code, useful when using client routers. If the path doesn't exist then the feature is not activated.
|
||||
|
||||
### SERVER_THREADS_MULTIPLIER
|
||||
|
||||
The number of worker threads multiplier will be multiplied by the number of system CPUs using the formula: `worker threads = number of CPUs * n` where `n` is the value that changes here. When the multiplier value is 0 or 1 then the `number of CPUs` is used. 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. Default one thread per core.
|
||||
|
||||
### SERVER_MAX_BLOCKING_THREADS
|
||||
|
||||
Maximum number of blocking threads.
|
||||
|
||||
### SERVER_HTTP2_TLS
|
||||
|
||||
Enable HTTP/2 with TLS support. Make sure also to adjust the current server port. Default `false` (disabled).
|
||||
|
||||
### SERVER_HTTP2_TLS_CERT
|
||||
|
||||
Specify the file path to read the certificate. Default empty (disabled).
|
||||
|
||||
### SERVER_HTTP2_TLS_KEY
|
||||
|
||||
Specify the file path to read the private key. Default empty (disabled).
|
||||
|
||||
### SERVER_HTTPS_REDIRECT
|
||||
|
||||
Redirect all requests with scheme "http" to "https" for the current server instance. It depends on "http2" to be enabled.
|
||||
|
||||
### SERVER_HTTPS_REDIRECT_HOST
|
||||
|
||||
Canonical hostname or IP of the HTTPS (HTTPS/2) server. It depends on "https-redirect" to be enabled. Default `localhost`.
|
||||
|
||||
### SERVER_HTTPS_REDIRECT_FROM_PORT
|
||||
|
||||
HTTP host port where the redirect server will listen for requests to redirect them to HTTPS. It depends on "https-redirect" to be enabled. Default `80`.
|
||||
|
||||
### SERVER_HTTPS_REDIRECT_FROM_HOSTS
|
||||
|
||||
List of host names or IPs allowed to redirect from. HTTP requests must contain the HTTP 'Host' header and match against this list. It depends on "https-redirect" to be enabled. Default `localhost`.
|
||||
|
||||
### SERVER_CORS_ALLOW_ORIGINS
|
||||
Specify an optional CORS list of allowed origin hosts separated by commas. Host ports or protocols aren't being checked. Use an asterisk (*) to allow any host. Default empty (disabled).
|
||||
|
||||
Specify an optional CORS list of allowed origin hosts separated by commas. Host ports or protocols aren't being checked. Use an asterisk (\*) to allow any host. Default empty (disabled).
|
||||
|
||||
### SERVER_CORS_ALLOW_HEADERS
|
||||
|
||||
Specify an optional CORS list of allowed HTTP headers separated by commas. It requires `SERVER_CORS_ALLOW_ORIGINS` to be used along with. Default `origin, content-type`.
|
||||
|
||||
### SERVER_CORS_EXPOSE_HEADERS
|
||||
|
||||
Specify an optional CORS list of exposed HTTP headers separated by commas. It requires `SERVER_CORS_ALLOW_ORIGINS` to be used along with. Default `origin, content-type`.
|
||||
|
||||
### SERVER_COMPRESSION
|
||||
|
||||
`Gzip`, `Deflate`, `Brotli` or `zlib` compression on demand determined by the `Accept-Encoding` header and applied to text-based web file types only. See [ad-hoc mime-type list](https://github.com/static-web-server/static-web-server/blob/master/src/compression.rs#L20). Default `true` (enabled).
|
||||
|
||||
### SERVER_COMPRESSION_LEVEL
|
||||
|
||||
Supported values are `fastest` (fast compression but larger resulting files), `best` (smallest file size but potentially slow) and `default` (algorithm-specific balanced compression level). Default is `default`.
|
||||
|
||||
### SERVER_COMPRESSION_STATIC
|
||||
|
||||
Look up the pre-compressed file variant (`.gz`, `.br` or `.zst`) on the disk of a requested file and serve it directly if available. Default `false` (disabled). The compression type is determined by the `Accept-Encoding` header.
|
||||
|
||||
### SERVER_DIRECTORY_LISTING
|
||||
|
||||
Enable directory listing for all requests ending with the slash character (‘/’). Default `false` (disabled).
|
||||
|
||||
### SERVER_DIRECTORY_LISTING_ORDER
|
||||
|
||||
Specify a default code number to order directory listing entries per `Name`, `Last modified` or `Size` attributes (columns). Code numbers supported: `0` (Name asc), `1` (Name desc), `2` (Last modified asc), `3` (Last modified desc), `4` (Size asc), `5` (Size desc). Default `6` (unordered).
|
||||
|
||||
### SERVER_DIRECTORY_LISTING_FORMAT
|
||||
|
||||
Specify a content format for the directory listing entries. Formats supported: `html` or `json`. Default `html`.
|
||||
|
||||
### SERVER_DIRECTORY_LISTING_DOWNLOAD
|
||||
|
||||
Specify list of enabled format(s) for directory download. Format supported: `targz`. Default to empty list (disabled).
|
||||
|
||||
### SERVER_SECURITY_HEADERS
|
||||
|
||||
Enable security headers by default when the HTTP/2 feature is activated. Headers included: `Strict-Transport-Security: max-age=63072000; includeSubDomains; preload` (2 years max-age), `X-Frame-Options: DENY` and `Content-Security-Policy: frame-ancestors 'self'`. Default `false` (disabled).
|
||||
|
||||
### SERVER_CACHE_CONTROL_HEADERS
|
||||
|
||||
Enable cache control headers for incoming requests based on a set of file types. The file type list can be found in [`src/control_headers.rs`](https://github.com/static-web-server/static-web-server/blob/master//src/control_headers.rs) file. Default `true` (enabled).
|
||||
|
||||
### SERVER_BASIC_AUTH
|
||||
|
||||
It provides [The "Basic" HTTP Authentication Scheme](https://datatracker.ietf.org/doc/html/rfc7617) using credentials as `user-id:password` pairs, encoded using `Base64`. Password must be encoded using the [BCrypt](https://en.wikipedia.org/wiki/Bcrypt) password-hashing function. Default empty (disabled).
|
||||
|
||||
### SERVER_REDIRECT_TRAILING_SLASH
|
||||
|
||||
Check for a trailing slash in the requested directory URI and redirect permanent (308) to the same path with a trailing slash suffix if it is missing. Default `true` (enabled).
|
||||
|
||||
### SERVER_IGNORE_HIDDEN_FILES
|
||||
|
||||
Ignore hidden files/directories (dotfiles), preventing them from being served and being included in auto HTML index pages (directory listing).
|
||||
|
||||
### SERVER_DISABLE_SYMLINKS
|
||||
|
||||
Prevent following files or directories if any path name component is a symbolic link.
|
||||
|
||||
### SERVER_HEALTH
|
||||
|
||||
Activate the health endpoint.
|
||||
|
||||
### SERVER_ACCEPT_MARKDOWN
|
||||
|
||||
Enable markdown content negotiation. When a client sends `Accept: text/markdown` header, the server will serve markdown files (`.md` or `.html.md`) if available. See [Markdown Content Negotiation](../features/markdown-content-negotiation.md) for details. Default `false`.
|
||||
|
||||
### SERVER_INDEX_FILES
|
||||
|
||||
List of files that will be used as an index for requests ending with the slash character (‘/’). Files are checked in the specified order. Default `index.html`.
|
||||
|
||||
### SERVER_MAINTENANCE_MODE
|
||||
|
||||
Enable the server's maintenance mode functionality.
|
||||
|
||||
### SERVER_MAINTENANCE_MODE_STATUS
|
||||
|
||||
Provide a custom HTTP status code when entering into maintenance mode. Default `503`.
|
||||
|
||||
### SERVER_MAINTENANCE_MODE_FILE
|
||||
|
||||
Provide a custom maintenance mode HTML file. If not provided then a generic message will be displayed.
|
||||
|
||||
## Windows
|
||||
|
||||
The following options and commands are Windows platform-specific.
|
||||
|
||||
### SERVER_WINDOWS_SERVICE
|
||||
|
||||
Run the web server in a Windows Service context. See [more details](../features/windows-service.md).
|
||||
|
||||
@@ -13,6 +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 feature page](https://static-web-server.net/features/docker/).
|
||||
|
||||
## Installation methods
|
||||
@@ -55,7 +56,7 @@ yay -S static-web-server-bin
|
||||
|
||||
Add the `rust` repository and install [the package](https://gitlab.exherbo.org/exherbo/rust/-/tree/master/packages/www-servers/static-web-server) through `cave`:
|
||||
|
||||
```
|
||||
```sh
|
||||
cave sync
|
||||
cave resolve -x repository/rust
|
||||
cave resolve -x static-web-server
|
||||
|
||||
@@ -11,6 +11,7 @@ The format to use is the following:
|
||||
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.
|
||||
@@ -23,13 +24,15 @@ htpasswd -nBC10 "username"
|
||||
```
|
||||
|
||||
!!! tip "Password Security Advice"
|
||||
|
||||
The password verification happens at runtime but its verification speed depends on the computing time cost of `bcrypt` algorithm used.
|
||||
|
||||
For example, the `htpasswd` tool supports a `-C` argument to adjust the `bcrypt`'s computing time.
|
||||
|
||||
|
||||
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 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 in [the Docker Compose file: variable substitution](https://docs.docker.com/compose/compose-file/compose-file-v2/#variable-substitution) page.
|
||||
|
||||
|
||||
@@ -5,6 +5,7 @@
|
||||
This feature can be controlled by the numeric `-b, --max-blocking-threads` option or the equivalent [SERVER_MAX_BLOCKING_THREADS](./../configuration/environment-variables.md#server_max_blocking_threads) env.
|
||||
|
||||
!!! info "WebAssembly"
|
||||
|
||||
We use `20` in [Wasm](https://webassembly.org/) by default and `512` in native environments (Tokio's default). See [Tokio ` max_blocking_threads` API](https://docs.rs/tokio/latest/tokio/runtime/struct.Builder.html#method.max_blocking_threads) for more details.
|
||||
|
||||
Below is an example.
|
||||
|
||||
@@ -5,6 +5,7 @@
|
||||
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.
|
||||
|
||||
!!! 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
|
||||
@@ -16,6 +17,7 @@ Control headers are applied only to the following file types with the correspond
|
||||
A `max-age` of *one day* duration is used by default.
|
||||
|
||||
!!! info "Note"
|
||||
|
||||
One-day `max-age` for example includes `html` and other file types.
|
||||
|
||||
### One hour
|
||||
|
||||
@@ -10,6 +10,7 @@ When the `compression-static` option is enabled and the pre-compressed file is f
|
||||
Otherwise, if the pre-compressed file is not found then SWS just continues the normal workflow (trying to serve the original file requested instead). Additionally, if for example the [compression](../features/compression.md) option was also enabled then the requested file can be compressed on the fly right after.
|
||||
|
||||
!!! info "Compressed file type"
|
||||
|
||||
The pre-compressed file type is determined by the [`Accept-Encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) header value.
|
||||
|
||||
Here is an example:
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
**`SWS`** provides optional [Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) support.
|
||||
|
||||
A list of allowed origin hosts (URLs) should be specified and separated by commas.
|
||||
Or an asterisk (*) can be used to allow any host.
|
||||
Or an asterisk (\*) can be used to allow any host.
|
||||
|
||||
This feature is disabled by default and can be controlled by the string `-c, --cors-allow-origins` option or the equivalent [SERVER_CORS_ALLOW_ORIGINS](../configuration/environment-variables.md#server_cors_allow_origins) env.
|
||||
|
||||
@@ -26,6 +26,7 @@ The server also supports a list of [CORS allowed headers](https://developer.mozi
|
||||
This feature depends on `--cors-allow-origins` to be used along with this feature. It can be controlled by the string `-j, --cors-allow-headers` option or the equivalent [SERVER_CORS_ALLOW_HEADERS](../configuration/environment-variables.md#server_cors_allow_headers) env.
|
||||
|
||||
!!! info "Tips"
|
||||
|
||||
- The default allowed headers value is `origin, content-type, authorization`.
|
||||
- The server also supports [preflight requests](https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request) via the `OPTIONS` method. See [Preflighted requests in CORS](./http-methods.md#preflight-requests-in-cors).
|
||||
|
||||
@@ -35,7 +36,7 @@ Below is an example of how to CORS.
|
||||
static-web-server \
|
||||
--port 8787 \
|
||||
--root ./my-public-dir \
|
||||
--cors-allow-origins "https://domain.com"
|
||||
--cors-allow-origins "https://domain.com" \
|
||||
--cors-allow-headers "origin, content-type, x-requested-with"
|
||||
```
|
||||
|
||||
@@ -46,6 +47,7 @@ The server also supports a list of [CORS-exposed headers to scripts](https://dev
|
||||
This feature depends on `--cors-allow-origins` to be used along with this feature. It can be controlled by the string `--cors-expose-headers` option or the equivalent [SERVER_CORS_EXPOSE_HEADERS](../configuration/environment-variables.md#server_cors_expose_headers) env.
|
||||
|
||||
!!! info "Tips"
|
||||
|
||||
- The default exposed header's is `origin, content-type`.
|
||||
- The server also supports [preflight requests](https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request) via the `OPTIONS` method. See [Preflighted requests in CORS](./http-methods.md#preflight-requests-in-cors).
|
||||
|
||||
@@ -55,6 +57,6 @@ Below is an example of how to CORS.
|
||||
static-web-server \
|
||||
--port 8787 \
|
||||
--root ./my-public-dir \
|
||||
--cors-allow-origins "https://domain.com"
|
||||
--cors-allow-origins "https://domain.com" \
|
||||
--cors-expose-headers "origin, content-type, x-requested-with"
|
||||
```
|
||||
|
||||
@@ -14,6 +14,7 @@ Each table entry should have two key/value pairs:
|
||||
A particular set of HTTP headers can only be applied when a `source` matches against the request URI.
|
||||
|
||||
!!! info "Custom HTTP headers take precedence over existing ones"
|
||||
|
||||
Whatever custom HTTP header could **replace** an existing one if it was previously defined (e.g. server default headers) and matches its `source`.
|
||||
|
||||
The header's order is important because determines its precedence.
|
||||
@@ -22,7 +23,7 @@ A particular set of HTTP headers can only be applied when a `source` matches aga
|
||||
|
||||
### Source
|
||||
|
||||
The source is a [Glob pattern](https://en.wikipedia.org/wiki/Glob_(programming)) that should match against the URI that is requesting a resource file.
|
||||
The source is a [Glob pattern](<https://en.wikipedia.org/wiki/Glob_(programming)>) that should match against the URI that is requesting a resource file.
|
||||
|
||||
### Headers
|
||||
|
||||
|
||||
@@ -59,6 +59,7 @@ Below are the possible number code values for sorting or ordering which are grou
|
||||
- `6`: Unordered
|
||||
|
||||
!!! tip "Tips"
|
||||
|
||||
- The `--directory-listing-order` option depends on `--directory-listing` to be enabled.
|
||||
- Use the query `?sort=NUMBER` to customize the sorting via the URI. E.g `https://localhost/?sort=5` (sort by size in descending order)
|
||||
|
||||
@@ -78,6 +79,7 @@ static-web-server \
|
||||
**`SWS`** provides support for specifying an output format either HTML (default) or JSON for the directory listing entries via the string `--directory-listing-format` option or the equivalent [SERVER_DIRECTORY_LISTING_FORMAT](./../configuration/environment-variables.md#server_directory_listing_format) env.
|
||||
|
||||
!!! tip "Tips"
|
||||
|
||||
- The `--directory-listing-format` option depends on `--directory-listing` to be enabled.
|
||||
|
||||
### HTML format
|
||||
@@ -106,7 +108,6 @@ The JSON format used is shown below for directories and files. Note that the `si
|
||||
|
||||
Here is an example of serving the directory listing in JSON format.
|
||||
|
||||
|
||||
```sh
|
||||
static-web-server \
|
||||
-p=8787 -d=tests/fixtures/public -g=trace \
|
||||
@@ -128,6 +129,7 @@ curl -iH "content-type: application/json" http://localhost:8787
|
||||
```
|
||||
|
||||
## Directory Download
|
||||
|
||||
**`SWS`** supports downloading the content of a directory as a single file when **Directory Listing** feature is enabled. To activate, specify the list of download format to enable using the `--directory-listing-download` flag or the equivalent [SERVER_DIRECTORY_LISTING_DOWNLOAD](./../configuration/environment-variables.md#server_directory_listing_download) env. Currently, `targz` format is supported.
|
||||
|
||||
```sh
|
||||
@@ -137,4 +139,3 @@ static-web-server \
|
||||
```
|
||||
|
||||
When **Directory Download** is enabled, append `?download` to a directory URL to download it. A link will also be added to the top part of **HTML** output format.
|
||||
|
||||
|
||||
@@ -19,9 +19,11 @@ All Docker images are [Multi-Arch](https://www.docker.com/blog/how-to-rapidly-bu
|
||||
- `linux/s390x` (Debian only)
|
||||
|
||||
!!! tip "`Scratch` and `Alpine` images use statically-linked binaries"
|
||||
|
||||
`Scratch` and `Alpine` based Docker images use a statically-linked binary that is portable, performant and dependency-free thanks to [musl libc](https://www.musl-libc.org/), keeping containers as lean as possible.
|
||||
|
||||
!!! tip "`Debian` images use dynamically-linked binaries"
|
||||
|
||||
`Debian` based Docker images use SWS dynamically-linked binaries, making containers highly optimized, performant and resource-efficient.
|
||||
|
||||
## Rootless
|
||||
@@ -29,6 +31,7 @@ All Docker images are [Multi-Arch](https://www.docker.com/blog/how-to-rapidly-bu
|
||||
The **Debian** and **Alpine** Docker images are rootless **by default** using a dedicated `sws` user and group. This reduces the attack surface and improves security.
|
||||
|
||||
!!! info "Remember"
|
||||
|
||||
Users can still run the containers as root if they _explicitly_ set the user to _root_ when running the container, e.g., using the `--user root` flag with `docker run`.
|
||||
|
||||
The `static-web-server` binary and all files under `/home/sws` (home directory) are owned by the non-root `sws` user and group.
|
||||
@@ -46,6 +49,7 @@ The current working directory is the _home directory_ by default.
|
||||
To give the server a quick try just run the following commands.
|
||||
|
||||
!!! tip "Tips"
|
||||
|
||||
- [The SWS CLI arguments](../configuration/command-line-arguments.md) 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.
|
||||
|
||||
@@ -221,4 +225,5 @@ spec:
|
||||
```
|
||||
|
||||
### TrueCharts
|
||||
|
||||
The [TrueCharts Community](https://truecharts.org) also provides a ready-to-use [Static Web Server Helm-Chart](https://truecharts.org/charts/stable/static-web-server/) that you can easily deploy in your Kubernetes.
|
||||
|
||||
@@ -5,6 +5,7 @@
|
||||
This feature is enabled by default and can be controlled either by the string `--page404` ([SERVER_ERROR_PAGE_404](./../configuration/environment-variables.md#server_error_page_404)) or the `--page50x` ([SERVER_ERROR_PAGE_50X](./../configuration/environment-variables.md#server_error_page_50x)) arguments.
|
||||
|
||||
!!! info "Tip"
|
||||
|
||||
Either `--page404` and `--page50x` have defaults (optional values) so they can be specified or omitted as required.
|
||||
|
||||
Below is an example of how to customize those HTML pages.
|
||||
@@ -24,6 +25,7 @@ The fallback page will be served with a `200` status code, useful when using cli
|
||||
If the path is not specified or simply doesn't exist then this feature will not be activated.
|
||||
|
||||
!!! info "The fallback page path is not relative to the root"
|
||||
|
||||
The fallback page is an independent path, so provide a valid relative or absolute path.
|
||||
|
||||
It can be set with the `SERVER_FALLBACK_PAGE` environment variable or with the CLI argument `--page-fallback`.
|
||||
|
||||
@@ -3,6 +3,7 @@
|
||||
**SWS** provides the ability to accept a socket listener as a file descriptor for use in sandboxing and on-demand applications via `systemd` (Linux), `launchd` (Macos) or similar.
|
||||
|
||||
!!! tip "Tip"
|
||||
|
||||
The [Socket Activation](http://0pointer.de/blog/projects/socket-activation.html) model is an alternative to TCP port binding.
|
||||
|
||||
Socket activation is supported by the `-f, --fd` option or the equivalent [SERVER_LISTEN_FD](./../configuration/environment-variables.md#server_listen_fd) env.
|
||||
|
||||
@@ -5,6 +5,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).
|
||||
|
||||
!!! 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.
|
||||
|
||||
@@ -17,6 +18,7 @@ In these situations, SWS allows delaying the graceful shutdown process right aft
|
||||
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.
|
||||
|
||||
!!! tip "Tip"
|
||||
|
||||
The maximum grace period value is `255` seconds (4.25 min). The default value is `0` (no delay).
|
||||
|
||||
Here is an example of delaying the graceful shutdown process by `10` seconds after a `SIGTERM`.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Health endpoint
|
||||
|
||||
SWS provides an optional `/health` endpoint that can be used to check if it is running properly.
|
||||
When the `/health` is requested, SWS will generate a log only at the `debug` level instead of the usual `info` level for a regular file.
|
||||
When the `/health` is requested, SWS will generate a log only at the `debug` level instead of the usual `info` level for a regular file.
|
||||
|
||||
The HTTP methods supported are `GET` and `HEAD`.
|
||||
|
||||
|
||||
@@ -5,23 +5,29 @@
|
||||
This feature is disabled by default and can be controlled by the boolean `--https-redirect` option or the equivalent [SERVER_HTTPS_REDIRECT](./../configuration/environment-variables.md#server_https_redirect) env.
|
||||
|
||||
!!! info "HTTP/2 required"
|
||||
|
||||
HTTPS redirect requires the [HTTP/2](../features/http2-tls.md) feature to be activated.
|
||||
|
||||
## HTTPS redirect
|
||||
The boolean `--https-redirect` is the main option and controls the whole HTTPS redirect feature. If `true` then will tell SWS to redirect all requests with scheme `http` to `https` for the current server instance with a `301 Moved Permanently` redirect status response code.
|
||||
|
||||
The boolean `--https-redirect` is the main option and controls the whole HTTPS redirect feature. If `true` then will tell SWS to redirect all requests with scheme `http` to `https` for the current server instance with a `301 Moved Permanently` redirect status response code.
|
||||
This option depends on [`http2`](../features/http2-tls.md) to be enabled.
|
||||
|
||||
## HTTPS redirect host
|
||||
|
||||
The string `--https-redirect-host` option represents the canonical hostname or IP of the HTTPS (HTTPS/2) server. This is usually associated with the `--host` option, however here this value will be used as the destination for the redirected requests.
|
||||
It depends on "https-redirect" option to be enabled. The default is `localhost`.
|
||||
|
||||
## HTTPS redirect from port
|
||||
|
||||
The string `--https-redirect-from-port` option represents the HTTP host port where the redirect server will listen for requests (source) to redirect them to HTTPS. It depends on "https-redirect" option to be enabled. The default is `80`.
|
||||
|
||||
## HTTPS redirect from hosts
|
||||
|
||||
The string `--https-redirect-from-hosts` option represents a list of hostnames or IPs allowed to redirect from using comma-separated values. Incoming HTTP requests must contain the [HTTP `Host` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Host) and match against this list. It depends on "https-redirect" option to be enabled. The default value is `localhost`.
|
||||
|
||||
!!! tip "Tip: define hostnames/IPs to redirect from for increasing security"
|
||||
|
||||
- Via the `--https-redirect-from-hosts` or its env you can tell SWS which hostnames or IPs are allowed to redirect from your SWS server instance to avoid potential spoofing issues.
|
||||
- When a hostname or IP is not found in the whitelist then SWS will respond with a `400 Bad Request` status response.
|
||||
|
||||
|
||||
@@ -24,6 +24,7 @@ curl -I -X OPTIONS http://localhost:8787/assets/main.js
|
||||
The HTTP [OPTIONS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS) method can also be used to send a request asking if it is acceptable to send requests to the server and if it is aware of using specific methods and headers.
|
||||
|
||||
!!! info "Tip"
|
||||
|
||||
If an `Access-Control-Request-Method` or `Access-Control-Request-Headers` value is not allowed then the server replies with a `403 Forbidden` HTTP error. See [CORS](./cors.md) feature for more details.
|
||||
|
||||
Example using an HTTP client.
|
||||
|
||||
@@ -3,6 +3,7 @@
|
||||
The HTTP/1 is the protocol by default and can be used by specifying a host address via the `-a, --host` ([SERVER_HOST](./../configuration/environment-variables.md#server_host)) argument, the port of the host via `-p, --port` ([SERVER_PORT](./../configuration/environment-variables.md#server_port)) and the directory of the static files using the `-d, --root` ([SERVER_ROOT](./../configuration/environment-variables.md#server_root)) argument.
|
||||
|
||||
!!! info "Tips"
|
||||
|
||||
- Either `--host`, `--port` and `--root` have defaults (optional values) so they can be specified or omitted as required.
|
||||
- The server provides [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 by default.
|
||||
|
||||
|
||||
@@ -10,20 +10,20 @@ SWS comes with safe TLS defaults for underlying cryptography.
|
||||
|
||||
- **Cipher suites:**
|
||||
- TLS1.3:
|
||||
```
|
||||
TLS13_AES_256_GCM_SHA384
|
||||
TLS13_AES_128_GCM_SHA256
|
||||
TLS13_CHACHA20_POLY1305_SHA256
|
||||
```
|
||||
```
|
||||
TLS13_AES_256_GCM_SHA384
|
||||
TLS13_AES_128_GCM_SHA256
|
||||
TLS13_CHACHA20_POLY1305_SHA256
|
||||
```
|
||||
- TLS1.2:
|
||||
```
|
||||
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
|
||||
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
|
||||
TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
|
||||
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
|
||||
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
|
||||
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
|
||||
```
|
||||
```
|
||||
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
|
||||
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
|
||||
TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
|
||||
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
|
||||
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
|
||||
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
|
||||
```
|
||||
- **Key exchange groups:**
|
||||
- `X25519`, `SECP256R1` and `SECP384R1`
|
||||
- **Protocol versions:**
|
||||
@@ -42,6 +42,7 @@ Only the following private key file formats are supported:
|
||||
## Example
|
||||
|
||||
!!! info "Tips"
|
||||
|
||||
- Either `--host`, `--port` and `--root` have defaults (optional values) so they can be specified or omitted as required.
|
||||
- Don't forget to adjust the proper `--port` value for the HTTP/2 & TLS feature.
|
||||
- When this feature is enabled (`--http2=true`) then the [security headers](./security-headers.md) are also enabled automatically.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Ignore files
|
||||
|
||||
**`SWS`** provides some options to ignore files or directories from being served and displayed if the directory listing is enabled.
|
||||
**`SWS`** provides some options to ignore files or directories from being served and displayed if the directory listing is enabled.
|
||||
|
||||
## Ignore hidden files (dotfiles)
|
||||
|
||||
|
||||
@@ -46,6 +46,7 @@ static-web-server -a "0.0.0.0" -p 8080 -d docker/public/ -g info --log-remote-ad
|
||||
```
|
||||
|
||||
The relevant log output:
|
||||
|
||||
```log
|
||||
INFO static_web_server::logger: logging level: info
|
||||
<...>
|
||||
@@ -78,8 +79,7 @@ To restrict the logging to only requests that originate from trusted proxy IPs,
|
||||
When used behind a reverse proxy the reported `remote_addr` indicates the proxies IP address and port, not the client's real IP.
|
||||
The Proxy server can be configured to provide the [X-Forwarded-For header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For), containing a comma-separated list of IP addresses, starting with the *real remote client IP*, and all following intermediate proxies (if any).
|
||||
|
||||
|
||||
To enable logging of the real remote IP, enable the `--log-forwarded-for` option or the equivalent [SERVER_LOG_FORWARDED_FOR](../configuration/environment-variables.md#server_log_forwarded_for) env. By default this will log all requests which have a correctly formatted `X-Forwarded-For` header.
|
||||
To enable logging of the real remote IP, enable the `--log-forwarded-for` option or the equivalent [SERVER_LOG_FORWARDED_FOR](../configuration/environment-variables.md#server_log_forwarded_for) env. By default this will log all requests which have a correctly formatted `X-Forwarded-For` header.
|
||||
|
||||
Since the content of the `X-Forwarded-For` header can be changed by all proxies in the chain, the remote IP address reported may not be trusted.
|
||||
|
||||
@@ -92,6 +92,7 @@ static-web-server -a "::" --log-forwarded-for=true --trusted-proxies="::1" -p 80
|
||||
```
|
||||
|
||||
Look for these lines in the log output:
|
||||
|
||||
```log
|
||||
<...>
|
||||
INFO static_web_server::info: log level: info
|
||||
@@ -113,22 +114,25 @@ Log entry for this request will look like:
|
||||
INFO static_web_server::handler: incoming request: method=GET uri=/ real_remote_ip=203.0.113.195
|
||||
```
|
||||
|
||||
---
|
||||
______________________________________________________________________
|
||||
|
||||
If we send the request from `127.0.0.1` instead:
|
||||
|
||||
```sh
|
||||
curl "http://127.0.0.1:8080" --header "X-Forwarded-For: 203.0.113.195, 2001:db8:85a3:8d3:1319:8a2e:370:7348"
|
||||
```
|
||||
|
||||
we get the following log output:
|
||||
|
||||
```log
|
||||
INFO static_web_server::handler: incoming request: method=GET uri=/
|
||||
```
|
||||
|
||||
`127.0.0.1` is not in the `trusted_proxies`, so we dont get a `real_remote_address` in the log.
|
||||
|
||||
Note the absence of the proxies remote address in these examples. If you want to log the remote address and the real remote address, you need to specify both `--log-remote-address` and `--log-forwarded-for`.
|
||||
|
||||
---
|
||||
______________________________________________________________________
|
||||
|
||||
**`SWS`** will parse the `X-Forwarded-For` header and if the provided client IP is invalid, it will be ignored to prevent log poisoning attacks. In such cases the `real_remote_ip` section will not be added.
|
||||
|
||||
|
||||
@@ -18,14 +18,16 @@ When not specified, the server will reply with the `503 Service Unavailable` sta
|
||||
|
||||
## HTML Page
|
||||
|
||||
The `--maintenance-mode-file` or the equivalent [SERVER_MAINTENANCE_MODE_FILE](./../configuration/environment-variables.md#server_maintenance_mode_file) env variable can be also used to customize the response content.
|
||||
The `--maintenance-mode-file` or the equivalent [SERVER_MAINTENANCE_MODE_FILE](./../configuration/environment-variables.md#server_maintenance_mode_file) env variable can be also used to customize the response content.
|
||||
|
||||
The value should be an existing local HTML file path. When not provided a generic message will be displayed.
|
||||
|
||||
!!! tip "Optional"
|
||||
|
||||
Remember that either `--maintenance-mode-status` and `--maintenance-mode-file` are optional and can be omitted as needed.
|
||||
|
||||
!!! info "Independent path"
|
||||
|
||||
The `--maintenance-mode-file` is an independent file path and not relative to the root.
|
||||
|
||||
## Example
|
||||
|
||||
@@ -17,7 +17,6 @@ You can generate completions for these shells and completion engines:
|
||||
|
||||
By typing the following command, all completions will be exported to a specific directory path:
|
||||
|
||||
|
||||
```sh
|
||||
static-web-server generate --completions /my-completions-dir
|
||||
```
|
||||
|
||||
@@ -71,6 +71,7 @@ curl -H "Accept: text/markdown" https://example.com/docs/
|
||||
```
|
||||
|
||||
This approach is superior to traditional `.md` URL suffixes because:
|
||||
|
||||
- Uses standard HTTP content negotiation
|
||||
- Same URL serves both HTML (browsers) and Markdown (LLMs)
|
||||
- No need for separate URL structures or redirects
|
||||
|
||||
@@ -3,6 +3,7 @@
|
||||
**`SWS`** allows to provide a list of files that will be used as an index for requests ending with the slash character (‘/’).
|
||||
|
||||
!!! info "Notes"
|
||||
|
||||
- Files are checked in the specified order from left to right.
|
||||
- The option value can be a single index or comma-separated when multiple values.
|
||||
- The default value is `index.html`.
|
||||
|
||||
@@ -7,6 +7,7 @@ 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.
|
||||
|
||||
!!! 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,8 +1,8 @@
|
||||
# URL Redirects
|
||||
# URL Redirects
|
||||
|
||||
**SWS** provides the ability to redirect request URLs with Glob pattern-matching support.
|
||||
|
||||
URI redirects are particularly useful with pattern matching ([globs](https://en.wikipedia.org/wiki/Glob_(programming))). Use them for example to prevent broken links if you've moved a page or to shorten URLs.
|
||||
URI redirects are particularly useful with pattern matching ([globs](<https://en.wikipedia.org/wiki/Glob_(programming)>)). Use them for example to prevent broken links if you've moved a page or to shorten URLs.
|
||||
|
||||
## Structure
|
||||
|
||||
@@ -16,6 +16,7 @@ Each table entry should have the following key/value pairs:
|
||||
- `kind`: optional number containing the HTTP response code (redirection).
|
||||
|
||||
!!! info "Note"
|
||||
|
||||
The incoming request(s) will reach the `destination` only if the request(s) URI matches the `source` pattern.
|
||||
|
||||
### Host
|
||||
@@ -23,18 +24,21 @@ Each table entry should have the following key/value pairs:
|
||||
Optional `host` redirect entry to be matched against the incoming host URI. If a `host` redirect setting is specified then SWS will attempt to match the value against the incoming URI host (request), applying the required redirect entry or ignoring it otherwise.
|
||||
|
||||
!!! tip "www to non-www redirects"
|
||||
|
||||
The host entry allows for instance to perform www to non-www redirects or vice versa (see example below).
|
||||
|
||||
### Source
|
||||
|
||||
The source is a [Glob pattern](https://en.wikipedia.org/wiki/Glob_(programming)) that should match against the URI that is requesting a resource file.
|
||||
The source is a [Glob pattern](<https://en.wikipedia.org/wiki/Glob_(programming)>) that should match against the URI that is requesting a resource file.
|
||||
|
||||
The glob pattern functionality is powered by the [globset](https://docs.rs/globset/latest/globset/) crate which supports Standard Unix-style glob syntax.
|
||||
|
||||
!!! tip "Glob pattern syntax"
|
||||
|
||||
For more details about the Glob pattern syntax check out https://docs.rs/globset/latest/globset/#syntax
|
||||
|
||||
!!! warning "Matching of path separator in `*`"
|
||||
|
||||
Up to version `2.33.1` the wildcard `*` was matching the path separator.
|
||||
For example, `/{*}/{*}/` matched `/assets/images/logo/`.
|
||||
|
||||
@@ -51,6 +55,7 @@ Additionally, a `destination` supports replacements for every Glob pattern group
|
||||
The replacement order starts from `0` to `n` and is defined with a dollar sign followed by an index (Glob pattern group occurrence).
|
||||
|
||||
!!! tip "Group your Glob patterns"
|
||||
|
||||
When using replacements, also group your Glob pattern by surrounding them with curly braces so every group should map to its corresponding replacement.<br>
|
||||
For example: `source = "**/{*}.{jpg,jpeg,svg}"`
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
**SWS** provides the ability to rewrite request URLs (routes) with Glob pattern-matching support.
|
||||
|
||||
URI rewrites are particularly useful with pattern matching ([globs](https://en.wikipedia.org/wiki/Glob_(programming))), as the server can accept any URL that matches the pattern and let the client-side code decide what to display.
|
||||
URI rewrites are particularly useful with pattern matching ([globs](<https://en.wikipedia.org/wiki/Glob_(programming)>)), as the server can accept any URL that matches the pattern and let the client-side code decide what to display.
|
||||
|
||||
## Structure
|
||||
|
||||
@@ -15,18 +15,21 @@ Each table entry should have two key/value pairs:
|
||||
- `redirect`: optional number containing the HTTP response code (redirection).
|
||||
|
||||
!!! info "Note"
|
||||
|
||||
The incoming request(s) will reach the `destination` only if the request(s) URI matches the `source` pattern.
|
||||
|
||||
### Source
|
||||
|
||||
It's a [Glob pattern](https://en.wikipedia.org/wiki/Glob_(programming)) that should match against the URI that is requesting a resource file.
|
||||
It's a [Glob pattern](<https://en.wikipedia.org/wiki/Glob_(programming)>) that should match against the URI that is requesting a resource file.
|
||||
|
||||
The glob pattern functionality is powered by the [globset](https://docs.rs/globset/latest/globset/) crate which supports Standard Unix-style glob syntax.
|
||||
|
||||
!!! tip "Glob pattern syntax"
|
||||
|
||||
For more details about the Glob pattern syntax check out https://docs.rs/globset/latest/globset/#syntax
|
||||
|
||||
!!! warning "Matching of path separator in `*`"
|
||||
|
||||
Up to version `2.33.1` the wildcard `*` was matching the path separator.
|
||||
For example, `/{*}/{*}/` matched `/assets/images/logo/`.
|
||||
|
||||
@@ -43,6 +46,7 @@ Additionally, a `destination` supports replacements for every Glob pattern group
|
||||
Replacements order start from `0` to `n` and are defined with a dollar sign followed by an index (Glob pattern group occurrence).
|
||||
|
||||
!!! tip "Group your Glob patterns"
|
||||
|
||||
When using replacements, also group your Glob pattern by surrounding them with curly braces so every group should map to its corresponding replacement.<br>
|
||||
For example: `source = "**/{*}.{png,gif}"`
|
||||
|
||||
|
||||
@@ -3,6 +3,7 @@
|
||||
**SWS** provides rudimentary support for name-based [virtual hosting](https://en.wikipedia.org/wiki/Virtual_hosting#Name-based). This allows you to serve files from different root directories depending on the ["Host" header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/host) of the request, with all other settings staying the same.
|
||||
|
||||
!!! warning "All other settings are the same!"
|
||||
|
||||
Each virtual host has to have all the same settings (aside from `root`). If using TLS, your certificates will have to cover all virtual host names as Subject Alternative Names (SANs). Also, beware of other conflicting settings like redirects and rewrites. If you find yourself needing different settings for different virtual hosts, it is recommended to run multiple instances of SWS.
|
||||
|
||||
Virtual hosting can be useful for serving more than one static website from the same SWS instance, if it's not otherwise feasible to run multiple instances of SWS. Browsers will automatically send a `Host` header which matches the hostname in the URL bar, which is how HTTP servers are able to tell which "virtual" host that the client is accessing.
|
||||
|
||||
@@ -3,6 +3,7 @@
|
||||
**SWS** can run in a [WebAssembly](https://webassembly.org/) context.
|
||||
|
||||
!!! info "Wasm/Wasix targets are not officially supported by SWS yet"
|
||||
|
||||
We do not officially support Wasm or Wasix targets yet. But SWS project will eventually support Wasix as a target in a not remote future.<br>
|
||||
In the meantime, [Wasmer](https://wasmer.io/) folks made it possible to [run SWS via Wasix today](https://wasmer.io/posts/announcing-wasix) via a series of patches.
|
||||
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
# 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. Therefore it also provides a subcommand to *install* SWS as a 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. 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.
|
||||
|
||||
|
||||
|
||||
> _Static Web Server running as a Windows Service and displayed by 'services.msc' application._
|
||||
|
||||
## Important Notes
|
||||
|
||||
@@ -21,12 +21,15 @@ 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`.
|
||||
|
||||
!!! tip "Tip"
|
||||
|
||||
When the `--threads-multiplier` input value is `0` or `1` then one thread per core is used (default value).
|
||||
|
||||
!!! info "WebAssembly"
|
||||
|
||||
We use `2` threads per core in [Wasm](https://webassembly.org/) and `1` in native environments by default.
|
||||
|
||||
!!! warn "Warn"
|
||||
|
||||
The number of worker threads resulted 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/latest/tokio/runtime/struct.Builder.html#method.worker_threads) for more details.
|
||||
|
||||
Below is an example of how to adjust the number of worker threads.
|
||||
|
||||
@@ -13,6 +13,7 @@ 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:/var/public` to overwrite the default root directory. See [Docker examples](features/docker.md).
|
||||
|
||||
- Type `static-web-server --help` or see the [Command-line arguments](./configuration/command-line-arguments.md) section.
|
||||
|
||||
@@ -5,13 +5,13 @@
|
||||
</a>
|
||||
</div>
|
||||
|
||||
<h1 class="sws-title" align="center">Static Web Server</h1>
|
||||
<h1 class="sws-title" align="center">Static Web Server</h1>
|
||||
|
||||
<h4 align="center">
|
||||
<h4 align="center">
|
||||
A cross-platform, high-performance & asynchronous web server for static files serving
|
||||
</h4>
|
||||
|
||||
<div align="center">
|
||||
<div align="center">
|
||||
<a href="https://github.com/static-web-server/static-web-server/actions/workflows/devel.yml" title="devel ci"><img src="https://github.com/static-web-server/static-web-server/actions/workflows/devel.yml/badge.svg?branch=master"></a>
|
||||
<a href="https://hub.docker.com/r/joseluisq/static-web-server/" title="Docker Image Version (tag latest semver)"><img src="https://img.shields.io/docker/v/joseluisq/static-web-server/2"></a>
|
||||
<a href="https://hub.docker.com/r/joseluisq/static-web-server/tags" title="Docker Image Size (tag)"><img src="https://img.shields.io/docker/image-size/joseluisq/static-web-server/2"></a>
|
||||
@@ -59,7 +59,7 @@ Cross-platform and available for `Linux`, `macOS`, `Windows`, `FreeBSD`, `NetBSD
|
||||
- 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 a [Windows Service](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2003/cc783643(v=ws.10)).
|
||||
- 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.
|
||||
- Built-in HTTP to HTTPS redirect.
|
||||
|
||||
@@ -10,6 +10,7 @@ However, it still tries to keep the same principles of its `v1`: lightness and e
|
||||
This major `v2` has a few breaking changes. However, migration should not represent a problem.
|
||||
|
||||
!!! tip "Tip"
|
||||
|
||||
It is always worth recommending that you test a major server version upgrade like this first with your application(s) in a development environment or similar.
|
||||
|
||||
Please keep in mind the following changes in `v2`:
|
||||
|
||||
@@ -3,65 +3,79 @@
|
||||
Currently, only the following platforms/architectures are supported.
|
||||
|
||||
!!! tip "Docker tip"
|
||||
|
||||
For the list of Docker images supported see [Docker OS/Arch](./features/docker.md#osarch) page.
|
||||
|
||||
## Linux
|
||||
|
||||
#### x86
|
||||
- `i686-unknown-linux-gnu`
|
||||
- `i686-unknown-linux-musl`
|
||||
### x86
|
||||
|
||||
#### x86_64
|
||||
- `x86_64-unknown-linux-gnu`
|
||||
- `x86_64-unknown-linux-musl`
|
||||
- `i686-unknown-linux-gnu`
|
||||
- `i686-unknown-linux-musl`
|
||||
|
||||
#### ARM
|
||||
- `arm-unknown-linux-gnueabihf` (armv6)
|
||||
- `arm-unknown-linux-musleabihf` (armv6)
|
||||
- `armv7-unknown-linux-musleabihf` (armv7)
|
||||
### x86_64
|
||||
|
||||
#### ARM64
|
||||
- `aarch64-unknown-linux-musl`
|
||||
- `aarch64-unknown-linux-gnu`
|
||||
- `aarch64-linux-android`
|
||||
- `x86_64-unknown-linux-gnu`
|
||||
- `x86_64-unknown-linux-musl`
|
||||
|
||||
### ARM
|
||||
|
||||
- `arm-unknown-linux-gnueabihf` (armv6)
|
||||
- `arm-unknown-linux-musleabihf` (armv6)
|
||||
- `armv7-unknown-linux-musleabihf` (armv7)
|
||||
|
||||
### ARM64
|
||||
|
||||
- `aarch64-unknown-linux-musl`
|
||||
- `aarch64-unknown-linux-gnu`
|
||||
- `aarch64-linux-android`
|
||||
|
||||
## macOS
|
||||
|
||||
#### x86_64
|
||||
- `x86_64-apple-darwin`
|
||||
### x86_64
|
||||
|
||||
#### ARM64
|
||||
- `aarch64-apple-darwin`
|
||||
- `x86_64-apple-darwin`
|
||||
|
||||
### ARM64
|
||||
|
||||
- `aarch64-apple-darwin`
|
||||
|
||||
## Windows
|
||||
|
||||
#### x86
|
||||
- `i686-pc-windows-msvc`
|
||||
### x86
|
||||
|
||||
#### x86_64
|
||||
- `x86_64-pc-windows-msvc`
|
||||
- `x86_64-pc-windows-gnu`
|
||||
- `i686-pc-windows-msvc`
|
||||
|
||||
#### ARM64
|
||||
- `aarch64-pc-windows-msvc`
|
||||
### x86_64
|
||||
|
||||
- `x86_64-pc-windows-msvc`
|
||||
- `x86_64-pc-windows-gnu`
|
||||
|
||||
### ARM64
|
||||
|
||||
- `aarch64-pc-windows-msvc`
|
||||
|
||||
## FreeBSD
|
||||
|
||||
#### x86
|
||||
- `i686-unknown-freebsd`
|
||||
### x86
|
||||
|
||||
#### x86_64
|
||||
- `x86_64-unknown-freebsd`
|
||||
- `i686-unknown-freebsd`
|
||||
|
||||
### x86_64
|
||||
|
||||
- `x86_64-unknown-freebsd`
|
||||
|
||||
## NetBSD
|
||||
|
||||
#### x86_64
|
||||
- `x86_64-unknown-netbsd`
|
||||
### x86_64
|
||||
|
||||
- `x86_64-unknown-netbsd`
|
||||
|
||||
## Illumos
|
||||
|
||||
#### x86_64
|
||||
- `x86_64-unknown-illumos`
|
||||
### x86_64
|
||||
|
||||
- `x86_64-unknown-illumos`
|
||||
|
||||
## PowerPC
|
||||
|
||||
|
||||
Reference in New Issue
Block a user