# Release

Run the commands in the project folder, in PowerShell or Git Bash. Example version: `2.4.0`.
First release? Do [Before the first release](#before-the-first-release) once.

## Tools this file assumes

| tool | used by |
|---|---|
| Node 22 + `npm ci` | every `npm run …` command — full list in [README](README.md#requirements-on-a-new-machine) |
| Git Bash (Windows) or any bash (Linux) | all commands below and `scripts/*.sh`; PowerShell runs the `npm` ones only |
| `curl` | `scripts/verify-deploy.sh`, `scripts/cache-probe.sh` |
| `ssh` + WSL `rsync`, or aaPanel's file manager | uploading `./out` in step 2 |
| `npx serve` | checking `./out` locally in step 1 |
| JDK 21, Android SDK 36, `android/keystore.properties` | `build:android` only — full list in [native.md](native.md#requirements) |
| a Mac with Xcode | iOS only, once — [native.md](native.md#ios-once-on-a-mac) |

## Steps

### 1. Build

```bash
npm run deploy:prepare -- --version 2.4.0 --grace 3
npm run build:android -- --mirrors
npm run app-update -- --platform android --channel direct --version 2.4.0
npx serve out
```

1. Sets the version and builds the website into `./out`.
2. Builds the APKs into `build/native/artifacts/`, and copies the website APK to `out/download/rangook-android.apk`.
3. Announces the new website APK to installed apps.
4. Check http://localhost:3000, then Ctrl+C.

Website-only release: skip `build:android` and `app-update`.

### 2. Upload `./out`

Site folder: `/www/wwwroot/app.rangook.ir` (check it in aaPanel → Website).

**aaPanel:** compress everything inside `./out` (not the folder itself, and not into `./out`), with `.htaccess`. Files → site folder → upload → extract, replacing files → delete the archive. Then Graceful Restart OpenLiteSpeed.

**Or SSH** (`user@host` = your server login):

```bash
wsl rsync -av --delete-after ./out/ user@host:/www/wwwroot/app.rangook.ir/
ssh user@host /usr/local/lsws/bin/lswsctrl restart
```

Then in Git Bash. It must end with "All checks passed.":

```bash
bash scripts/verify-deploy.sh
```

### 3. Stores

| file in `build/native/artifacts/` | upload to |
|---|---|
| `rangook-2.4.0-2040000-bazaar.apk` | Cafe Bazaar developer panel |
| `rangook-2.4.0-2040000-myket.apk` | Myket developer panel |

### 4. After each store publishes

```bash
npm run app-update -- --platform android --channel bazaar --version 2.4.0
```

Upload `public/app-update.json` to the site folder (aaPanel, or `wsl rsync -av public/app-update.json user@host:/www/wwwroot/app.rangook.ir/`). The same for `--channel myket`. Then commit `public/app-update.json`.

## Versions

| | |
|---|---|
| set by | `deploy:prepare --version`: one version for the website and the apps |
| next version | fixes `2.4.1`, new features `2.5.0`. Never reuse or lower one |
| Android build number | automatic: `2.4.0` → `2040000` (MINOR and PATCH 0-99). Must go up with every store upload |
| app-only fix, same version | add `--build-number 1` to `build:android` and to every `app-update` (`2040001`), then steps 2-4 |

## version.json (website)

`deploy:prepare` writes it: the version and a new build id, in `out/version.json`. It goes live with the upload; open tabs see the new build id and reload onto the new version. Never edit it. `public/version.json` changes with every build; ignore it.

## app-update.json (apps)

One file for every app, at `https://app.rangook.ir/app-update.json`, with one entry per platform and store: `android.bazaar`, `android.myket`, `android.direct`, later `ios.<store>`. `app-update` changes only the entry you name, in `public/` and `out/`.

Each app reads its own entry at launch, and when reopened after 30+ minutes:

| the app's build | user sees |
|---|---|
| ≥ `latestBuild` | nothing |
| < `latestBuild` | "new version" sheet ("later" hides it for 24 h) |
| < `minimumBuild` | a screen they cannot close until they update |

`npm run app-update -- --platform android --channel <store>` plus:

| option | does |
|---|---|
| `--version 2.4.0` | a new release on that store. Direct: the link `rangook-android.apk?v=2040000` is added for you |
| `--minimum 2.4.0` | older versions must update (only once 2.4.0 is live on that store). `--minimum none` undoes it |
| `--note "..."` | a line in the update sheet, repeatable; replaces the old lines |

`npm run app-update -- --show` prints the file. Upload it after every change. If it is missing or broken, the apps show no prompt and keep working.

Website APK link for landing pages, always the newest: `https://app.rangook.ir/download/rangook-android.apk`

## Before the first release

1. Backend: merge `feature/app-payment-return` into `master`, deploy it, then on the server run `php artisan optimize:clear`.
2. Merge `feature/native-apps` into `main`, and release from `main`.
3. `.env.local`: set `NEXT_PUBLIC_API_BASE_URL` and `NEXT_PUBLIC_SENTRY_DSN`. The scripts set the rest; never set `NEXT_PUBLIC_APP_TARGET`.
4. Android build PC: Node 22, `JAVA_HOME` = JDK 21, `ANDROID_HOME` = Android SDK with platform 36, and `android/keystore.properties` ([native.md](native.md#signing)).
5. SSH uploads only: rsync deletes what is not in `./out`, so first make `./out` equal to the live site:

   ```bash
   wsl rsync -av --delete user@host:/www/wwwroot/app.rangook.ir/ ./out/
   ```

6. Ask Cafe Bazaar whether course payments through Zarinpal are allowed; they may require their own billing.

## Rules

- Back up the signing key (`E:\PishiStudio\rangook\signing\`). Without it the app can never be updated.
- Build the website only with `deploy:prepare`, never a bare `npm run build`: it keeps the APK in `./out`.
- Only the website APK goes on the website; the store APKs go only to their stores.
- A website release does not change the apps. App code changes need a new APK.

## iOS

Not ready: it needs a Mac, the setup in [native.md](native.md#ios-once-on-a-mac), and a store that accepts Iranian developers (e.g. Sibche, Sibapp). Then per release: `npm run build:ios`, `npx cap open ios`, set Version `2.4.0` and Build `2040000` in Xcode, Archive, upload, and announce with `npm run app-update -- --platform ios --channel <store> --version 2.4.0`.
