Installation Guide

⚠️ Documentation Under Review: This documentation is currently being updated and verified against the actual implementation. Some information may be incorrect or incomplete. Please verify all code examples against the actual source code before use.

Overview

This guide provides comprehensive instructions for installing and configuring the Neuron CMS component. Two installation methods are available: an automated installation command that handles configuration interactively, and a manual installation process for environments requiring specific customization or non-standard configurations.

System Requirements

PHP Requirements

Database Requirements

One of the following database systems is required:

Server Requirements

Software Dependencies

Installation Methods

Method 1: Automated Installation (Recommended)

The automated installation process utilizes the cms:install command to configure the system interactively.

Step 1: Install Package

composer require neuron-php/cms

This command installs the CMS package and its dependencies:

Step 2: Execute Installation Command

./vendor/bin/neuron cms:install [options]

Options:

Step 3: Installation Process

The installer executes the following operations sequentially:

3.1: Directory Structure Creation

Creates the application directory hierarchy:

app/
├── Controllers/
├── Events/
├── Initializers/
├── Jobs/
├── Listeners/
├── Models/
├── Repositories/
└── Services/

config/

db/
├── migrate/
└── seed/

public/

resources/
└── views/
    ├── admin/
    ├── auth/
    ├── blog/
    ├── content/
    ├── emails/
    ├── http_codes/
    ├── layouts/
    └── member/

storage/
├── cache/
└── logs/
3.2: View Template Publication

Publishes pre-built view templates from the package to the project's resources/views/ directory. Templates include:

3.3: Initializer Publication

Publishes application bootstrap initializers to app/Initializers/:

3.4: Configuration File Creation

Creates configuration files in config/:

neuron.yaml: Primary application configuration

system:
  timezone: UTC
  base_path: resources
  routes_path: resources/config

logging:
  destination: \Neuron\Log\Destination\File
  format: \Neuron\Log\Format\PlainText
  file: storage/logs/app.log
  level: info

cache:
  enabled: false
  storage: file
  path: storage/cache/views
  ttl: 3600
  html: true
  markdown: true
  json: false
  xml: false

views:
  path: resources/views

site:
  name: Neuron CMS
  url: https://localhost
  description: A modern content management system built with Neuron
  title: Neuron CMS

theme:
  admin: vapor
  subscriber: sandstone
  guest: sandstone

member:
  registration_enabled: true
  default_role: subscriber
  require_email_verification: true
  verification_url: /verify-email
  verification_token_expiration_minutes: 60

database:
  adapter: sqlite
  name: storage/database.sqlite3

auth.yaml: Authentication system configuration

auth:
  default: session

  session:
    lifetime: 120
    expire_on_close: false
    cookie_name: neuron_session
    cookie_httponly: true
    cookie_secure: true
    cookie_samesite: Lax

  remember:
    enabled: true
    lifetime: 43200

  passwords:
    min_length: 8
    require_uppercase: true
    require_lowercase: true
    require_numbers: true
    require_special_chars: false
    hash_algorithm: argon2id

  throttle:
    enabled: true
    max_attempts: 5
    lockout_duration: 15

routes.yaml: HTTP route definitions

Contains pre-configured routes for:

event-listeners.yaml: Event-to-listener mappings

Configures event listeners for system events.

3.5: Front Controller Creation

Creates public/index.php:

<?php

require_once __DIR__ . '/../vendor/autoload.php';

use function Neuron\Mvc\Boot;
use function Neuron\Mvc\Dispatch;

$app = Boot( __DIR__ . '/../config' );
Dispatch( $app );
3.6: Database Configuration

The installer prompts for database configuration:

For SQLite:

For MySQL/MariaDB:

For PostgreSQL:

The configuration is written to config/neuron.yaml.

3.7: Migration File Publication

Copies database migration files to db/migrate/:

Core Authentication & User Management:

Content Management:

Event Management:

Database Optimizations:

All migrations are copied during installation and can be executed immediately or later via ./vendor/bin/neuron db:migrate.

3.8: Migration Execution (Optional)

The installer offers to execute migrations immediately. If accepted, the following tables are created:

users table:

password_reset_tokens table:

email_verification_tokens table:

3.9: Administrative User Creation

The installer prompts for initial administrative user credentials:

The user is created with:

Method 2: Manual Installation

Manual installation provides complete control over the installation process.

Step 1: Install Package

composer require neuron-php/cms

Step 2: Create Directory Structure

mkdir -p app/{Controllers,Events,Initializers,Jobs,Listeners,Models,Repositories,Services}
mkdir -p config
mkdir -p db/{migrate,seed}
mkdir -p public
mkdir -p resources/views/{admin,auth,blog,content,emails,http_codes,layouts,member}
mkdir -p storage/{cache,logs}

Set appropriate permissions:

chmod 755 storage storage/cache storage/logs

Step 3: Publish View Templates

Copy view templates from the package:

cp -r vendor/neuron-php/cms/resources/views/* resources/views/

Alternatively, symlink for easier updates:

ln -s ../vendor/neuron-php/cms/resources/views resources/views

Step 4: Publish Initializers

cp -r vendor/neuron-php/cms/resources/app/Initializers/* app/Initializers/

Step 5: Create Configuration Files

config/neuron.yaml
system:
  timezone: America/New_York
  base_path: /var/www/html/project
  routes_path: /var/www/html/project/config

logging:
  destination: \Neuron\Log\Destination\File
  format: \Neuron\Log\Format\PlainText
  file: storage/logs/app.log
  level: info

cache:
  enabled: true
  storage: file
  path: storage/cache/views
  ttl: 3600
  html: true
  markdown: true
  json: false
  xml: false

views:
  path: resources/views

site:
  name: My Website
  title: Welcome to My Website
  url: https://example.com
  description: A comprehensive content management system

theme:
  admin: vapor
  subscriber: sandstone
  guest: sandstone

member:
  registration_enabled: true
  default_role: subscriber
  require_email_verification: true
  verification_url: /verify-email
  verification_token_expiration_minutes: 60

database:
  adapter: mysql
  host: localhost
  port: 3306
  name: cms_database
  user: cms_user
  pass: secure_password
  charset: utf8mb4
config/auth.yaml

Copy from package:

cp vendor/neuron-php/cms/config/auth.yaml config/

Or create manually with the structure shown in the automated installation section.

config/routes.yaml

Copy from package:

cp vendor/neuron-php/cms/resources/config/routes.yaml config/
config/event-listeners.yaml

Copy from package:

cp vendor/neuron-php/cms/resources/config/event-listeners.yaml config/

Step 6: Create Front Controller

Create public/index.php:

<?php

require_once __DIR__ . '/../vendor/autoload.php';

use function Neuron\Mvc\Boot;
use function Neuron\Mvc\Dispatch;

$app = Boot( __DIR__ . '/../config' );
Dispatch( $app );

Step 7: Configure Database

SQLite Configuration

Create the database file:

touch storage/database.sqlite3
chmod 644 storage/database.sqlite3

Ensure config/neuron.yaml contains:

database:
  adapter: sqlite
  name: storage/database.sqlite3
MySQL/MariaDB Configuration

Create the database:

CREATE DATABASE cms_database CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'cms_user'@'localhost' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON cms_database.* TO 'cms_user'@'localhost';
FLUSH PRIVILEGES;

Configure in config/neuron.yaml:

database:
  adapter: mysql
  host: localhost
  port: 3306
  name: cms_database
  user: cms_user
  pass: secure_password
  charset: utf8mb4
PostgreSQL Configuration

Create the database:

CREATE DATABASE cms_database;
CREATE USER cms_user WITH PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE cms_database TO cms_user;

Configure in config/neuron.yaml:

database:
  adapter: pgsql
  host: localhost
  port: 5432
  name: cms_database
  user: cms_user
  pass: secure_password

Step 8: Copy Migration Files

cp vendor/neuron-php/cms/resources/database/migrate/* db/migrate/

Step 9: Execute Migrations

./vendor/bin/neuron db:migrate

This creates the database schema.

Step 10: Create Administrative User

./vendor/bin/neuron cms:user:create

Follow the prompts to create an administrative account with the admin role.

Post-Installation Configuration

Email Configuration

Configure SMTP settings in config/neuron.yaml:

email:
  driver: smtp
  host: smtp.gmail.com
  port: 587
  username: [email protected]
  password: your-app-password
  encryption: tls
  from_address: [email protected]
  from_name: My Website
  test_mode: false

For development, enable test mode to log emails instead of sending:

email:
  test_mode: true

Member Registration Configuration

Configure member registration in config/neuron.yaml:

member:
  registration_enabled: true
  default_role: subscriber
  require_email_verification: true
  verification_url: /verify-email
  verification_token_expiration_minutes: 60

Cache Configuration

Enable caching for production:

cache:
  enabled: true
  storage: file
  path: storage/cache
  ttl: 3600
  html: true
  markdown: true

Session Configuration

For production with HTTPS:

auth:
  session:
    cookie_secure: true
    cookie_samesite: Strict

For development without HTTPS:

auth:
  session:
    cookie_secure: false
    cookie_samesite: Lax

Production Deployment

Web Server Configuration

Apache Configuration

Create .htaccess in public/:

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

Configure virtual host:

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

    <Directory /var/www/html/project/public>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/cms_error.log
    CustomLog ${APACHE_LOG_DIR}/cms_access.log combined
</VirtualHost>

Nginx Configuration

server {
    listen 80;
    server_name example.com;
    root /var/www/html/project/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_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\. {
        deny all;
    }
}

File Permissions

Set secure permissions:

# Set owner
chown -R www-data:www-data /var/www/html/project

# Set directory permissions
find /var/www/html/project -type d -exec chmod 755 {} \;

# Set file permissions
find /var/www/html/project -type f -exec chmod 644 {} \;

# Writable directories
chmod -R 775 /var/www/html/project/storage
chmod -R 775 /var/www/html/project/storage/cache
chmod -R 775 /var/www/html/project/storage/logs

Environment-Specific Configuration

Create separate configuration files:

config/
├── neuron.yaml              # Development
├── neuron.production.yaml   # Production
└── neuron.staging.yaml      # Staging

Load based on environment variable:

// public/index.php
$env = getenv( 'APP_ENV' ) ?: 'development';
$configFile = $env === 'production' ? 'neuron.production.yaml' : 'neuron.yaml';
$app = Boot( __DIR__ . '/../config', $configFile );

SSL/TLS Configuration

For HTTPS deployments:

  1. Obtain SSL certificate (Let's Encrypt, commercial CA)
  2. Configure web server for SSL
  3. Update config/auth.yaml:
auth:
  session:
    cookie_secure: true
  1. Update config/neuron.yaml:
site:
  url: https://example.com

Background Job Processing

Configure systemd service for job processing:

# /etc/systemd/system/neuron-jobs.service
[Unit]
Description=Neuron CMS Job Processor
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/html/project
ExecStart=/usr/bin/php /var/www/html/project/vendor/bin/neuron jobs:run
Restart=always

[Install]
WantedBy=multi-user.target

Enable and start:

systemctl enable neuron-jobs
systemctl start neuron-jobs

Verification

Automated Verification

Create a verification script verify-installation.php:

<?php

require_once __DIR__ . '/vendor/autoload.php';

$checks = [
    'PHP Version' => version_compare( PHP_VERSION, '8.4.0', '>=' ),
    'PDO Extension' => extension_loaded( 'pdo' ),
    'JSON Extension' => extension_loaded( 'json' ),
    'cURL Extension' => extension_loaded( 'curl' ),
    'Storage Writable' => is_writable( __DIR__ . '/storage' ),
    'Cache Writable' => is_writable( __DIR__ . '/storage/cache' ),
    'Logs Writable' => is_writable( __DIR__ . '/storage/logs' ),
    'Config Exists' => file_exists( __DIR__ . '/config/neuron.yaml' ),
];

foreach( $checks as $check => $result )
{
    echo sprintf( "%-20s: %s\n", $check, $result ? 'OK' : 'FAIL' );
}

Execute:

php verify-installation.php

Manual Verification

  1. Access login page: http://example.com/login
  2. Authenticate with administrative credentials
  3. Navigate to dashboard: http://example.com/admin
  4. Verify user listing: http://example.com/admin/users
  5. Create test post: http://example.com/admin/posts/create
  6. View public blog: http://example.com/blog

Troubleshooting

Database Connection Issues

Symptom: PDO connection exceptions

SQLite Solutions:

# Verify file exists
ls -l storage/database.sqlite3

# Check permissions
chmod 644 storage/database.sqlite3
chmod 755 storage

# Verify SQLite extension
php -m | grep pdo_sqlite

MySQL/PostgreSQL Solutions:

# Test connection
mysql -u cms_user -p -h localhost cms_database
psql -U cms_user -h localhost -d cms_database

# Verify credentials in config/neuron.yaml
# Ensure database exists
# Check firewall rules

Permission Errors

Symptom: Unable to write to storage directory

Solution:

# Set ownership
chown -R www-data:www-data storage

# Set permissions
chmod -R 775 storage

Session Issues

Symptom: Cannot maintain login session

Solutions:

  1. Verify session directory is writable
  2. Check session.save_path in php.ini
  3. Ensure cookies are enabled in browser
  4. Verify cookie_secure matches HTTPS availability
  5. Check cookie_samesite compatibility

Migration Failures

Symptom: Migration execution errors

Solutions:

# Verify database connection
./vendor/bin/neuron db:status

# Check migration syntax
php -l db/migrate/*.php

# Manual table creation
# (Execute SQL from migration files directly)

View Template Not Found

Symptom: Template file not found errors

Solutions:

# Verify views published
ls -la resources/views/admin

# Re-publish views
cp -r vendor/neuron-php/cms/resources/views/* resources/views/

# Check views.path in config/neuron.yaml

Composer Autoload Issues

Symptom: Class not found errors

Solution:

composer dump-autoload

Memory Limit Exceeded

Symptom: PHP fatal error: Allowed memory size exhausted

Solution:

# php.ini
memory_limit = 256M

Uninstallation

To remove the CMS:

  1. Backup database:
# SQLite
cp storage/database.sqlite3 backup/

# MySQL
mysqldump -u cms_user -p cms_database > backup.sql

# PostgreSQL
pg_dump -U cms_user cms_database > backup.sql
  1. Remove package:
composer remove neuron-php/cms
  1. Remove published files:
rm -rf resources/views/admin
rm -rf resources/views/auth
rm -rf resources/views/member
rm -rf app/Initializers
rm config/routes.yaml config/auth.yaml config/event-listeners.yaml
  1. Drop database tables (if desired):
DROP TABLE users;
DROP TABLE password_reset_tokens;
DROP TABLE email_verification_tokens;
DROP TABLE posts;
DROP TABLE categories;
DROP TABLE tags;

Additional Resources