# Installation and Configuration Guide: [Product name] [version]

> Complete guide for installing, configuring, verifying, upgrading and
> removing a software product. The structure follows the installation
> information for users described in ISO/IEC/IEEE 26514:2022. Replace every
> `[bracketed]` value and every row marked *Example*.

<!--
Guidance: How to use this template
- Test every command on a clean machine for each platform before you
  publish. Untested install steps are the main source of support tickets.
- Give the expected output after each important command so the reader
  knows whether to continue.
- Separate the minimum path (install, verify) from optional configuration
  so first-time readers are not overwhelmed.
- Keep version numbers in one place (Document control) and refer to them,
  so an upgrade of the guide is a small change.
-->

## Document control

<!-- Guidance: Identify the product version the guide installs. A guide that does not state its version will be followed for the wrong release. -->

| Field | Value |
|---|---|
| Document ID | [IG-PRODUCT-001] |
| Product and version | [Product name] [3.2.0] |
| Guide version | [0.1] |
| Status | [Draft / In review / Approved / Superseded] |
| Owner | [@docs-owner] |
| Approvers | [@release-manager], [@security-lead] |
| Classification | [Public / Customer confidential / Internal] |
| Last updated | YYYY-MM-DD |

### Approvals

| Role | Name | Decision | Date |
|---|---|---|---|
| Release manager | [@name] | [Approved / Rejected / Approved with comments] | YYYY-MM-DD |
| Platform engineer (tested installs) | [@name] | [Decision] | YYYY-MM-DD |
| Security reviewer | [@name] | [Decision] | YYYY-MM-DD |

## Revision history

<!-- Guidance: One row per published version; note which platforms were re-tested. -->

| Version | Date | Author | Change summary |
|---|---|---|---|
| 0.1 | YYYY-MM-DD | [@name] | Initial draft |
| 1.0 | YYYY-MM-DD | [@name] | *Example:* Tested on Ubuntu 24.04, Windows Server 2022, macOS 15 |
| 1.1 | YYYY-MM-DD | [@name] | *Example:* Added container install and TLS hardening steps |

## Contents

1. [Introduction](#1-introduction)
2. [System requirements](#2-system-requirements)
3. [Pre-installation checklist](#3-pre-installation-checklist)
4. [Installation](#4-installation)
5. [Post-installation verification](#5-post-installation-verification)
6. [Configuration](#6-configuration)
7. [Upgrade](#7-upgrade)
8. [Uninstall](#8-uninstall)
9. [Security hardening](#9-security-hardening)
10. [Troubleshooting](#10-troubleshooting)
11. [Support](#11-support)
12. [Appendix A. Glossary](#appendix-a-glossary)

## 1. Introduction

<!-- Guidance: State who should install the product, what they end up with, and how long it takes. Point to other guides for usage and administration. -->

### 1.1 Purpose and scope

This guide explains how to install [Product name] [3.2.0] on
[Linux, Windows, macOS and container platforms], verify the installation,
apply the initial configuration, upgrade from earlier versions and remove
the product. Day-to-day operation is covered in the [Administrator Guide];
end-user features in the [User Manual].

### 1.2 Audience

This guide is for system administrators and DevOps engineers who have
administrator or root access to the target host and are comfortable with
a command line, package managers and basic networking (ports, DNS, TLS).

### 1.3 Installation overview

A typical single-node installation takes [20] minutes. The flow is:

```mermaid
flowchart LR
    A["Check requirements"] --> B["Prepare host"]
    B --> C["Install package"]
    C --> D["Verify"]
    D --> E["Configure"]
    E --> F["Harden"]
```

### 1.4 Choosing an installation method

| Method | Best for | Not recommended when |
|---|---|---|
| Native package (APT, DNF, MSI) | Long-lived servers managed with standard OS tooling | You need several versions side by side |
| Container image | Teams already running Docker or Kubernetes; fast rollback | The host forbids container runtimes |
| Offline bundle | Air-gapped or regulated networks | The host has normal internet access |
| Homebrew (macOS) | Evaluation and local development | Production use |

If you are unsure, choose the native package on a supported Linux
distribution: it is the most widely tested path and the one support can
reproduce fastest.

### 1.5 Conventions

Commands prefixed with `$` run as a normal user; `#` means run as root or
with `sudo`. Values in `[brackets]` must be replaced. Notes marked
**Caution** describe a step that can cause data loss or downtime.

## 2. System requirements

<!-- Guidance: Give minimum and recommended values and say what you tested. "Recommended" should be the configuration you would run in production yourself. -->

### 2.1 Hardware

| Resource | Minimum | Recommended (production) | Notes |
|---|---|---|---|
| CPU | 2 vCPU | 4 vCPU | x86_64 or arm64 |
| Memory | 4 GB | 8 GB | Add 1 GB per 100 concurrent users |
| Disk | 20 GB | 100 GB SSD | Data directory grows about [2 GB per month] |
| Network | 100 Mbit/s | 1 Gbit/s | Static IP or stable DNS name |

### 2.2 Software

| Component | Supported versions | Tested version |
|---|---|---|
| Operating system | Ubuntu 22.04 / 24.04, RHEL 9, Windows Server 2022, macOS 14+ | [Ubuntu 24.04] |
| Database | PostgreSQL 15 to 17 | [16.4] |
| Runtime | [None, self-contained binary] | [n/a] |
| Container runtime (optional) | Docker 26+, Podman 5+ | [Docker 27.1] |
| Browser for admin console | Current Chrome, Edge, Firefox, Safari | [Chrome 129] |

### 2.3 Network

| Port | Protocol | Direction | Purpose |
|---|---|---|---|
| 443 | TCP (HTTPS) | Inbound | User and API traffic |
| 8443 | TCP (HTTPS) | Inbound, admin network only | Admin console |
| 5432 | TCP | Outbound to database | PostgreSQL |
| [Port] | [Protocol] | [Direction] | [Purpose] |

### 2.4 Accounts and permissions

- Root or administrator rights on the host for installation.
- A dedicated service account (created by the installer as `[appuser]`).
- A database role with `CREATE` rights on the target database.

## 3. Pre-installation checklist

<!-- Guidance: Everything the installer must have before starting. A missed item here means a half-finished install later. -->

| # | Item | Done |
|---|---|---|
| 1 | Host meets the minimum requirements in section 2 | [ ] |
| 2 | DNS name `[app.example.com]` resolves to the host | [ ] |
| 3 | TLS certificate and private key are available (PEM) | [ ] |
| 4 | Database is reachable and credentials are stored in a secret manager | [ ] |
| 5 | Firewall rules from 2.3 are in place | [ ] |
| 6 | Licence key received (`[XXXX-XXXX-XXXX]`) | [ ] |
| 7 | Backup of any existing installation taken (upgrades only) | [ ] |
| 8 | Maintenance window agreed with users (production only) | [ ] |

## 4. Installation

<!-- Guidance: One subsection per platform. Each step has one command and, where useful, the expected output. Never hide a required step inside a note. -->

### 4.1 Linux (Debian and Ubuntu)

1. Add the signing key and the package repository:

   ```bash
   curl -fsSL https://packages.example.com/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/example.gpg
   echo "deb [signed-by=/usr/share/keyrings/example.gpg] https://packages.example.com/apt stable main" | sudo tee /etc/apt/sources.list.d/example.list
   ```

2. Install the package:

   ```bash
   sudo apt-get update
   sudo apt-get install -y productname=3.2.0
   ```

   Expected output ends with `Setting up productname (3.2.0) ...`.

3. Enable and start the service:

   ```bash
   sudo systemctl enable --now productname
   ```

### 4.2 Linux (RHEL and compatible)

Run the following as a user with `sudo` rights. The repository file
contains the signing key URL, so `dnf` verifies the package signature
automatically; answer `y` when asked to import the key and check that
its fingerprint matches `[ABCD 1234 ...]` from the download page.

```bash
sudo dnf config-manager --add-repo https://packages.example.com/rpm/example.repo
sudo dnf install -y productname-3.2.0
sudo systemctl enable --now productname
```

### 4.3 Windows Server

1. Download `productname-3.2.0-x64.msi` and check its SHA-256 checksum
   against the value on the download page:

   ```powershell
   Get-FileHash .\productname-3.2.0-x64.msi -Algorithm SHA256
   ```

2. Run the installer silently with a log file:

   ```powershell
   msiexec /i productname-3.2.0-x64.msi /qn /l*v install.log INSTALLDIR="C:\Program Files\ProductName"
   ```

3. The service **ProductName** starts automatically. Confirm with
   `Get-Service ProductName`; the status is `Running`.

### 4.4 macOS

macOS is supported for evaluation and development only, not for
production. Install with Homebrew; the service then runs under your user
account and stores data in `$(brew --prefix)/var/productname`.

```bash
brew install example/tap/productname@3.2
brew services start productname
```

### 4.5 Container

```yaml
services:
  app:
    image: ghcr.io/example/productname:3.2.0
    ports: ["443:8443"]
    env_file: ./productname.env
    volumes: ["app-data:/var/lib/productname"]
    restart: unless-stopped
volumes:
  app-data: {}
```

Start with `docker compose up -d`. Pin the image tag; do not use `latest`
in production. Keep `productname.env` out of version control because it
holds the database URL and licence key.

### 4.6 Offline (air-gapped) installation

For hosts without internet access, download the offline bundle
`productname-3.2.0-offline.tar.gz` on a connected machine, verify its
checksum, and copy it to the target host with your approved transfer
method. Then run:

```bash
tar -xzf productname-3.2.0-offline.tar.gz
cd productname-3.2.0-offline
sudo ./install.sh --offline --license-file ./license.key
```

The script installs the bundled dependencies, creates the service account
and starts the service. Updates follow the same process with a new bundle.

### 4.7 Installation record

Record what you installed so that support and the next administrator can
reproduce it.

| Item | Value |
|---|---|
| Host name and IP | *Example:* app01.internal, 10.0.4.21 |
| Installation method | *Example:* APT package |
| Version installed | 3.2.0 |
| Installed by and date | [@name], YYYY-MM-DD |
| Data directory | `/var/lib/productname` |
| Configuration file | `/etc/productname/config.yaml` |
| Deviations from this guide | [None / description and reason] |

## 5. Post-installation verification

<!-- Guidance: Give checks with an unambiguous pass condition. The reader should finish this section knowing the install works, not hoping it does. -->

| # | Check | Command or action | Pass condition |
|---|---|---|---|
| V-01 | Service is running | `systemctl status productname` | `active (running)` |
| V-02 | Version is correct | `productname --version` | `3.2.0` |
| V-03 | Health endpoint answers | `curl -fsS https://[host]/healthz` | `{"status":"ok"}` |
| V-04 | Database connection | Admin console > System > Database | Status **Connected** |
| V-05 | Admin sign-in | Open `https://[host]:8443` | Dashboard loads without errors |
| V-06 | Logs are clean | `journalctl -u productname --since "10 min ago"` | No `ERROR` lines |

## 6. Configuration

<!-- Guidance: List every parameter an installer may need to change, with type, default and allowed range. Say which changes need a restart. Full option lists belong in the Configuration Reference; link to it. -->

### 6.1 Configuration file

The main file is `/etc/productname/config.yaml` (Windows:
`C:\ProgramData\ProductName\config.yaml`). Environment variables override
file values; see the [Configuration Reference] for precedence.

```yaml
server:
  public_url: https://app.example.com
  port: 8443
database:
  url: postgres://appuser@db.internal:5432/productname
  pool_size: 20
logging:
  level: info
```

### 6.2 Parameters

| Parameter | Type | Default | Allowed range | Restart needed | Description |
|---|---|---|---|---|---|
| `server.port` | integer | 8443 | 1024 to 65535 | Yes | Port the service listens on |
| `server.public_url` | URL | none (required) | HTTPS URL | Yes | Address users reach; used in links and emails |
| `database.pool_size` | integer | 20 | 5 to 200 | Yes | Maximum open database connections |
| `logging.level` | enum | info | debug, info, warn, error | No | Log verbosity |
| `session.timeout_minutes` | integer | 720 | 15 to 10080 | No | Idle time before sign-out |
| [parameter] | [type] | [default] | [range] | [Yes / No] | [Description] |

Size the database pool from expected concurrency, for example
$\text{pool\_size} \approx \text{peak requests per second} \times \text{mean query time in seconds} \times 2$.

### 6.3 Apply and validate changes

```bash
sudo productname config validate
sudo systemctl restart productname
```

`config validate` prints `Configuration OK` or the first invalid key with
its line number.

### 6.4 Environment-specific settings

Keep one configuration per environment and change only the values that
must differ. A typical split looks like this:

| Parameter | Development | Staging | Production |
|---|---|---|---|
| `logging.level` | debug | info | info |
| `database.pool_size` | 5 | 20 | 50 |
| `session.timeout_minutes` | 10080 | 720 | 480 |
| `server.public_url` | `https://localhost:8443` | `https://staging.example.com` | `https://app.example.com` |

Store these files in version control without secrets, and inject secrets
at deploy time from the secret manager.

## 7. Upgrade

<!-- Guidance: State supported upgrade paths, the backup step, and how to roll back. Upgrades that skip versions often need an intermediate step. -->

| From version | To 3.2.0 | Notes |
|---|---|---|
| 3.0.x, 3.1.x | Direct | Database migration runs automatically on start |
| 2.x | Via 3.0.4 | Upgrade to 3.0.4 first, then to 3.2.0 |
| 1.x | Not supported | Export data and reinstall |

> **Caution:** Back up the database and `/etc/productname` before upgrading.

```bash
sudo productname backup create --output /var/backups/productname-pre-3.2.0.tar.gz
sudo apt-get install -y productname=3.2.0
sudo productname --version
```

Upgrade checklist:

1. Read the release notes for every version between yours and 3.2.0,
   especially breaking changes and deprecated parameters.
2. Run the upgrade on staging first with a copy of production data.
3. Take the backup shown above and confirm the archive is readable.
4. Upgrade, then repeat the checks in section 5.
5. Watch error rates and logs for one hour before closing the window.

Rollback: reinstall the previous package version and restore the backup
with `productname backup restore [file]`. Rollback after users have
written new data loses that data; agree the cut-off with the service owner.

## 8. Uninstall

<!-- Guidance: Separate removing the software from deleting the data, and make the data deletion an explicit, warned step. -->

1. Stop and disable the service: `sudo systemctl disable --now productname`.
2. Remove the package: `sudo apt-get remove productname` (Windows:
   **Settings > Apps > ProductName > Uninstall**).
3. Optional, irreversible: delete data and configuration.

   > **Caution:** This permanently deletes all application data.

   ```bash
   sudo rm -rf /var/lib/productname /etc/productname
   ```

4. Drop the database and remove the service account if no longer needed.

## 9. Security hardening

<!-- Guidance: List the secure-by-default settings the installer must confirm or change before going live. Each item should be checkable. -->

| ID | Control | How to apply | Verify |
|---|---|---|---|
| SH-01 | TLS 1.2+ only, strong ciphers | `server.tls.min_version: "1.2"` | `nmap --script ssl-enum-ciphers -p 443 [host]` |
| SH-02 | Admin console on internal network only | Firewall rule on port 8443 | External scan shows 8443 closed |
| SH-03 | Default admin password changed | Admin console > Users | Sign-in with default fails |
| SH-04 | Secrets outside config file | Use `DATABASE_URL` from secret manager | `grep password config.yaml` returns nothing |
| SH-05 | Service runs as non-root | Installer creates `appuser` | `ps -o user= -C productname` shows `appuser` |
| SH-06 | Automatic security updates for the OS | `unattended-upgrades` enabled | Package log shows recent updates |

## 10. Troubleshooting

<!-- Guidance: Symptoms as the installer sees them, with the log line to look for and the fix. -->

| Symptom | Where to look | Cause | Fix |
|---|---|---|---|
| *Example:* Service fails to start | `journalctl -u productname` shows `bind: address already in use` | Port 8443 taken | Change `server.port` or stop the other service |
| *Example:* Health check returns 503 | Log shows `database unreachable` | Wrong host or firewall | Test with `psql`; open port 5432 |
| *Example:* MSI rolls back on Windows | `install.log` shows error 1603 | Missing admin rights or pending reboot | Run as administrator after rebooting |
| [Symptom] | [Log location] | [Cause] | [Fix] |

## 11. Support

<!-- Guidance: Tell the reader what to collect before contacting support so the first reply can help. -->

Before contacting support, run `productname support-bundle` and attach the
generated archive (it excludes secrets). Include the product version,
operating system, installation method and the step that failed.

| Channel | Address | Hours |
|---|---|---|
| Support portal | [https://support.example.com] | [24x7 for severity 1] |
| Email | [support@example.com] | [Business days, 09:00 to 18:00 UTC] |
| Release notes and known issues | [https://docs.example.com/releases] | Continuous |

## Appendix A. Glossary

<!-- Guidance: Define only terms the installer may not know or that this product uses in a specific sense. -->

| Term | Meaning in this guide |
|---|---|
| Service account | Operating system user that runs the product with minimum rights |
| Health endpoint | URL that reports whether the service and its dependencies work |
| Offline bundle | Archive containing the product and all dependencies for hosts without internet |
| Rollback | Returning to the previous version and data after a failed upgrade |
| [Term] | [Meaning] |

## Standard and licence note

Structure aligned with ISO/IEC/IEEE 26514:2022, *Systems and software
engineering: Design and development of information for users*, for the
installation, configuration and maintenance information given to users.
This template is original text written for this collection and
reproduces no text from the standard; obtain the standard from ISO, IEC
or IEEE for its normative requirements. Template licence: MIT.