108 lines
3.7 KiB
Markdown
108 lines
3.7 KiB
Markdown
# Mobile app releases (Android APK)
|
|
|
|
Tloto can distribute Android APK updates from its own infrastructure without Google Play.
|
|
|
|
## Architecture
|
|
|
|
- **Admin web**: Options → Mobile versions (`/admin/mobile-versions`)
|
|
- **API public**: `GET /api/v1/app-updates/android`, download + events
|
|
- **API admin**: `/api/v1/admin/mobile-releases*`
|
|
- **Storage**: Docker volume `apk_releases` → `/app/data/apk-releases/{staging|published}`
|
|
- **Flutter**: checks at splash + resume, downloads APK, verifies SHA-256, opens system installer
|
|
|
|
## Prerequisites — Android signing
|
|
|
|
Upgrades replace the installed app **only if**:
|
|
|
|
1. Same `applicationId` (`com.prediqo.mobile`)
|
|
2. Same signing certificate
|
|
3. Higher `versionCode`
|
|
|
|
### Create a release keystore (once)
|
|
|
|
```bash
|
|
keytool -genkey -v -keystore tloto-release.jks -keyalg RSA -keysize 2048 -validity 10000 -alias tloto
|
|
```
|
|
|
|
Store the `.jks` **offline** (password manager / encrypted backup). Never commit it or leave it only on the VPS.
|
|
|
|
### Wire Flutter release signing
|
|
|
|
1. Copy `prediqo_mobile/android/key.properties.example` → `key.properties`
|
|
2. Fill `storePassword`, `keyPassword`, `keyAlias`, `storeFile`
|
|
3. Build: `flutter build apk --release`
|
|
|
|
### Fingerprint for the backend
|
|
|
|
```bash
|
|
keytool -list -v -keystore tloto-release.jks -alias tloto
|
|
# Copy SHA-256 certificate fingerprint (hex), strip colons
|
|
```
|
|
|
|
Set in `.env` / Compose:
|
|
|
|
```env
|
|
ANDROID_APK_EXPECTED_CERT_SHA256=<hex without colons>
|
|
ANDROID_APK_EXPECTED_PACKAGE=com.prediqo.mobile
|
|
```
|
|
|
|
Empty fingerprint skips cert check (dev only).
|
|
|
|
The API reads the signing cert from APK Signature Scheme **v2/v3** (and JAR v1 when present). Modern Flutter release APKs often have no `META-INF/*.RSA`.
|
|
|
|
## Admin publish flow
|
|
|
|
1. Create a release (version name + **versionCode** strictly greater than the current published one)
|
|
2. Upload the signed `.apk`
|
|
3. Backend validates package name, versionCode, optional cert fingerprint, computes file SHA-256
|
|
4. Submit → Publish
|
|
5. Optionally set rollout % (5 / 20 / 50 / 100) and update policy (optional / recommended / mandatory)
|
|
|
|
### Suspend / rollback
|
|
|
|
- **Suspend** or **retire** stops offering that APK to new checks
|
|
- Devices that already installed it **cannot** be downgraded; ship a higher `versionCode` hotfix instead
|
|
|
|
## Mobile client behaviour
|
|
|
|
- Compares installed `buildNumber` (versionCode) to server
|
|
- Policies:
|
|
- optional / recommended → dismissible dialog
|
|
- mandatory (or below `min_supported_version_code`) → blocking dialog; sensitive APIs return **426**
|
|
- Download over HTTPS with HMAC token; size + SHA-256 verified before install
|
|
- Android system installer prompt is never bypassed
|
|
|
|
## Backup & VPS migration
|
|
|
|
```bash
|
|
# List volumes
|
|
docker volume ls | grep apk
|
|
|
|
# Backup APK volume
|
|
docker run --rm -v <project>_apk_releases:/data -v "$(pwd)":/backup alpine \
|
|
tar czf /backup/apk_releases.tgz -C /data .
|
|
|
|
# Restore on new host then recreate stack with the same volume name
|
|
```
|
|
|
|
Also dump PostgreSQL tables `mobile_app_releases`, `mobile_app_release_events`, `mobile_app_update_settings`.
|
|
|
|
`storage_key` values are relative (`published/<uuid>.apk`) so the mobile `downloadUrl` contract stays API-driven if you later move blobs to object storage.
|
|
|
|
## iOS
|
|
|
|
Architecture reserves `platform=ios` but **does not** distribute IPA files. Future: App Store / TestFlight links only.
|
|
|
|
## Manual test checklist
|
|
|
|
- [ ] Detect new version (versionCode +1)
|
|
- [ ] Optional update — Later still uses the app
|
|
- [ ] Recommended update messaging
|
|
- [ ] Mandatory update blocks bets / withdraw (426)
|
|
- [ ] Interrupted download / bad network
|
|
- [ ] Corrupted APK / wrong SHA-256 rejected
|
|
- [ ] Wrong signing cert rejected on upload
|
|
- [ ] User cancels Android installer
|
|
- [ ] Local session retained after successful update
|
|
- [ ] Suspended release no longer offered
|