99 lines
3.5 KiB
Markdown
99 lines
3.5 KiB
Markdown
# 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.
|