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

```bash
# 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:

```bash
venv/bin/pytest -v
```

---

## 2. Docker & Docker Compose

### Launch App + PostgreSQL Together
```bash
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](file:///home/isaac/Workspaces/trymeapp/version.ini) (`0.1`):

```bash
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
```bash
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`:

```bash
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.