Skip to main content

Install SkillFlaw for deployment - Python

This guide covers the deployment-oriented installation path for the SkillFlaw Python backend runtime.

Use this page when your deployment target is based on:

  • docker/docker-compose-py.yml
  • docker/backend/Dockerfile
  • make init / make init_db
  • make backend / make frontend
  • make run_cli / make run_clic

If you are preparing a TypeScript deployment instead, use Install SkillFlaw for deployment - TypeScript.

Delivery modes​

  • Docker installation: run the packaged local stack from docker/docker-compose-py.yml
  • Source installation: run the Python product directly from the repository
  • Development installation: use the Python repository workflow with make init, make init_db, make backend, and make frontend

Docker installation​

The Python deployment path uses docker/docker-compose-py.yml and starts these services:

  • frontend
  • backend_py
  • doc
  • redis
  • pgsql

Docker prerequisites​

  • install Docker Engine or Docker Desktop
  • install the docker compose CLI plugin
  • the default Docker path does not require a separate local PostgreSQL, Redis, or SKILLFLAW_SECRET_KEY_FILE
  • create the repository-root .env only when you want to provide extra runtime variables or local overrides to the Python backend container

Steps​

  1. Optional: copy .env.example to .env when you need runtime overrides.

  2. Start the stack:


    _10
    docker compose -f docker/docker-compose-py.yml up -d

On first startup, Compose runs the one-shot secret_init service, generates a high-entropy secret key file, and persists it in the skillflaw_secret_data volume for backend reuse.

Default access points​

  • frontend: http://localhost:3001
  • backend health: http://localhost:7860/health
  • docs: http://localhost:3002

Docker success check​

Treat the installation as successful when all of the following are true:

  • docker compose -f docker/docker-compose-py.yml ps shows pgsql, redis, backend_py, frontend, and doc running, while secret_init has completed successfully
  • http://localhost:7860/health returns a healthy response
  • http://localhost:3001 opens the SkillFlaw frontend
  • http://localhost:3002 opens the standalone docs site

Source installation​

Use source installation when you want to run the Python product directly from the repository.

Source-installation prerequisites​

  • prepare SKILLFLAW_DATABASE_URL
  • prepare SKILLFLAW_SECRET_KEY_FILE
  • keep the secret-key file as one line of high-entropy random text outside the repository
  • PostgreSQL is required, recommended 16, minimum compatible 14
  • Redis is required when SKILLFLAW_CACHE_TYPE=redis, recommended 7, minimum compatible 6

Steps​

  1. Copy .env.example to .env.
  2. Configure SKILLFLAW_DATABASE_URL.
  3. Configure SKILLFLAW_SECRET_KEY_FILE.
  4. Run make init.
  5. Run make init_db.
  6. Run make backend and make frontend.

If you want a built-frontend runtime closer to the release shape, run make run_cli or make run_clic from the repository root.

Database initialization​

make init only installs dependencies and prepares the environment. make init_db is the only command that creates the target database when needed, initializes schema, imports exported init data, and prepares the default admin account.

If the PostgreSQL database referenced by SKILLFLAW_DATABASE_URL does not exist yet, make init_db tries to create it automatically before loading schema and init data. The PostgreSQL user must have CREATE DATABASE permission.

Optional runtime dependencies​

OpenSandbox and OpenCode are optional for base platform startup.

  • For OpenSandbox, configure the repository-root .env and ensure the configured domain is reachable from the Python backend runtime.
  • For OpenCode, the Python Docker image already bundles opencode, while the Python source-install path expects opencode in the same host environment as make backend.
  • SKILLFLAW_CONTAINER_OPENCODE_* is only intended for the containerized Python backend path.

Default admin account​

The default admin account prepared by repository initialization is:

  • username: admin
  • password: Skillflaw@123321

Initialization data export​

Run make export_db_init_data to regenerate data/postgresql/skillflaw_init_data.sql.

Next steps​