---

name: app-deployment description: "Install, launch, configure, and troubleshoot the Kotaemon Gradio app for document QA users and operators." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Kotaemon App Deployment

Use this sub-skill when the task is to get the Kotaemon Gradio application running, diagnose its runtime configuration, prepare a safe update or data migration, or explain the operator-facing UI for document QA.

Route here for

• Docker vs local installation decisions, including uv, conda, editable installs, and release-style launch scripts.
• .env, flowsettings.py, settings.yaml.example, Gradio, first setup, login, app-data, PDF.js, and Resources/Settings tab behavior.
• Safe diagnostics before launch, update, or Chroma migration; use the bundled scripts instead of running app/update/migration scripts blindly.
• Operator troubleshooting for missing credentials, placeholder model defaults, local-provider URLs, data permissions, optional parsers/providers, PDF viewer assets, and broad dependency installs.

Do not use this for

• Custom component, plugin, page, or flow authoring; use ../extensions/SKILL.md.
• Low-level kotaemon RAG APIs, indexes, retrieval, document objects, or QA pipelines; use ../rag-core/SKILL.md.
• Provider-specific model tuning, GraphRAG details, local model server tuning, or credential semantics beyond app deployment checks; use ../model-providers/SKILL.md.

Fast workflow

1. Pick the deployment mode using references/deployment.md: Docker for isolated operator use, local uv/conda for source/developer installs, Hugging Face duplicate Space for online installs.
2. Check runtime configuration with references/configuration.md and run python scripts/check_app_config.py --env-file .env --repo-root . from a Kotaemon checkout or copied deployment directory.
3. For first-run issues, login/resource visibility, PDF viewer problems, data directory permissions, updates, or migrations, follow references/troubleshooting.md.
4. Before any Chroma metadata migration, run python scripts/inspect_chroma_migration_inputs.py --chroma-dir <vectorstore-dir> --sqlite-uri sqlite:///<sql.db> and back up ktem_app_data before mutating anything with external migration code.

Safety rules

• Do not start python app.py, run Docker, execute release scripts, download PDF.js, update packages, pull local models, or mutate Chroma/SQLite data unless the user explicitly approves side effects.
• Treat .env as a first-run seeding mechanism for models/credentials; after the app database exists, Resources and Settings UI entries may override what the file originally seeded.
• Never print secrets. The bundled config script reports whether key-like values are missing or placeholders, not the values themselves.
• Back up ktem_app_data/ before update or migration work; it contains user uploads, SQLite state, vector/doc stores, caches, and model cache directories.

Bundled references

• references/deployment.md - install modes, launch choices, data directory, PDF.js, Docker/local/HF notes.
• references/configuration.md - .env, flowsettings.py, app settings/resources tabs, first setup/login, Gradio settings.
• references/troubleshooting.md - diagnostic decision tree, safe update/migration cautions, common failure modes.

Bundled scripts

• scripts/check_app_config.py - read-only .env and PDF.js/app-data diagnostic; never starts Kotaemon.
• scripts/inspect_chroma_migration_inputs.py - read-only Chroma/SQLite migration preflight; never updates collections or SQL rows.