From 87c9a11edcf5dbc527b07ba3b4d555e0726133c6 Mon Sep 17 00:00:00 2001
From: cesnimda <connor.babbington@cesnimda.co.uk>
Date: Sun, 22 Mar 2026 18:55:40 +0100
Subject: [PATCH] chore: document mariadb bootstrap and add deploy health
 checks

---
 .gitea/workflows/ci-deploy.yml     |  2 +
 JobTrackerApi/JobTrackerApi.csproj |  2 +-
 deploy/MARIADB.md                  | 76 ++++++++++++++++++++++++++++++
 deploy/README.md                   |  8 ++++
 4 files changed, 87 insertions(+), 1 deletion(-)
 create mode 100644 deploy/MARIADB.md

diff --git a/.gitea/workflows/ci-deploy.yml b/.gitea/workflows/ci-deploy.yml
index 477e322..bdeeac9 100644
--- a/.gitea/workflows/ci-deploy.yml
+++ b/.gitea/workflows/ci-deploy.yml
@@ -71,3 +71,5 @@ jobs:
             APP_BUILD_STAMP="$(date -u +'%Y-%m-%d %H:%M UTC')" \
             ./deploy/deploy.sh
             docker compose ps
+            docker compose exec -T backend sh -lc 'wget -qO- http://127.0.0.1:8080/api/auth/config >/dev/null'
+            docker compose exec -T summarizer python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8001/health', timeout=5).read()"
diff --git a/JobTrackerApi/JobTrackerApi.csproj b/JobTrackerApi/JobTrackerApi.csproj
index 13fabba..f4c38da 100644
--- a/JobTrackerApi/JobTrackerApi.csproj
+++ b/JobTrackerApi/JobTrackerApi.csproj
@@ -18,7 +18,7 @@
       <PrivateAssets>all</PrivateAssets>
     </PackageReference>
     <PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="9.0.2" />
-    <PackageReference Include="Pomelo.EntityFrameworkCore.MySql" Version="9.0.0-preview.3" />
+    <PackageReference Include="Pomelo.EntityFrameworkCore.MySql" Version="9.0.0-preview.3.efcore.9.0.0" />
   </ItemGroup>
 
 </Project>
diff --git a/deploy/MARIADB.md b/deploy/MARIADB.md
new file mode 100644
index 0000000..cc1ce11
--- /dev/null
+++ b/deploy/MARIADB.md
@@ -0,0 +1,76 @@
+# MariaDB production bootstrap
+
+## What this app supports
+- SQLite for local/dev fallback
+- MariaDB/MySQL for production when configured with:
+  - `DATABASE_PROVIDER=mariadb`
+  - `JOBTRACKER_CONNECTION_STRING=...`
+
+## 1. Create database and user in MariaDB
+Run this against your MariaDB server/container:
+
+```sql
+CREATE DATABASE jobtracker CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+CREATE USER 'jobtracker'@'%' IDENTIFIED BY 'REPLACE_WITH_STRONG_PASSWORD';
+GRANT ALL PRIVILEGES ON jobtracker.* TO 'jobtracker'@'%';
+FLUSH PRIVILEGES;
+```
+
+## 2. Configure server `.env`
+Example:
+
+```env
+DATABASE_PROVIDER=mariadb
+JOBTRACKER_CONNECTION_STRING=server=mariadb;port=3306;database=jobtracker;user=jobtracker;password=REPLACE_WITH_STRONG_PASSWORD
+AUTH_JWT_KEY=replace_with_long_random_secret
+AUTH_ADMIN_EMAIL=you@example.com
+AUTH_ADMIN_PASSWORD=replace_with_strong_password
+APP_PUBLIC_BASE_URL=https://your-domain.example
+SUMMARIZER_BASE_URL=http://summarizer:8001
+```
+
+## 3. First startup
+On first deploy, the API will run EF migrations at startup.
+That means the MariaDB schema is created automatically as long as:
+- the DB exists
+- credentials are correct
+- the backend container can reach `mariadb`
+
+## 4. SQLite to MariaDB migration notes
+This repo does **not** yet include an automated data migration tool.
+If you already have real data in SQLite, recommended migration path is:
+
+1. Stop writes to the app
+2. Back up SQLite DB file
+3. Start MariaDB-backed environment on a staging copy
+4. Export/import the critical tables with a small migration script or one-time tool
+5. Validate users, companies, jobs, correspondence, attachments metadata
+6. Switch production `.env` to MariaDB
+
+## Tables you would likely want to migrate
+- `AspNetUsers`
+- `AspNetRoles`
+- `AspNetUserRoles`
+- `Companies`
+- `JobApplications`
+- `Correspondences`
+- `Attachments`
+- `JobEvents`
+- `GmailConnections`
+- `UserRuleSettings`
+
+## Important note on attachments
+Files are stored separately from DB rows.
+When moving environments, make sure you preserve:
+- `/data`
+- especially attachments and data-protection keys
+
+## Suggested validation checklist after switching
+- can log in with admin user
+- profile loads
+- jobs list loads
+- correspondence loads
+- attachments metadata still matches files on disk
+- summarizer works
+- reminders page works
+- admin/system page loads
diff --git a/deploy/README.md b/deploy/README.md
index 47c1d21..024808d 100644
--- a/deploy/README.md
+++ b/deploy/README.md
@@ -63,3 +63,11 @@ If this app is going to be a real production service on Ubuntu:
 2. Gitea Actions runs tests
 3. if green, workflow uploads repo to server
 4. `deploy/deploy.sh` runs `docker compose build && docker compose up -d`
+5. workflow checks service status after deployment
+
+## Post-deploy verification you should also do manually the first time
+- confirm reverse proxy routes to the frontend correctly
+- confirm API auth/login works with production config
+- confirm backend can connect to MariaDB
+- confirm summarizer container is reachable from backend
+- confirm reminder and admin/system pages load