Deployment Instructions

1. Architecture Overview

FieldNotes AI is a cross-platform mobile and web app built with React Native (Expo). The backend is a self-hosted Supabase instance running on the client's Azure VM via Docker Compose. Sensitive third-party services (Azure OpenAI and Azure Speech) are accessed through Supabase Edge Functions so API keys never leave the server.

Layer	Technology	Where It Runs
Frontend	React Native / Expo (TypeScript)	iOS, Android, Web Browser
Backend / Auth / DB	Supabase (self-hosted)	Azure VM via Docker Compose
Serverless Functions	Supabase Edge Functions (Deno)	Supabase VM
AI Services	Azure OpenAI + Azure Speech	Proxied via Edge Functions
CI/CD	GitHub Actions	GitHub (all PRs to main / sprint*)

2. Prerequisites

Make sure the following are installed before starting.

Requirement	Version	Purpose
Node.js	v18 LTS or later	Run Expo / npm scripts
npm	v9+	Package management
Expo CLI	Latest (via npx)	Build and run the app
Git	Any recent version	Clone the repository
SSH client	OpenSSH or equivalent	Access the Azure VM
SSH private key	From team Discord	Authenticate to Supabase VM
Supabase CLI	Latest	Deploy Edge Functions and migrations

Note: VM credentials (IP, username, SSH key filename) are shared in the team Discord. Do not commit these to the repository.

3. Environment Configuration

3.1 Clone the Repository

git clone https://github.com/ualberta-cmput401/W26project-JarilloConsulting.git
cd W26project-JarilloConsulting/fieldnotes-ai-app
npm install
cp .env.example .env

Then fill in real values in .env.

3.2 Required Environment Variables

The .env file lives in the fieldnotes-ai-app/ directory.

Variable	Example Value	Required
EXPO_PUBLIC_AUTH_PROVIDER	supabase	Yes
EXPO_PUBLIC_SUPABASE_URL	https://api.jarilloengineering.com	Yes
EXPO_PUBLIC_SUPABASE_ANON_KEY	<anon key from Supabase dashboard>	Yes

Note: Azure API keys (OpenAI, Speech) are not needed in .env. They are stored as Supabase Edge Function secrets on the server.

For local development without Supabase, set EXPO_PUBLIC_AUTH_PROVIDER=mock and use practitioner@test.com / password123 or admin@test.com / admin123.

4. Supabase Backend Deployment

Supabase runs on the client's Azure VM using Docker Compose. The public endpoint is https://api.jarilloengineering.com.

4.1 SSH Access to the VM

Add the following to your ~/.ssh/config file:

Host supabase-vm
    HostName <vm-ip>
    User <username>
    IdentityFile ~/.ssh/<keyfile>.pem
    IdentitiesOnly yes

Then connect with:

ssh supabase-vm

4.2 Verify Docker Services

Once SSHed in, confirm all Supabase containers are running:

cd ~/supabase-deployment/supabase/docker
docker compose ps

If a container is down, restart it:

docker compose restart <service-name>

To view logs:

docker compose logs -f <service-name>

4.3 Access Supabase Studio

Use an SSH tunnel to access the Studio dashboard locally:

ssh -L 8001:localhost:8000 supabase-vm

Then open http://localhost:8001 in your browser.

To get the dashboard credentials while SSHed in:

cat ~/supabase-deployment/supabase/docker/.env | grep DASHBOARD

5. Database Migrations

Schema changes are tracked as SQL files under fieldnotes-ai-app/supabase/migrations/.

5.1 Apply Migrations

Install the Supabase CLI if not already installed:

npm install -g supabase

Link the CLI to the remote project (run once from the fieldnotes-ai-app directory):

supabase login
supabase link --project-ref <project-id>

Push all pending migrations:

supabase db push

Note: Only run migrations against the production VM during a scheduled maintenance window or after team approval.

5.2 Row Level Security (RLS)

RLS policies are in fieldnotes-ai-app/supabase/policies/ for readability. The deployed policies are part of the remote_schema migration. To update a policy, add a new migration file. Do not edit the remote_schema file directly.

6. Edge Function Deployment

Edge Functions handle all calls to Azure OpenAI, Azure Speech, and admin user creation. They live in fieldnotes-ai-app/supabase/functions/.

6.1 Deploy All Functions

cd fieldnotes-ai-app
supabase functions deploy azure-openai
supabase functions deploy azure-speech
supabase functions deploy admin-create-user

6.2 Set Function Secrets

Azure API keys must be set as Supabase secrets via the CLI, never in .env:

supabase secrets set AZURE_OPENAI_KEY=<your-key>
supabase secrets set AZURE_OPENAI_ENDPOINT=<your-endpoint>
supabase secrets set AZURE_SPEECH_KEY=<your-key>
supabase secrets set AZURE_SPEECH_REGION=<your-region>

Note: Secrets are never stored in the repository. The app calls Edge Functions via supabase.functions.invoke() so no Azure keys reach the mobile bundle.

7. Application Deployment

Make sure the .env file is configured correctly (Section 3) before running or building.

7.1 Run Locally (Development)

cd fieldnotes-ai-app
npx expo start
npx expo start --tunnel

Platform-specific dev servers:

npx expo start --ios
npx expo start --android
npx expo start --web

7.2 Production Web Build

npx expo export --platform web

Output is in the dist/ folder. Deploy dist/ to any static host (Netlify, Vercel, Azure Static Web Apps, etc.).

7.3 Production iOS / Android Build

Use EAS (Expo Application Services) for native builds:

npm install -g eas-cli
eas login
eas build --platform ios
eas build --platform android

Note: Native store submissions require additional credentials (certificates, provisioning profiles). Coordinate with the client before attempting a production mobile release.

8. CI/CD Pipeline

GitHub Actions automatically runs the full pipeline on every push or PR to main or sprint* branches.

8.1 Pipeline Stages

Stage	What It Does
Setup	Install Node and npm dependencies
Lint	ESLint checks (npm run lint)
Type Check	TypeScript validation (npx tsc --noEmit)
Test	Jest unit tests with coverage (npm test)
Build	Verify iOS, Android, and Web exports

8.2 Run CI Locally Before Pushing

make test
make test-fix

8.3 Branch and Release Strategy

All production releases are cut from main. Feature branches must be merged into the current sprint branch via a PR with at least 2 reviews (3 for PRs to main). The Scrum Master must approve sprint-to-main merges.

9. Post-Deployment Verification

Run through this checklist after completing all steps above.

• [ ] All Docker containers on the Azure VM show status running (docker compose ps)
• [ ] Supabase Studio is accessible via SSH tunnel at http://localhost:8001
• [ ] App starts without errors: npx expo start
• [ ] Login works with a real Supabase account (not mock mode)
• [ ] Practitioners see only their own cases (RLS enforced)
• [ ] Admin can create a new user via the Edge Function (admin-create-user)
• [ ] Audio recording uploads to the audio-recordings storage bucket
• [ ] AI summarisation returns a result (Azure OpenAI Edge Function responds)
• [ ] Speech-to-text transcription works (Azure Speech Edge Function responds)
• [ ] make test passes with no failures locally
• [ ] GitHub Actions CI passes on the sprint branch

10. Common Issues and Troubleshooting

Symptom	Fix
Module not found @/...	Run make clean, then check tsconfig.json path aliases
Expo SDK version mismatch	Run npx expo install --fix and commit
Port 8081 already in use	Run lsof -ti:8081 \| xargs kill -9
Install / dependency failures	Run make reset to regenerate node_modules
Supabase 401 Unauthorized	Check EXPO_PUBLIC_SUPABASE_ANON_KEY in .env
Supabase 403 Forbidden	RLS policy is blocking; check user role in Supabase
Edge Function returns error	Check supabase secrets set; secrets may be missing
Docker container is down	SSH in and run docker compose restart <service>
CI lint failure	Run npm run lint:fix locally, commit, and re-push
CI test timeout	Increase waitFor timeout or add missing await in test

11. Key References

1. Project docs site: https://ualberta-cmput401.github.io/W26project-JarilloConsulting/
2. Supabase Studio (via SSH tunnel): http://localhost:8001
3. Production API endpoint: https://api.jarilloengineering.com
4. VM credentials and SSH key: Team Discord channel
5. GitHub repo: https://github.com/ualberta-cmput401/W26project-JarilloConsulting

Note: Sensitive credentials (VM IP, SSH keys, Azure API keys, Supabase service role key) must never be committed to the repository. Share via Discord or a secure password manager.