The server

Setting up a local server that matches as closely as possible the hosting server can help reduce the amount of deployment issues that have to be solved. In my case my host uses Ubuntu, MySQL, Apache2, and PHP, along with the mpm-itk module for apache2 (see http://mpm-itk.sesse.net/ and notes below). In addition, PHP modules are requirements of SilverStripe. So starting with a fresh Ubuntu (because that is what my web-host runs) installation:

sudo apt install zip unzip p7zip
sudo apt install tasksel
sudo tasksel install lamp-server
sudo apt install libapache2-mpm-itk
sudo apt install php7.4-common php7.4-xml php7.4-intl php7.4-mbstring php7.4-curl
sudo a2enmod mpm_itk
sudo a2enmod rewrite

My web-host is configured so that when a site is created, it is assigned to a specific web-host/server. On that server there is an associated Linux user added to the system that supports this site. In that user’s home directory a directory is created with the same name as the site name. That directory contains the public facing contents of the site. In our case, we want to change that directory to be a symbolic link instead, and then that link will point at the public folder within the Silverstripe installation.

We want to configure the local server the same way so that deployments to this test server are the same as to the live server. This means having site contents stored under my home directory and owned by my Linux user (as apposed to the www-data user).

I’m not a proponent of having a local development environment that is totally dissimilar to the production environment. I want my local environment to provide some assurance that when I deploy, it will work. I’m willing to deal with some lack of work-flow to get that, though in practice, it is not a big deal.

Global MySQL installation

MySQL is by default installed with a root user that can administer the server, and this account is set to have no password. Note that the MySQL root user is not the same as the Linux user root, although the only Linux user that can access the MySQL root user is the Linux root user. So to update the MySQL root user to something more secure than a blank password:

sudo mysql_secure_installation

To log into MySQL run the following and use the password just entered

sudo mysql -u root -p

Note that there are two forks of MySQL, MySQL and MariaDB, for our purposes, either will work fine.

Global Apache Configuration

/etc/apache2/apache2.conf - these are all default values, but are important and worth noting here so they can be verified.

• Enable configuration within .htaccess files.

    AccessFileName .htaccess

• Disallow any access to .htaccess though the web-server.

    <FilesMatch "^\.ht">
        Require all denied
    </FilesMatch>

• Load the site-specific configuration from a file.

    IncludeOptional sites-enabled/*.conf

Composer installation

Install composer from source (not from your linux system’s repository) so that it is located at /usr/local/bin/composer. It needs to be a current version and the linux repository versions (ie. apt install …) are not kept up to date enough to avoid issues.

Then follow the guide at https://getcomposer.org/download/ . In my case I ran this, but update the middle section based on what is specified at getcompser.org:

cd
mkdir composer
cd composer


php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php -r "if (hash_file('sha384', 'composer-setup.php') === '756890a4488ce9024fc62c56153228907f1545c228516cbf63f885e036d37e9a59d27d63f46af1d4d07ee0f76181c7d3') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
php composer-setup.php
php -r "unlink('composer-setup.php');"

sudo cp composer.phar /usr/local/bin/composer
cd
composer -V

The last command should return with the composer version number.

Site-specific SilverStripe installation

Create a Silverstripe install for the site. The last name silverstripe below is the folder name the installation will be created in, e.g. /home/ken/silverstripe:

cd
composer create-project silverstripe/installer silverstripe

Site-specific Database setup

Follow guide at https://rainshowers.org/post/mysql_user_db/ to create database and user. Also, read the notes on that page for “gotchas” you may encounter.

For example, the database name might be silverstripe_db and the user silverstripe_user'@'localhost'. An example session:

ken@ubuntu:~$ sudo mysql -u root -p
[sudo] password for ken:      // Linux user password
Enter password:               // MySQL root password

mysql> create user 'silverstripe_user'@'localhost' identified by 'reallystrongpassword';
Query OK, 0 rows affected (0.16 sec)

mysql> create database silverstripe_db;
Query OK, 1 row affected (0.82 sec)

mysql> grant all privileges on silverstripe_db.* to 'silverstripe_user'@'localhost';
Query OK, 0 rows affected (0.80 sec)

mysql> quit
Bye
ken@ubuntu:~$

Site-specific Apache Configuration

For example /etc/apache2/sites-enabled/001-art-rainshowers.conf is a symlink to ../site-available/001-art-rainshowers.conf. In site-available there is a 000-default.conf file, and the below configuration differs from the default/example in that:

• ServerName is specified
• DocumentRoot is changed to the the name of a symlink in the home folder that points at the public folder of the site
• ErrorLog and CustomLog are made specific to the site name
• A Directory section is added for the site
• The mpm_itk_module is enabled

cd /etc/apache2/sites-available
sudo nano 001-art-rainshowers.conf

This file contains a virtual-host for the site, add this to the file and save it:

<VirtualHost *:80>
        ServerName art.rainshowers.org
        ServerAdmin webmaster@localhost
        DocumentRoot /home/ken/art.rainshowers.org
        <Directory /home/ken/art.rainshowers.org>
            Options Indexes FollowSymLinks
            Require all granted
            DirectoryIndex index.html index.php
            # this directive allows .htaccess file to function
            AllowOverride All
        </Directory>
        ErrorLog ${APACHE_LOG_DIR}/silverstripe.log
        CustomLog ${APACHE_LOG_DIR}/silverstripe.log combined
        # This enables serving the site from under the home directory.
        # The linux username in this case is ken, but may differ on the live site.
        <IfModule mpm_itk_module>
            AssignUserId ken www-data
        </IfModule>
</VirtualHost>

Silverstripe environment settings

This takes care of three interests:

(1) The credentials to connect to the database. Note that the user and database need to be created, but should be empty to start out with.

SS_DATABASE_CLASS="MySQLDatabase"
SS_DATABASE_SERVER="localhost"
SS_DATABASE_USERNAME="silverstripe_user"
SS_DATABASE_PASSWORD="***********"
SS_DATABASE_NAME="silverstripe_db"

(2) The credentials to login to the CMS admin section of the site. Navigate to your site in the browser and change the path to /admin. The login screen will ask for an “Email” but the email in the case of the admin login is just “admin”.

SS_DEFAULT_ADMIN_USERNAME="admin"
SS_DEFAULT_ADMIN_PASSWORD="***********"

(3) The development vs. production environment setting.

SS_ENVIRONMENT_TYPE="dev"

All of these items are configured in environment variables. However, how these variables get set is confusing. There are two options:

(1) Configure the variables in the web-server’s configuration. If you have a dedicated server in which you can configure apache environment variables outside of the document root of the site, this is a viable and preferred method. However, when running a site on a apache based shared server environment / host, you don’t have access to add this configuration and at best would have to add this to a .htaccess file. The .htaccess file is by design located within the web-root of the site and putting anything credential related under the web-root is not a viable option. So we are left with option 2. There is a note in the Silverstripe “lessons” that indicates that the .env file is only meant for development environments and not a live server. This is misleading in my opinion, as most shared hosting does not support setting “true” environment variables safely.

(2) Configure varabiles in the .env file in the project root (one level higher than the web-root). The .env file is read by the PHP Silverstripe scripts, and as a result does not need to be in a location that is accessable by the web-server (the web-root).

For example, a typical shared hosting environment a user’s site will be within their home directory on the server as a subdirectory:

/home/ken                        <--- user's home directory
/home/ken/art.rainshowers.org    <--- shared hosting sets this folder as the web-root of the site
/home/ken/silverstripe           <--- user installation of Silverstripe
/home/ken/silverstripe/.env      <--- .env file for silverstripe configuration
/home/ken/silverstripe/public    <--- the folder that is designed to be the web-root of the Silverstripe installation

Shared hosting sets /home/ken/art.rainshowers.org as the web-root of the site. This name cannot be changed, though we are going to change it from being a directory to being a sym-link. In order for this folder be the webroot, it needs to be converted to a symlink that points to the /home/ken/silverstripe/public folder.

cd
mv art.rainshowers.org art.rainshowers.org_original
ln -s silverstripe/public art.rainshowers.org

Configuration of the .env file.

cd
cd silverstripe
cp .env.example .env
nano .env

Edit the SS_ENVIRONMENT_TYPE, SS_DATABASE_ and add entries for SS_DEFAULT_ADMIN_USERNAME and SS_DEFAULT_ADMIN_PASSWORD.

Visit the site in the browser, e.g. http://art.rainshowers.org. Silverstripe will redirect to dev/build and it will create the database content for the site. Once that is complete you can again go to the site and the default page for the site should load. You can also go to the admin section of the site by going to, e.g. http://art.rainshowers.org/admin.