From ae0dcfdc939dc03197b34e33f3a4a6240b3c4012 Mon Sep 17 00:00:00 2001 From: Jose Quintana Date: Mon, 23 May 2022 15:15:53 +0200 Subject: [PATCH] docs: windows service page --- README.md | 1 + docs/content/configuration/command-line-arguments.md | 14 ++++++++++++++ docs/content/configuration/environment-variables.md | 7 +++++++ docs/content/features/windows-service.md | 143 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/content/index.md | 1 + docs/mkdocs.yml | 1 + 6 files changed, 167 insertions(+) create mode 100644 docs/content/features/windows-service.md diff --git a/README.md b/README.md index 67ee839..020c464 100644 --- a/README.md +++ b/README.md @@ -54,6 +54,7 @@ It's cross-platform and available for `Linux`, `macOS`, `Windows` and `FreeBSD` - 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. - Default and custom error pages. - 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. diff --git a/docs/content/configuration/command-line-arguments.md b/docs/content/configuration/command-line-arguments.md index e167887..0be9bcc 100644 --- a/docs/content/configuration/command-line-arguments.md +++ b/docs/content/configuration/command-line-arguments.md @@ -100,3 +100,17 @@ OPTIONS: 32,768 though it is advised to keep this value on the smaller side [env: SERVER_THREADS_MULTIPLIER=] [default: 1] ``` + +## Windows + +Following options and commands are Windows platform specific. + +``` + -s, --windows-service + Run the web server as a Windows Service [env: SERVER_WINDOWS_SERVICE=] [default: false] + +SUBCOMMANDS: + help Prints this message or the help of the given subcommand(s) + install Install a Windows Service for the web server + uninstall Uninstall the current Windows Service +``` diff --git a/docs/content/configuration/environment-variables.md b/docs/content/configuration/environment-variables.md index bab3034..04dbe09 100644 --- a/docs/content/configuration/environment-variables.md +++ b/docs/content/configuration/environment-variables.md @@ -71,3 +71,10 @@ Enable cache control headers for incoming requests based on a set of file types. ### 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). + +## Windows + +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). diff --git a/docs/content/features/windows-service.md b/docs/content/features/windows-service.md new file mode 100644 index 0000000..7523042 --- /dev/null +++ b/docs/content/features/windows-service.md @@ -0,0 +1,143 @@ +# 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)). + +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** + +- 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 to enable it via the [configuration file](../configuration/config-file.md) (`windows-service = true`) because it's already enabled during the service installation. + +## 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 to 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. + +## Install the service + +To install the SWS service use the `install` command along with a [configuration file](../configuration/config-file.md) for further SWS options customization. + +Make sure to provide a configuration file to run SWS service properly. In particular, configure the server `address`, `port` and `root` directory accordingly. +If not so then the service might not start. + +The following command will create the SWS service called `static-web-server` with a "`Static Web Server`" display name. + +```powershell +static-web-server.exe -w C:\Users\MyUser\config.toml install +# Windows Service (static-web-server) is installed successfully! +# Start the service typing: sc.exe start "static-web-server" (it requires administrator privileges) or using the 'services.msc' application. +``` + +## Interact with the service + +SWS doesn't provide a way to interact with Windows services directly. Instead, use the Windows built-in tools to interact with the SWS service once created. + +For that purpose you can use either the Windows [sc.exe](https://docs.microsoft.com/en-us/windows/win32/services/configuring-a-service-using-sc) or the [services.msc](https://docs.microsoft.com/en-us/windows/win32/services/services) application. + +For example, using `sc.exe` you can show the SWS service configuration used once installed. + +```powershell +sc.exe qc "static-web-server" +# [SC] QueryServiceConfig SUCCESS + +# SERVICE_NAME: static-web-server +# TYPE : 10 WIN32_OWN_PROCESS +# START_TYPE : 3 DEMAND_START +# ERROR_CONTROL : 1 NORMAL +# BINARY_PATH_NAME : C:\Users\MyUser\static-web-server.exe +# --windows-service=true +# --config-file=C:\Users\MyUser\config.toml +# LOAD_ORDER_GROUP : +# TAG : 0 +# DISPLAY_NAME : Static Web Server +# DEPENDENCIES : +# SERVICE_START_NAME : LocalSystem +``` + +Remember that alternatively you can also use the `services.msc` application if you prefer GUI service control. + +### Start + +To start the service use the following `sc.exe` command. + +```powershell +sc.exe start "static-web-server" +# SERVICE_NAME: static-web-server +# TYPE : 10 WIN32_OWN_PROCESS +# STATE : 2 START_PENDING +# (NOT_STOPPABLE, NOT_PAUSABLE, IGNORES_SHUTDOWN) +# WIN32_EXIT_CODE : 0 (0x0) +# SERVICE_EXIT_CODE : 0 (0x0) +# CHECKPOINT : 0x0 +# WAIT_HINT : 0x7d0 +# PID : 3068 +# FLAGS : +``` + +### Status + +To show the service status use the following `sc.exe` command. + +```powershell +sc.exe query "static-web-server" +# SERVICE_NAME: static-web-server +# TYPE : 10 WIN32_OWN_PROCESS +# STATE : 4 RUNNING +# (STOPPABLE, NOT_PAUSABLE, IGNORES_SHUTDOWN) +# WIN32_EXIT_CODE : 0 (0x0) +# SERVICE_EXIT_CODE : 0 (0x0) +# CHECKPOINT : 0x0 +# WAIT_HINT : 0x0 +``` + +### Stop + +To stop the service use the following `sc.exe` command. + +```powershell +sc.exe stop "static-web-server" +# SERVICE_NAME: static-web-server +# TYPE : 10 WIN32_OWN_PROCESS +# STATE : 3 STOP_PENDING +# (STOPPABLE, NOT_PAUSABLE, IGNORES_SHUTDOWN) +# WIN32_EXIT_CODE : 0 (0x0) +# SERVICE_EXIT_CODE : 0 (0x0) +# CHECKPOINT : 0x2 +# WAIT_HINT : 0xbb8 +``` + +After stopping the service you can also show its status. + +```powershell +sc.exe query "static-web-server" +# SERVICE_NAME: static-web-server +# TYPE : 10 WIN32_OWN_PROCESS +# STATE : 1 STOPPED +# WIN32_EXIT_CODE : 0 (0x0) +# SERVICE_EXIT_CODE : 0 (0x0) +# CHECKPOINT : 0x0 +# WAIT_HINT : 0x0 +``` + +## Uninstall the service + +To uninstall the SWS service just use the `uninstall` command. Note that the service should be first stopped before to uninstall it. + +```powershell +static-web-server.exe uninstall +# Windows Service (static-web-server) is uninstalled! +``` + +After uninstalling the service you can verify if removed. + +```powershell +sc.exe qc "static-web-server" +# [SC] OpenService FAILED 1060: +# +# The specified service does not exist as an installed service. +``` diff --git a/docs/content/index.md b/docs/content/index.md index 96e4138..aee440a 100644 --- a/docs/content/index.md +++ b/docs/content/index.md @@ -58,6 +58,7 @@ It's cross-platform and available for `Linux`, `macOS`, `Windows` and `FreeBSD` - 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. - Default and custom error pages. - 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. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 898d8f5..42e4759 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -139,6 +139,7 @@ nav: - 'Worker Threads Customization': 'features/worker-threads.md' - 'Error Pages': 'features/error-pages.md' - 'Custom HTTP Headers': 'features/custom-http-headers.md' + - 'Windows Service': 'features/windows-service.md' - 'Platforms & Architectures': 'platforms-architectures.md' - 'Migration from v1 to v2': 'migration.md' - 'Changelog v2 (latest stable)': 'https://github.com/joseluisq/static-web-server/blob/master/CHANGELOG.md' -- libgit2 1.7.2