Installation

Get ZephyrPHP up and running in under 5 minutes. One command to install, then the setup wizard handles the rest.

System Requirements

Requirement	Version/Details
PHP	8.2 or higher
Composer	2.0 or higher
PHP Extensions	PDO, mbstring, openssl, json
Database	MySQL 5.7+ / MariaDB / PostgreSQL / SQLite

Quick Install

composer create-project zephyrphp/starter mysite
cd mysite
php craftsman serve

Open http://localhost:8000 in your browser. The setup wizard will launch automatically.

Setup Wizard

The setup wizard runs automatically on first visit and handles everything:

Database Configuration — Enter your database credentials. The wizard tests the connection and creates the database if needed.
Admin Account — Create your admin user with email and password.
Security — APP_KEY is auto-generated on first boot. No manual step needed.
Done — You're redirected to the CMS admin panel at /cms.

No CLI After Install

After the initial composer create-project and php craftsman serve, everything else is managed through the GUI. Database setup, user management, content, themes, settings — all from the admin panel.

Environment Configuration

The .env file is created automatically from .env.example. Key settings:

# Application
APP_NAME="My Website"
APP_DEBUG=true
ENV=dev
APP_URL=http://localhost:8000

# Security (auto-generated on first boot if empty)
APP_KEY=

# Database (configured via setup wizard)
DB_CONNECTION=pdo_mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=mysite
DB_USERNAME=root
DB_PASSWORD=

Security

Never commit your .env file. It contains your database credentials and encryption key. Each environment should have its own .env file.

Directory Permissions

Ensure the storage/ directory is writable by your web server:

Linux/macOS:

chmod -R 775 storage

Windows:

Ensure your web server user has write access to the storage/ directory.

Web Server Configuration

Development

The built-in server is all you need for development:

php craftsman serve

Apache (Production)

ZephyrPHP includes an .htaccess file in public/. Ensure mod_rewrite is enabled:

<VirtualHost *:80>
    ServerName mysite.com
    DocumentRoot "/var/www/mysite/public"

    <Directory "/var/www/mysite/public">
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

Nginx (Production)

server {
    listen 80;
    server_name mysite.com;
    root /var/www/mysite/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_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

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

Troubleshooting

Blank Page / No Errors

Check storage/logs/app.log
Ensure APP_DEBUG=true in .env
Verify storage/ is writable

404 Errors on All Pages

Apache: Enable mod_rewrite and set AllowOverride All
Nginx: Verify try_files directive points to /index.php
Ensure document root points to public/

Database Connection Issues

Re-run the setup wizard by deleting the lock file:

rm storage/.installed

Then visit your site again — the wizard will restart.

Next Steps

Create your first Collection
Design pages with the Visual Page Builder
Customize your Theme