From 48f7c6fbb7d592a18c5bd101433b00bce03f20f3 Mon Sep 17 00:00:00 2001 From: rishabhraj36 Date: Wed, 17 Jun 2026 15:33:16 +0530 Subject: [PATCH 1/2] docs: fix self-hosting quick start and first-run flow --- README.md | 7 +++++-- docs/guides/self-hosting.md | 23 ++++++++++++++++++++--- 2 files changed, 25 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index c62db167..fa88ebf7 100644 --- a/README.md +++ b/README.md @@ -115,11 +115,14 @@ uv tool install authsome Run a persistent daemon in Docker — no Python required on the host: ```bash +export AUTHSOME_POSTGRES_PASSWORD="$(openssl rand -hex 24)" +export AUTHSOME_MASTER_KEY="$(openssl rand -base64 32)" +export AUTHSOME_UI_SESSION_KEY="$(openssl rand -base64 32)" docker compose up -d -export AUTHSOME_BASE_URL=http://localhost:7998 +curl http://localhost:7998/health ``` -See the [self-hosting guide](docs/guides/self-hosting.md) for volume backup, TLS termination, and environment variable reference. +For a hosted daemon, set `AUTHSOME_BASE_URL` to the public HTTPS URL before starting the stack. See the [self-hosting guide](docs/guides/self-hosting.md) for first-run setup, volume backup, TLS termination, and environment variable reference. ## Quick Start diff --git a/docs/guides/self-hosting.md b/docs/guides/self-hosting.md index 6b10e3f5..9f472ea2 100644 --- a/docs/guides/self-hosting.md +++ b/docs/guides/self-hosting.md @@ -7,9 +7,9 @@ Run Authsome as a production service with Postgres for the server registries and The repository ships a compose file that wires the daemon to Postgres and Redis. Set a stable master key source first, then bring the stack up and verify the root health check. ```bash -export AUTHSOME_POSTGRES_PASSWORD='change-me-to-a-long-random-password' -export AUTHSOME_MASTER_KEY='base64-encoded-32-byte-key' -export AUTHSOME_UI_SESSION_KEY='base64-encoded-32-byte-key' +export AUTHSOME_POSTGRES_PASSWORD="$(openssl rand -hex 24)" +export AUTHSOME_MASTER_KEY="$(openssl rand -base64 32)" +export AUTHSOME_UI_SESSION_KEY="$(openssl rand -base64 32)" docker compose up -d curl http://localhost:7998/health ``` @@ -17,6 +17,22 @@ curl http://localhost:7998/health The daemon should answer on `http://localhost:7998`. The root `/health` endpoint is the container health target used by the image and by `docker compose`. The included compose file reads `AUTHSOME_MASTER_KEY` and `AUTHSOME_UI_SESSION_KEY` from the host environment. The `_FILE` variants are supported by Authsome itself, but if you want to use file-mounted secrets you must add those mounts and pass the file paths yourself in a custom compose file. +## First run + +After `/health` responds, point the CLI at the daemon and run onboarding: + +```bash +authsome onboard --base-url http://localhost:7998 +``` + +For a hosted deployment, use the same public URL that you configured as `AUTHSOME_BASE_URL`: + +```bash +authsome onboard --base-url https://authsome.example.com +``` + +Onboarding creates a local Identity, registers it with the daemon, and opens the browser claim flow. Complete the claim to bind the Identity to a Principal and its default Vault before running agent commands against the hosted daemon. + ## What this deployment does - Postgres stores the relational server registries: identities, principals, vaults, claims, and bindings. @@ -115,5 +131,6 @@ Because schema migrations run at startup, keep the Postgres and Redis services h - Use your platform secret store for `AUTHSOME_MASTER_KEY` and `AUTHSOME_UI_SESSION_KEY`. Only switch to `_FILE` variables if you have added real secret mounts and file paths to your own compose file. - Set `AUTHSOME_BASE_URL` to the public URL behind your reverse proxy. +- Terminate TLS at your reverse proxy, such as Caddy, nginx, Traefik, or your platform load balancer. The Authsome container serves plain HTTP on port `7998` inside the private network. - Keep `AUTHSOME_HOME` mounted only if you want local logs or fallback key material to persist. - Consider pointing `AUTHSOME_POSTHOG_API_KEY` at a real analytics key only if you have opted in to telemetry. From 57c8409e6eea9190e672531bad7b83b959e2bab8 Mon Sep 17 00:00:00 2001 From: rishabhraj36 Date: Wed, 17 Jun 2026 16:20:42 +0530 Subject: [PATCH 2/2] docs: updated self hosting docs --- docs/guides/self-hosting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/self-hosting.md b/docs/guides/self-hosting.md index 9f472ea2..d2ceeff9 100644 --- a/docs/guides/self-hosting.md +++ b/docs/guides/self-hosting.md @@ -31,7 +31,7 @@ For a hosted deployment, use the same public URL that you configured as `AUTHSOM authsome onboard --base-url https://authsome.example.com ``` -Onboarding creates a local Identity, registers it with the daemon, and opens the browser claim flow. Complete the claim to bind the Identity to a Principal and its default Vault before running agent commands against the hosted daemon. +Onboarding creates a local Identity, registers it with the daemon, and opens the browser claim flow. On a fresh hosted daemon the claim page first asks you to register an account with an email and password; that account becomes the Principal that owns the vault. On later runs you sign in to the same account instead of registering again. Completing the claim binds the Identity to that Principal and its default Vault, after which the daemon is ready for agent commands. ## What this deployment does