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 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.

1. Get the compose file#

The image is published on Docker Hub as selfdochub/selfdochub. You only need the compose file and the example settings, not the whole repository:

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:

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 can be added to .env.

3. Start#

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:

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#

Last updated: