Skip to main content

Install SkillFlaw for deployment - TypeScript

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

Use this page when your deployment target is based on:

  • docker/docker-compose-ts.yml
  • ghcr.io/cwinux/skillflaw_backend_ts:latest
  • make ts_install_backend / make ts_init_db
  • make ts_backend
  • make ts_backend_verify

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

Delivery modes​

  • Docker installation: run the packaged local stack from docker/docker-compose-ts.yml
  • Source installation: run the TypeScript product directly from the repository
  • Development installation: use the TypeScript repository workflow with make ts_install_backend, make ts_init_db, make ts_backend, and make frontend

Docker installation​

The TypeScript deployment path uses docker/docker-compose-ts.yml and starts these services:

  • frontend
  • backend_ts
  • doc
  • redis
  • pgsql

Docker prerequisites​

  • install Docker Engine or Docker Desktop
  • install the docker compose CLI plugin
  • the repository-root .env is optional unless you need TypeScript runtime overrides
  • this path provisions a dedicated TypeScript database through SKILLFLAW_TS_DATABASE_URL

Steps​

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

  2. Start the stack:


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

On first startup, this path creates the secret key file in skillflaw_secret_ts_data, runs db_init_ts, exports current bootstrap data through db_init_export_ts, and finishes with the one-shot stack_check_ts verification service.

Default access points​

  • frontend: http://localhost:3003
  • backend health: http://localhost:7861/health
  • docs: http://localhost:3004

Docker success check​

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

  • docker compose -f docker/docker-compose-ts.yml ps shows pgsql, redis, backend_ts, frontend, and doc running, while secret_init, db_init_ts, db_init_export_ts, and stack_check_ts have completed successfully
  • docker compose -f docker/docker-compose-ts.yml logs stack_check_ts ends with [backend_ts] ok, [frontend] ok, and [doc] ok
  • http://localhost:7861/health returns a healthy response
  • http://localhost:3003 opens the SkillFlaw frontend
  • http://localhost:3004 opens the standalone docs site

Source installation​

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

Source-installation prerequisites​

  • prepare SKILLFLAW_TS_DATABASE_URL
  • prepare SKILLFLAW_SECRET_KEY_FILE
  • prepare SKILLFLAW_TS_TEST_DATABASE_URL when tests or package validation are in scope
  • 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_TS_DATABASE_URL.
  3. Configure SKILLFLAW_SECRET_KEY_FILE.
  4. Run make ts_install_backend.
  5. Run make ts_init_db.
  6. Run make ts_backend and make frontend.

When package validation is in scope, also run the appropriate validation chain such as make ts_backend_verify, make ts_lfx_build, make ts_lfx_test, make ts_tool_build, and make ts_tool_test.

Database initialization​

make ts_install_backend only installs dependencies for the TypeScript backend runtime. make ts_init_db is the TypeScript backend entrypoint that initializes the target database and prepares bootstrap data.

Keep the TypeScript deployment database isolated from the Python deployment database by using a dedicated SKILLFLAW_TS_DATABASE_URL.

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 host environment where make ts_backend runs.
  • For OpenCode, the documented TypeScript runtime path expects opencode in the same host environment as make ts_backend.
  • The TypeScript repository path does not use SKILLFLAW_CONTAINER_OPENCODE_*.

Default admin account​

The default admin account prepared by repository initialization is:

  • username: admin
  • password: Skillflaw@123321

Initialization data export​

The TypeScript Docker workflow exports its bootstrap data to data/postgresql/skillflaw_ts_init_data.sql through db_init_export_ts.

Next steps​