Chuyển tới nội dung chính

Deployment Plan: LinguFlow (Phase 1)

This document outlines the production deployment strategy for LinguFlow, migrating from obsolete monolithic Express/MongoDB assumptions to a decoupled multi-cloud architecture.


🎯 Target Infrastructure​

ComponentTarget PlatformHosting Model
FrontendVercelStatic SPA (frontend/dist) with serverless HTTP proxy rules
BackendRailwayPython 3.12 Docker Container running Uvicorn
DatabaseRailwayManaged PostgreSQL 16 database instance
Object StorageCloudflare R2S3-compatible media storage (aioboto3 presigned URLs)

📋 Step-by-Step Platform Setup​

1. Cloudflare R2 Media Storage​

  1. Open Cloudflare Dashboard > R2.
  2. Create bucket named linguflow-media.
  3. Under Manage API Tokens, generate a token with Object Read & Write permissions scoped to linguflow-media.
  4. Note credentials:
    • Access Key ID
    • Secret Access Key
    • Endpoint URL (https://<ACCOUNT_ID>.r2.cloudflarestorage.com)

2. Railway Backend & Postgres​

  1. Create a project in Railway and add a PostgreSQL database plugin.
  2. Add a service connecting to GitHub repo newtc22222/lingu-flow:
    • Set Root Directory to backend.
    • Set Builder to Dockerfile.
  3. Set Start Command:
    alembic upgrade head && uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-8000}
  4. Generate a public Railway domain URL under Settings > Networking (e.g. https://linguflow-backend-production.up.railway.app).

3. Vercel Frontend SPA​

  1. Import newtc22222/lingu-flow repo in Vercel.
  2. Configure settings:
    • Root Directory: frontend
    • Framework Preset: Vite
    • Build Command: npm run build
    • Output Directory: dist
  3. Configure frontend/vercel.json rewrites to proxy /api/* requests to your Railway domain.

🔐 Environment Variables Matrix​

PlatformVariable NameRequiredDescription
Vercel(None)NoManaged via frontend/vercel.json proxy rewrites
RailwayDATABASE_URLYesAuto-injected by Railway Postgres (${{Postgres.DATABASE_URL}})
RailwayENVIRONMENTYesSet to production
RailwayPORTYesInjected by Railway (${{PORT}})
RailwayJWT_SECRETYes64-char random hex string (openssl rand -hex 32)
RailwayJWT_ALGORITHMYesHS256
RailwayCORS_ORIGINSYes["https://linguflow.vercel.app","http://localhost:5173"]
RailwayCORS_ORIGIN_REGEXYeshttps://linguflow-.*\.vercel\.app
RailwayR2_ACCOUNT_IDYesCloudflare Account ID
RailwayR2_ACCESS_KEY_IDYesCloudflare R2 Access Key ID
RailwayR2_SECRET_ACCESS_KEYYesCloudflare R2 Secret Access Key
RailwayR2_BUCKET_NAMEYeslinguflow-media
RailwayR2_ENDPOINT_URLYeshttps://<ACCOUNT_ID>.r2.cloudflarestorage.com

🔄 CI/CD & Deployment Triggers​

  • Frontend (Vercel):

    • Pushes to main trigger production deployments.
    • Pull Requests generate Vercel preview environments automatically.
    • CORS regex allows preview domains (https://linguflow-.*\.vercel\.app) to communicate seamlessly with the backend.
  • Backend (Railway):

    • Pushes to main trigger container rebuilds.
    • Executed start command automatically runs alembic upgrade head prior to starting Uvicorn, guaranteeing schema safety on every deployment.

✅ Deployment Verification Checklist​

  • GET /api/health returns 200 OK from Railway backend.
  • POST /api/media/presign-upload returns valid presigned upload URL.
  • Vercel SPA loads root route / and routes /auth, /library without asset 404s.
  • CORS headers allow requests from production Vercel domain and preview subdomains.