🚢 Deployment & DevOps Guide
This guide details the complete deployment setup for LinguFlow across cloud providers:
- Frontend: Vercel
- Backend: Railway
- Database: Railway PostgreSQL
- Media Storage: Cloudflare R2
- Local Dev / Staging: Docker Compose
For the staging git branch, Railway staging environment, and the later move of production onto lingu-flow.com, see Domain Cutover.
🏗️ Architecture Overview
1. Local Development (Docker Compose)
Run the full stack locally with PostgreSQL:
# Start PostgreSQL database container
docker-compose up -d postgres
# Run backend locally
cd backend
python -m venv venv
.\venv\Scripts\activate
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload --port 8000
# Run frontend locally
cd ../frontend
npm install
npm run dev
2. Backend Deployment (Railway)
- Connect your GitHub repository
newtc22222/lingu-flowto Railway. - Select root directory
backend/. - Add a PostgreSQL database service on Railway.
- Configure environment variables in Railway dashboard:
ENVIRONMENT=production
PORT=8000
DATABASE_URL=postgresql+asyncpg://postgres:PASSWORD@postgres.railway.internal:5432/railway
JWT_SECRET=super_secret_production_random_key_min_32_chars
CORS_ORIGINS=["https://linguflow.vercel.app"]
CORS_ORIGIN_REGEX=https://linguflow-.*\.vercel\.app
# Cloudflare R2
R2_ACCOUNT_ID=your_cloudflare_account_id
R2_ACCESS_KEY_ID=your_r2_access_key
R2_SECRET_ACCESS_KEY=your_r2_secret_key
R2_BUCKET_NAME=linguflow-media
R2_ENDPOINT_URL=https://your_account_id.r2.cloudflarestorage.com
- Railway builds the app using
backend/Dockerfileor nixpacks, runsalembic upgrade headand startsuvicorn app.main:app --host 0.0.0.0 --port 8000.
3. Frontend Deployment (Vercel)
- Connect repository to Vercel.
- Set Root Directory to
frontend/. - Build Settings:
- Framework Preset: Vite
- Build Command:
npm run build - Output Directory:
dist
- Add
vercel.jsonrewrite configuration for Vue Router SPA fallback and API proxying:
{
"rewrites": [
{
"source": "/api/:path*",
"destination": "https://backend-production.up.railway.app/api/:path*"
},
{
"source": "/(.*)",
"destination": "/index.html"
}
]
}
4. Media Storage Setup (Cloudflare R2)
Full pipeline, diagnosis, and the CORS JSON: Card Image Uploads (R2 + CORS).
- Log in to Cloudflare Dashboard → R2 Object Storage.
- Create bucket named
linguflow-media(and a separatelinguflow-media-stagingif you isolate staging objects). - Under Settings → CORS policy, allow the SPA origins to
PUT/GET/HEADwithcontent-type. FastAPICORS_ORIGINSdoes not apply to the browser’s direct PUT to R2. Without this, the card editor shows “Không thể tải ảnh lên” and Chrome logsCORS not configured for this bucket. - Create an API Token with Object Read & Write permissions scoped to that bucket.
- Copy Account ID, Access Key ID, Secret Access Key, bucket name, and endpoint into Railway /
backend/.env. Restart the API after changingR2_*—get_settings()is cached and--reloaddoes not re-read.env.