Getting Started

Environment Configuration

Configure the three .env files that control Docker services, the Laravel backend, and the Nuxt frontend.

SaaS4Builders uses three .env files, each controlling a different part of the stack. The make install command creates these files automatically from their .example templates, but you will need to customize them — especially for Stripe billing and OAuth providers.

Three Configuration Files

File	Scope	Read By
`.env` (root)	Docker Compose variables: ports, database credentials, Reverb, VAPID	Docker Compose, passed to containers
`backend/.env`	Laravel application configuration	PHP container (Laravel `config()`)
`frontend/.env`	Nuxt runtime configuration	Node container (Nuxt `useRuntimeConfig()`)

The root .env is read by Docker Compose to configure containers and pass environment variables into them. The backend/.env and frontend/.env are read by the Laravel and Nuxt applications running inside those containers.

Root `.env` — Docker and Infrastructure

This file controls the Docker Compose setup. It sets ports, database credentials, and variables that are passed into containers.

Ports

Variable	Default	Service
`NGINX_PORT`	`8000`	Backend API (Nginx reverse proxy)
`NUXT_PORT`	`3000`	Frontend (Nuxt dev server)
`DB_PORT`	`5432`	PostgreSQL
`REDIS_PORT`	`6379`	Redis
`MAILPIT_UI_PORT`	`8025`	Mailpit email testing UI
`MAILPIT_SMTP_PORT`	`1025`	Mailpit SMTP server
`REVERB_PORT`	`8080`	Reverb WebSocket server
`HMR_PORT`	`24679`	Nuxt hot module replacement

Change these if you have port conflicts with other services on your machine.

Database Credentials

Variable	Default	Description
`DB_DATABASE`	`saas`	PostgreSQL database name
`DB_USERNAME`	`saas`	PostgreSQL user
`DB_PASSWORD`	`secret`	PostgreSQL password
`COMPOSE_PROJECT_NAME`	`saas-boilerplate`	Docker Compose project prefix for container names

These credentials are used by both the PostgreSQL container (to create the database) and the backend .env (to connect to it).

Broadcasting / Reverb

Variable	Default	Description
`REVERB_APP_KEY`	`saas-reverb-key`	Reverb application key
`REVERB_APP_SECRET`	`saas-reverb-secret`	Reverb application secret
`REVERB_APP_ID`	`saas-local`	Reverb application ID
`REVERB_HOST`	`reverb`	Internal Docker hostname for Reverb
`REVERB_HOST_PUBLIC`	`localhost`	Public hostname for WebSocket connections
`REVERB_PORT`	`8080`	Reverb WebSocket port
`REVERB_SCHEME`	`http`	WebSocket protocol (`http` for dev, `https` for production)

Web Push Notifications (VAPID)

Variable	Default	Description
`VAPID_SUBJECT`	`https://your-app.com`	URL or `mailto:` identifying the push sender
`VAPID_PUBLIC_KEY`	(empty)	Public VAPID key
`VAPID_PRIVATE_KEY`	(empty)	Private VAPID key

Generate VAPID keys with:

make vapid

This generates the keys inside the PHP container, writes them to backend/.env, then syncs them to the root .env and frontend/.env on the host.

Option	Usage	Description
--force	make vapid ARGS=--force	Overwrite existing VAPID keys
--show	make vapid ARGS=--show	Display keys without writing to any file

Nuxt Studio

Variable	Default	Description
`STUDIO_GITHUB_TOKEN`	(empty)	GitHub PAT for content commits
`STUDIO_REPOSITORY_PROVIDER`	`github`	Git provider (`github` or `gitlab`)
`STUDIO_REPOSITORY_OWNER`	(empty)	Repository owner/org
`STUDIO_REPOSITORY_NAME`	(empty)	Repository name
`STUDIO_REPOSITORY_BRANCH`	`main`	Branch for content commits

These are only needed if you use Nuxt Studio for visual content editing.

Backend `.env` — Laravel Application

This is the standard Laravel .env file with project-specific additions for billing, multi-tenancy, and OAuth.

Application

Variable	Default	Description
`APP_NAME`	`SaaS4Builders`	Application name (used in emails, notifications)
`APP_ENV`	`local`	Environment: `local`, `testing`, `production`
`APP_KEY`	(generated)	Encryption key (auto-generated by `make install`)
`APP_DEBUG`	`true`	Show debug info (`false` in production)
`APP_TIMEZONE`	`UTC`	Application timezone
`APP_URL`	`http://localhost:8000`	Backend API URL
`FRONTEND_URL`	`http://localhost:3000`	Frontend URL (used for CORS, redirects, emails)

In production, set APP_ENV=production, APP_DEBUG=false, and both URLs to your actual domains. See the Deployment Guide for the full production checklist.

Localization

Variable	Default	Description
`APP_LOCALE`	`en`	Default locale
`APP_FALLBACK_LOCALE`	`en`	Fallback when translation is missing
`APP_SUPPORTED_LOCALES`	`en,fr,es,it`	Comma-separated list of supported locales
`APP_SUPPORT_EMAIL`	`support@example.com`	Support email shown in notifications

Database

Variable	Default	Description
`DB_CONNECTION`	`pgsql`	Database driver (PostgreSQL)
`DB_HOST`	`postgres`	Hostname (Docker service name)
`DB_PORT`	`5432`	Port
`DB_DATABASE`	`saas`	Database name
`DB_USERNAME`	`saas`	Username
`DB_PASSWORD`	`secret`	Password

The DB_HOST is postgres (the Docker service name), not localhost. Inside the Docker network, containers reach each other by service name.

Cache and Sessions

Variable	Default	Description
`SESSION_DRIVER`	`redis`	Session storage backend
`SESSION_LIFETIME`	`120`	Session lifetime in minutes
`CACHE_STORE`	`redis`	Cache backend
`CACHE_PREFIX`	`saas_`	Cache key prefix (prevents collisions)

Queue

Variable	Default	Description
`QUEUE_CONNECTION`	`redis`	Queue backend

The queue worker runs in a separate Docker container (saas-queue). Jobs dispatched by the application are stored in Redis and processed asynchronously.

Redis

Variable	Default	Description
`REDIS_CLIENT`	`phpredis`	Redis PHP extension
`REDIS_HOST`	`redis`	Hostname (Docker service name)
`REDIS_PASSWORD`	`null`	Password (none in development)
`REDIS_PORT`	`6379`	Port

Mail

Variable	Default	Description
`MAIL_MAILER`	`smtp`	Mail driver
`MAIL_HOST`	`mailpit`	SMTP host (Mailpit in development)
`MAIL_PORT`	`1025`	SMTP port
`MAIL_USERNAME`	`null`	SMTP username
`MAIL_PASSWORD`	`null`	SMTP password
`MAIL_ENCRYPTION`	`null`	Encryption (`tls` for production)
`MAIL_FROM_ADDRESS`	`hello@saas.local`	Default sender email
`MAIL_FROM_NAME`	`${APP_NAME}`	Default sender name

In development, all emails are captured by Mailpit and visible at http://localhost:8025. No emails are actually sent.

For production, replace Mailpit with a real mail provider (Mailgun, Postmark, Amazon SES, or custom SMTP).

Sanctum (Authentication)

Variable	Default	Description
`SANCTUM_STATEFUL_DOMAINS`	`localhost:3000,127.0.0.1:3000`	Domains allowed for cookie-based auth

Critical for production: This must exactly match your frontend domain (including port if non-standard). Example: app.yourdomain.com. If this is wrong, authentication will silently fail.

Stripe and Billing

Variable	Default	Description
`STRIPE_KEY`	(empty)	Stripe publishable key (`pk_test_...` or `pk_live_...`)
`STRIPE_SECRET`	(empty)	Stripe secret key (`sk_test_...` or `sk_live_...`)
`STRIPE_WEBHOOK_SECRET`	(empty)	Webhook signing secret (`whsec_...`)
`STRIPE_TAX_ENABLED`	`false`	Enable Stripe Tax for automatic tax calculation
`TAX_PROVIDER`	`stripe_tax`	Tax calculation provider
`BILLING_MODE`	`stripe_managed`	Billing mode (only `stripe_managed` in V1)
`BILLING_DEFAULT_CURRENCY`	`USD`	Default currency for new subscriptions
`BILLING_FALLBACK_CURRENCY`	`EUR`	Fallback currency

To enable billing flows, you need Stripe test keys:

Create a Stripe account.
Go to Developers → API Keys in test mode.
Copy the publishable key and secret key.
For webhooks, use the Stripe CLI to forward events locally:

stripe listen --forward-to http://localhost:8000/api/v1/stripe/webhook

The CLI will print a webhook signing secret (whsec_...) — add it to STRIPE_WEBHOOK_SECRET.

OAuth Providers

Variable	Default	Description
`OAUTH_PROVIDERS`	(empty)	Comma-separated list of enabled providers (e.g., `google,github`)
`GOOGLE_CLIENT_ID`	(empty)	Google OAuth client ID
`GOOGLE_CLIENT_SECRET`	(empty)	Google OAuth client secret
`GOOGLE_REDIRECT_URI`	`${APP_URL}/api/v1/auth/oauth/google/callback`	Google OAuth callback URL
`GITHUB_CLIENT_ID`	(empty)	GitHub OAuth client ID
`GITHUB_CLIENT_SECRET`	(empty)	GitHub OAuth client secret
`GITHUB_REDIRECT_URI`	`${APP_URL}/api/v1/auth/oauth/github/callback`	GitHub OAuth callback URL

OAuth is optional. Leave OAUTH_PROVIDERS empty to disable social login entirely. To enable a provider, add its name to the list and fill in the credentials.

Broadcasting / Reverb

Variable	Default	Description
`BROADCAST_CONNECTION`	`reverb`	Broadcasting driver
`REVERB_APP_ID`	`saas-local`	Must match root `.env`
`REVERB_APP_KEY`	`saas-reverb-key`	Must match root `.env`
`REVERB_APP_SECRET`	`saas-reverb-secret`	Must match root `.env`
`REVERB_HOST`	`reverb`	Internal Docker hostname
`REVERB_PORT`	`8080`	Reverb port
`REVERB_SCHEME`	`http`	Protocol
`REVERB_SERVER_HOST`	`0.0.0.0`	Bind address for the Reverb server
`REVERB_SERVER_PORT`	`8080`	Server listen port

Logging

Variable	Default	Description
`LOG_CHANNEL`	`stack`	Log channel
`LOG_STACK`	`single`	Stack channels
`LOG_DEPRECATIONS_CHANNEL`	`null`	Deprecation log channel
`LOG_LEVEL`	`debug`	Minimum log level (`warning` or `error` for production)

Frontend `.env` — Nuxt Application

The frontend .env configures the Nuxt application's runtime behavior.

Localization

Variable	Default	Description
`NUXT_PUBLIC_LOCALE`	`en`	Default locale
`NUXT_PUBLIC_FALLBACK_LOCALE`	`en`	Fallback locale

API

Variable	Default	Description
`NUXT_PUBLIC_API_BASE_URL`	`http://localhost:8000`	Backend API URL for client-side requests

In the Docker setup, the Node container receives two API URLs from docker-compose.yml: NUXT_API_BASE_URL=http://nginx:80 for server-side rendering and NUXT_PUBLIC_API_BASE_URL=http://localhost:8000 for client-side requests. These Docker-level variables override what's in frontend/.env.

Authentication

Variable	Default	Description
`NUXT_PUBLIC_AUTH_MODE`	`cookie`	Auth mode: `cookie` (Sanctum SPA) or `token` (Bearer tokens)

The default cookie mode uses Sanctum's cookie-based SPA authentication. This is recommended for the built-in frontend. Use token mode if you are building a separate client application.

Multi-Tenancy

Variable	Default	Description
`NUXT_PUBLIC_TENANCY_MODE`	`header`	How the current tenant is communicated to the API
`NUXT_PUBLIC_TENANCY_HEADER_NAME`	`X-Tenant-ID`	Header name (when mode is `header`)
`NUXT_PUBLIC_TENANCY_PATH_PARAM`	`tenantId`	URL parameter name (when mode is `path`)
`NUXT_PUBLIC_TENANCY_BASE_DOMAIN`	`localhost`	Base domain (when mode is `subdomain`)

The default header mode sends the tenant ID in an X-Tenant-ID HTTP header with every API request. Other modes (path, subdomain) are available for different URL strategies.

Nuxt Studio

Variable	Default	Description
`STUDIO_REPOSITORY_PROVIDER`	`github`	Git provider
`STUDIO_REPOSITORY_OWNER`	(empty)	Repository owner
`STUDIO_REPOSITORY_NAME`	(empty)	Repository name
`STUDIO_REPOSITORY_BRANCH`	`main`	Content branch
`STUDIO_GITHUB_TOKEN`	(empty)	GitHub PAT for commits

These are only needed for Nuxt Studio integration. Studio uses the application's existing Sanctum authentication — no separate OAuth setup is required.

Variable Relationships

Some variables must stay in sync across files:

Setting	Root `.env`	Backend `.env`	Frontend `.env`
Database credentials	`DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`	Same values (different host: `postgres`)	—
Reverb config	`REVERB_APP_KEY`, `REVERB_APP_SECRET`, etc.	Same values	Receives via `docker-compose.yml`
VAPID keys	`VAPID_PUBLIC_KEY`, `VAPID_PRIVATE_KEY`	Same values	Receives public key via `docker-compose.yml`

The make install command copies the same .example templates, so values are consistent by default. If you change a shared variable, update it in all relevant files.

What's Next

Running the Demo — See what the seeded demo data looks like.
Docker Setup — Understand which container reads which configuration.
Deployment Guide — Production values for all these variables.

Docker Setup

Understand the Docker services, networks, and volumes that power the SaaS4Builders development environment.

Running the Demo

Explore the CraftDesk demo: 12 tenants, 89 users, subscriptions, invoices, and usage events across a 2-year timeline.