trymeapp/INSTALL.md

TryMe Gaming App — Installation & Operations (INSTALL.md)

Prerequisites

• Python 3.11+
• Node.js 22+ and npm (for building the React + TypeScript SPA locally)
• Docker & Docker Compose (for containerized deployment)
• Helm 3.x (for Kubernetes deployment)

---

1. Local Development Setup

# 1. Create Python virtual environment and install backend + test dependencies
python3 -m venv venv
venv/bin/pip install --upgrade pip
venv/bin/pip install -e ".[dev]"

# 2. Apply Alembic database migrations (defaults to local SQLite ./tryme.db)
venv/bin/alembic upgrade head

# 3. Install and build the frontend SPA
cd frontend
npm ci
npm run build
cd ..

# 4. Start the FastAPI server (serves API, /docs, /openapi.yaml, and SPA on :8000)
SEED_STARTER_QUIZZES=true venv/bin/uvicorn app.main:app --reload --port 8000

Run the automated test suite:

venv/bin/pytest -v

---

2. Docker & Docker Compose

Launch App + PostgreSQL Together

docker compose up --build

The application will run Alembic migrations automatically and listen at http://localhost:8000 (Swagger UI at http://localhost:8000/docs, OpenAPI YAML at http://localhost:8000/openapi.yaml).

Standalone Container Build

The container tag is tracked in version.ini (0.1):

VERSION=$(awk -F'=[ \t]*' '/^version[ \t]*=/ {gsub(/[ \t"'\''\r]/, "", $2); print $2}' version.ini)
docker build -t trymeapp:${VERSION} .
docker run -p 8000:8000 -e DEV_AUTH_ENABLED=true -e SEED_STARTER_QUIZZES=true trymeapp:${VERSION}

---

3. Kubernetes Deployment (Helm Chart)

Option A: With External / Cluster PostgreSQL

helm upgrade --install tryme ./helm-chart \
  --set database.mode=postgres \
  --set database.url="postgresql+psycopg://tryme:secret@postgres-svc:5432/trymedb" \
  --set config.adminUser="moderator@school.edu" \
  --set config.auth0Domain="your-tenant.us.auth0.com" \
  --set config.auth0ClientId="your-client-id" \
  --set secrets.auth0ClientSecret="your-client-secret" \
  --set secrets.sessionSecret="$(openssl rand -hex 32)"

Option B: With SQLite + Automatic PersistentVolumeClaim (PVC)

When database.mode=sqlite is set, the Helm chart automatically creates a PersistentVolumeClaim, switches the deployment strategy to Recreate, mounts the volume at /data, and points DATABASE_URL to /data/tryme.db:

helm upgrade --install tryme ./helm-chart \
  --set database.mode=sqlite \
  --set persistence.size=5Gi \
  --set config.adminUser="moderator@school.edu"

---

4. CI/CD Workflows & Required Repository Secrets

Two CI/CD workflows are included:

1. Gitea Actions (.gitea/workflows/cicd.yaml):

   • Reads the version tag from version.ini and registry path from the final line of Dockerfile (#harbor.freshbrewed.science/library/trymeapp).
   • Builds and pushes the image to Harbor and Docker Hub, then packages ./helm-chart and pushes it to oci://harbor.freshbrewed.science/chartrepo/trymeapp-helm.
   • Required Gitea Secrets:
     • CR_USER / CR_PAT: Harbor container registry & Helm OCI chart repository credentials.
     • DHUSER / DHPAT: Docker Hub username & personal access token.

2. GitHub Actions (.github/workflows/ci.yml):

   • Runs alembic upgrade head against a PostgreSQL 16 service container, executes pytest, compiles the TypeScript/Vite SPA, builds the Docker image tagged from version.ini, and validates ./helm-chart in both PostgreSQL and SQLite PVC modes.