# Installation

This page describes how to deploy SelfDocHub on a server with Docker. SelfDocHub is a single static binary with the web UI embedded, and it needs no database server. The Docker image is published on Docker Hub, and the compose file and settings live in the [self-doc-hub-image](https://github.com/SelfDocHub/self-doc-hub-image) repository.

> **Warning:** Run exactly one container per data volume. Storage has no cross-instance locking, so two processes writing to the same data can corrupt it.

## Prerequisites

- A Linux server with Docker and the Docker Compose plugin.
- For a real TLS certificate, a domain name pointed at the server.
- A license file for the installation. See [License and Tiers](/documentation/license).

## 1. Get the compose file

The image is published on Docker Hub as [selfdochub/selfdochub](https://hub.docker.com/r/selfdochub/selfdochub). You only need the compose file and the example settings, not the whole repository:

```bash
mkdir selfdochub && cd selfdochub
curl -fsSLO https://raw.githubusercontent.com/SelfDocHub/self-doc-hub-image/main/docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/SelfDocHub/self-doc-hub-image/main/.env.example -o .env
```

The compose file pins a release tag of the image, so the version you run never changes by itself.

## 2. Configure

`.env.example` contains only the required settings:

```bash
DOCS_HUB_BASE_URL=https://docs.example.com
DOCS_HUB_SESSION_SECRET=<generate with: openssl rand -base64 32>
```

- `DOCS_HUB_BASE_URL` must be the public HTTPS address. It is used to build links and is the base of the SSO redirect URI.
- `DOCS_HUB_SESSION_SECRET` signs session tokens. Anyone who knows it can forge a session, so use a random value. It also derives the key that encrypts two-factor secrets, SSO client secrets and notification secrets, so keep it stable.

Leave the data directory and listen address as the `Dockerfile` sets them (`/data` and `:8080`). Any other setting from the [Configuration Reference](/documentation/configuration) can be added to `.env`.

## 3. Start

```bash
docker compose pull
docker compose up -d
docker compose logs -f docs-hub
```

The image contains only the `docs-hub` binary. All state is stored in the `docs-hub-data` Docker volume. The container health check polls `GET /healthz`.

## 4. Put Nginx with TLS in front

The container publishes its port only to `127.0.0.1:8080`, so put a reverse proxy on the host:

```nginx
server {
    listen 443 ssl http2;
    server_name docs.example.com;

    ssl_certificate     /etc/letsencrypt/live/docs.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/docs.example.com/privkey.pem;

    client_max_body_size 12m;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }
}
```

`client_max_body_size` must be at least `DOCS_HUB_MAX_SPEC_BYTES` (10 MiB by default), otherwise Nginx rejects large uploads before they reach SelfDocHub. Serve the application over HTTPS: some browser features, such as the clipboard API used by the copy buttons, only work in a secure context. Open only ports 80 and 443 in the firewall.

## First run

Run the command-line subcommands through `docker compose exec`:

1. Create the first administrator: `docker compose exec docs-hub docs-hub --create-user --user-login admin --user-password <password> --user-role admin`
2. Print the device ID: `docker compose exec docs-hub docs-hub --print-device-id`. Send it to whoever issues your license, then upload `license.json` on the License page.
3. Verify: `curl https://docs.example.com/healthz`

## Next steps

- [Configuration Reference](/documentation/configuration)
- [License and Tiers](/documentation/license)
- [Upgrading and Backups](/documentation/upgrading-and-backups)

---
Source: https://selfdochub.com/documentation/installation
