docs: prepare final release submission documents

README.md

@@ -74,6 +74,11 @@ For Android development:
 - Android Studio
 - Android SDK compatible with the project
 
+## Live deployment
+
+- Web app: `https://neph.app/`
+- Backend API: `https://api.neph.app/api`
+
 ## Environment variables
 
 Keep secrets and real credentials out of the repository. Use local env files or shell overrides.
@@ -105,6 +110,7 @@ Notes:
 - Email-based flows require valid SMTP credentials.
 - Placeholder SMTP values in the example file are not usable as-is.
 - In Docker Compose, the backend connects to PostgreSQL through the internal service name `postgres`.
+- Production deployments must use real database credentials and secure secrets. `JWT_SECRET` must not remain at the default value in production.
 
 ### Web
 
@@ -119,8 +125,10 @@ Important variables include:
 
 Notes:
 
-- `NEXT_PUBLIC_API_BASE_URL` is used for browser-facing requests.
-- `API_BASE_URL` can be used for server-side requests inside the Docker network.
+- `NEXT_PUBLIC_API_BASE_URL` is the browser/client-side API base.
+- `API_BASE_URL` is the server-side Next.js rewrite target.
+- `/api` works for Docker and Next.js rewrite usage.
+- `http://localhost:3000/api` works for direct backend access outside the rewrite path.
 
 ### Docker Compose overrides
 
@@ -169,9 +177,76 @@ Notes:
 - the backend waits for PostgreSQL to become healthy before starting
 - the web container is configured to talk to the backend in the local Docker setup
 
-### Optional demo data seed
+### Backend setup
+
+To run the backend directly:
+
+```bash
+cd backend
+cp .env.example .env
+npm install
+npm run migrate
+npm start
+```
+
+Use real database credentials and secure secrets for production. `JWT_SECRET` must not remain at the default value in production.
 
-Demo-ready data is stored as SQL seed migrations under `backend/demo-migrations/`, but it is not applied by the normal backend migration flow. This keeps regular `npm run migrate` and `start:with-migrations` safe for normal environments.
+### Web setup
+
+To run the web app directly:
+
+```bash
+cd web
+cp .env.example .env.local
+npm install
+npm run dev
+npm run build
+npm run start
+```
+
+Use `NEXT_PUBLIC_API_BASE_URL=/api` with the Next.js rewrite, including Docker. Use `NEXT_PUBLIC_API_BASE_URL=http://localhost:3000/api` when the browser should call the backend directly.
+
+### Mobile setup
+
+To build the Android app:
+
+```bash
+cd android
+cp .env.example .env
+cp keystore.properties.example keystore.properties
+./gradlew :app:assembleDebug
+./gradlew :app:assembleRelease
+```
+
+Debug Android emulator builds use `http://10.0.2.2:3000/api` to reach the host backend. Do not use `localhost` from inside the emulator for the host backend. Release builds use `NEPH_RELEASE_API_BASE_URL`, defaulting to `https://api.neph.app/api`.
+
+`android/.env.example` is included for submission documentation. Local Gradle builds read release values from `keystore.properties`, environment variables, or Gradle properties. Before running `./gradlew :app:assembleRelease`, replace the placeholder values in `keystore.properties` with real signing values and make sure the keystore file exists at `ANDROID_KEYSTORE_PATH`. Do not include real secrets in the repository.
+
+The signed release APK must be attached to the GitHub Release manually or by the release workflow.
+
+### Final Boğaziçi demo data
+
+Final demo data is stored in the normal backend migration flow:
+
+- `backend/migrations/20260512_120000__seed_bogazici_final_demo_data.sql`
+
+It is applied by the normal backend migration runner. In Docker Compose, backend migrations run automatically on startup, so no separate `ENABLE_DEMO_SEED=true npm run seed:demo` command is needed for the Boğaziçi final demo data after migrations run. The old `backend/demo-migrations/` flow is optional legacy demo data only.
+
+Boğaziçi final demo accounts:
+
+| Email | Password |
+| --- | --- |
+| `bogazici_reserve_1@neph.test` | `DemoPass123!` |
+| `bogazici_reserve_2@neph.test` | `DemoPass123!` |
+| `bogazici_reserve_3@neph.test` | `DemoPass123!` |
+| `bogazici_reserve_4@neph.test` | `DemoPass123!` |
+| `bogazici_assigned_1@neph.test` | `DemoPass123!` |
+| `bogazici_assigned_2@neph.test` | `DemoPass123!` |
+| `bogazici_requester_new_hall@neph.test` | `DemoPass123!` |
+
+### Optional legacy demo data seed
+
+Additional legacy demo-ready data is stored as SQL seed migrations under `backend/demo-migrations/`, but it is not applied by the normal backend migration flow. This keeps regular `npm run migrate` and `start:with-migrations` safe for normal environments.
 
 To apply the demo dataset intentionally, run the regular migrations first and then run the guarded demo seed command:
 
@@ -237,17 +312,26 @@ Relevant files:
 - `web/Dockerfile`
 - `infra/docker/postgres/init.sql`
 
-## Mobile note
+## Production setup
+
+Production deployment requires backend production environment values for database credentials or `DATABASE_URL`, a secure `JWT_SECRET`, SMTP values if email flows are used, Google OAuth values if Google Sign-In is used, and push notification values if push delivery is enabled. It also requires web production values for `NEXT_PUBLIC_API_BASE_URL` and `API_BASE_URL`.
 
-The Android application lives in `android/`.
+Use secure secrets instead of demo/default values. Start the backend with the normal migration-enabled startup flow so SQL migrations are applied before serving traffic.
 
-- local debug builds are expected to reach the backend through the emulator bridge at `http://10.0.2.2:3000`
-- Android is not part of the root Docker Compose workflow
-- mobile build and release steps are handled separately from the local Docker setup
+Before final release, verify the backend health endpoint, the backend API base at `https://api.neph.app/api`, and the deployed web URL. The signed Android APK must be attached to the GitHub Release.
 
 ## Deployment note
 
-This README focuses on local development and evaluation. Deployment- and release-related files may exist elsewhere in the repository, but the top-level guide is intentionally centered on how to build and run the project locally.
+The deployed backend API base is `https://api.neph.app/api`. The deployed web URL must be filled into this README and the GitHub Release notes before final submission if it is not already known.
+
+## Final release checklist
+
+- Code is merged to `main`.
+- Tag `final-milestone` points to the final `main` commit.
+- GitHub Release name is `1.0.0`.
+- GitHub Release is official, not a pre-release.
+- Release notes include the deployed web URL.
+- Signed APK is attached to the GitHub Release.
 
 ## Development notes
 

android/.env.example

@@ -0,0 +1,7 @@
+NEPH_RELEASE_API_BASE_URL=https://api.neph.app/api
+GOOGLE_SERVER_CLIENT_ID=YOUR_GOOGLE_SERVER_CLIENT_ID
+
+ANDROID_KEYSTORE_PATH=release.keystore
+ANDROID_KEYSTORE_PASSWORD=YOUR_KEYSTORE_PASSWORD
+ANDROID_KEY_ALIAS=YOUR_KEY_ALIAS
+ANDROID_KEY_PASSWORD=YOUR_KEY_PASSWORD

android/keystore.properties.example

@@ -1,7 +1,7 @@
-ANDROID_KEYSTORE_PATH=neph-release-key.jks
-ANDROID_KEYSTORE_PASSWORD=CHANGE_ME
-ANDROID_KEY_ALIAS=neph-release
-ANDROID_KEY_PASSWORD=CHANGE_ME
-NEPH_RELEASE_API_BASE_URL=https://YOUR-REAL-BACKEND/api
-# OAuth – Web Client ID from Google Cloud Console (same project as google-services.json)
-GOOGLE_SERVER_CLIENT_ID=YOUR_GOOGLE_SERVER_CLIENT_ID
+NEPH_RELEASE_API_BASE_URL=https://api.neph.app/api
+GOOGLE_SERVER_CLIENT_ID=YOUR_GOOGLE_SERVER_CLIENT_ID
+
+ANDROID_KEYSTORE_PATH=release.keystore
+ANDROID_KEYSTORE_PASSWORD=YOUR_KEYSTORE_PASSWORD
+ANDROID_KEY_ALIAS=YOUR_KEY_ALIAS
+ANDROID_KEY_PASSWORD=YOUR_KEY_PASSWORD

backend/.env.example

@@ -36,3 +36,5 @@ NOTIFICATION_PENDING_REQUEST_TTL_HOURS=72
 HELP_REQUEST_GUEST_CREATE_ENABLED=true
 HELP_REQUEST_GUEST_MATCHING_ENABLED=false
 HELP_REQUEST_GUEST_TOKEN_TTL=2h
+VOLUNTEER_LOCATION_MAX_AGE_MINUTES=120
+VOLUNTEER_AVAILABILITY_TTL_MINUTES=360

web/.env.example

@@ -1,6 +1,11 @@
-NEXT_PUBLIC_API_BASE_URL=http://localhost:3000
+# Browser/client-side API base.
+# For Docker/Next.js rewrite usage, keep this as /api.
+# For direct backend access, use http://localhost:3000/api.
+NEXT_PUBLIC_API_BASE_URL=/api
 
-# Google OAuth — required for Google Sign-In
-# Must match the GOOGLE_CLIENT_ID set in the backend .env
-# Get this from https://console.cloud.google.com/apis/credentials
+# Server-side Next.js rewrite target.
+API_BASE_URL=http://localhost:3000/api
+
+# Google OAuth — required for Google Sign-In.
+# Must match the GOOGLE_CLIENT_ID set in the backend environment.
 NEXT_PUBLIC_GOOGLE_CLIENT_ID=YOUR_GOOGLE_CLIENT_ID