SaasForgeKit Docs

Appearance

Deploy on a VPS ​

This guide explains a manual production deployment of SaasForgeKit on a VPS (Ubuntu/Debian style workflow with Nginx or Apache).

1) Prerequisites ​

  • A VPS with SSH access
  • PHP 8.4+ and required PHP extensions
  • Composer 2+
  • Node.js 18+ and npm
  • MySQL 8+ or MariaDB 10.5+
  • A web server (Nginx or Apache)
  • A process manager for queues (Supervisor recommended)

2) Upload project files ​

Deploy your project to a directory such as:

bash
/var/www/saasforgekit

You can upload files directly or clone from Git.

3) Install dependencies ​

From project root:

bash
composer install --no-dev --optimize-autoloader
npm install
npm run build

4) Configure environment ​

Create .env from .env.example and set production values:

bash
cp .env.example .env

At minimum, configure:

  • APP_ENV=production
  • APP_DEBUG=false
  • APP_URL=https://your-domain.com
  • Database credentials (DB_*)
  • Mail settings (MAIL_*)
  • Stripe keys (STRIPE_*)
  • Social auth credentials (GOOGLE_*, GITHUB_*) if used

Set tenancy mode before migrations:

env
TENANCY_DB_MODE=single_db

Use multi_db only if your DB infrastructure is prepared for per-tenant databases.

If you use multi_db ​

Your DB user must have privileges to create/manage tenant databases. For MySQL/MariaDB this usually means:

  • CREATE / DROP database-level capability
  • Full schema privileges inside tenant databases (tables, indexes, etc.)

Example grant strategy (adjust names/host/password):

sql
CREATE USER 'saasforgekit'@'%' IDENTIFIED BY 'strong_password_here';
GRANT ALL PRIVILEGES ON `tenant%`.* TO 'saasforgekit'@'%';
GRANT ALL PRIVILEGES ON `saasforgekit_central`.* TO 'saasforgekit'@'%';
FLUSH PRIVILEGES;

Using a tenant% prefix keeps grants scoped to tenant databases rather than all databases on the server.

5) Generate key, link storage, run migrations ​

bash
php artisan key:generate
php artisan storage:link
php artisan migrate --force

If this is your first deployment and you need the default admin user:

bash
php artisan db:seed --class=AdminRoleSeeder --force

6) Set file permissions ​

Ensure web server user can write to storage and cache directories:

bash
sudo chown -R www-data:www-data /var/www/saasforgekit
sudo chmod -R 775 /var/www/saasforgekit/storage /var/www/saasforgekit/bootstrap/cache

7) Configure web server ​

Point your document root to:

text
/var/www/saasforgekit/public

Nginx (example) ​

nginx
server {
    server_name your-domain.com;
    root /var/www/saasforgekit/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.4-fpm.sock;
    }
}

8) Run queue worker in production ​

SaasForgeKit uses queues (emails, billing events, background jobs). Run a persistent worker with Supervisor.

Example program:

ini
[program:saasforgekit-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/saasforgekit/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=/var/www/saasforgekit/storage/logs/worker.log

9) Post-deploy checklist ​

  • Site loads over HTTPS
  • Login works
  • Admin account exists (if seeded):
  • Queue worker is running
  • Stripe webhook endpoint is reachable (if Stripe is enabled)