Cachet Deployment & Usage Guide

Prerequisites

PHP: Version 8.2 or later with extensions: pdo, mbstring, tokenizer, openssl, json, curl, gd, xml, ctype, fileinfo, bcmath
Composer: Latest stable version for dependency management
Database: One of the following:
- SQLite (default, file-based)
- MySQL 5.7+ / MariaDB 10.3+
- PostgreSQL 11+
Web Server: Nginx or Apache with mod_rewrite enabled
Optional: Redis (for queues/caching), Node.js (for asset compilation if modifying frontend)

Installation

1. Clone the Repository

git clone https://github.com/cachethq/cachet.git
cd cachet

2. Install PHP Dependencies

composer install --no-dev --optimize-autoloader

3. Environment Setup

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

4. Database Setup

For SQLite (quick start):

touch database/database.sqlite

For MySQL/PostgreSQL: Create a database and user with appropriate privileges.

5. Run Migrations

php artisan migrate

6. Create Admin User

php artisan cachet:user:create --name="Admin" --email="admin@example.com" --password="secure-password"

Configuration

Edit the .env file with your environment-specific values:

Core Application

APP_NAME="Cachet Status Page"
APP_ENV=production
APP_DEBUG=false
APP_URL=https://status.yourdomain.com

Database Configuration

SQLite (default):

DB_CONNECTION=sqlite
DB_DATABASE=/absolute/path/to/database.sqlite
DB_FOREIGN_KEYS=true

MySQL:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=cachet
DB_USERNAME=cachet_user
DB_PASSWORD=secure_password

PostgreSQL:

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=cachet
DB_USERNAME=cachet_user
DB_PASSWORD=secure_password

Cachet-Specific Settings

CACHET_ENABLED=true
CACHET_PATH=/
CACHET_DOMAIN=status.yourdomain.com
CACHET_GUARD=web
CACHET_USER_MIGRATIONS=true

Session Configuration

SESSION_DRIVER=database
SESSION_LIFETIME=120
SESSION_EXPIRE_ON_CLOSE=false
SESSION_ENCRYPT=false

Queue & Cache (Recommended for Production)

QUEUE_CONNECTION=database
CACHE_DRIVER=file
# Or use Redis:
# CACHE_DRIVER=redis
# QUEUE_CONNECTION=redis
# REDIS_HOST=127.0.0.1
# REDIS_PASSWORD=null
# REDIS_PORT=6379

Logging

LOG_CHANNEL=stack
LOG_LEVEL=error

Build & Run

Development Mode

php artisan serve --host=0.0.0.0 --port=8000

Access at http://localhost:8000

Production Optimization

After configuration changes, run:

php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan event:cache

Queue Worker (Required for Notifications)

Run a queue worker to process background jobs:

php artisan queue:work --sleep=3 --tries=3

For production, use Supervisor to keep the queue running:

[program:cachet-queue]
process_name=%(program_name)s_%(process_num)02d
command=php /path/to/cachet/artisan queue:work --sleep=3 --tries=3
autostart=true
autorestart=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/log/cachet-queue.log

Scheduler Setup

Add to crontab (crontab -e):

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

Web Server Configuration

Nginx example:

server {
    listen 80;
    listen [::]:80;
    server_name status.yourdomain.com;
    root /path/to/cachet/public;

    index index.php;

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

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

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Apache .htaccess (if not using provided public/.htaccess):

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteRule ^(.*)$ public/$1 [L]
</IfModule>

Deployment

Docker (Recommended)

Cachet provides official Docker support:

docker run -d \
  --name=cachet \
  -p 80:8000 \
  -e DB_DRIVER=sqlite \
  -e APP_KEY=base64:your-generated-key \
  cachethq/cachet:latest

For production Docker deployments with external database:

version: '3'
services:
  cachet:
    image: cachethq/cachet:latest
    ports:
      - "8000:8000"
    environment:
      - APP_ENV=production
      - APP_KEY=base64:your-key-here
      - DB_DRIVER=mysql
      - DB_HOST=db
      - DB_DATABASE=cachet
      - DB_USERNAME=cachet
      - DB_PASSWORD=secret
      - CACHE_DRIVER=redis
      - SESSION_DRIVER=redis
      - QUEUE_DRIVER=redis
      - REDIS_HOST=redis
    depends_on:
      - db
      - redis
  
  db:
    image: mysql:8.0
    environment:
      - MYSQL_DATABASE=cachet
      - MYSQL_USER=cachet
      - MYSQL_PASSWORD=secret
      - MYSQL_ROOT_PASSWORD=secret
    volumes:
      - mysql_data:/var/lib/mysql
  
  redis:
    image: redis:alpine

volumes:
  mysql_data:

Traditional VPS Deployment

Provision server with PHP 8.2+, Nginx, and MySQL/PostgreSQL
Clone repository to /var/www/cachet
Follow Installation steps above

Set proper permissions:

chown -R www-data:www-data /var/www/cachet
chmod -R 755 /var/www/cachet/storage
chmod -R 755 /var/www/cachet/bootstrap/cache

Configure Nginx/Apache virtual host
Enable SSL with Let's Encrypt (Certbot)

Platform-as-a-Service

Laravel Forge: Native support for Laravel applications; configure with PHP 8.2 and MySQL
DigitalOcean App Platform: Use Dockerfile or Nixpacks with PHP 8.2 runtime
Railway/Render: Deploy from GitHub repository with environment variables configured

Troubleshooting

Permission Denied Errors

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

Database Connection Issues

Verify database server is running: sudo systemctl status mysql
Check credentials in .env match actual database user
For SQLite: Ensure the web server user has write permissions to the database directory and .sqlite file

500 Errors with No Details

Set APP_DEBUG=true temporarily in .env to see detailed error messages. Disable in production.

Queue Jobs Not Processing

Verify queue worker is running: ps aux | grep queue:work
Check logs: tail -f storage/logs/laravel.log
Ensure QUEUE_CONNECTION matches your setup (database/redis)

Session Issues (Login Problems)

If using database driver (default), ensure the sessions table exists: php artisan migrate
Clear session cache: php artisan cache:clear and rm -rf storage/framework/sessions/*
Check SESSION_DOMAIN matches your actual domain

CSS/Assets Not Loading

Ensure the web root points to the /public directory, not the project root.

Demo Reset Notice

If testing the official demo, note it resets every 30 minutes (credentials: test@test.com / test123).

How to Deploy & Use CachetHQ/Cachet