Documentation hosting

How the documentation is served #

The korenactdocs/public directory contains checked-in HTML, CSS, browser JavaScript, and search metadata. The Docker docs service copies those files directly into Nginx; no Node installation, frontend framework, or documentation compilation is needed. Caddy routes docs.korenact.com to docs:8080 and manages HTTPS.

The documentation is public and independent of workspace sign-in. It never needs API credentials. The HTML stays readable without JavaScript; JavaScript adds search and navigation. Directory redirects remain relative so the browser retains HTTPS.

Configure the hostname #

1. Point the docs.korenact.com A record to the Korenact VPS. Publish an AAAA record only when IPv6 reaches the same server.
2. Allow inbound ports 80 and 443 for Caddy and outbound HTTPS/DNS for certificate issuance.
3. In the deployment root .env, set KORENACT_DOCS_DOMAIN=docs.korenact.com.
4. Keep the Caddy certificate volumes across redeployments.
5. Use the root Compose deployment. The backend subdirectory Compose file does not publish this documentation hostname.

Deploy documentation updates #

On an existing healthy Korenact deployment, run from the repository root:

docker compose up -d --build --wait docs
docker compose up -d --no-deps --force-recreate edge
sh scripts/check-docs-host.sh

The edge recreation loads the current hostname configuration and can briefly interrupt public traffic. Use your maintenance procedure. The documentation-only build does not compile the React workspace. The root Compose parser still requires the existing DATABASE_URL, SECRET_KEY, and TELNYX_PUBLIC_KEY, even when updating only documentation.

For a new application release with database changes, use a maintenance window and rehearse against a separate restored database. Build the reviewed release first, then stop traffic and runtimes:

docker compose --parallel 1 build
docker compose stop edge frontend api webhook-worker

Allow in-flight work to finish and account for carrier retries. Take and verify a backup of the external PostgreSQL database, retaining the matching previous source and images. Then run a fresh migration job:

docker compose run --rm --no-deps migrate

Continue only after a successful migration. Start the matching release and check documentation:

docker compose up -d --force-recreate api webhook-worker frontend docs edge
sh scripts/check-docs-host.sh

The migration head is 0008_agent_teams. Confirm API readiness, worker progress and provider acceptance before restoring customer traffic. If migration fails, leave traffic stopped; rolling back images alone does not restore the database. Keep the existing populated root environment file.

The repository docs/ folder contains internal Markdown architecture and deployment notes. The public container serves korenactdocs/public/. To edit a public guide, change its HTML directly and run python3 korenactdocs/scripts/check.py --refresh-index from the repository root before deploying.

Verify HTTPS and troubleshoot #

1. Open https://docs.korenact.com with certificate validation enabled.
2. Open the Agent teams, Sending email, and External webhooks guides.
3. Use documentation search and navigate a result. Check the Open workspace link.
4. Run the repository's public-host check. It verifies TLS, health, representative guides, and the search asset.
5. If HTTPS fails, inspect docker compose logs --tail=100 edge docs on the VPS. Check certificate issuance, DNS, ports, and the current edge configuration.
6. If HTTP redirects to HTTPS but HTTPS fails, confirm Caddy has successfully issued a certificate for the docs hostname. Do not bypass certificate checks to mark the site healthy.
7. If HTTPS returns 502, check docker compose ps docs edge and docs service health. Ensure the current docs image and edge configuration were deployed.

A successful local link check or Compose configuration check does not prove that the public VPS is serving the latest site. Verify the real public hostname after deployment.