Skip to content

chore: update dockerfile compose and self hosting guide for hosted authsome#445

Merged
manojbajaj95 merged 2 commits into
mainfrom
423-chore-update-dockerfile-compose-and-self-hosting-guide-for-hosted-authsome
Jun 17, 2026
Merged

chore: update dockerfile compose and self hosting guide for hosted authsome#445
manojbajaj95 merged 2 commits into
mainfrom
423-chore-update-dockerfile-compose-and-self-hosting-guide-for-hosted-authsome

Conversation

@rishabhraj36

Copy link
Copy Markdown
Collaborator

Description

Make the self-hosting documentation truthful and runnable so a new operator can stand up a hosted Authsome stack end-to-end without hitting undocumented requirements.

  • README self-hosting section: the quick start now exports the three secrets docker-compose.yml hard-requires (AUTHSOME_POSTGRES_PASSWORD, AUTHSOME_MASTER_KEY, AUTHSOME_UI_SESSION_KEY) and verifies /health, instead of a bare docker compose up -d that failed immediately on the missing ${VAR:?} secrets.
  • Postgres password generator: use openssl rand -hex 24 rather than -base64, because base64 output can contain / or +, which corrupts the AUTHSOME_DATABASE_URL DSN and breaks daemon boot.
  • First-run flow: added a "First run" section to the self-hosting guide documenting authsome onboard --base-url, the browser account registration (email + password → Principal), and the identity claim that binds the Identity to its default Vault.
  • Production hardening: added a TLS-termination / reverse-proxy note (Caddy, nginx, Traefik) clarifying the container serves plain HTTP on 7998 behind the proxy.

No application code, Dockerfile, or compose changes — verification confirmed those are already correct and in sync.

Motivation and Context

docker-compose.yml hard-requires three secrets via ${VAR:?}, but the README told operators to just run docker compose up -d, so a first-time self-hoster hit an immediate failure. The base64 Postgres password was an additional latent bug that would intermittently break boot via DSN parsing. The issue also asked for the hosted first-run/init flow (account registration + identity claim) to be documented.

Closes #423 (GHCR image publishing — phrased as "Consider" and not part of the acceptance criteria — is intentionally left for a separate follow-up so the release-pipeline permission change can be reviewed on its own).

How Has This Been Tested?

  • Live docker compose up -d --build with secrets generated exactly as documented: all three containers (authsome, postgres:16-alpine, redis:7-alpine) came up healthy, and curl http://localhost:7998/health returned HTTP 200 with store_backend: postgres. Torn down cleanly with docker compose down -v.
  • DSN parsing: confirmed an -hex password yields a valid postgresql://… URL (correct host/port/password), whereas a base64 password with / makes Python's URL parser misread the host and crash on the port — proving the fix.
  • Verified no Dockerfile/compose drift: UI embed path (src/authsome/ui/web) matches the server's static mount, [postgres,redis] extras match pyproject.toml, and the /health route exists and responds.
  • uv run ruff check and ruff format --check pass. Full uv run pytest is green except 4 pre-existing failures in tests/cli/test_client_signing.py that are unrelated to this change (reproduced on a clean tree at main).

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)

Documentation-only change (no docs:-specific checkbox in the template); checked "Bug fix" because it repairs a broken quick start and a latent DSN bug.

Checklist:

  • My code follows the code style of this project.
  • I have read the CONTRIBUTING document.
  • All new and existing tests passed.

Note: 4 unrelated, pre-existing tests/cli/test_client_signing.py failures exist on main (identity lookup by DID vs. handle) and are not touched by this PR.

@rishabhraj36 rishabhraj36 linked an issue Jun 17, 2026 that may be closed by this pull request
5 tasks
@rishabhraj36 rishabhraj36 changed the title 423 chore update dockerfile compose and self hosting guide for hosted authsome chore: update dockerfile compose and self hosting guide for hosted authsome Jun 17, 2026
@rishabhraj36 rishabhraj36 marked this pull request as ready for review June 17, 2026 10:54
@manojbajaj95 manojbajaj95 merged commit 5917d32 into main Jun 17, 2026
2 of 3 checks passed
@manojbajaj95 manojbajaj95 deleted the 423-chore-update-dockerfile-compose-and-self-hosting-guide-for-hosted-authsome branch June 17, 2026 12:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

chore: Update Dockerfile, compose, and self-hosting guide for hosted Authsome

2 participants