From a8f4b06b66765748e19f6cc75ac1130098860333 Mon Sep 17 00:00:00 2001 From: Oliver Pelly Date: Sat, 18 Apr 2026 23:23:52 +0100 Subject: [PATCH] added developer install and deply instructions. --- docs/technical.html | 219 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 207 insertions(+), 12 deletions(-) diff --git a/docs/technical.html b/docs/technical.html index 41deabe..66451b6 100644 --- a/docs/technical.html +++ b/docs/technical.html @@ -1224,25 +1224,220 @@

5. Application Installation

+

+ 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. +

-

Prerequisites

-

Node.js, .NET 9 SDK, MySQL, Docker

+

5.1 Local Development Environment

+

+ 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. +

-

Frontend

- 
cd frontend
-npm install
-npm start
+

Prerequisites

+ -

Backend

- 
cd 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.
+