Deployment Guide

This guide covers everything you need to move SaaS4Builders from your local Docker environment to a production server. It assumes you are deploying a standard server-based setup — the recommended path uses Laravel Forge or Ploi, but Docker and other platforms are also covered.

Production Checklist

Work through this checklist before going live. Every item matters.

Application Settings

Authentication and CORS

CORS is configured in backend/config/cors.php:

'allowed_origins' => [env('FRONTEND_URL', 'http://localhost:3000')],

Setting FRONTEND_URL correctly in your backend .env automatically configures CORS. Only your frontend domain will be allowed to make cross-origin requests.

Database

Use a managed PostgreSQL service instead of a Docker container:

Run migrations on first deploy:

php artisan migrate --force

Cache, Sessions, and Queues

Use a managed Redis instance for all three:

Stripe Billing

Switch from test keys to live keys:

Register your webhook endpoint in the Stripe Dashboard:

• URL: https://api.yourdomain.com/api/v1/stripe/webhook
• Events to listen for: All invoice.*, customer.subscription.*, checkout.session.*, and charge.* events.

Mail

Replace Mailpit with a production mail provider:

MAIL_MAILER=mailgun
MAILGUN_DOMAIN=your-domain.com
MAILGUN_SECRET=your-mailgun-key

MAIL_MAILER=postmark
POSTMARK_TOKEN=your-postmark-token

MAIL_MAILER=ses
AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret
AWS_DEFAULT_REGION=us-east-1

MAIL_MAILER=smtp
MAIL_HOST=smtp.your-provider.com
MAIL_PORT=587
MAIL_USERNAME=your-username
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls

Update the sender address:

MAIL_FROM_ADDRESS=noreply@yourdomain.com
MAIL_FROM_NAME="Your App Name"

OAuth Providers

If you use Google or GitHub OAuth, register new OAuth applications with your production domains:

Create new OAuth apps in the Google Cloud Console and GitHub Developer Settings with your production callback URLs.

Broadcasting / Reverb

If you use real-time features (WebSocket):

Alternatively, replace Reverb with a managed service like Pusher or Ably.

Web Push Notifications

Generate production VAPID keys:

php artisan webpush:vapid

Set VAPID_SUBJECT to your production URL:

VAPID_SUBJECT=https://yourdomain.com

Logging

Avoid debug level in production — it generates excessive log volume and may expose sensitive data.

Cron and Scheduler

The Laravel scheduler requires a system cron job that runs every minute:

* * * * * cd /path-to-your-backend && php artisan schedule:run >> /dev/null 2>&1

On Forge or Ploi, the scheduler is configured through the UI — no manual cron setup needed.

Scheduled Tasks

The application schedules these tasks automatically:

These tasks run without overlapping (a second instance will not start if the previous one is still running).

Queue Worker

The queue worker processes background jobs (emails, webhooks, billing sync). It must run continuously in production.

php artisan queue:work --sleep=3 --tries=3 --max-time=3600

Ensure QUEUE_CONNECTION=redis is set in your backend .env so the worker uses the Redis driver.

This command:

• Processes jobs from the configured queue connection (Redis)
• Waits 3 seconds between polling when idle
• Retries failed jobs up to 3 times
• Restarts automatically after 1 hour (prevents memory leaks)

Keeping the Worker Running

Use a process manager to ensure the worker restarts if it crashes:

[program:saas-queue-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /path-to-your-backend/artisan queue:work --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/path-to-your-backend/storage/logs/worker.log
stopwaitsecs=3600

[Unit]
Description=SaaS Queue Worker
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/path-to-your-backend
ExecStart=/usr/bin/php artisan queue:work --sleep=3 --tries=3 --max-time=3600
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

On Forge or Ploi, queue workers are managed through the dashboard — add a worker with the command above.

After each deployment, restart the queue worker to pick up new code:

php artisan queue:restart

Deployment with Forge or Ploi

Laravel Forge and Ploi are the recommended deployment platforms. They handle server provisioning, SSL certificates, queue workers, and scheduled tasks.

Setup Steps

1. Provision a server — Ubuntu 24.04 with PHP 8.3+, PostgreSQL 16, Redis 7, Nginx.
2. Create a site — Point it to your domain. Set the web directory to backend/public.
3. Configure environment — Add all production .env variables through the platform's UI.
4. Set up the database — Create a PostgreSQL database and user.
5. Configure the queue worker — Add a worker with the command: php artisan queue:work --sleep=3 --tries=3 --max-time=3600.
6. Enable the scheduler — Enable the cron-based scheduler in the platform settings.
7. Set up SSL — Use the platform's Let's Encrypt integration.

Deploy Script

Configure your deploy script to run on each push:

cd /home/forge/api.yourdomain.com

# Pull latest code
git pull origin main

# Install dependencies (no dev packages)
composer install --no-interaction --prefer-dist --optimize-autoloader --no-dev

# Run migrations
php artisan migrate --force

# Cache configuration for performance
php artisan config:cache
php artisan route:cache
php artisan view:cache

# Restart the queue worker to pick up new code
php artisan queue:restart

Frontend Deployment

The Nuxt frontend is a separate deployment. Options:

1. Static hosting — Run pnpm build and deploy the .output/ directory to Vercel, Netlify, or Cloudflare Pages.
2. Node server — Run pnpm build and then node .output/server/index.mjs behind a reverse proxy.
3. Same server — Deploy both backend and frontend on the same server with separate Nginx configurations.

Build the frontend for production:

cd frontend
pnpm install --frozen-lockfile
pnpm build

Docker Production Deployment

Key Differences from Development

Recommendations

• Use managed database and Redis — Do not run PostgreSQL or Redis in Docker containers in production. Use your cloud provider's managed services (AWS RDS, DigitalOcean Managed Databases, etc.).
• SSL termination — Use a reverse proxy (Traefik, Caddy) or cloud load balancer for HTTPS.
• Container orchestration — For scaling, consider Docker Swarm or Kubernetes. For a single server, Docker Compose with production settings is sufficient.

Security Checklist

Before going live, verify every item:

• APP_DEBUG is false
• APP_ENV is production
• APP_KEY is generated and stored securely (not committed to git)
• HTTPS is enforced on all endpoints (API and frontend)
• SANCTUM_STATEFUL_DOMAINS matches your production frontend domain exactly
• FRONTEND_URL is set to your production frontend URL (controls CORS)
• Database credentials are strong and unique (not the default secret)
• Stripe is using live keys (not test keys)
• Stripe webhook endpoint is registered with the correct production URL
• OAuth redirect URIs use production domains
• LOG_LEVEL is warning or error (not debug)
• Redis has a password set (if accessible from outside the private network)
• Queue worker is running and monitored (Supervisor or systemd)
• Scheduler cron job is configured
• VAPID keys are generated for production
• MAIL_FROM_ADDRESS uses your actual domain

What's Next

• Environment Configuration — Detailed reference for all environment variables.
• Architecture Overview — Understand the codebase before building features.
• Docker Setup — Reference for the development Docker environment.