From e4228af63064281172c93cf7de0f82f935404eff Mon Sep 17 00:00:00 2001 From: Jose Quintana Date: Tue, 19 Jul 2022 02:40:57 +0200 Subject: [PATCH] docs: feature and config pages improvements [skip ci] --- docs/content/configuration/config-file.md | 11 ++++++++--- docs/content/configuration/environment-variables.md | 4 ++-- docs/content/features/cache-control-headers.md | 2 ++ docs/content/features/logging.md | 2 +- docs/content/features/security-headers.md | 4 +++- docs/content/features/windows-service.md | 14 ++++++++------ 6 files changed, 24 insertions(+), 13 deletions(-) diff --git a/docs/content/configuration/config-file.md b/docs/content/configuration/config-file.md index b633cc5..ff83cbb 100644 --- a/docs/content/configuration/config-file.md +++ b/docs/content/configuration/config-file.md @@ -2,7 +2,7 @@ **`SWS`** can be configured using a [TOML](https://toml.io/en/) file to adjust the general server features as well as other advanced ones. -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. +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. ## TOML File (Manifest) @@ -66,7 +66,12 @@ log-remote-address = false ### Windows Only -#### Run the web server as a Windows Service +#### Windows Service suport. +#### NOTE: this doesn't create a Windows Service per se, +#### instead, it just tells SWS to run in a Windows Service context, +#### so it's necessary to install the SWS Windows Service first +#### using the `static-web-server.exe -w config.toml install` command. +#### More details on https://sws.joseluisq.net/features/windows-service/ # windows-service = false @@ -80,7 +85,7 @@ log-remote-address = false The TOML `[general]` section allows adjusting the current options available via the CLI/ENV ones. -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. +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. diff --git a/docs/content/configuration/environment-variables.md b/docs/content/configuration/environment-variables.md index 30e60e6..a64e89d 100644 --- a/docs/content/configuration/environment-variables.md +++ b/docs/content/configuration/environment-variables.md @@ -4,7 +4,7 @@ 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. + - [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 `[::]`. @@ -79,4 +79,4 @@ It provides [The "Basic" HTTP Authentication Scheme](https://datatracker.ietf.or The following options and commands are Windows platform-specific. ### SERVER_WINDOWS_SERVICE -Run the web server as a Windows Service. See [more details](../features/windows-service.md). +Run the web server in a Windows Service context. See [more details](../features/windows-service.md). diff --git a/docs/content/features/cache-control-headers.md b/docs/content/features/cache-control-headers.md index cf12d85..43877d4 100644 --- a/docs/content/features/cache-control-headers.md +++ b/docs/content/features/cache-control-headers.md @@ -4,6 +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. + ## Cache-Control Max-Age Control headers are applied only to the following file types with the corresponding `max-age` values. diff --git a/docs/content/features/logging.md b/docs/content/features/logging.md index ab691ac..d9c8ed8 100644 --- a/docs/content/features/logging.md +++ b/docs/content/features/logging.md @@ -15,7 +15,7 @@ static-web-server \ ## Log Remote Addresses -SWS provides **Remote Address (IP)** logging for every request via an `INFO` log level. +SWS provides *Remote Address (IP)* logging for every request via an `INFO` log level. This feature is disabled by default and can be enabled by the boolean `--log-remote-address` option or the equivalent [SERVER_LOG_REMOTE_ADDRESS](./../configuration/environment-variables.md#server_log_remote_address) env. diff --git a/docs/content/features/security-headers.md b/docs/content/features/security-headers.md index 63b85f6..5e8ba4b 100644 --- a/docs/content/features/security-headers.md +++ b/docs/content/features/security-headers.md @@ -6,9 +6,11 @@ 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. + ## Headers included -The following headers are only included. +The following headers are included by default. - `Strict-Transport-Security: max-age=63072000; includeSubDomains; preload" (2 years max-age)` - `X-Frame-Options: DENY` diff --git a/docs/content/features/windows-service.md b/docs/content/features/windows-service.md index e8fecee..31f0f0c 100644 --- a/docs/content/features/windows-service.md +++ b/docs/content/features/windows-service.md @@ -1,22 +1,24 @@ # Windows Service -**`SWS`** can be also executed as a [Windows Service](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2003/cc783643(v=ws.10)). +**`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. 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](https://user-images.githubusercontent.com/1700322/169807572-d62a7bab-b596-4597-85f7-31a7c02aeefe.png) > _Static Web Server running as a Windows Service and displayed by 'services.msc' application._ -**Important notes** +## Important Notes -- This is a Windows platform-specific feature. It means the `--windows-service` argument and its env will not be present in Unix-like systems. -- Running SWS as a Windows service doesn't require enabling it via the [configuration file](../configuration/config-file.md) (`windows-service = true`) because it's already enabled during the service installation. +- This is a 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. ## Service privileges -To either install or uninstall the SWS Windows service requires *administrator* privileges, so make sure to open the terminal application as administrator or give your [Powershell](https://docs.microsoft.com/en-us/powershell/scripting/overview?view=powershell-7.2)](https://docs.microsoft.com/en-us/powershell/scripting/overview?view=powershell-7.2) session enough privileges otherwise you will get an `"Access is denied"` error. +To either install or uninstall the SWS Windows service requires *administrator* privileges, so make sure to open the terminal application as administrator or give your [Powershell](https://docs.microsoft.com/en-us/powershell/scripting/overview?view=powershell-7.2) session enough privileges otherwise you will get an `"Access is denied"` error. -We recommend a [Powershell](https://docs.microsoft.com/en-us/powershell/scripting/overview?view=powershell-7.2) session with administrator privileges. +We recommend a Powershell session with administrator privileges. ## Install the service -- libgit2 1.7.2