VelvetCMS Docs LATEST

Install & Bootstrap

Prerequisites, environment setup, and first boot of VelvetCMS Core.

Category: Getting Started

Requirements #

Dependency Version
PHP 8.3+ with pdo, mbstring, json
Composer 2.6+
Database SQLite (default), MySQL, or PostgreSQL
Extensions openssl, ctype, iconv, optional redis

Tip: PHP 8.4 works out of the box. The framework relies on readonly properties, first-class callable syntax, and other 8.x features—older runtimes are not supported.

1. Clone and install vendors #

git clone https://github.com/VelvetCMS/VelvetCMS-Core.git
cd VelvetCMS-Core
composer install

Composer registers the velvet binary automatically via the bin section in composer.json.

2. Run the installer #

./velvet install

InstallCommand performs four steps:

  1. Copies .env.example to .env (or writes a default file) and lets you re-run with --force if needed.
  2. Creates storage, content, and theme directories with safe permissions.
  3. Runs SQL migrations from database/migrations/*.sql using DefaultMigrationRunner and your configured connection.
  4. Ensures sample content exists (content/pages/welcome.md).

3. Configure the environment #

Open .env and adjust:

APP_NAME=VelvetCMS
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:8000

DB_CONNECTION=sqlite
DB_DATABASE=storage/database.sqlite

CACHE_DRIVER=file
CONTENT_DRIVER=file
  • Switching to MySQL/PostgreSQL? Update DB_* variables as defined in config/db.php.
  • To enable Redis cache, set CACHE_DRIVER=redis and provide REDIS_HOST, REDIS_PORT, REDIS_PASSWORD.
  • Velvet only distinguishes between production and “local” environments. Any value other than production is treated as local, which defaults to APP_DEBUG=true so you get formatted HTML/JSON exception pages.

4. Start the dev server #

./velvet serve --host=localhost --port=8000

The command wraps php -S and serves from public/. Browse to http://localhost:8000 to see the default theme render the welcome page via PageService.

5. Create your first page #

Ready to ship content? Head to the Quick Start guide, which walks through page:make, editing frontmatter, theming, publishing, and adding a module without repeating the install steps above.

Troubleshooting #

Symptom Fix
Error: Composer autoloader not found. Run composer install inside VelvetCMS-Core/.
Database connection failed during install Verify .env DB settings; SQLite path is relative to project root.
Route cache does not exist. Safe to ignore unless you previously cached routes. Run ./velvet route:cache to regenerate.
Permissions errors in storage Ensure storage/ is writable by your PHP user. Installer attempts to create directories at 0755.

Stay in the default local mode (anything except APP_ENV=production) while developing. Switch to production—which also defaults APP_DEBUG to false—before deploying to hide stack traces and serve the generic error page. Details live in the Deployment guide.

Previous VelvetCMS Core Overview Next Directory Structure