Basics of Administering a GIAMedia (Drupal) Site

For this site, Drupal has been installed behind a web server with PostgreSQL. For Drupal system requirements, including the recommendations for web server, database and PHP requirements, see System Requirements.

Basic (First-time) Setup

Drupal was installed using composer. See basic Drupal installation notes: Drupal core 8.9.x install.txt. You should try to understand those, especially the basic system requirements for your system and the use of composer to manage dependencies for Drupal, its modules and tools. Brief summary of important steps:

1. Create a project folder and download GIAMedia This can be done by cloning the git repository for this project (not yet public, but hopefully soon: contact me) or by unpacking a downloaded project zip. This will give you a project folder and the composer.json and composer.lock files that define the Drupal version and software extensions used. This project has been tested and is in use on linux development and server installations: results may differ on other OS.
   • The steps described below are carried out in the project root folder unless otherwise specified. Note that the project root folder is not necessarily the root folder of your website (referred to as the "web root"). Using the GIAMedia folder layout and assuming that the "project root" is a folder called "giamedia" (e.g., /var/www/giamedia), the "web root" will be the folder named "web" inside drupal8 (i.e., /var/www/giamedia/web).
   • The "giamedia" folder, in addition to holding the web root, contains disk storage locations for data that is to be kept private from the web server (/private), a folder for site and database backups that keeps these outside the web root (/backups), a folder for local administration scripts (/bin, only containing a bash backup script so far), a configuration synchronization folder (/config/sync: more on that below) and a folder for the installation of composer packages (/vendor).

2. Within the project root folder issue the following command to download and install all of the Drupal software, including the extensions used by GIAMedia.

   composer install

3. The above command should have installed the command line tool called "drush" although you may need to adjust your search path to run it simply (see notes about installing a site-local copy of drush: https://docs.drush.org/en/master/install/). If so, you can create an empty database (see postgresql instructions for Drupal), create a database user account, noting the user name and password for use in this step, and initialize that with the following drush command if you are building a site without importing already created content.

   • Run the following command to initialize the database:

     drush site:install

     This will ask for the name of your database, the connection port (leave as default), the database username name and password. Use the details you set up while creating the database and database user account.

   • If you are cloning an existing site, again create an empty database, create a database user account (keeping the user name the same as used in the database being restored is easiest) and restore the backup from the working database into the newly created database. Configure your project to use the database just created (don't use drush site:install to initialize the database in this case).

4. The web server must be configured to serve the website using the "giamedia/web" folder as its document root. For generic instructions about configuring Drupal with an Apache2 server, see Install Drupal 8 with Apache, … Ignore instructions for setting up MySQL etc. and note that these instructions are probably adequate only for configuring the web server on a local development system (security settings recommended in these instructions are weak if you plan to expose this system to the public web).
5. You will often need to add group write privileges to files/folders under the project root to make Drupal work properly. See Securing file permissions and ownership for recommendations. In particular, note the use of owner and www-data group ownership settings. For a development site that is not really exposed to the internet you may not need to worry about this much but it is good to understand the issues.

A backup script (in giamedia/bin) assumes the presence of the giamedia/backups folder and should be run when needed from the project root folder. It's a bash script so appropriate for use on linux and possibly Mac OS but possibly not Windows. Storing the backups in /backups (outside of the web root) hides these files from the web server by default.

Similar to the separation of backup files  from the web server data, this folder layout includes a private folder that you can use to store uploaded files (images and other media) as part of the data created on this site. By default, these files will then also be invisible to the web server although they can be shared with authenticated (logged in) users through permissions configuration. When creating each Drupal content field type, you must select the option to store uploaded files using private storage if you want to manage site data this way. By default, uploaded files are stored as publicly accessible and the web server will allow access to these even for users that are not signed in.

Developing a Drupal Project so that it can be easily copied and redeployed

The procedure just completed should result in a working Drupal website (possibly at https://localhost or https://localhost/giamedia, depending on how you've configured the site and URL remapping within the web server). You are now ready to understand the mode of working with this Drupal project so that you can:

1. Easily replicate work done to date, possibly to create a new similar web site or to recreate the current website in the case of disaster.
2. Support experimentation with the site with the possibility of easily backing out changes that don't work and creating checkpoint versions that you can back up to if in the future you need to back out of a failed experiment.

To do this, you need to understand and use a software version control system to store a Drupal project in a code repository and commit successful updates to that as you develop the configuration of your website. I suggest you use the git version control system because that seems to be widely used with Drupal and there is community documentation and knowledge that refers to this approach.

Figure 1 shows the project components and important data flows in the development of sharing of a web site (e.g., when moving a working configuration from a development setup on your laptop to a production or testing server). The web server requires access to the Drupal software (core, modules and themes) as configured by composer. In addition, this project contains custom extensions to Drupal (e.g., the custom theme created to include a Leaflet map on the front page) and some patches that fix software problems or add features to the site software. Software additions to create custom extensions (such as the front page map) are added to the project folder (/web/themes/custom/mappy in this case) and then included in software version control as part of this project. As shown, this software has been included in git version control. Similarly, as composer is used to add published extensions to the Drupal software used in this project, the changes to the composer.json and composer.lock files are tracked in git version control. Finally, the configuration changes made to the Drupal site (e.g., definition of a page or rules about which users see a type of content) are reflected in the database but can be imported or exported on demand to the configuration synchronization folder (/config/sync) within the project folder. These folders are then also included in git version control (see notes on drush cim and drush cex commands, below). With this setup in place, a new installation of the project matching an existing working site can be created by pushing the software changes from your development system to the new site (or a site needing to be updated) through the version control system (see git documentation listed below for guidance on how to accomplish this).

If you have created your project by cloning a git repository, you are set to move on. Otherwise, create a git repository for the project and commit the basic project information to it. The idea here is to create a Drupal development site in which the project configuration is tracked in git version control, as described above)

Tracking site updates through a single method works only to a certain point with Drupal because of the amount of the configuration that is carried in the database. As discussed above, software and configuration changes can be tracked using software version control. Changes that have been made in the site content appear as changes in the database or as changes in the media folder of the Drupal site. These must be managed separately and it is more common to move these from the public site once up and running back to the development site when you want to test problems being reported or develop new features that will eventually require updated software to again be moved from the development system to the production site.

See the following pages for instructions and guidance about setting up software version control for a Drupal site using git:

• Using Configuration Management and Git in Drupal 8.
• Add a sensible .gitignore file. This discussion was useful in understanding the intended interaction between git and composer in managing the site. Setting up a .gitignore (or two with the Drupal 8+ structure that includes the web root in, for example, giamedia/web) is an important step in managing a project this way. Drupal 8+ leaves this for every system administrator to figure out but this is now included in the repository for THIS project so you can inherit that by cloning this project.

Ongoing work on your site

You are now ready to install application-specific extensions to the Drupal software as needed, configure options of the site or create content on the site. Depending on the changes you make, the changes will be reflected in different ways on the Drupal site.

• software extensions added using composer will be reflected in the composer.json and composer.lock files in the project root folder (these are version controlled files in this project and should be in most Drupal 8+ projects) and in the contents of the vendor folder (not version controlled because it can be recreated when needed based on composer.json and composer.lock).
  • When software extensions are added to the site and you have verified that these should be kept, you simply need to commit the changed versions of the composer.json and composer.lock files to version control.

  • To add a Drupal module, referred to as <mod>, using composer, visit the module project web page and click on the version of the module that best matches your site (based mainly on software version but sometimes also depending on features available in different versions). The download page for a Drupal module always includes the composer command you need to run to add that extension to your site. It will be of the form of the first of the following commands (or similar with specific version information added to the requirement specification). The second command simply enables the new module in the site configuration.

    composer require 'drupal/<mod>'
drush en <mod>

• Drupal core and module options configured using drush or the Drupal web interface will be reflected in updates in the Drupal database.
  • When you are happy with changes of this sort and want to commit these to version control, you must first use the Drupal Configuration Management interfaces (either drush as below or the configuration synchronization web interface in the web site itself) to export the configuration changes to an external view of those changes. This project includes a config/sync folder within the project root that is version controlled and this is used to store these "externalized" views of site configuration changes.

  • The following command executed in the project root folder will export the changes (since the last configuration export) to the Drupal site configuration from the database:

    drush cex

  • When you need to apply externalized configuration to your Drupal site, you can reverse the above command by importing the contents of the config/sync folder back into the database using:

    drush cim
• Content created (instances of document types and menu links, for example) on the Drupal site will be reflected in updates in the Drupal database.
  • For backup purpose and to share (when appropriate) these changes from your site, you must back up the project database.

See the web page on configuration management above. It discusses scenarios in which you want to move configuration, as developed, from a development system to a production system. The configuration management, version control and the backups of your Drupal site will help you to ensure that you only move working site changes onto your production site.