Run your site from the admin console

Staff readers run the docs site in the browser at /admin: who can read it, its custom domain, which repository it is built from, readers and organizations, the site's look, sign-in, the GitHub connection and the web editor. No server access or environment variables needed.

About this task

Only signed-in staff readers can open the console. Anyone else gets a 404; visitors who are not signed in are sent to the sign-in page first. Staff readers see an Admin link next to their name on every docs page.

The console works without JavaScript. Every change is a form protected by a token tied to your session, is refused from other sites, and is written to the audit log as staff:your email. A change applies at once on every server, without a restart.

Become the first staff reader with a one-time setup link.
The first time, nobody is staff yet. Whoever operates the server mints a setup link, which works once, for 30 minutes, and only while no staff reader exists:
```
opend-server admin-link                     # on Railway: run it in the web service's shell
# or, with the admin token:
curl -X POST "$PUBLIC_URL/admin/api/setup-links" -H "authorization: Bearer $OPEND_ADMIN_TOKEN" \
  -H 'content-type: application/json' -d '{"minutes":30}'
```
Open the link, enter your email address and name, and you are signed in as a staff reader of the staff organization (or your existing reader is made staff). Use the address you will sign in with from then on, with GitHub or your company account.

On a managed site, sign in at https://opend.app/login instead and choose Open admin next to the site: the account panel signs you in to the console through /admin/handoff, with a link that works once, for a minute. The site's owner is made staff the first time; other people must already be staff.
The console's Overview opens, with what is left to set up.
Connect GitHub on the GitHub page.
Self-hosted sites create their own GitHub App in a few clicks (Connect GitHub from the admin console). Managed sites install the provider's app with Connect GitHub.
Choose the docs repository on the Docs source page.

Pick it from the repositories the GitHub App can access, or give a public repository's https:// clone URL. Set the branches and tags that publish (such as main, v*) and the folder that holds opend.config.yaml. Build now queues a build of every matching branch and tag; Rebuild now does it again later. Choosing another repository keeps the site's access settings and readers.

When the GitHub App can access only one repository, the site does this step itself as soon as the app is installed, and the Overview says so; when it cannot (several repositories or docs folders), the Overview says why. See Set the site up from opend.config.yaml.
Decide who can read the site on the Site & access page.
Settings the docs repository declares in the site block of its opend.config.yaml show Set by opend.config.yaml and are read-only; change them in the repository.
Private or Public, and for a public site the products, features and release anonymous visitors see, chosen from those the published release declares in opend.config.yaml. See Make a site public or private. The site title comes from the repository and is shown read-only. The release version may be latest, the newest live release line. Release lines groups releases by major or by minor version; switching moves the live releases to their new lines at once, and older minor versions come back only with their next build (see Release lines by major or minor version). The overview's Live releases card links to it. Version picker sets what readers can choose beside the site title, including Every live version; see Let readers choose the version they read.
Optional: serve the site at your own domain on the Custom domain page.
On a managed site, enter a domain such as docs.example.com and add the DNS records the page lists at your DNS provider; it shows whether each has propagated and when it was last checked. The site keeps its own address until they are in place, then switches by itself, and the old address keeps working. Remove domain goes back at once. A self-hosted site's domain is its PUBLIC_URL, so the page only explains that. See Serve your site at your own domain.
Add organizations and readers on the People page.
An organization's products, features and release decide what its readers see. Readers sign in with an account whose verified email is the one you give. Make teammates staff here; you cannot remove your own staff role, yourself or your own organization.
Optional: set the site theme and PDF template on the Appearance page.
A colour preset or your brand colour, fonts, corners, reading width, colour scheme and custom CSS for the site, the help panel and PDFs, and the template every PDF prints with. See Change the site's look from the admin console.
Choose how readers sign in on the Sign-in page.
Sign in with GitHub comes with the connected GitHub App and can be turned off. Company sign-in (OIDC) takes the issuer URL, client id and client secret from your identity provider; register $PUBLIC_URL/auth/callback there as the redirect URI. Demo readers can be turned off where the server allows them; they never appear in production.
Set up the web editor on the Editor page.
Give the editor's address to turn on Edit this page links, choose whether View source on GitHub links show, and add authors who sign in with company sign-in. The editor service itself needs only DATABASE_URL, SESSION_SECRET, EDITOR_PUBLIC_URL and PUBLIC_URL; see Run the web editor.
Optional: under API & AI, create API keys for your own tools and AI assistants.

Each key has a name, what it can do (read, propose changes, publish, builds), whose view of the docs it reads (everything, one org, or public) and an expiry. The key is shown once; revoke it here at any time. On a managed site the page also shows the address to connect AI assistants. See Public API and AI assistants.

Results

Settings set by environment variables are shown as Set by environment and cannot be changed in the console; see Console settings, environment variables and the secret key. Secrets you enter (client secrets) are stored encrypted and never shown again: the console only says whether one is set.