All posts
Engineering
Run VocatAI locally: Postgres, API, and Flutter
8 min read
Jump to section
Developers need the database, the API, and the Flutter app pointed at each other. The docs assume PostgreSQL 16 or newer, Node.js 22, and a Flutter SDK matching the app pubspec.
1. Database
Create a role and database, then set DATABASE_URL in backend/.env. Example: postgres://vocatai:password@127.0.0.1:5432/vocatai
2. Backend
- cd backend && cp .env.example .env
- Fill DATABASE_URL, JWT_SECRET, GOOGLE_CLIENT_ID (Web client ID string; required at process start), OPENROUTER_API_KEY, and every SMTP_* field—the loader treats them as required.
- npm install && npm run db:migrate && npm run db:seed && npm run dev
- Health check: GET /health should return { ok: true }.
3. Flutter
- cd app && flutter pub get && flutter run
- Physical device or custom host: flutter run --dart-define=API_BASE_URL=http://YOUR_LAN_IP:3000
- Google Sign-In: pass GOOGLE_WEB_CLIENT_ID matching the server GOOGLE_CLIENT_ID web client.
SMTP
The current backend loader requires real SMTP values before the process starts—use a dev mailbox or local sink that accepts your credentials. OTP sign-up will not work until mail sends successfully.