Requirements

This page covers the software requirements for running VelvetCMS Core in development and production environments.

Quick Checklist #

PHP Requirements #

Version #

VelvetCMS requires PHP 8.4 or higher. It uses modern PHP features introduced in 8.4 and cannot run on earlier versions.

Check your PHP version:

php -v

Expected output:

PHP 8.4.x (cli) ...

Required Extensions #

These extensions must be enabled:

Check if they're installed:

php -m | grep -E 'pdo|mbstring|json'

All three should appear in the output.

Database-Specific Extensions #

Depending on your chosen database:

Note: Most PHP installations include pdo_sqlite by default.

Optional Extensions #

These extensions enable additional features:

APCu for High-Performance Caching

APCu provides in-memory caching that's faster than file-based caching:

# Install on Ubuntu/Debian
sudo apt install php8.4-apcu

# Install on Fedora
sudo dnf install php-pecl-apcu

# Install via PECL
pecl install apcu

Enable in php.ini:

extension=apcu.so
apc.enabled=1
apc.shm_size=64M

Redis for Distributed Caching

If you're running multiple servers or need persistent caching:

# Install the PHP extension
pecl install redis

# Or via package manager
sudo apt install php8.4-redis

Composer #

VelvetCMS uses Composer 2.x for dependency management.

Installation #

If you don't have Composer:

# Download installer
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"

# Install globally
php composer-setup.php --install-dir=/usr/local/bin --filename=composer

# Clean up
php -r "unlink('composer-setup.php');"

Verify Installation #

composer --version

Expected:

Composer version 2.7.x ...

Database #

VelvetCMS supports three database systems. Choose based on your needs.

SQLite (Recommended for Development) #

SQLite requires no setup - VelvetCMS creates the database file automatically.

Pros:

• Zero configuration
• No separate server process
• Portable (single file)
• Perfect for development

Cons:

• Limited concurrent writes
• Not suitable for high-traffic production

Check SQLite support:

php -m | grep pdo_sqlite

MySQL / MariaDB #

For production sites with moderate to high traffic.

Requirements:

• MySQL 8.0+ or MariaDB 10.6+
• pdo_mysql extension

Setup:

# Install MySQL (Ubuntu)
sudo apt install mysql-server

# Create database
mysql -u root -p

CREATE DATABASE velvetcms CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'velvet'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON velvetcms.* TO 'velvet'@'localhost';
FLUSH PRIVILEGES;

PostgreSQL #

For complex queries or when you need advanced database features.

Requirements:

• PostgreSQL 15+
• pdo_pgsql extension

Setup:

# Install PostgreSQL (Ubuntu)
sudo apt install postgresql

# Create database
sudo -u postgres psql

CREATE DATABASE velvetcms;
CREATE USER velvet WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE velvetcms TO velvet;

Web Server #

Development #

For local development, use the built-in PHP server via the Velvet CLI:

./velvet serve

This starts a server at http://localhost:8000.

Production #

In production, use a proper web server.

Nginx (Recommended)

server {
    listen 80;
    server_name example.com;
    root /var/www/velvetcms/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;
    }

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

Apache

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot /var/www/velvetcms/public

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

Create public/.htaccess:

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ index.php [L]
</IfModule>

Caddy

example.com {
    root * /var/www/velvetcms/public
    php_fastcgi unix//var/run/php/php8.4-fpm.sock
    file_server
    
    @notStatic {
        not file
    }
    rewrite @notStatic /index.php
}

Directory Permissions #

VelvetCMS needs write access to certain directories:

# Make storage writable
chmod -R 775 storage/
chmod -R 775 user/

# Set proper ownership (adjust user/group as needed)
chown -R www-data:www-data storage/ user/

Required writable directories:

Production Checklist #

Before deploying to production:

PHP Configuration #

; php.ini recommendations for production

; Enable OPcache
opcache.enable=1
opcache.memory_consumption=256
opcache.interned_strings_buffer=16
opcache.max_accelerated_files=10000
opcache.validate_timestamps=0  ; Set to 1 during development
opcache.save_comments=1
opcache.enable_file_override=1

; Increase memory if needed
memory_limit=256M

; Hide PHP version
expose_php=Off

Security Hardening #

1. Environment file: Keep user/config/ outside web root
2. Debug mode: Disable debug in production config
3. HTTPS: Always use HTTPS in production
4. File permissions: Web server should not have write access to src/

Performance Optimization #

# Generate optimized autoloader
composer dump-autoload --optimize

# Clear and warm caches
./velvet cache:clear
./velvet cache:warmup

Troubleshooting #

"PHP version must be at least 8.4.0" #

Upgrade PHP to 8.4+. On Ubuntu:

sudo add-apt-repository ppa:ondrej/php
sudo apt update
sudo apt install php8.4 php8.4-cli php8.4-fpm php8.4-pdo php8.4-mbstring

"Extension not found" Errors #

Install the missing extension:

# Find available extensions
apt search php8.4-

# Install (example: mbstring)
sudo apt install php8.4-mbstring

# Restart PHP-FPM
sudo systemctl restart php8.4-fpm

Permission Denied Errors #

# Fix storage permissions
chmod -R 775 storage/
chown -R www-data:www-data storage/

# On shared hosting, you may need:
chmod -R 777 storage/  # Less secure, use sparingly

Composer Memory Errors #

Increase PHP memory limit:

php -d memory_limit=-1 /usr/local/bin/composer install

Next Steps #

• Installation - Install VelvetCMS step by step
• Configuration - Configure your environment