Creating an ExpressionEngine site on Linux - Stevenage, Hertfordshire UK

So you are installing an ExpressionEngine site on a development machine running linux.

There needs to be a check list because there are a number of things that can lead you to that white screen with the error message or worse, the one that is totally blank.

You've installed apache, you've installed mysql or mariadb, you've installed all the necessary php modules.

What's next?

I tend to separate the files that are deployed from the files that I use to build the site. So beneath my project directory I have a directory called deploy

e.g. /deploy

so you get

/deploy/public_html
/deploy/system

Notice that I move my system folder above the root of the site to keep from prying hacker eyes.
N.B. If you do this then you will need to update your index.php file and your admin.php file in the root of your public directory swapping out:

$system_path = './system';

for

$system_path = '../system';Of course you don't have to keep the name 'system'; just make sure that both the folder and the reference to it make tally. I also like to rename the admin.php file for further obfuscation.

The names inside the chevrons should be replaced with the real path to your project, servername or other project dependent string.

1. Create your virtual hosts file

Usually these are created in /etc/apache2/sites-available

These are named after your development server name e.g. mysite.dev.conf

So if your virtual host is called mysite.dev.conf then in the code below would be mysite.dev
Below is a template for use with PHP 8.3, you can just swap out the line
Define FCGIPHPVERSION "8.3.14"
for whatever version you are on if you are using fast CGI


<VirtualHost *:80>
	ServerName <your-server-name>
	DocumentRoot "<path-to-project-folder>/deploy/public_html"
  ErrorLog <path-to-project-folder>/logs/mysite-error.log
  CustomLog <path-to-project-folder>/logs/mysite-access.log common
  DirectoryIndex index.php index.html
	<Directory  "<path-to-project-folder>/deploy/public_html/">
		Options +Indexes +Includes +FollowSymLinks +MultiViews
		AllowOverride All
		Require local
	</Directory>
  <IfModule fcgid_module>
    Define FCGIPHPVERSION "8.3.14"
    FcgidInitialEnv PHPRC ${PHPROOT}${FCGIPHPVERSION}
    <Files ~ "\.php$">
      Options +Indexes +Includes +FollowSymLinks +MultiViews +ExecCGI
      AddHandler fcgid-script .php
      FcgidWrapper "${PHPROOT}${FCGIPHPVERSION}/php-cgi.exe".php
    </Files>
  </IfModule>
</VirtualHost>

Don't forget to create the logs directory in your project folder.
Tell apache to create the site:

sudo a2ensite mysite.dev.conf

then restart apache

sudo service apache2 restart

Watch out for any errors before proceeding further. My most repeated mistake is to forget to create the logs folder.

2. File permissions

Ensure that you still have the right permissions for your files.

The files below deploy should have the right ownership and permissions. Go to the deployment (e.g. deploy) directory of your project and run

sudo chown -R username:www-data <path-to-project-folder>/deploy/</path-to-project-folder>
sudo chmod -R 775 <path-to-project-folder>/deploy/</path-to-project-folder>
sudo chmod 666 <path-to-project-folder>/deploy/system/user/config/config.php</path-to-project-folder>You can double check on the required permissions in the EE docs here: https://docs.expressionengine.com/latest/installation/installation.html#3-set-file-permissions

3. Create your environment

If you are on ExpressionEngine version 7.0.0 or later

At the same level as your public_html (or www, whatever your chosen public folder name) create an .env.php file


#URLs #########
BASE_URL="<your-server-name>"
BASE_PATH="<path-to-project-folder>/deploy/public_html/"
THEME_URL=${BASE_URL}themes/
THEME_PATH=${BASE_PATH}themes/

# DATABASE SETTINGS
# # # # # # # # # # # #
DB_HOSTNAME=127.0.0.1
DB_DATABASE="<project-db-name>"
DB_USERNAME="<project-db-username>"
DB_PASSWORD="<project-db-password>"
DB_PORT=3306

# Debug
ENV_DEBUG=FALSE

The ENV_DEBUG comes in handy if you want to swap out things depending on the environment. e.g. if you want to use an uncompressed version of a stylesheet or JS file. Or just stop loading google analytics.

Go to your system/user/config/config.php file and add the following:


$config['database'] = array(
	'expressionengine' => array(
		'hostname' => $_ENV["DB_HOSTNAME"],
		'database' => $_ENV["DB_DATABASE"],
		'username' => $_ENV["DB_USERNAME"],
		'password' => $_ENV["DB_PASSWORD"],
		'dbprefix' => 'exp_',
		'port'     => ''
	),
);

4. get rid of index.php

Follow the instructions found here: https://docs.expressionengine.com/latest/installation/best-practices.html#removing-indexphp-from-your-urls

Now add in your .htaccess file to the root of your public directory. You may need to install some additional apache modules such as mod_rewrite. As before, swap out livesitename.com with the actual live domain name:


<IfModule mod_rewrite.c>
  RewriteEngine On

  # Redirect to https and force www
  RewriteCond %{HTTPS} off
  RewriteCond %{HTTP_HOST} !^dev
  RewriteCond %{HTTP_HOST} !^localhost
  RewriteCond %{HTTP_HOST} ^livesitename\.com [NC]
  RewriteRule ^(.*)$ https://livesitename.com/$1 [L,R=301,NC]

  #### force www ###
  RewriteCond %{HTTP_HOST} ^livesitename\.com [NC]
  RewriteCond %{HTTP_HOST} !^dev
  RewriteCond %{HTTP_HOST} !^localhost:3000.*$ [NC]
  RewriteRule ^(.*)$ https://www.wildlifeonline.me.uk/$1 [L,R=301,NC]


  # Removes index.php from ExpressionEngine URLs
  RewriteCond %{THE_REQUEST} ^GET.*index\.php [NC]
  RewriteCond %{REQUEST_URI} !/sys/.* [NC]
  RewriteRule (.*?)index\.php/*(.*) /$1$2 [R=301,NE,L]

  # Directs all EE web requests through the site index file
  RewriteCond $1 !\.(gif|jpe?g|png|pdf)$ [NC]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule ^(.*)$ /index.php/$1 [L]
</IfModule>

5. Rename index.html

If you find that some of your other pages are giving you an error, it might be that the site is only displaying your index.html file (you can see it listed in my virtual hosts example). The quickest answer to this is to rename it.

Why rename rather than delete? Well it can come in handy to use when you turn off the site during maintenance.

The logs are your friends

Normally you will find your apache log files in /var/log/apache2 and if you followed my configuration above, your site logs will be just where you put them!

<path-to-project-folder>/logs/</path-to-project-folder>

If you are still having problems, try changing your index.php or admin.php file to show

$debug = 1;
instead of
$debug = 0;

That will usually show up any errors that you may have. I haven't touched on creating an instand of the database in this post, so you may well be now looking at the sql error that this will result in!
Perhaps that is for another post?