Local Installation

docsfy is a Python FastAPI service packaged with a pyproject.toml + uv.lock workflow.

[project]
name = "docsfy"
version = "0.1.0"
requires-python = ">=3.12"

[project.scripts]
docsfy = "docsfy.main:run"

[project.optional-dependencies]
dev = ["pytest", "pytest-asyncio", "pytest-xdist", "httpx"]

Prerequisites

Python 3.12+
uv (used for dependency and runtime commands in this repo)
git (required for repository cloning and diffing during generation)

def clone_repo(repo_url: str, base_dir: Path) -> tuple[Path, str]:
    result = subprocess.run(
        ["git", "clone", "--depth", "1", "--", repo_url, str(repo_path)],
        capture_output=True,
        text=True,
        timeout=300,
    )

Tip: Generation supports claude, gemini, and cursor providers.

ai_provider: Literal["claude", "gemini", "cursor"] | None = None

1) Install dependencies

From the repository root:

uv sync --frozen --no-dev

This is the same locked install pattern used by the project container build:

RUN uv sync --frozen --no-dev

If you want to run tests later, the repo uses this dev command in tox.toml:

commands = [["uv", "run", "--extra", "dev", "pytest", "-n", "auto", "tests"]]

2) Configure local environment

Copy the env template and create a local data directory:

cp .env.example .env
mkdir -p data

Base .env values come from .env.example:

ADMIN_KEY=your-secure-admin-key-here-min-16-chars

AI_PROVIDER=claude
AI_MODEL=claude-opus-4-6[1m]
AI_CLI_TIMEOUT=60

# ANTHROPIC_API_KEY=
# GEMINI_API_KEY=
# CURSOR_API_KEY=

LOG_LEVEL=INFO
# SECURE_COOKIES=false

Runtime defaults are defined in src/docsfy/config.py:

admin_key: str = ""
ai_provider: str = "claude"
ai_model: str = "claude-opus-4-6[1m]"
ai_cli_timeout: int = Field(default=60, gt=0)
log_level: str = "INFO"
data_dir: str = "/data"
secure_cookies: bool = True

Storage paths are derived from DATA_DIR:

DB_PATH = Path(os.getenv("DATA_DIR", "/data")) / "docsfy.db"
DATA_DIR = Path(os.getenv("DATA_DIR", "/data"))
PROJECTS_DIR = DATA_DIR / "projects"

Recommended local overrides in .env:

DATA_DIR=./data
SECURE_COOKIES=false

Warning: ADMIN_KEY is mandatory and must be at least 16 characters, or startup exits.

if not settings.admin_key:
    logger.error("ADMIN_KEY environment variable is required")
    raise SystemExit(1)

if len(settings.admin_key) < 16:
    logger.error("ADMIN_KEY must be at least 16 characters long")
    raise SystemExit(1)

Warning: For plain local HTTP (http://127.0.0.1:8000), keep SECURE_COOKIES=false so login sessions work in the browser.

3) Run the service

Start docsfy:

uv run docsfy

The entrypoint behavior is:

reload = os.getenv("DEBUG", "").lower() == "true"
host = os.getenv("HOST", "127.0.0.1")
port = int(os.getenv("PORT", "8000"))
uvicorn.run("docsfy.main:app", host=host, port=port, reload=reload)

Common local override (bind all interfaces, custom port, reload on code changes):

HOST=0.0.0.0 PORT=8800 DEBUG=true uv run docsfy

4) Verify startup

Health endpoint:

curl http://127.0.0.1:8000/health

Expected response:

{"status":"ok"}

Open the login page: http://127.0.0.1:8000/login

Username: admin
Password: value of ADMIN_KEY

if username == "admin" and api_key == settings.admin_key:
    is_admin = True
    authenticated = True

API auth smoke test (Bearer token):

export ADMIN_KEY="your-admin-key"
curl -sS http://127.0.0.1:8000/api/status \
  -H "Authorization: Bearer ${ADMIN_KEY}"

Note: Only /login and /health are public routes by default.

_PUBLIC_PATHS = frozenset({"/login", "/login/", "/health"})

5) Optional: generation smoke test

curl -X POST http://127.0.0.1:8000/api/generate \
  -H "Authorization: Bearer ${ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"repo_url":"https://github.com/org/repo.git"}'

Generation checks AI CLI availability at runtime:

available, msg = await check_ai_cli_available(
    ai_provider, ai_model, cli_flags=cli_flags
)
if not available:
    await update_project_status(
        project_name,
        ai_provider,
        ai_model,
        status="error",
        owner=owner,
        error_message=msg,
    )
    return

Note: Install and authenticate the CLI for the provider you use (claude, gemini, or cursor) before running generation jobs.

6) Optional: run tests

uv run --extra dev pytest -n auto tests

This matches the project’s tox.toml command exactly.