> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bunship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Reference

> Environment variables, feature flags, and analytics setup for BunShip Pro.

# 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                  |

<Tip>Set `DEMO_MODE=true` to run without Stripe. All billing pages will show mock data.</Tip>

### 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

```tsx theme={null}
auth: {
  enableEmailPassword: true,
  enableMagicLink: true,
  enableGoogleOAuth: true,
  enableGithubOAuth: true,
  enableTwoFactor: true,
  enableSessionManagement: true,
  requireEmailVerification: true,
}
```

### Organization Features

```tsx theme={null}
organizations: {
  enabled: true,
  allowMultipleOrgs: true,
  allowOrgCreation: true,
  requireOrgOnSignup: false,
  maxOrgsPerUser: 10,
}
```

### Billing Features

```tsx theme={null}
billing: {
  enabled: true,
  provider: "stripe",
  trialDays: 14,
  allowFreePlan: true,
}
```

To disable a feature, change its value to `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

```bash theme={null}
VITE_ANALYTICS_PROVIDER=plausible
VITE_PLAUSIBLE_DOMAIN=yourdomain.com
```

### PostHog

```bash theme={null}
VITE_ANALYTICS_PROVIDER=posthog
VITE_POSTHOG_KEY=phc_xxx
```

### Google Analytics 4

```bash theme={null}
VITE_ANALYTICS_PROVIDER=ga4
VITE_GA4_ID=G-XXXXXXXXXX
```

Only one provider can be active at a time.

## Next Steps

* [Getting Started](/pro/getting-started) — Initial setup and first run
* [Email Templates](/pro/email-templates) — Configure email provider and customize templates