Installation Guide

This guide walks you through installing Tenanto on your server or local development environment.

Requirements

Server Requirements

PHP Extensions

bcmath, ctype, curl, dom, fileinfo, hash, json,
mbstring, openssl, pcre, pdo, pdo_pgsql, session,
tokenizer, xml, redis

Installation Methods

Method 1: Docker (Recommended)

Docker provides the easiest setup with all services pre-configured.

Step 1: Extract the Package

unzip tenanto-v1.0.0.zip -d /path/to/your/projects/
cd /path/to/your/projects/tenanto

Step 2: Configure Environment

cp .env.example .env

Edit .env with your settings:

APP_NAME="Your SaaS Name"
APP_URL=https://yourdomain.com

# Database (Docker defaults work out of the box)
DB_CONNECTION=pgsql
DB_HOST=db
DB_PORT=5432
DB_DATABASE=tenanto
DB_USERNAME=tenanto
DB_PASSWORD=secret

# Redis
REDIS_HOST=redis
REDIS_PORT=6379

Step 3: Start Docker

docker compose up -d

This starts 7 services:

• app - PHP-FPM application
• nginx - Web server (ports 80, 443)
• db - PostgreSQL database
• redis - Cache and queue
• queue - Background job worker
• scheduler - Cron tasks
• mailhog - Email testing (port 8025)

Step 4: Install Dependencies

docker compose exec app composer install
docker compose exec app npm install && npm run build

Step 5: Initialize Application

docker compose exec app php artisan key:generate
docker compose exec app php artisan migrate --seed

Step 6: Configure DNS

Add to your hosts file:

Linux/macOS: /etc/hosts Windows: C:\Windows\System32\drivers\etc\hosts

127.0.0.1 yourdomain.local
127.0.0.1 admin.yourdomain.local
127.0.0.1 demo.yourdomain.local

Method 2: Traditional Server

Step 1: Clone/Upload Files

Upload the extracted files to your server's web root.

Step 2: Install Dependencies

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

Step 3: Configure Environment

cp .env.example .env
php artisan key:generate

Edit .env:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com

DB_CONNECTION=pgsql
DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=tenanto
DB_USERNAME=your_db_user
DB_PASSWORD=your_db_password

REDIS_HOST=localhost

Step 4: Database Setup

php artisan migrate --seed

Step 5: Web Server Configuration

Nginx:

server {
    listen 80;
    server_name yourdomain.com *.yourdomain.com;
    root /var/www/tenanto/public;

    index index.php;

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

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.4-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

Step 6: Permissions

chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

Step 7: Queue Worker & Scheduler

Supervisor (queue):

[program:tenanto-queue]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/tenanto/artisan queue:work redis --sleep=3 --tries=3
autostart=true
autorestart=true
user=www-data
numprocs=2

Cron (scheduler):

* * * * * cd /var/www/tenanto && php artisan schedule:run >> /dev/null 2>&1

Post-Installation

1. Access the Admin Panel

Navigate to http://admin.yourdomain.com/admin

Default credentials:

• Email: [email protected]
• Password: password

Important: Change this password immediately!

2. Create Your First Tenant

Go to Tenants → New tenant

3. Configure Stripe (Optional)

See Billing Setup for Stripe configuration.

Troubleshooting

Docker containers won't start

# Check Docker is running
docker info

# Check for port conflicts
netstat -tulpn | grep -E '80|443|5432'

# View logs
docker compose logs -f

"Class not found" errors

composer dump-autoload
php artisan config:clear
php artisan cache:clear
php artisan view:clear

Database connection refused

• Docker: Use db as host, not localhost
• Check PostgreSQL is running: docker compose ps
• Verify credentials in .env

Permissions errors

chmod -R 775 storage bootstrap/cache
# Docker:
docker compose exec app chmod -R 775 storage bootstrap/cache

Next Steps

• Admin Panel Guide - Managing tenants and users
• Tenant Panel Guide - Using the tenant admin
• Billing Setup - Configure Stripe integration