Configuration

3 min readStableIntermediate

OwnDocs is configured through environment variables and two optional files: owndocs.config.json for build-time variable substitution and .env.local for local secrets. This page is the complete reference for every value the application reads. Run bash scripts/setup-env.sh to generate the required secrets locally.

Access mode

ACCESS_MODEstringDefault: private

private (password-protected, default) or public (open access). Private mode requires APP_PASSWORD, JWT_SECRET, and COOKIE_SALT, and blocks crawlers.

Private-mode secrets

APP_PASSWORDstring

Site access password. Required in private mode. Generate: openssl rand -base64 48 | tr -dc 'a-zA-Z0-9' | head -c 24.

JWT_SECRETstring

JWT signing key. Required in private mode. Generate: openssl rand -base64 48.

COOKIE_SALTstring

Salt for cookie-name generation. Required in private mode. Generate: openssl rand -hex 32.

Appearance

THEME_VARIANTstringDefault: emerald

One of 26 color palettes: amber, blue, cyan, emerald, fuchsia, gray, green, indigo, lime, mauve, mist, neutral, olive, orange, pink, purple, red, rose, sky, slate, stone, taupe, teal, violet, yellow, zinc.

NEXT_PUBLIC_FOOTER_COMPANY_NAMEstring

Company name shown in the footer. No default.

NEXT_PUBLIC_FOOTER_COMPANY_URLstring

Company URL linked in the footer. No default.

NEXT_PUBLIC_SITE_URLstring

Canonical site URL for the sitemap and Open Graph tags. Optional; auto-detected on Vercel.

Announcement bar

NEXT_PUBLIC_ANNOUNCEMENT_IDstring

Unique id for the announcement, used to key the dismiss state in localStorage.

NEXT_PUBLIC_ANNOUNCEMENT_MESSAGEstring

Announcement text shown in the site-wide banner. When empty, the bar is hidden.

NEXT_PUBLIC_ANNOUNCEMENT_HREFstring

Optional link destination for the announcement.

NEXT_PUBLIC_ANNOUNCEMENT_LINK_LABELstring

Optional link text; requires NEXT_PUBLIC_ANNOUNCEMENT_HREF.

NEXT_PUBLIC_ANNOUNCEMENT_DISMISSIBLEstringDefault: true

Set false to make the announcement non-dismissible.

AI chat

AI_PROVIDERstring

anthropic, openai-compatible (or openai), ollama, or ollama-cloud. See the AI Chat integration for full setup.

AI_API_KEYstring

Provider API key. Optional for local Ollama.

AI_BASE_URLstring

Provider base URL. Optional; presets exist per provider.

AI_MODELstring

Model id. Required for non-Anthropic providers.

ANTHROPIC_API_KEYstring

Anthropic-specific API key alias.

ANTHROPIC_MODELstring

Anthropic-specific model alias; defaults to claude-sonnet-5.

Feedback

FEEDBACK_DIRstringDefault: ./data/feedback

Reader-feedback storage directory.

NOTION_API_KEYstring

Notion integration token (starts with ntn_) for read-only hosts. See the Notion integration.

NOTION_DATABASE_IDstring

32-character Notion database id that receives reader votes.

MCP server

MCP_ENABLEDstring

Set true to expose /api/mcp in private mode. See the MCP integration.

MCP_BEARER_TOKENstring

Bearer token required by MCP clients. Generate: openssl rand -hex 32.

Edit link

NEXT_PUBLIC_REPO_URLstring

Repository URL used to build the edit-on-GitHub link in the page footer. When unset, the edit link is hidden.

NEXT_PUBLIC_REPO_BRANCHstringDefault: main

Branch the edit link targets.

Build-time variables

OwnDocs substitutes {{vars.<name>}} tokens in MDX content at build time. There are two sources, merged with environment variables taking precedence.

owndocs.config.json - a root-level JSON file with a vars object, for example { "vars": { "brand": "OwnDocs" } }.
NEXT_PUBLIC_DOCS_VAR_* environment variables - each one becomes a variable by stripping the prefix and camel-casing the rest. For example, NEXT_PUBLIC_DOCS_VAR_API_URL becomes https://api.example.com.

Use the variable in content as https://api.example.com; the remark plugin replaces it at build time.

Result

Every secret above should be generated, stored in .env.local or your host's secret store, and never committed. The .env.example file documents the same set with placeholder values for reference. NEXT_PUBLIC_* values are inlined at build time, so changing them requires a rebuild.

Installation

Deployment

AI Chat

Was this page helpful?