Add new installation guide and some other minor changes

Author: LinddritAliu

docusaurus/testbench-defect-service/cli.md

@@ -5,7 +5,7 @@ title: CLI reference
 
 # CLI Reference
 
-The Testbench Defect Service is controlled entirely from the command line. The main entry point is:
+The TestBench Defect Service is controlled entirely from the command line. The main entry point is:
 
 ```bash
 testbench-defect-service [COMMAND] [OPTIONS]

docusaurus/testbench-defect-service/clients/custom-client.md

@@ -5,7 +5,7 @@ title: Custom Client
 
 # Custom Client
 
-The Testbench Defect Service supports custom backends through a pluggable client interface. Any Python class that extends `AbstractDefectClient` and implements the required methods can be used as a drop-in replacement for the built-in JSONL or Jira clients.
+The TestBench Defect Service supports custom backends through a pluggable client interface. Any Python class that extends `AbstractDefectClient` and implements the required methods can be used as a drop-in replacement for the built-in JSONL or Jira clients.
 
 Typical use cases:
 

docusaurus/testbench-defect-service/clients/index.md

@@ -4,7 +4,7 @@ title: Clients
 ---
 # Clients
 
-The Testbench Defect Service uses a pluggable client architecture. A **client** is a Python class that connects the service's generic defect API to a specific backend — such as a file system or a project management tool.
+The TestBench Defect Service uses a pluggable client architecture. A **client** is a Python class that connects the service's generic defect API to a specific backend — such as a file system or a project management tool.
 
 ---
 

docusaurus/testbench-defect-service/clients/jira-client.md

@@ -5,7 +5,7 @@ title: Jira Client
 
 # Jira Client
 
-The Jira client integrates the Testbench Defect Service with [Jira Cloud](https://www.atlassian.com/software/jira) and [Jira Data Center / Server](https://www.atlassian.com/enterprise/data-center/jira). It maps TestBench defect operations to Jira issue operations using the official `jira` Python library.
+The Jira client integrates the TestBench Defect Service with [Jira Cloud](https://www.atlassian.com/software/jira) and [Jira Data Center / Server](https://www.atlassian.com/enterprise/data-center/jira). It maps TestBench defect operations to Jira issue operations using the official `jira` Python library.
 
 ---
 
@@ -23,7 +23,7 @@ When the Jira client is active, defect CRUD operations performed by TestBench ar
 
 ---
 
-## Prerequisites
+## Requirements
 
 The Jira client is an **optional** component. Install it with:
 

docusaurus/testbench-defect-service/clients/jsonl-client.md

@@ -4,7 +4,7 @@ title: JSONL Client
 ---
 # JSONL Client
 
-The JSONL client is the default, zero-dependency backend for the Testbench Defect Service. It stores defects as [newline-delimited JSON](https://jsonlines.org) (`.jsonl`) files on the local file system.
+The JSONL client is the default, zero-dependency backend for the TestBench Defect Service. It stores defects as [newline-delimited JSON](https://jsonlines.org) (`.jsonl`) files on the local file system.
 
 ---
 

docusaurus/testbench-defect-service/configuration.md

@@ -5,7 +5,7 @@ title: Configuration
 
 # Configuration
 
-The Testbench Defect Service is configured through a single TOML file (`config.toml` in the working directory by default). This page documents every available option.
+The TestBench Defect Service is configured through a single TOML file (`config.toml` in the working directory by default). This page documents every available option.
 
 :::tip
 Use the CLI wizards instead of editing the file by hand — they validate your input and prevent syntax errors:
@@ -115,6 +115,27 @@ ssl_ca_cert = "certs/ca.crt"   # optional — enables mTLS
 
 ---
 
+## Server Process Settings
+
+**`[testbench-defect-service.server]`**
+
+Controls how Sanic spawns and manages its worker process. In most cases you can leave this section out and rely on the defaults.
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `single_process` | boolean | `true` | Run in single-process mode. Required when using mTLS. Set to `false` to enable multi-worker throughput. |
+| `keep_alive_timeout` | integer | `5` | Seconds an idle HTTP keep-alive connection is held open waiting for the next request before being closed. A shorter value reduces the number of open connections that can delay shutdown. |
+| `run_kwargs` | table | `{}` | Raw keyword arguments forwarded verbatim to Sanic's `run()` call. Use for advanced Sanic tuning not exposed by other settings. |
+
+```toml
+[testbench-defect-service.server]
+single_process = false
+keep_alive_timeout = 3
+run_kwargs = { workers = 4 }
+```
+
+---
+
 ## Logging
 
 ### Console
@@ -194,20 +215,20 @@ Each `start` command loads exactly one config file and binds to one port. To ser
 `jsonl_config.toml`
 ```toml
 [testbench-defect-service]
-reader_class = "testbench_defect_service.clients.JsonlDefectClient"
+client_class = "testbench_defect_service.clients.JsonlDefectClient"
 port = 8030
 
-[testbench-defect-service.reader_config]
+[testbench-defect-service.client_config]
 # Jsonl-specific settings ...
 ```
 
 `jira_config.toml`
 ```toml
 [testbench-defect-service]
-reader_class = "testbench_defect_service.clients.JiraDefectClient"
+client_class = "testbench_defect_service.clients.JiraDefectClient"
 port = 8031
 
-[testbench-defect-service.reader_config]
+[testbench-defect-service.client_config]
 # Jira-specific settings ...
 ```
 

docusaurus/testbench-defect-service/getting-started/installation.md

@@ -2,107 +2,156 @@
 sidebar_position: 1
 title: Installation
 ---
+
 # Installation
 
-## Requirements
+There are two options depending on whether you want to install Python or not:
+
+- **[Option 1: Ready-to-use executable](#option-1-ready-to-use-executable)** (**No Python required**. Download a zip, extract, run. Best for Windows service deployments.)
+- **[Option 2: Install with Python](#option-2-install-with-python)** (For users who have Python or are installing it. Managed via pip.)
 
-- **Python 3.10 or higher** — [Download Python](https://www.python.org/downloads/)
-- **pip** — included with Python 3.4+; verify with `pip --version`
 ---
 
-## Option 1: Install from PyPI *(Recommended)*
+## Option 1: Ready-to-use executable
 
-Install the latest release directly from [PyPI](https://pypi.org/project/testbench-defect-service/):
+The executable is a self-contained zip archive. No Python, no pip, no virtual environment needed. Both clients (JSONL and Jira) are included.
 
-```bash
-pip install testbench-defect-service
+**1. Download the zip**
+
+Either use the zip you received directly, or download it from the [GitHub releases page](https://github.com/imbus/testbench-defect-service/releases) — expand **Assets** and pick the file for your platform (e.g. `testbench-defect-service-x.y.z-win_amd64.zip`).
+
+**2. Extract to a permanent location**
+
+Unzip to a folder you won't move later, for example `C:\TestBenchDefectService\`:
+
+```
+C:\TestBenchDefectService\
+  testbench-defect-service.exe
+  <support files>
 ```
 
-To include Jira support:
+**3. Verify**
 
-```bash
-pip install "testbench-defect-service[jira]"
+```cmd
+C:\TestBenchDefectService\testbench-defect-service.exe --version
 ```
 
 ---
 
-## Option 2: Install from a wheel package *(Offline)*
+## Option 2: Install with Python
 
-Use this option when installing on a machine without internet access, for example when you received an offline installation package (`.zip`).
+Use this option if you have Python installed or are about to install it.
 
-**1. Extract the zip:**
+### Requirements
 
-Unzip the provided package to a local folder, e.g. `C:\install\`:
+- **Python 3.10–3.14** — 3.13 recommended ([download](https://www.python.org/downloads/))
+- **pip** (included with Python)
 
+### Set up a virtual environment
+
+:::note
+For [From source](#from-source-developers): skip this step and create the virtual environment inside the cloned repository instead (shown there).
+:::
+
+A virtual environment keeps the installation isolated and provides a stable, predictable path to the executable. Navigate to the directory where you want the service to live, then run:
+
+```bash
+python -m venv .venv
 ```
-C:\install\
-  testbench_defect_service-x.y.z-py3-none-any.whl
-  <dependency wheels ...>
+
+```bash
+# Windows
+.venv\Scripts\activate
+
+# Linux / macOS
+source .venv/bin/activate
 ```
 
-**2. Install from the local folder:**
+---
+
+### From PyPI *(online, recommended)*
 
 ```bash
-pip install --no-index --find-links "C:\install" testbench-defect-service
+pip install testbench-defect-service
 ```
 
-To include optional extras, add them as usual — pip will resolve them from the local folder:
+The base install includes the [JSONL client](../clients/jsonl-client.md). Add extras for other clients:
 
+| Client | Install command |
+|--------|-----------------|
+| [JSONL](../clients/jsonl-client.md) *(default)* | `pip install testbench-defect-service` |
+| [Jira](../clients/jira-client.md) | `pip install testbench-defect-service[jira]` |
+
+Verify:
 ```bash
-pip install --no-index --find-links "C:\install" testbench-defect-service[jira]
+testbench-defect-service --version
 ```
 
-:::note
-The offline package is platform- and Python-version-specific. Make sure you use the package that matches your system (e.g. `win_amd64`, `py310`).
-:::
-
 ---
 
-## Option 3: Install from Source *(Development)*
+### From a wheel file *(offline)*
 
-Clone the repository and install in editable mode:
+Use this if you received a `.whl` file or downloaded one from the [GitHub releases page](https://github.com/imbus/testbench-defect-service/releases) (look for `testbench_defect_service-x.y.z-py3-none-any.whl` in the Assets).
 
 ```bash
-git clone https://github.com/imbus/testbench-defect-service.git
-cd defect-service-python
-pip install -e ".[dev,jira]"
+pip install testbench_defect_service-x.y.z-py3-none-any.whl
 ```
 
-Available extras:
+With optional extras:
+
+```bash
+pip install "testbench_defect_service-x.y.z-py3-none-any.whl[jira]"
+```
 
-| Extra | Packages installed | When to use |
-|---|---|---|
-| *(default)* | — | Uses JSONL files as data source; included in base install |
-| `jira` | `jira`, `beautifulsoup4` | Required for Jira backend |
-| `dev` | `ruff`, `pre-commit`, `invoke`, `mypy`, `flit`, `wheel`, `robotframework`, `pytest`, … | Development, linting, and testing |
+Verify:
 
----
+```bash
+testbench-defect-service --version
+```
+
+:::note Fully offline install
+By default pip still fetches dependencies from PyPI. To install on a machine with no internet access:
+
+**On a machine with internet access**, download the wheel and all its dependencies into a local folder:
+
+```bash
+pip download "testbench_defect_service-x.y.z-py3-none-any.whl[jira]" -d ./wheels
+```
+
+This saves every required wheel into `./wheels/`. Copy that folder together with the `.whl` file to the target machine.
+
+**On the target machine**, install entirely from the local folder:
+
+```bash
+pip install --no-index --find-links ./wheels "testbench_defect_service-x.y.z-py3-none-any.whl[jira]"
+```
+:::
 
-## Verifying the Installation
+---
 
-After installation, verify the CLI is available:
+### From source *(developers)*
 
 ```bash
-testbench-defect-service --help
+git clone https://github.com/imbus/testbench-defect-service.git
+cd testbench-defect-service
 ```
 
-Expected output:
+Create and activate the virtual environment inside the cloned repository. See [Set up a virtual environment](#set-up-a-virtual-environment).
 
+Install with all clients and development dependencies:
+
+```bash
+pip install -e .[jira,dev]
 ```
-Usage: testbench-defect-service [OPTIONS] COMMAND [ARGS]...
 
-Options:
-  --help  Show this message and exit.
+Verify:
 
-Commands:
-  configure        Create or update the service configuration interactively.
-  init             Initialize a new service configuration interactively.
-  set-credentials  Set the service username and password.
-  start            Start the defect service.
+```bash
+testbench-defect-service --version
 ```
 
 ---
 
-## Next Step
+## Next steps
 
-→ [Quick Start](quickstart.md)
+Head to the [Quickstart](quickstart.md) to configure and start the service.

docusaurus/testbench-defect-service/getting-started/quickstart.md

@@ -49,7 +49,7 @@ curl -u "admin:mypassword" http://127.0.0.1:8030/projects
 
 ### 1. Install optional dependencies (if needed)
 
-Choose the extras for your backend. See [Installation](installation.md#available-extras) for available options.
+Choose the extras for your backend. See [Installation](installation.md#from-pypi-online-recommended) for available options.
 
 ### 2. Create `config.toml`
 
@@ -99,9 +99,19 @@ curl -u "admin:mypassword" http://127.0.0.1:8030/projects
 Use `testbench-defect-service configure` to update specific parts of your configuration later without starting from scratch.
 :::
 
+## API documentation endpoints
+
+Once the service is running, these endpoints are available without authentication:
+
+| Endpoint | Description |
+|----------|-------------|
+| `/docs` | Interactive Swagger UI |
+| `/docs/openapi.json` | OpenAPI specification (JSON) |
+| `/openapi.yaml` | OpenAPI specification (YAML) |
+
 ## Next steps
 
 - Customize the service → [Configuration](../configuration.md)
 - Learn about clients → [Clients overview](../clients/index.md)
 - Connect TestBench → [TestBench Integration](../testbench-integration.md)
-- Explore all CLI options → [CLI commands](../cli.md)
+- Explore all CLI options → [CLI reference](../cli.md)

docusaurus/testbench-defect-service/intro.md

@@ -5,7 +5,7 @@ title: Introduction
 
 # Introduction
 
-[**Testbench Defect Service**](https://github.com/imbus/testbench-defect-service) is a lightweight, asynchronous REST API service that acts as a bridge between [Imbus TestBench](https://www.testbench.com/de/) and external defect tracking systems.
+[**TestBench Defect Service**](https://github.com/imbus/testbench-defect-service) is a lightweight, asynchronous REST API service that acts as a bridge between [Imbus TestBench](https://www.testbench.com/de/) and external defect tracking systems.
 
 ## What It Does
 
@@ -56,4 +56,10 @@ The service is built on [Sanic](https://sanic.dev), a Python async web framework
 
 The backend is selected via the `client_class` configuration key and can be switched at any time by updating the config file and restarting the service.
 
+## Where to go next
+
+- **New here?** Start with the [Installation](getting-started/installation.md) and [Quickstart](getting-started/quickstart.md) guides.
+- **Configuring the service?** See the [Configuration](configuration.md) page.
+- **Choosing a client?** Check the [Clients overview](clients/index.md), then dive into [JSONL](clients/jsonl-client.md) or [Jira](clients/jira-client.md).
+- **CLI reference?** See the [CLI reference](cli.md) page.
 

docusaurus/testbench-defect-service/testbench-integration.md

@@ -4,7 +4,7 @@ title: TestBench Integration
 ---
 # TestBench Integration
 
-This page explains how to connect TestBench to the running Testbench Defect Service.
+This page explains how to connect TestBench to the running TestBench Defect Service.
 
 ---
 
@@ -14,9 +14,9 @@ TestBench communicates with the Defect Service through the **DMProxy** (Defect M
 
 ---
 
-## Prerequisites
+## Requirements
 
-- Testbench Defect Service is installed and running (see [Quick Start](getting-started/quickstart)).
+- TestBench Defect Service is installed and running (see [Quick Start](getting-started/quickstart)).
 - You know the host and port the service is listening on.
 - You have set credentials with `testbench-defect-service set-credentials`.