Installation

This guide walks you through installing VelvetCMS Core, from cloning the repository to running your first page.

Quick Start #

# Clone the repository
git clone https://github.com/VelvetCMS/core.git my-project
cd my-project

# Install dependencies
composer install --no-dev

# Run the setup wizard
./velvet install

# Start the development server
./velvet serve

Visit http://localhost:8000 to see your new VelvetCMS site.

Installation Methods #

Interactive Wizard (Recommended) #

The ./velvet install command launches an interactive setup wizard that guides you through all configuration options:

./velvet install

The wizard walks you through 6 steps:

1. Creating directories - Sets up required folder structure
2. Database configuration - Choose and configure your database
3. Database migrations - Create required tables
4. Content storage - Select how content is stored
5. Cache configuration - Choose your caching strategy
6. Additional options - Markdown parser, multi-tenancy, sample content

Non-Interactive Mode #

For automated deployments or CI/CD pipelines, use the --defaults flag:

./velvet install --defaults

This installs VelvetCMS with sensible defaults:

• SQLite database (storage/database.sqlite)
• File-based content driver
• File-based cache
• Auto-detected markdown parser
• Multi-tenancy disabled
• Sample content included

Command Flags #

Combine flags as needed:

# Re-install with defaults, no samples
./velvet install --defaults --force --no-sample

Wizard Walkthrough #

Step 1: Directory Structure #

The wizard creates the following directories:

my-project/
├── storage/
│   ├── cache/          # Cached data
│   ├── logs/           # Application logs
│   └── sessions/       # Session files
└── user/
    ├── config/         # Your configuration overrides
    ├── content/
    │   └── pages/      # Markdown page files
    ├── modules/        # Custom modules
    └── views/
        └── layouts/    # View templates

Step 2: Database Configuration #

Choose from three database drivers:

SQLite (Recommended for development)

Zero configuration required. Creates a database file at storage/database.sqlite:

Available drivers:
  [1] sqlite - Zero config, file-based (recommended)
  [2] mysql  - MySQL/MariaDB server
  [3] pgsql  - PostgreSQL server

Select database driver [1]:

MySQL / MariaDB

For MySQL, you'll be prompted for connection details:

Database host [127.0.0.1]: localhost
Database port [3306]: 3306
Database name [velvetcms]: my_velvet_db
Username [root]: velvet_user
Password: ********

Note: Create the database before running the installer. VelvetCMS will create tables but not the database itself.

PostgreSQL

Similar to MySQL, with PostgreSQL-specific defaults:

Database host [127.0.0.1]: localhost
Database port [5432]: 5432
Database name [velvetcms]: my_velvet_db
Username [postgres]: velvet_user
Password: ********

The wizard tests the connection and reports success or failure:

✓ Connection test: OK

Step 3: Database Migrations #

If a database connection was established, you'll be asked to run migrations:

Run database migrations? [Y/n]:

Migrations create the necessary tables for pages, users, and other core data. Skip this step if you're using an existing database with the tables already set up.

Step 4: Content Driver #

Choose how your content is stored:

Available drivers:
  [1] file   - Markdown files with frontmatter (recommended)
  [2] db     - All content in database
  [3] hybrid - Metadata in DB, content in files
  [4] auto   - Switches based on page count

Select content driver [1]:

Tip: Start with file for development. It's easy to version control and edit directly.

Step 5: Cache Driver #

Select your caching strategy:

Available drivers:
  [1] file  - File-based cache (works everywhere)
  [2] apcu  - In-memory (requires APCu extension)
  [3] redis - Redis server (requires connection)

Select cache driver [1]:

For Redis, you'll be prompted for connection details:

Redis host [127.0.0.1]: localhost
Redis port [6379]: 6379

Step 6: Additional Options #

Markdown Parser

VelvetCMS auto-detects available parsers:

Markdown parser:
  [1] commonmark - Full-featured (not installed)
  [2] parsedown  - Fast & simple (not installed)
  [3] html       - No parsing (raw HTML only)

Select parser [3]:

If your chosen parser isn't installed, you'll see a note:

Note: Run 'composer require league/commonmark'

Install your preferred parser:

# Full-featured (CommonMark spec, extensions support)
composer require league/commonmark

# Or lightweight alternative
composer require erusev/parsedown

Multi-Tenancy

Enable if you're running multiple sites from one installation:

Enable multi-tenancy? [y/N]: y

Tenant resolver:
  [1] host - Based on hostname/subdomain
  [2] path - Based on URL path segment

Select resolver [1]:

Sample Content

The wizard can create sample pages and layouts to get you started:

Create sample content? [Y/n]:

Sample content includes:

• A welcome page (user/content/pages/index.md)
• A basic layout (user/views/layouts/default.velvet)

Post-Installation #

Configuration Files #

After installation, your configuration lives in user/config/. These files override the defaults in config/:

user/config/
├── app.php        # Application settings
├── cache.php      # Cache driver settings
├── content.php    # Content driver settings
├── db.php         # Database connections
├── session.php    # Session handling
├── tenancy.php    # Multi-tenancy settings
└── view.php       # View/template settings

Edit these files directly to fine-tune your configuration.

Starting the Server #

Launch the built-in development server:

./velvet serve

Options:

# Custom host and port
./velvet serve --host=0.0.0.0 --port=3000

# With verbose output
./velvet serve -v

Verifying Installation #

Check your installation status:

./velvet about

This displays:

• VelvetCMS version
• PHP version
• Loaded extensions
• Active drivers (database, cache, content)
• Registered modules

Troubleshooting #

"Permission denied" on ./velvet #

Make the CLI executable:

chmod +x velvet

Database Connection Failed #

1. SQLite: Ensure storage/ directory is writable
2. MySQL/PostgreSQL: Verify credentials and that the database exists
3. Check the error message for specific details

Migrations Failed #

If migrations fail partway through:

# Check migration status
./velvet migrate:status

# Roll back and retry
./velvet migrate:rollback
./velvet migrate

Missing PHP Extensions #

Check required extensions are installed:

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

For optional extensions:

# APCu cache driver
php -m | grep apcu

# Redis cache driver
php -m | grep redis

"Class not found" Errors #

Regenerate the autoloader:

composer dump-autoload

Sample Content Not Showing #

1. Ensure you have a default layout at user/views/layouts/default.velvet
2. Check that your page's frontmatter references an existing layout
3. Clear the cache:

./velvet cache:clear

Next Steps #

• Overview - Learn what VelvetCMS can do
• Requirements - Detailed system requirements
• Configuration - Deep dive into configuration
• Creating Pages - Start building content