Configuration Reference

This page documents every configuration knob for the docsfy server, CLI, and Docker deployment. Each setting lists its name, type, default, valid values, and a concrete example.

Server Environment Variables

The docsfy server reads its configuration from environment variables (or an .env file in the working directory). Settings are loaded by pydantic_settings — variable names are case-insensitive.

Example .env file

ADMIN_KEY=my-very-long-secret-key-here
AI_PROVIDER=cursor
AI_MODEL=gpt-5.4-xhigh-fast
AI_CLI_TIMEOUT=60
LOG_LEVEL=INFO
DATA_DIR=/data
SECURE_COOKIES=true
MAX_CONCURRENT_PAGES=10

Warning: ADMIN_KEY is required. The server will exit immediately at startup if it is empty or shorter than 16 characters.

Note: Rotating ADMIN_KEY invalidates all existing user API key hashes. Every user must regenerate their API key after an ADMIN_KEY change.

Valid AI Providers

See Configuring AI Providers for provider setup details.

Valid Log Levels

DEBUG, INFO, WARNING, ERROR, CRITICAL

Data Directory Layout

All persistent state lives under DATA_DIR (default /data).

<DATA_DIR>/
├── docsfy.db                  # SQLite database
└── projects/
    └── <owner>/
        └── <project>/
            └── <branch>/
                └── <provider>/
                    └── <model>/
                        ├── cache/pages/   # Cached page markdown
                        └── site/          # Rendered HTML site

• <owner> is the username of the project creator (_default when empty).
• <branch> defaults to main.
• <provider> and <model> identify the AI variant used for generation.

CLI Configuration File

The CLI stores server profiles in a TOML file at:

~/.config/docsfy/config.toml

The file is created with permissions 600 (owner read/write only).

File Structure

# Default server profile to use when --server is not specified
[default]
server = "dev"

# Server profiles — add as many as needed
[servers.<profile-name>]
url = "<server-url>"
username = "<username>"
password = "<api-key>"

Keys Reference

Tip: Valid key prefixes for docsfy config set are default. and servers. only.

Example

[default]
server = "dev"

[servers.dev]
url = "http://localhost:8000"
username = "admin"
password = "<your-dev-key>"

[servers.prod]
url = "https://docsfy.example.com"
username = "admin"
password = "<your-prod-key>"

CLI Config Commands

docsfy config init

Interactive setup that prompts for profile name, server URL, username, and password. Creates the config file if it doesn't exist, or adds a new profile.

docsfy config init

Profile name [dev]: prod
Server URL: https://docsfy.example.com
Username: admin
Password: ********
Profile 'prod' saved to /home/user/.config/docsfy/config.toml

docsfy config show

Displays all profiles with masked passwords.

docsfy config show

Config file: /home/user/.config/docsfy/config.toml
Default server: dev

[dev] (default)
  URL:      http://localhost:8000
  Username: admin
  Password: my***

docsfy config set

Set a single configuration key.

docsfy config set default.server prod
docsfy config set servers.dev.url https://new-server.com
docsfy config set servers.staging.password new-api-key

See Using the CLI for the full CLI setup workflow and CLI Command Reference for all commands.

CLI Connection Resolution

When the CLI connects to a server, parameters are resolved in this priority order (highest first):

1. Explicit CLI flags (--host, --port, --username, --password)
2. Named server profile from --server flag
3. Default server profile from [default].server in config
4. Error if nothing is configured

# Use config default
docsfy list

# Use a named profile
docsfy --server prod list

# Override host and port
docsfy --host myserver --port 9000 -u admin -p my-key list

Note: When --host is used with a profile, the scheme is preserved from the profile URL. Without a profile, the scheme defaults to https.

Docker Compose Configuration

Compose File Reference

services:
  docsfy:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8000:8000"
      # - "5173:5173"  # Uncomment for DEV_MODE
    volumes:
      - ./data:/data
      # - ./frontend:/app/frontend  # Uncomment for frontend hot reload
    env_file:
      - .env
    environment:
      - ADMIN_KEY=${ADMIN_KEY}
      # - DEV_MODE=true
    restart: unless-stopped

Compose Options

Container DEV_MODE

When DEV_MODE=true, the container entrypoint:

1. Runs npm ci and starts the Vite dev server on port 5173
2. Recompiles sidecar TypeScript from source
3. Starts uvicorn with --reload --reload-dir /app/src

services:
  docsfy:
    ports:
      - "8000:8000"
      - "5173:5173"
    volumes:
      - ./data:/data
      - ./frontend:/app/frontend
    environment:
      - ADMIN_KEY=${ADMIN_KEY}
      - DEV_MODE=true

Note: When DEV_MODE is not true, the container serves the prebuilt frontend from frontend/dist.

See Deploying with Docker for production deployment patterns.

Container Ports

Health Check

The container health check probes both the server and the sidecar:

curl -f http://localhost:${PORT:-8000}/health
curl -f http://localhost:${SIDECAR_PORT:-9100}/health

• Interval: 30 seconds
• Timeout: 10 seconds
• Start period: 30 seconds
• Retries: 3

Session and Authentication Constants

These values are compiled into the server and cannot be changed via environment variables.

See Managing Users and Access Control for role descriptions.

Git Operation Timeouts

Internal timeouts for git subprocess calls. These are compiled constants in repository.py.

GenerateRequest Defaults

When submitting a generation request (via API or CLI), these defaults apply to omitted fields.

Warning: Branch names cannot contain / characters. Use hyphens instead (e.g. release-1.x rather than release/1.x).

See Generating Documentation for generation workflows and REST API Reference for the POST /api/generate endpoint.

Generation Stages

A generation run progresses through these stages in order. The current_stage field reflects the active stage in status responses and WebSocket messages.

Prompt Constraints

Internal limits applied during AI prompt construction.

WebSocket Constants

Internal constants for the WebSocket connection (/api/ws).

Frontend Constants

Client-side timing constants defined in frontend/src/lib/constants.ts.

Project Database Schema

The composite primary key for project variants:

PRIMARY KEY (name, branch, ai_provider, ai_model, owner)

Related Pages

• Deploying with Docker
• Configuring AI Providers
• CLI Command Reference
• Using the CLI
• Generating Documentation