WELIFE Docs Swagger Admin Web

ENV packaging — đóng gói môi trường theo từng phần

Chuẩn hóa .env / .env.example / .env.production.example cho mọi surface. Không commit secret. Owner điền Pay/SMS/OpenAI khi go-live.

1. Gói theo surface

Phần Local Staging Production template Runtime file
Compose infra .env.example .env.staging.example (cùng keys mạnh hơn trên VPS) .env / .env.staging
API Nest api/.env.example api/.env.staging.example api/.env.production.example api/.env / api/.env.staging
Consumer Expo mobile/.env.example mobile/.env.staging.example mobile/.env.production.example mobile/.env + .env.local
Driver driver/.env.example driver/.env.staging.example driver/.env.production.example driver/.env
Partner partner/.env.example partner/.env.staging.example partner/.env.production.example partner/.env
Dashboard Vite dashboard/.env.example dashboard/.env.staging.example dashboard/.env.production.example dashboard/.env / .env.production

Compose staging: deploy/docker-compose.staging.yml (COMPOSE_PROJECT_NAME=welife-stg, ports lệch). Prod VPS: thêm deploy/docker-compose.resources.yml.

2. Lệnh

# Tạo/merge thiếu (không ghi đè secret đang có)
npm run env:bootstrap

# Kiểm tra (không in secret)
npm run env:check

# Lần đầu monorepo
npm run setup

3. Local “chạy tốt” (không cần OWNER secret)

Windows (PowerShell)

npm run env:bootstrap
npm run dev:up                 # PG + Redis + MinIO + Mailpit + migrate + env:check
npm run api:dev
npm run dev:smoke
npm run mobile:start           # Expo local (heap + system CA)
npm run mobile:start:lan       # Expo Go device · in LAN IP
# staging/prod API: copy mobile/.env.staging.example|production.example → .env.local
#   rồi npm run mobile:start:staging | mobile:start:prod
# Metro kẹt: npm run mobile:reset:metro  (không kill api:dev)
# OSRM optional: npm run dev:up -- --with-osrm  (sau bash deploy/osrm/bootstrap-osrm.sh)
# Chi tiết: docs/reports/APP-DESIGN-BUILD-MIRROR-2026-08-12.md

Bash

  1. npm run env:bootstrap
  2. npm run infra:up (+ docker compose --profile mail up -d mailpit nếu OTP email) — hoặc npm run dev:up
  3. npm run api:dev
  4. npm run mobile:start — emulator: localhost; device thật: sửa LAN IP trong mobile/.env.local
  5. Routing: OSRM mặc định (ROUTING_PROVIDER=auto) — không cần Mapbox

4. Production pack (VPS)

  1. Copy api/.env.production.example → /opt/welife/api/.env
  2. Điền: JWT (≥32), DB/Redis/MinIO passwords, CORS_ORIGINS cụ thể
  3. Giữ: ROUTING_OSRM_ENABLED=true, PAYMENTS_MOCK=true đến khi có MoMo/VNPay
  4. OTP: email + Mailpit/SMTP · hoặc SMS_PROVIDER=esms + keys
  5. Dashboard: VITE_API_URL=https://api.<domain>/api/v1 rồi npm run build
  6. Mobile release: dùng mobile/.env.production.example / EAS plaintext EXPO_PUBLIC_*

5. OWNER_REQUIRED (không tự bịa)

Biến Khi nào
OPENAI_API_KEY Bật assistant AI
MoMo / VNPay * PAYMENTS_MOCK=false
ESMS_* / Twilio OTP SMS production
MAPBOX_ACCESS_TOKEN Optional (đã có OSRM)

6. Quy tắc đóng gói