Deploy October CMS with DeployHQ Guide

Prerequisites

An October CMS project ready for deployment
A Git repository (GitHub, GitLab, or Bitbucket)
A web hosting service or server with:
- PHP >= 7.4
- MySQL/PostgreSQL database
- Composer installed
- PHP extensions: PDO, cURL, OpenSSL, MBString, ZipArchive
SSL certificate (recommended)

Initial Setup

1. Create your October CMS project

# Install October CMS via Composer
composer create-project october/october myoctober

# Navigate to project
cd myoctober

# Install dependencies
composer install

# Generate application key
php artisan key:generate

2. Configure environment file

Copy and edit .env file:

cp .env.example .env

Essential .env configurations:

APP_DEBUG=false
APP_URL=https://your-domain.com
APP_KEY=your-generated-key

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=october
DB_USERNAME=root
DB_PASSWORD=password

CMS_ROUTES_CACHE=true
CMS_ASSET_CACHE=true
ENABLE_CSRF=true

3. Initialize Git repository

git init
git add .
git commit -m "Initial commit"
git remote add origin <your-repository-url>
git push -u origin main

DeployHQ Configuration

1. Create DeployHQ Account

Visit DeployHQ
Sign up for a new account

2. Create New Project

Click "New Project"
Choose project name
Select repository provider
Grant repository access

3. Configure Server

Go to "Servers & Groups"
Add new server
Configure server details:
- Server type (SFTP/SSH recommended)
- Hostname
- Username
- Authentication method
- Remote path

4. Configure Build Pipeline

Go to "Build Pipeline"
Add commands:

# Install Composer dependencies
composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader

# Clear and cache routes
php artisan route:cache

# Clear and cache config
php artisan config:cache

# Clear and cache views
php artisan view:cache

# October CMS specific commands
php artisan october:up
php artisan cache:clear

5. Configure Deployment

Go to "Deployment Config"
Set up file rules:

# Include
app/**/*
bootstrap/**/*
config/**/*
modules/**/*
plugins/**/*
themes/**/*
vendor/**/*
.htaccess
index.php
artisan

# Exclude
.env
.git/**/*
.github/**/*
storage/framework/cache/**/*
storage/framework/sessions/**/*
storage/framework/views/**/*
storage/logs/**/*
storage/app/**/*
tests/**/*

6. Environment Configuration

Add production environment variables
Configure database credentials
Set up mail settings
Configure cache and session settings

First Deployment

1. Database Setup

Create production database
Update .env with database credentials
Run migrations:

php artisan october:up

You can leave this command as a SSH Command and it will run every time. If there are no migrations, the command will end without errors

2. Storage Setup

# Set proper permissions
chmod -R 775 storage
chmod -R 775 bootstrap/cache

3. Initial Deployment

Go to "Deployments"
Click "Deploy Now"
Select branch
Review and confirm

Ongoing Usage

1. Regular Updates

# Make changes locally
git add .
git commit -m "Update changes"
git push origin main

2. Post-Deployment Tasks

Clear cache
Update database if needed
Check file permissions

Troubleshooting

500 Errors: Check storage permissions
White Screen: Enable debug mode temporarily
Database Issues: Verify credentials and migrations
Asset Problems: Check mix manifest and compilation
Cache Issues: Clear all cache types

Best Practices

Use deployment hooks for automation
Regular database backups
Implement staging environment
Monitor error logs
Keep October CMS updated
Use SSL/HTTPS
Configure proper caching

Production Configurations

1. Apache Configuration (.htaccess)

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /

    # Force HTTPS
    RewriteCond %{HTTPS} !=on
    RewriteRule ^ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]

    # Handle Front Controller
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^ index.php [L]
</IfModule>

2. Nginx Configuration

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    server_name your-domain.com;

    root /path/to/october/install;
    index index.php;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

3. Cache Configuration

// config/cache.php
'default' => env('CACHE_DRIVER', 'file'),
'stores' => [
    'redis' => [
        'driver' => 'redis',
        'connection' => 'default',
    ],
]

Security Considerations

Enable CSRF protection
Configure secure headers
Set up proper file permissions
Use strong passwords
Regular security updates
Enable SSL/HTTPS
Configure firewall rules

This guide provides a comprehensive approach to deploying October CMS using DeployHQ. Adjust configurations based on your specific needs and hosting environment. Remember to follow security best practices and keep your system updated.