From 07b2650f116dd51a4c26e2bd92f6dd274f5e49fd Mon Sep 17 00:00:00 2001 From: kckagancan <118129306+kckagancan@users.noreply.github.com> Date: Tue, 12 May 2026 11:33:49 +0300 Subject: [PATCH 1/4] doc: prepare submision documents --- README.md | 76 ++++++++++++++++++++++++----- android/.env.example | 7 +++ android/keystore.properties.example | 14 +++--- backend/.env.example | 2 + web/.env.example | 13 +++-- 5 files changed, 90 insertions(+), 22 deletions(-) create mode 100644 android/.env.example diff --git a/README.md b/README.md index 1bfa1d8a..53db8697 100644 --- a/README.md +++ b/README.md @@ -74,6 +74,11 @@ For Android development: - Android Studio - Android SDK compatible with the project +## Live deployment + +- Web app: `LIVE_WEB_URL_TO_BE_FILLED_BEFORE_RELEASE` +- 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,7 +177,52 @@ 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. + +### 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`. + +The signed release APK must be attached to the GitHub Release manually or by the release workflow. + +### Optional legacy demo data seed 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. @@ -237,17 +290,18 @@ Relevant files: - `web/Dockerfile` - `infra/docker/postgres/init.sql` -## Mobile note - -The Android application lives in `android/`. +## Deployment note -- 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 +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. -## Deployment note +## Final release checklist -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. +- 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 diff --git a/android/.env.example b/android/.env.example new file mode 100644 index 00000000..39c88e5a --- /dev/null +++ b/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 diff --git a/android/keystore.properties.example b/android/keystore.properties.example index 062bd582..39c88e5a 100644 --- a/android/keystore.properties.example +++ b/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 \ No newline at end of file +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 diff --git a/backend/.env.example b/backend/.env.example index c87ec8ac..6d114bd1 100644 --- a/backend/.env.example +++ b/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 diff --git a/web/.env.example b/web/.env.example index 8bbf785c..93d194e7 100644 --- a/web/.env.example +++ b/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 From b7267ae2f5c0b87af2ab342438184163212ea540 Mon Sep 17 00:00:00 2001 From: kckagancan <118129306+kckagancan@users.noreply.github.com> Date: Tue, 12 May 2026 11:49:14 +0300 Subject: [PATCH 2/4] doc: improve README file --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index 53db8697..3da86d29 100644 --- a/README.md +++ b/README.md @@ -220,6 +220,8 @@ cp keystore.properties.example keystore.properties 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. ### Optional legacy demo data seed @@ -290,6 +292,14 @@ Relevant files: - `web/Dockerfile` - `infra/docker/postgres/init.sql` +### 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`. + +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. + +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 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. From 2a76528393a2f0872fbb42e3cb141d0e6af9f81c Mon Sep 17 00:00:00 2001 From: kckagancan <118129306+kckagancan@users.noreply.github.com> Date: Tue, 12 May 2026 12:34:43 +0300 Subject: [PATCH 3/4] doc: add new demo data into README --- README.md | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3da86d29..37e28472 100644 --- a/README.md +++ b/README.md @@ -224,9 +224,29 @@ Debug Android emulator builds use `http://10.0.2.2:3000/api` to reach the host b 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 -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. +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: @@ -292,7 +312,7 @@ Relevant files: - `web/Dockerfile` - `infra/docker/postgres/init.sql` -### Production setup +## 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`. From 6f0b8c46039ce46ad3224298fd2ab9c77d1d436b Mon Sep 17 00:00:00 2001 From: kckagancan <118129306+kckagancan@users.noreply.github.com> Date: Tue, 12 May 2026 12:45:10 +0300 Subject: [PATCH 4/4] fix: replace placeholder url with neph url --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 37e28472..cea1efa7 100644 --- a/README.md +++ b/README.md @@ -76,7 +76,7 @@ For Android development: ## Live deployment -- Web app: `LIVE_WEB_URL_TO_BE_FILLED_BEFORE_RELEASE` +- Web app: `https://neph.app/` - Backend API: `https://api.neph.app/api` ## Environment variables