Skip to main content

Configuration

4 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. scripts/setup-env.sh generates 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: violet

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

The "Was this page helpful?" widget on every page sends votes to /api/feedback. Clicking Yes saves the vote immediately. Clicking No opens an optional comment field, up to 1000 characters, with a "Send feedback" button and a "Send without comment" link. The endpoint caps request bodies at 8KB and accepts only printable characters in comments.

By default, votes are appended to daily-rotated JSONL files named feedback-YYYY-MM-DD.jsonl under FEEDBACK_DIR. A file stops accepting writes once it reaches 25MB. Set NOTION_API_KEY and NOTION_DATABASE_ID to store votes in Notion instead — required on read-only hosts like Vercel.

FEEDBACK_DIRstringDefault: ./data/feedback

Directory for the daily-rotated JSONL feedback files. The Docker image sets it to /app/data/feedback, a writable directory inside the container.

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.

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.

Secret storage and value inlining

Every secret above belongs in .env.local or your host's secret store, never in a commit. .env.example documents the same set with placeholder values. NEXT_PUBLIC_* values are inlined at build time, so changing one requires a rebuild.

Related pages

Installation

Deployment

AI Chat

Was this page helpful?