Skip to content

development.md

Latest commit

 

History

History
123 lines (94 loc) · 3.21 KB

development.md

File metadata and controls

123 lines (94 loc) · 3.21 KB
Raw

Development

Services

Local Docker services:

  • postgres
  • clickhouse
  • backend
  • frontend

Start the production-style local stack:

docker compose up --build -d

Start the development stack with backend reload and the Vite dev server:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build -d

Stop everything:

docker compose down

Full reset:

docker compose down -v
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build -d

Backend

cd backend
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Run tests:

backend/.venv/bin/python -m pytest

Frontend

cd frontend
npm install
npm run dev

Run checks:

cd frontend
npm run tsc
npm run lint
npm test
npm run build

The frontend is the only Node package in the repository. Run npm commands from frontend/.

Key Environment Variables

Variable Purpose
POSTGRES_HOST Postgres hostname
POSTGRES_PORT Postgres port
POSTGRES_DB Postgres database
POSTGRES_USER Postgres user
POSTGRES_PASSWORD Postgres password
CLICKHOUSE_HOST ClickHouse hostname
CLICKHOUSE_HTTP_PORT ClickHouse HTTP port used by the backend
CLICKHOUSE_DATABASE ClickHouse database
CLICKHOUSE_USER ClickHouse user
CLICKHOUSE_PASSWORD ClickHouse password
SECRET_KEY JWT signing secret
CORS_ORIGINS Allowed frontend origins
CORS_ORIGIN_REGEX Optional regex for local/dev frontend origins
READS_PATH BAM/CRAM directory
REFERENCE_FASTA_PATH Reference FASTA for sequence/CRAM lookups
REFERENCE_ALIAS_PATH Optional chromosome alias map
REFERENCE_CYTOBAND_PATH Optional cytoband fallback file
GENE_REFERENCE_DBNSFP_GENE_PATH Local dbNSFP gene file for gene reference sync; defaults to /data/ref-data/dbNSFP5.3_gene.gz and online sources are used as fallback
GENE_REFERENCE_BOOTSTRAP_ON_STARTUP Queue the first dbNSFP-backed human gene reference sync on startup when GRCh38 genes exist and gene_info is still empty; defaults to true
VITE_API_BASE_URL Frontend API base URL; defaults to same-origin /api, proxied to the backend

Troubleshooting

Check containers:

docker compose ps
docker compose logs backend --tail=100
docker compose logs postgres --tail=100
docker compose logs clickhouse --tail=100

Check backend env inside the container:

docker exec coga-backend-1 printenv | egrep '^(POSTGRES_|CLICKHOUSE_|SECRET_KEY|READS_PATH|REFERENCE_)'

Storage Notes

  • Metadata issues usually come from Postgres schema or bad UUID references.
  • Variant ingestion/listing issues usually come from ClickHouse schema or assembly table creation.
  • The Administration data-management page now includes a ClickHouse variant operations section for inspecting per-assembly table status and running ensure/optimize actions.
  • The same maintenance API is available through:
    • GET /admin/clickhouse/variants
    • POST /admin/clickhouse/variants/{assembly_name}/ensure
    • POST /admin/clickhouse/variants/{assembly_name}/optimize