+ The application is composed of three moving parts — an Angular 20 SPA (ui/winstudentgoaltracker),
+ a .NET 9 Web API (api/), and a MySQL 8 database initialised from the SQL objects in
+ db/Objects/. Configuration for every tier is read from a single .env file at the
+ repository root. Two workflows are supported: running the stack directly on a developer workstation, or
+ deploying the full stack to a server with docker compose behind an existing Traefik reverse
+ proxy.
+
Node.js, .NET 9 SDK, MySQL, Docker
+
+ The recommended local workflow runs MySQL in Docker (so the schema initialises itself from
+ db/docker-init/01-schema.sh) while the API and UI run on the host for fast iteration and
+ debugging.
+
cd frontend
-npm install
-npm startcd backend
+ Step 1 — Clone and create .env
+
+ Clone the repository and create a .env file at the project root. The API reads it via
+ DotNetEnv (which traverses parent directories), the UI/API containers read it through
+ docker-compose.yml's env_file directive, and the MySQL container consumes the
+ MYSQL_* variables natively.
+
+ git clone <repo-url> WinStudentGoalTracker
+cd WinStudentGoalTracker
+ Create .env with the following keys (replace the secrets before sharing or deploying):
+ # MySQL container bootstrap
+MYSQL_ROOT_PASSWORD=change_me_root
+MYSQL_DATABASE=winstudentgoaltracker
+MYSQL_USER=appuser
+MYSQL_PASSWORD=change_me_app
+
+# Connection used by the .NET API
+MYSQL_HOST=127.0.0.1
+MYSQL_PORT=3309
+# (the api falls back to root/no-password if MYSQL_USER/PASSWORD are omitted)
+
+# JWT signing key — must be >= 32 bytes
+JWT_KEY=replace_with_a_long_random_string_at_least_32_chars
+
+ .env is listed in .gitignore; never commit it. For local dev, point
+ MYSQL_HOST at 127.0.0.1 so the host-side API can reach the containerised MySQL
+ through the published port 3309.
+
+
+ Step 2 — Start MySQL
+
+ Bring up only the database service from the root compose file. On first run it creates the volume, creates
+ the database and application user, and executes db/docker-init/01-schema.sh which loads tables,
+ functions, views, and stored procedures from db/Objects/ in the correct order.
+
+ docker compose up -d mysql
+docker compose logs -f mysql # watch for "Schema initialization complete"
+
+ MySQL is exposed on host port 3309 (mapped to container port 3306). To reset the
+ database during development, stop the container and remove the named volume:
+ docker compose down && docker volume rm winstudentgoaltracker_win_mysql_data.
+
+
+ Step 3 — Run the API
+ cd api
dotnet restore
dotnet run
+
+ The API listens on http://localhost:5000 (and https://localhost:5001) by default
+ via Kestrel. Swagger UI is available at /swagger when running in the
+ Development environment (the default for dotnet run). On startup the console
+ prints the resolved MySQL connection string — verify it points at 127.0.0.1:3309 and the
+ database name from your .env.
+
- Database
- Create DB, import schema, update .env.
+ Step 4 — Run the UI
+ cd ui/winstudentgoaltracker
+npm install
+npm start
+
+ The Angular dev server starts on http://localhost:4200. The base URL the UI calls is defined in
+ src/environments/environment.development.ts. For a fully local stack, edit that file so
+ apiBaseUrl points at your locally running API (e.g. http://localhost:5000) instead
+ of the deployed https://winapi.opelly.me. The API's CORS policy already allows any origin in
+ development.
+
- Docker
- docker-compose up --build
+ Step 5 — Seed a user
+
+ The schema initialises empty. To sign in, insert at least one user, one
+ school_district, one program, and a user_program row linking the user
+ to the program with a role. Passwords are hashed with PBKDF2 by PasswordHasher; the simplest
+ path is to use an existing seeded dump (ask a team member for seed.sql) or register via a
+ super_admin account using the admin endpoints.
+
+
+ 5.2 Production Deployment (Docker Compose + Traefik)
+
+ Production deploys all four tiers — MySQL, .NET API, Nginx-served Angular build, and the Traefik reverse
+ proxy — as Docker containers on a single VPS. The repository's docker-compose.yml brings up
+ MySQL, the API, and the UI; Traefik runs in a separate compose stack on the same host and
+ publishes ports 80/443 for the whole server. The two stacks communicate through an external Docker network
+ named web.
+
+
+ Prerequisites on the server
+
+ - Linux VPS with Docker Engine and the Compose plugin installed
+ - Ports 80 and 443 open on the server's firewall
+ - Two DNS
A records pointing at the server's public IP:
+ win.<your-domain> (UI) and winapi.<your-domain> (API)
+ - A working Traefik stack on the host (see next section)
+
+
+ Setting up Traefik (one-time)
+
+ Traefik is the edge router that terminates TLS, requests Let's Encrypt certificates, and forwards traffic to
+ the correct container based on the Host() rule. The WIN compose file assumes Traefik is already
+ running on the host and configured with:
+
+
+ - An external Docker network named
web that Traefik is attached to. The
+ application's UI and API containers join this network so Traefik can reach them.
+ docker network create web
+
+ - An entrypoint named
websecure listening on :443 (and typically
+ a redirect from :80).
+ - A certificate resolver named
letsencrypt (ACME, HTTP or DNS challenge)
+ configured with an email and a persistent acme.json volume.
+ - Two file-provider middlewares referenced by the labels in
docker-compose.yml:
+ gzip@file (compression) and
+ security-headers@file (HSTS, frame-deny, etc.).
+
+
+ A minimal Traefik docker-compose.yml typically lives in /opt/traefik/ alongside a
+ traefik.yml static config (declaring the entrypoints, providers, and ACME resolver) and a
+ dynamic/ directory containing the gzip and security-headers
+ middleware definitions. Traefik's official documentation at
+ doc.traefik.io covers this setup in detail — the WIN stack
+ does not prescribe a specific Traefik configuration, it only requires that the network, entrypoint, cert
+ resolver, and middleware names above exist.
+
+
+ Step 1 — Prepare the repository on the server
+ git clone <repo-url> /opt/winstudentgoaltracker
+cd /opt/winstudentgoaltracker
+
+ Step 2 — Populate .env
+ Same keys as the local workflow, but with production-safe values. For the containerised deployment,
+ MYSQL_HOST must be the service name mysql (the API container resolves it over the
+ internal backend Docker network) and MYSQL_PORT must be 3306 (the
+ container's internal port, not the host-mapped 3309):
+ MYSQL_ROOT_PASSWORD=<strong-random>
+MYSQL_DATABASE=winstudentgoaltracker
+MYSQL_USER=appuser
+MYSQL_PASSWORD=<strong-random>
+MYSQL_HOST=mysql
+MYSQL_PORT=3306
+JWT_KEY=<32+ byte random secret>
+
+ Step 3 — Update domain labels (if not using opelly.me)
+
+ docker-compose.yml hard-codes the Traefik Host() rules
+ winapi.opelly.me and win.opelly.me. Edit those two labels to match your DNS
+ records before bringing the stack up. The UI also points at https://winapi.opelly.me via
+ src/environments/environment.ts; update that file and rebuild the UI image so the browser calls
+ your API host.
+
+
+ Step 4 — Build and start the stack
+ docker compose up -d --build
+ This creates:
+
+ winstudent-mysql — MySQL 8 on the internal backend network, volume
+ win_mysql_data, schema loaded on first start.winstudent-api — .NET 9 API on port 8005, attached to both
+ backend (to reach MySQL) and web (to be reached by Traefik). Published at
+ winapi.<your-domain> over HTTPS.winstudent-ui — Angular build served by Nginx on port 8006, attached to
+ web. Published at win.<your-domain> over HTTPS.
+
+ Traefik picks up the new containers automatically via its Docker provider, requests TLS certificates from
+ Let's Encrypt on first request, and begins routing traffic. Confirm with
+ docker compose ps (all services healthy/running) and
+ docker compose logs -f api (look for the Kestrel startup line and the printed connection
+ string).
+
+
+ Step 5 — Verify
+
+ - Visit
https://win.<your-domain> — the login page should load over HTTPS with a valid
+ Let's Encrypt certificate.
+ - Visit
https://winapi.<your-domain>/swagger — should return 404 in production (Swagger
+ is only enabled in Development); a 404 from the API itself confirms routing works.
+ - Sign in with a seeded user and check
docker compose logs api for successful
+ /api/Auth/Login requests.
+
+
+ Updating a running deployment
+ cd /opt/winstudentgoaltracker
+git pull
+docker compose up -d --build # rebuilds changed images and recreates containers
+docker compose logs -f
+
+ MySQL is not rebuilt by --build (it uses the upstream image) and its volume
+ persists across up/down cycles, so data survives code deployments. Schema
+ migrations should be applied by running the appropriate SQL files from db/migrations/ against
+ the running MySQL container; see section 7 for backup procedures before running migrations.
+