Configuration Reference
BunShip Pro is configured through environment variables (in .env) and feature flags (in code).
Environment Variables
All variables are defined in .env at the repository root. Copy .env.example to get started.
Application
| Variable | Required | Default | Description |
|---|
NODE_ENV | No | development | development or production |
PORT | No | 3000 | API server port |
API_URL | No | http://localhost:3000 | Base URL for the API |
FRONTEND_URL | No | http://localhost:3001 | Base URL for the frontend |
CORS_ORIGINS | No | http://localhost:3001 | Comma-separated allowed origins |
Database
| Variable | Required | Default | Description |
|---|
TURSO_DATABASE_URL | Yes | file:./local.db | SQLite file path or Turso URL |
TURSO_AUTH_TOKEN | Production | — | Auth token for hosted Turso |
Authentication
| Variable | Required | Default | Description |
|---|
JWT_SECRET | Yes | — | Secret for signing access tokens (32+ chars) |
JWT_REFRESH_SECRET | Yes | — | Secret for signing refresh tokens (32+ chars) |
Stripe Billing
| Variable | Required | Default | Description |
|---|
STRIPE_SECRET_KEY | No | — | Stripe API secret key (sk_test_... or sk_live_...) |
STRIPE_WEBHOOK_SECRET | No | — | Stripe webhook signing secret (whsec_...) |
STRIPE_PRO_MONTHLY_PRICE_ID | No | Built-in | Stripe price ID for Pro monthly plan |
STRIPE_PRO_YEARLY_PRICE_ID | No | Built-in | Stripe price ID for Pro yearly plan |
STRIPE_ENTERPRISE_MONTHLY_PRICE_ID | No | Built-in | Stripe price ID for Enterprise monthly |
STRIPE_ENTERPRISE_YEARLY_PRICE_ID | No | Built-in | Stripe price ID for Enterprise yearly |
Set DEMO_MODE=true to run without Stripe. All billing pages will show mock data.
Email
| Variable | Required | Default | Description |
|---|
EMAIL_PROVIDER | No | resend | resend, smtp, or console |
RESEND_API_KEY | No | — | Resend API key (when provider is resend) |
RESEND_FROM_EMAIL | No | — | Sender address (e.g., App <hello@yourdomain.com>) |
SMTP_HOST | No | — | SMTP server hostname (when provider is smtp) |
SMTP_PORT | No | 587 | SMTP port |
SMTP_SECURE | No | false | Use TLS |
SMTP_USER | No | — | SMTP username |
SMTP_PASS | No | — | SMTP password |
File Storage (S3)
| Variable | Required | Default | Description |
|---|
S3_ENDPOINT | No | — | S3-compatible endpoint URL |
S3_BUCKET | No | — | Bucket name |
AWS_ACCESS_KEY_ID | No | — | AWS access key |
AWS_SECRET_ACCESS_KEY | No | — | AWS secret key |
AWS_REGION | No | us-east-1 | AWS region |
S3_FORCE_PATH_STYLE | No | false | Enable for MinIO or other S3-compatible services |
MAX_FILE_SIZE | No | 52428800 | Max upload size in bytes (default 50 MB) |
Redis
| Variable | Required | Default | Description |
|---|
REDIS_URL | No | redis://localhost:6379 | Redis connection URL for background jobs |
OAuth (Optional)
| Variable | Required | Default | Description |
|---|
GOOGLE_CLIENT_ID | No | — | Google OAuth client ID |
GOOGLE_CLIENT_SECRET | No | — | Google OAuth client secret |
GITHUB_CLIENT_ID | No | — | GitHub OAuth client ID |
GITHUB_CLIENT_SECRET | No | — | GitHub OAuth client secret |
Admin
| Variable | Required | Default | Description |
|---|
CRON_SECRET | No | — | Secret for authenticating cron job endpoints |
Frontend Analytics
These are VITE_ prefixed and available to the frontend:
| Variable | Required | Default | Description |
|---|
VITE_ANALYTICS_PROVIDER | No | — | plausible, posthog, or ga4 |
VITE_PLAUSIBLE_DOMAIN | No | — | Your domain for Plausible analytics |
VITE_POSTHOG_KEY | No | — | PostHog project API key |
VITE_GA4_ID | No | — | Google Analytics 4 measurement ID |
Feature Flags
Feature flags are defined in packages/config/src/features.ts. They control which features are enabled at build time.
Auth Features
auth: {
enableEmailPassword: true,
enableMagicLink: true,
enableGoogleOAuth: true,
enableGithubOAuth: true,
enableTwoFactor: true,
enableSessionManagement: true,
requireEmailVerification: true,
}
Organization Features
organizations: {
enabled: true,
allowMultipleOrgs: true,
allowOrgCreation: true,
requireOrgOnSignup: false,
maxOrgsPerUser: 10,
}
Billing Features
billing: {
enabled: true,
provider: "stripe",
trialDays: 14,
allowFreePlan: true,
}
false in the config file. The frontend and backend both read from this shared config, so changes apply everywhere.
Admin Feature Flags
The admin panel at /admin/feature-flags provides a UI for toggling features at runtime. These are grouped by category: authentication, billing, organizations, and file uploads.
Analytics Setup
To add analytics, set the provider and its key in .env:
Plausible
VITE_ANALYTICS_PROVIDER=plausible
VITE_PLAUSIBLE_DOMAIN=yourdomain.com
PostHog
VITE_ANALYTICS_PROVIDER=posthog
VITE_POSTHOG_KEY=phc_xxx
Google Analytics 4
VITE_ANALYTICS_PROVIDER=ga4
VITE_GA4_ID=G-XXXXXXXXXX
Next Steps
