Quick Start

This page gets a local SelfDocHub instance running, creates the first administrator and publishes one specification. Use it to evaluate the product; for a production server follow Installation.

Prerequisites#

  • Docker with the Docker Compose plugin and curl.

1. Run#

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 image comes from Docker Hub (selfdochub/selfdochub); nothing is built locally.

Edit .env: set DOCS_HUB_SESSION_SECRET (for example openssl rand -base64 32) and set DOCS_HUB_BASE_URL to http://localhost:8080 for a local trial. Then start:

docker compose pull
docker compose up -d

The server listens on 127.0.0.1:8080 and keeps its data in the docs-hub-data volume. To change the published port, edit ports in docker-compose.yml.

Check that it is alive:

curl http://localhost:8080/healthz

2. Create the first administrator#

Users are not seeded from files. Create the first administrator with the command line:

docker compose exec docs-hub docs-hub --create-user \
  --user-login admin --user-password change-me-admin-password --user-role admin

3. Register a service#

A service is registered once. Its upload token is printed a single time, and only a hash is stored:

docker compose exec docs-hub docs-hub --register-service \
  --service-slug billing-api --service-name "Billing API"

You can also register services in the web UI (administrators only). See Services and Groups.

4. Install a license#

Without a valid license the server still starts, and you can sign in and open the License page. Every other API route answers 402 Payment Required. Get the installation's device ID and request a license:

docker compose exec docs-hub docs-hub --print-device-id

Then upload the resulting license.json on the License page. See License and Tiers.

5. Publish a specification#

curl -X POST http://localhost:8080/api/v1/services/billing-api/spec \
  -H "Authorization: Bearer $DOCS_UPLOAD_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @openapi.json

Use --data-binary, not -d: -d strips newlines and corrupts YAML and GraphQL bodies.

Open http://localhost:8080 and sign in. The service appears in the left menu.

Note: Before exposing an instance to other people, replace the default session secret. See Configuration Reference.

Next steps#

Last updated: