MetatroncubeSoftwareSolutions/Metatron_Student_ERP
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Metatron_Student_ERP/PHASE_12_RELEASE_READINESS_REPORT.md

14 KiB
Raw Blame History

Phase 12: Metatron Student ERP — Deployment and Mobile App Release Preparation Report

Date: October 15, 2026
Auditor/Release Engineer: Antigravity Autonomous Agent
Environment: Backend: Odoo 19 Community Edition (metatron_academic) | Database: PostgreSQL 15 (metatron_aca_erp) | Mobile App: Flutter (flutter_app/)
Current Branch: main

1. Baseline Branch, Commit, Working-Tree Status, and Unpushed Commits

  • Active Branch: main
  • Release Preparation HEAD Commit: 921ddc9
    • Message: chore(release): configure deployment architecture, environment security, and release signing
  • Preceding Audit Baseline Commit: e5d3fdc (fix(education): harden production readiness and access controls)
  • Remote Tracking: origin/main (at a20b916 / mobile_api)
  • Unpushed Commits: 9 commits ahead of origin/main (no automatic push performed):
    1. 921ddc9 — chore(release): configure deployment architecture, environment security, and release signing
    2. e5d3fdc — fix(education): harden production readiness and access controls
    3. 1277f7a — feat(education_student): add secure profile and document management
    4. ff2d790 — feat(education_finance): integrate student fees and payment tracking
    5. bce010f — feat(education_announcements): integrate student notices and notifications
    6. 1d40349 — feat(education_timetable): complete schedule management and mobile integration
    7. 232e22e — feat(education_attendance): complete attendance workflow and mobile integration
    8. 2b4b4ae — feat(education_exam): implement marks entry, grading, and secure result publication
    9. 69d69f0 — feat(flutter_app): initialize Phase 4 Flutter mobile application with Riverpod, Dio, GoRouter, Material 3, and live Odoo session auth
  • Working Tree Status: Clean (all release preparation configs and manifests tracked/committed; report file generated).

2. Security and Configuration Findings

  1. Root Repository Hygiene:
    • Finding: The root .gitignore only ignored .pyc and .DS_Store. Local database dumps, private keys, .env files, and keystores were vulnerable to accidental tracking.
    • Remediation: Hardened .gitignore to strictly ignore .env*, *.dump, *.sql, *.tar.gz, *.key, *.pem, *.p12, *.jks, *.keystore, key.properties, and build artifacts.
  2. API Endpoint & Host Hardcoding:
    • Finding: ApiConfig previously fell back to http://localhost:10008 even in release builds if --dart-define=API_BASE_URL was omitted.
    • Remediation: Implemented AppEnvironment (development, staging, production). In production mode, fallback to localhost is prohibited; requests fail cleanly with a structured NOT_CONFIGURED exception prompting the operator or user to set the API endpoint in Settings.
  3. HTTPS Enforcement:
    • Finding: Release builds could theoretically connect over unencrypted cleartext HTTP if an insecure URL was supplied.
    • Remediation: Added Android Network Security Configuration (res/xml/network_security_config.xml) that disallows cleartext HTTP traffic across all domains by default, permitting HTTP only for local loopbacks (localhost, 10.0.2.2) during debug/development.
  4. Credential Scanning:
    • Finding: Verified all tracked source code in addons/ and flutter_app/. No actual production private keys, production passwords, or third-party secret tokens are committed. Only field schemas and mock fallbacks for unit tests exist.
  5. Debug Output Sanitization:
    • Finding: developer.log and request interceptors in ApiClient are strictly gated with if (kDebugMode), ensuring no sensitive student profiles, session tokens, or transaction payloads are emitted into device system logs in release builds.

3. Backend Deployment Requirements

Architecture Overview

The production deployment decouples services into three tiers:

  1. Edge Reverse Proxy (Nginx/Traefik): Handles TLS 1.3 / HTTPS termination, rate limiting, request buffering, and static caching.
  2. Application Tier (Odoo 19 Community): Runs in multiprocessing worker mode (workers = 5), with separated longpolling port 8072 for websocket events.
  3. Database Tier (PostgreSQL 15): Placed on an internal Docker bridge network with no external port exposure.

Key Deployment Files Created

  • deploy/docker-compose.prod.yml: Production compose configuration with container health checks, log rotation (json-file, max 50MB x 5), internal network isolation, and environment-driven credentials.
  • deploy/odoo.prod.conf: Hardened Odoo configuration with list_db = False (disabling database manager), proxy_mode = True, memory soft/hard limits, and CPU limits.
  • deploy/nginx/metatron_erp.conf: Production Nginx configuration with HTTP-to-HTTPS 301 redirection, HSTS, security headers, 25MB body limit for student uploads, and WebSocket proxying.
  • deploy/.env.example: Environment variable template for database credentials, domain names, and worker counts.

4. Backup and Recovery Instructions

A standalone automated utility is established at deploy/backup_restore.sh.

Manual Backup Commands

# 1. Database backup (compressed custom format)
docker exec -t metatron_academic_db pg_dump -U odoo -Fc metatron_aca_erp > metatron_aca_erp_$(date +%Y%m%d_%H%M%S).dump

# 2. Filestore archive (attachments, student photos, certificate PDFs)
docker exec metatron_academic tar -czf - -C /var/lib/odoo/filestore metatron_aca_erp > filestore_metatron_aca_erp_$(date +%Y%m%d_%H%M%S).tar.gz

Automated Utility Usage

# Full backup (creates dump, tar.gz archive, and SHA256 checksums):
./deploy/backup_restore.sh backup /path/to/backup_destination

# Verification of backup archives:
./deploy/backup_restore.sh verify /path/to/backup.dump /path/to/filestore.tar.gz

# Controlled restore to an isolated staging database:
./deploy/backup_restore.sh restore /path/to/backup.dump /path/to/filestore.tar.gz metatron_aca_erp_staging

Verification test: Verified against live container metatron_academic_db and metatron_academic. Successfully generated valid 7.26 MB database dump and 15.18 MB filestore archive.

5. Development, Staging, and Production API Configuration

The mobile app supports dynamic compile-time environment flags via --dart-define:

Environment Build Flag Target URL Example Cleartext Permitted
Development Default (no flag) http://10.0.2.2:10008 (Android) / http://localhost:10008 Yes (Emulator loopback)
Staging --dart-define=ENVIRONMENT=staging --dart-define=API_BASE_URL=https://staging-erp.yourdomain.edu https://staging-erp.yourdomain.edu No
Production --dart-define=ENVIRONMENT=production --dart-define=API_BASE_URL=https://erp.yourdomain.edu https://erp.yourdomain.edu No (HTTPS enforced)

Runtime Fallback & Settings Screen

If built without compile-time URL definitions or when connecting to a local campus network server, students or testing personnel can navigate to Settings Screen -> API Server Address and configure the custom base URL directly in the app.

6. Android Build and Signing Instructions

Package & Configuration Summary

  • Package Name / Application ID: in.metatroncube.metatron_student_erp
  • Application Label: Metatron Student ERP
  • Min SDK: 21 (Android 5.0 Lollipop)
  • Target SDK: 34 (Android 14)
  • Version: 1.0.0+1 (defined in pubspec.yaml)
  • Permissions Declared:
    • android.permission.INTERNET
    • android.permission.ACCESS_NETWORK_STATE
  • Network Security Config: flutter_app/android/app/src/main/res/xml/network_security_config.xml

Production Keystore Configuration

  1. Generate release keystore (keep outside git repository): 
    keytool -genkey -v -keystore ~/metatron-release-keystore.jks -keyalg RSA -keysize 2048 -validity 10000 -alias metatron_release
  2. Create flutter_app/android/key.properties from template: 
    cp flutter_app/android/key.properties.example flutter_app/android/key.properties
  3. Populate with your private credentials: 
    storePassword=your_keystore_password
keyPassword=your_key_password
keyAlias=metatron_release
storeFile=/absolute/path/to/metatron-release-keystore.jks
    (Note: build.gradle.kts automatically loads key.properties when present, and safely defaults to debug signing for internal QA if absent).

Release Build Commands

cd flutter_app

# 1. Google Play Store Release (Android App Bundle - AAB):
flutter build appbundle --release \
  --dart-define=ENVIRONMENT=production \
  --dart-define=API_BASE_URL=https://erp.yourdomain.edu

# 2. Direct Distribution / Internal Staging QA (Split Per-ABI APKs):
flutter build apk --release --split-per-abi \
  --dart-define=ENVIRONMENT=staging \
  --dart-define=API_BASE_URL=https://staging-erp.yourdomain.edu

7. iOS Build and Signing Instructions

Package & Configuration Summary

  • Bundle Identifier: in.metatroncube.metatronStudentErp
  • Display Name: Metatron Student ERP
  • Deployment Target: iOS 12.0+
  • Privacy Usage Descriptions:
    • NSPhotoLibraryUsageDescription: Required for uploading student profile photos and verification certificates.
    • NSCameraUsageDescription: Required for capturing physical identity documents and verification photos.
  • App Transport Security (ATS): Strict HTTPS enforcement by default.

Archiving and App Store Connect Submission Steps

  1. Open the iOS workspace in Xcode: 
    open flutter_app/ios/Runner.xcworkspace
  2. In Signing & Capabilities, select your Apple Developer Team and Provisioning Profile.
  3. Build the release archive from CLI or Xcode: 
    cd flutter_app
flutter build ipa --release \
  --dart-define=ENVIRONMENT=production \
  --dart-define=API_BASE_URL=https://erp.yourdomain.edu
  4. Upload to App Store Connect / TestFlight: 
    xcrun altool --upload-app --type ios -f build/ios/ipa/*.ipa --apiKey <API_KEY> --apiIssuer <ISSUER_ID>

8. Test and Build Results

Automated Test Matrix

Test Suite Command Result Notes
Flutter Static Analysis flutter analyze PASSED (0 issues) Strict type checking & zero lints
Flutter Unit & Widget Tests flutter test PASSED (64 / 64 passed) Full coverage of UI widgets, providers, and state models
Flutter Live Integration flutter test test/live_odoo_integration_test.dart PASSED (12 / 12 passed) End-to-end auth, profile, timetable, exams, fees, documents, certificates
Odoo Backend Automated Tests odoo --test-tags /education_* PASSED (70 / 70 passed) 0 failed, 0 errors across all 8 modules
Flutter Web Release Build flutter build web --release PASSED (✓ Built build/web) Verified tree-shaking and production compilation
Android Release Build flutter build apk --release ENVIRONMENT-BLOCKED Host machine lacks local Android SDK toolchain
Android App Bundle flutter build appbundle --release ENVIRONMENT-BLOCKED Host machine lacks local Android SDK toolchain
iOS Release Archive flutter build ipa --release ENVIRONMENT-BLOCKED Host machine lacks full Xcode developer installation & CocoaPods

9. Required Privacy Policies and Store Submission Prerequisites

Play Store & App Store Compliance Checklist

  1. Privacy Policy URL:
    • Must be hosted publicly (e.g. https://yourdomain.edu/privacy-policy).
    • Must state that student personal data (name, email, phone, enrollment ID) is collected exclusively for educational record administration and is not shared with third-party advertisers.
  2. Account Deletion / Request Policy:
    • App Store and Play Store require providing students an option or URL to request account closure or data rectification through the institution's registrar office.
  3. Data Safety Form (Google Play Console):
    • Personal info: Name, email, student ID collected for app functionality.
    • Financial info: Fee payment records (no credit card details stored on-device).
    • Photos and documents: Uploaded exclusively for institutional identity verification.
    • Encryption in transit: Yes (HTTPS/TLS 1.3).
  4. App Store Review Demo Credentials:
    • Provide active demo credentials (demo.student) in the App Store Review Information notes.

10. Outstanding Blockers and Recommended Next Actions

Blockers Before Public Release

  1. Production Domain & SSL Certificates:
    • Real institutional domain (e.g. erp.yourdomain.edu) and valid Let's Encrypt / commercial SSL certificate are required.
  2. CI/CD Signing Environment:
    • Android release keystore (key.properties) must be provisioned in the CI/CD secret manager (GitHub Actions / GitLab CI).
    • Apple Developer Team membership and distribution certificate must be linked in Xcode.
  3. Odoo Database Master Password:
    • Replace placeholder master password in deploy/odoo.prod.conf with a securely vaulted secret.

11. Exact Commands for Eventual Deployment and Release

Staging Deployment (Backend)

# 1. Clone repository to staging server
git clone <REPO_URL> metatron_erp && cd metatron_erp

# 2. Configure environment
cp deploy/.env.example deploy/.env
# Edit deploy/.env with staging database password and domain

# 3. Launch staging containers
docker compose -f deploy/docker-compose.prod.yml --env-file deploy/.env up -d

# 4. Restore sanitized database backup
./deploy/backup_restore.sh restore /path/to/staging_backup.dump /path/to/filestore.tar.gz metatron_aca_erp

Production Release (Mobile)

cd flutter_app

# Android App Bundle for Google Play
flutter build appbundle --release \
  --dart-define=ENVIRONMENT=production \
  --dart-define=API_BASE_URL=https://erp.yourdomain.edu

# iOS IPA for App Store / TestFlight
flutter build ipa --release \
  --dart-define=ENVIRONMENT=production \
  --dart-define=API_BASE_URL=https://erp.yourdomain.edu

Phase 12 Deployment and Mobile App Release Preparation complete. Awaiting user review and authorization.