Introduction
Deploying a CMS like October CMS should be a breeze, but sometimes you run into roadblocks. This guide addresses specific issues encountered when using the October CMS Deploy plugin for deployment.
Prerequisites
- A server running Ubuntu that meets October CMS requirements
- A LAMP stack: Apache, MySQL, and PHP
- October CMS and Deploy plugin installed
Issue 1: .envFile Permission
Problem
The Deploy plugin cannot write to the .envfile, leading to a non-writable file error.
Solution
Correct the file permissions using the command line:
chmod 644 /var/www/[your-domain]/.env
If you need to modify permissions for the entire directory, do so with caution:
chmod -R 755 /var/www/[your-domain]
Note: Restrict the use of 777permissions only to situations where it’s absolutely necessary and revert it back once the task is complete to avoid security risks.
Issue 2: Max Upload Size
Problem
The default server configuration limits the size of file uploads, which might not suit the needs of your site.
Solution
Increase the maximum file upload size by editing php.ini:
sudo nano /etc/php/[version]/apache2/php.ini
Locate and modify the following values:
upload_max_filesize = 64M
post_max_size = 64M
After changes, restart Apache to apply the new configuration:
sudo systemctl restart apache2
Issue 3: Missing PHP Extensions
Problem
Errors like “Class ‘ZipArchive’ not found” or “Class ‘DOMDocument’ not found” indicate missing PHP extensions.
Solution
Install the necessary PHP extensions with:
sudo apt-get install php-zip
sudo apt-get install php-xml
Always restart the web server after installing new PHP extensions.
Issue 4: .htaccess and Mod_Rewrite Not Enabled
Problem
The web server returns “Not Found” errors for CMS pages due to .htaccess not being read or mod_rewrite not being enabled.
Solution
Enable .htaccessby editing the Apache configuration file for your site:
sudo nano /etc/apache2/sites-available/[your-domain].conf
Within the <Directory> section for your document root, set AllowOverride All to enable .htaccess files:
sudo nano /etc/apache2/sites-available/[your-domain].conf
Within the <Directory>section for your document root, set AllowOverride Allto enable .htaccessfiles:
<Directory /var/www/[your-domain]> AllowOverride All </Directory>
Enable mod_rewritewith:
sudo a2enmod rewrite
Then, restart Apache:
sudo systemctl restart apache2
Issue 5: 404 Errors on CMS Pages
Problem
Receiving 404 errors when trying to access various CMS pages due to incorrect server configuration.
Solution
First, ensure the .htaccess file is in the root directory of October CMS with the correct rewrite rules. If it’s missing, download a fresh copy from the October CMS repository.
Check your Apache configuration to make sure it is set to process .htaccess files by allowing overrides as described in Issue 4.
This blog post provides a comprehensive approach to tackling common deployment issues with October CMS using the Deploy plugin. Adapting these solutions should help streamline the deployment process and enhance your overall experience with October CMS.