Recap

We will use Next.js for the Frontend as it is one of the most performant systems I’ve seen. Performance is my goal for both SEO and UX reasons. For our backend we are going to use Drupal because, in my opinion, it is unrivalled for functionality, security, extendibility and all the other reasons we would choose a Backend.

The reasons for choosing this headless ‘pattern’ over simply creating a website in, for example Drupal, is performance. A CMS cannot compare to a website created in today’s frontend specific tec and a website created with a new, fast, framework cannot compete with a mature CMS for functionality (not yet anyway).

For a full recap, have a read of Going Headless: A CMS Story, what and why go headless – Part 1.

Todo list

We have 3 main goals to achieve to create for this headless system:

Hosting and Domain from Hostinger.
Drupal CMS install and configure.
Next.js install and configure.

We will look at the first 2 in this part of the article.

Hosting & Domain

Skip this step and move to Drupal CMS if you’re working locally or have your own hosting and domain. You can use any hosting you’re comfortable with and I’d advise using your local if you’ve not done this before or are on a budget. I’ve chosen Hostinger because I know everything works.

Go to Hostinger (or other host) and purchase the one you feel comfortable with. The cheapest will work, and you can upgrade at any time. At the time of writing, you can purchase Premium (for 4 years for) for $44 per year. You can get free hosting on something like AWS, but it will cost a lot in a year when the free tier ends. I’ve used AWS a few times and it works well.

Once the hosting is purchased, you’ll want to wait for the setup, which can take a few minutes. Just long enough for a nice tea or coffee.

After everything is setup by the host, you’ll need to fill in some forms, make sure this is correct, especially for the domain, because it can be a lot for work to fix it if there are issues. I didn’t check on the domain information when moving domain, a while ago and it was suspended for over a week. I got it back with a contact to Nominet.

If you do have issues with domains let me know and I’ll try to help you fix it.

You should now have hosting with 1 domain.

Click on websites on the left and choose the dashboard for your domain (if there isn’t one you may need to create it with the Add website button, use Empty PHP/HTMP website and the domain you have purchased).

If you have a domain with a different company than your host, it will make things more difficult. You’ll need to change the name server values so your registrar is still the same i.e. you pay the same company for the domain, but your hosting company manages the server. It can take up to 24 hours for a change to the name servers to propagate, but you can usually see it within a few minutes.

Once you are set up and have hosting and domain connected, we can move on.

SSL

Hostinger install your SSL certificate automatically, but we want to check if it is complete. Click security on the left, then SSL. If it says pending, you’ll need to wait a little longer (5 minutes at most). If it’s active, then you are ready to server traffic using https.

Before moving on you’ll want to make sure SSL is working correctly (unless using local), because your site might not appear on Google if you don’t have SSL so make sure this is working.

Subdomain

We want the CMS on its own subdomain, not a separate domain name. This helps you manage what CMS goes with what and makes it easier for CORS and other security. This tutorial is 1 CMS per website, but you could always add all the CMS systems to the same domain and have your client’s login to their own part of the CMS (think something like Shopify), which is pretty simple, but not in scope of this tutorial.

On the left, click Domains -> Subdomains and you’ll have a form with the main domain filled in. Add in ‘cms’ (lower case) to the subdomain field and hit create.

Once that is done, check the SSL cert (same as above) and wait for your CMS SLL to be active too.

If you go to the subdomain (e.g. https://cms.yourdomain.com) you should see the Hostinger page and if you try the http version, we should be redirected to the correct https version as Hostinger sets all this up for you.

If there are any issues, check for typos and give it some extra time (it can take some time depending on location). If you still can’t get it working leave me a comment and I’ll try to help.

Local

My usual way of working is to create the system locally, test it, create a repository for it, and push the code up. With a CMS we won’t be changing too much, but we’ll still make a few adjustments to the theme and adding some modules (yes, I add mods to the repo because I’ve had mods disappear before).

I usually use Docker locally because it saves installing everything and will work on Windows and Linux depending how I’m working. We'll do the same here.

We'll need to install Docker first, but if you already have it skip to running containers below.

Go to Docker and follow the instructions for your operating system e.g. for Windows the instructions are:

Download the installer using the download button at the top of the page.
Double-click Docker Desktop Installer.exe to run the installer. By default, Docker Desktop is installed at C:\Program Files\Docker\Docker.
When prompted, ensure the Use WSL 2 option on the Configuration page is selected.
Follow the instructions on the installation wizard to authorize the installer and proceed with the install.
When the installation is successful, select 'Close' to complete the installation process.
Start Docker
Select Accept to continue.
Docker Desktop starts after you accept the terms.

Running containers

To run Drupal locally we need one Docker container for MySQL and one for Drupal. All the instructions are here, but I’ve put together the simple version for you.

Let’s start with the MySQL container, in PowerShell run:

docker run -d --name drupal-mysql --restart unless-stopped -p 3306:3306 -e MYSQL_DATABASE=drupal_db -e MYSQL_USER=user -e MYSQL_PASSWORD=qwerty123 -e MYSQL_ROOT_PASSWORD=password mysql:5.7

Once this is complete, you will have a MySQL database, on the usual port 3306, with a simple username ‘user’ and password ‘qwerty123’ for use locally only. The MySQL container should also run when Docker starts (with your computer) because of the line --restart unless-stopped.

Once this has complete, we can create the Drupal container, but:

We don’t want the container running on port 80 as that may be used for a Frontend (not in this tutorial), so we map it to port 8080.
We keep it running with Docker with --restart unless-stopped ever after restart.
We cannot access the files outside the container. This is fine for some cases, but for myself I want to access the files in Windows as that is where my IDE is. To get that working we must create a Docker volume to hold the files and sysc it to a place in the drupal container.

docker volume create drupal-volume
docker run --name drupal -p 8080:80 -d -v drupal-volume:/var/www/html drupal 
docker run --name drupal --restart unless-stopped -p 8080:80 -d -v drupal-volume:/var/www/html drupal

Files are now stored in \\wsl$\docker-desktop-data\data\docker\volumes\drupal-volume\_data

CMS Install, update & configure

If you go to http://localhost:8080 you will see the install for the new Drupal site. Follow the instructions, including adding the database details (you may need to hit advanced and change the URL if it cannot be found, don’t forget the port).

Webpage showing welcome for Tramp Creative

Once it’s all setup the system will install all the new mods and translations for you and setup with the basic theme. We’ll replace this first.

Themes

There are lots of themes for Drupal, both paid and free we can add at any time. Our goal is headless, so we need a theme for the admin side for editors and a theme for the to disable most of the Drupal Frontend.

Admin Theme

Let’s deal with a good, solid admin theme first:

Hit Appearance at the top.
Open a new tab and go to the theme Gin.
At the bottom click the link for the release (at the time of writing 8.x-3.0-rc13).
Under “Alternative installation files” right-click Download tar.gz and choose “copy link address”.
Back in your CMS Appearance tab click the “Add new theme” button.
Paste in the link and hit the “Continue” button.
Back in Appearance click “Install” under the new Gin theme (not “Install and set”…).
At the bottom under “Administration theme” select Gin and click the button “Save configuration”

Headless Theme

Now we need a theme to use for the Drupal Frontend that will not show content. This is to stop any duplication of content in search engines (you will be penalised for this). We’ll use robots.txt to make sure our CMS is not picked up on search engines, but we want to make sure nothing shows to visitors too.

Install the Bootstrap theme as above, but in step 7 hit “Install and set as default” and don’t do step 8. Now we have a new theme, but unless you hit the home button or view a page on the site you won’t see it. We work in the admin side unless logging in or viewing content.

Our aim is to create a new theme from the Bootstrap theme, that is exactly the same until we override something. This makes updating a theme simple and uncluttered and Drupal can do some of the work for us.

Hit Appearance at the top.
Click the Settings tab under Appearance then the Bootstrap5 tab.
Scroll down to the bottom and open the Subtheme tab.
Change:
1. Subtheme location to “themes”.
2. Subtheme name to “Headless”.
3. Subtheme machine name to “headless”.
Click the red Create button.
Hit Appearance at the top.

You will now have a new theme in your list called “Headless”. You could install it, but don’t do that just yet as we don’t have a Frontend to show content.

In your file structure, find the new headless theme in under ‘themes/headless’.

If you open headless.info.yml you’ll see a line around 5 showing 'base theme': bootstrap5. Any time the theme needs a file and doesn’t find it, it’ll check in the base theme. If you want to have a look at any defaults, check in the bootstrap5 theme. It’s very well documented. We need to override the titles so we only ever see ‘CMS’, then we need to override the content so it is empty unless logged in. If a visitor sees the page it will not show content erroneously.

In our headless folder create a new folder called ‘templates’, in that folder create 2 more folders:

layout
content

Within the content folder create 2 files:

node.html.twig
page-title.html.twig

Folder structure for the CMS showing the 3 new pages

Within the layout folder create the file html.html.twig and add the code:

{%
  set body_classes = [
    logged_in ? 'user-logged-in',
    not root_path ? 'path-frontpage' : 'path-' ~ root_path|clean_class,
    node_type ? 'page-node-type-' ~ node_type|clean_class,
    db_offline ? 'db-offline',
    (b5_body_schema == 'light' ? ' text-dark' : (b5_body_schema == 'dark' ? ' text-light' :  ' ')),
    (b5_body_bg_schema != 'none' ? " bg-#{b5_body_bg_schema}" : ' '),
    'd-flex flex-column h-100'
  ]
%}
<!DOCTYPE html>
<html{{ html_attributes.addClass('h-100') }}>
  <head>
    <title>CMS</title>
    <css-placeholder token="{{ placeholder_token }}">
    <js-placeholder token="{{ placeholder_token }}">
  </head>
  <body{{ attributes.addClass(body_classes) }}>
    <div class="visually-hidden-focusable skip-link p-3 container">
      <a href="#main-content" class="p-2">
        {{ 'Skip to main content'|t }}
      </a>
    </div>
    {{ page_top }}
    {{ page }}
    {{ page_bottom }}
    <js-bottom-placeholder token="{{ placeholder_token }}">
  </body>
</html>

We’ve removed a line to add things like the meta tags and changed the title tag to always show ‘CMS’.

In page-title.html.twig add the code:

{{ title_prefix }}
{% if title|render|striptags|trim %}
<h1{{title_attributes}}>CMS</h1>
{% endif %}
{{ title_suffix }}

This removes the titles and changes them to ‘CMS’. We could do something a bit more interesting here if the user is logged-in, but this will do.

In node.html.twig add the code:

<style>
  .container{
    max-width: 100% !important;
    width:100% !important;
    padding: 0 !important;
  }
</style>
{%
  set classes = [
    'node',
    'node--type-' ~ node.bundle|clean_class,
    node.isPromoted() ? 'node--promoted',
    node.isSticky() ? 'node--sticky',
    not node.isPublished() ? 'node--unpublished',
    view_mode ? 'node--view-mode-' ~ view_mode|clean_class,
  ]
%}
{{ attach_library('bootstrap5/node') }}
<article{{ attributes.addClass(classes) }}>
  {{ title_prefix }}
  {% if label and not page %}
    <h2{{ title_attributes }}>
      <a href="{{ url }}" rel="bookmark">{{ label }}</a>
    </h2>
  {% endif %}
  {{ title_suffix }}
  {% set domain = 'https://www.example.com' %}
  {% set thisDomain = url('<current>')  %}
  {% if 'localhost' in thisDomain|render|render %}
    {% set domain = 'http://localhost:3000' %}
  {% endif %}
  {%  if logged_in %}
    {% if node.isPublished() %}
      <iframe
        style="height: calc( 100vh - 230px )"
        width="100%"
        height="100%"
        loading="eager"
        allowfullscreen
        src="{{ domain }}{{ url }}"
        title="Test page view"
      ></iframe>
    {% else %}
      {{ content }}
    {% endif %}
  {% else %}
    <div{{ content_attributes.addClass('node__content') }}>
      <p>This is the Content Management System, please use the links at the top to navigate.</p>
    </div>
  {% endif %}
</article>

This is the most interesting file. If the user is not logged-in we show a message to login (we could add a login form here later). If the user is logged in and the content is not published then we simply show the content, but if the content is published, we show it in an iframe.

We also check for the domain to see if we are on local or not so this can work automatically locally. If you have a development or staging server, you can update the domain around line 32 to take these into account too.

Lastly, we have a domain name at around line 29, update this to your own Frontend domain (which will probably be the same as the CMS exchanging cms. for www.

Until we have a working Frontend on the correct domain, this theme will not work correctly, so let’s leave this uninstalled for now and install after the Frontend is ready.

Modules

Mods add all the functionality we need that does not come as standard, so we’ll need to add some now. We’ll install the same way we installed the themes, but feel free to use composer, file upload or Git if you’re more comfortable with another method.

Install some core modules, simply type the name in the filter and tick the box next to the name. When you have them all ticked, hit the ‘Install’ button at the bottom:

Syslog
Pathauto
HTTP Basic Authentication
JSON:API
RESTful Web Services
Serialization
Token

Once installed you will be shown a box to complete permissions, we’ll leave permissions for now.

Let’s uninstall a few modules we don’t need. Hit the uninstall tab at the top and search for these modules. Uninstall 1 at a time. Tick the box next to the mod and hit the Uninstall button at the bottom. Agree to the uninstall:

Announcements
Contact
Search

Reasons to uninstall, we don’t want anyone in our admin bothered by announcements from Drupal, the contact is not geared up for headless and neither is the search, so they all need to go.

Now we need to install some 3^rd party modules that add in some real functionality. You may not want or need some of these so have a read and choose for yourself:

Let’s start with ‘Color Field’:

Go to the URL for the module.
Click on the version at the bottom.
Under “Alternative installation files” right-click Download tar.gz and choose “copy link address”.
Back in the CMS, under Extend click the ‘Add new module’ button.
Paste the link into the field.
Click the Continue button.
Under Next steps click ‘Install newly added modules’.
Search for the module e.g. ‘color’.
Tick the box next to the title.
Hit the ‘Install’ button.

Most of the modules are setup automatically and we don’t need to worry about them, but a few will need special setup. At the moment it's enough to install. Once you have all the modules installed, we are ready to configure everything.

Fixes & Security

Let’s fix the errors first:

Go to /admin/structure/webform/config/advanced.
Uncheck all.
Click ‘Save configuration’.

Some of the erroneous errors will be removed.

Open the settings.php file in sites/default (you may need to change the permissions to executable 666).
Go to about line 774 and uncomment line $settings['trusted_host_patterns'] = [];
Change it to:

$settings['trusted_host_patterns'] = [
    '^example\.com$',
    '^.+\.example\.com$',
];

Make sure you change the domain name to your own

Save the file.
Go to the page /admin/reports/status#error and we should have no errors.

Let’s fix our private files:

Open the settings.php file in sites/default (you may need to change the permissions to executable 666)
Go to about line 627 and find the line # $settings['file_private_path'] = '';
Change it to $settings['file_private_path'] = $app_root . '/../../private';
In your file browser go to the root of the website (usually public_html), it’s 2 folders below cms/.
In that folder add a new folder called ‘private’

In that folder add a file called .htaccess and add the code:

# Deny all requests from Apache 2.4+.
<IfModule mod_authz_core.c>
Require all denied
</IfModule>
# Deny all requests from Apache 2.0-2.2.
<IfModule !mod_authz_core.c>
Deny from all
</IfModule>
# Turn off all options we don't need.
Options -Indexes -ExecCGI -Includes -MultiViews
# Set the catch-all handler to prevent scripts from being executed.
SetHandler Drupal_Security_Do_Not_Remove_See_SA_2006_006
<Files *>
  # Override the handler again if we're run later in the evaluation list.
  SetHandler Drupal_Security_Do_Not_Remove_See_SA_2013_003
</Files>
# If we know how to do it safely, disable the PHP engine entirely.
<IfModule mod_php.c>
php_flag engine off
</IfModule>

Clear all caches at /admin/config/development/performance

That’s all the warnings and errors we need to fix. Next, we need to look at CORS so our CMS will only except from certain domains (same as 'trusted_host_patterns' above):

In your file browser go to the root of your CMS and go to sites/default
Copy the file default.services.yml to services.yml
Edit services.yml

Near line 217 we find the cors.config, lets enable and set it up:

cors.config:
  enabled: true
  # Specify allowed headers, like 'x-allowed-header'.
  allowedHeaders: ['*']
  # Specify allowed request methods, specify ['*'] to allow all possible ones.
  allowedMethods: ['*']
  # Configure requests allowed from specific origins. Do not include trailing
  # slashes with URLs.
  allowedOrigins: [example.com']
  # Configure requests allowed from origins, matching against regex patterns.
  allowedOriginsPatterns: [
    '^example\.com$',
    '^.+\.example\.com$',
  ]
  # Sets the Access-Control-Expose-Headers header.
  exposedHeaders: false
  # Sets the Access-Control-Max-Age header.
  maxAge: false
  # Sets the Access-Control-Allow-Credentials header.
  supportsCredentials: false

Change the domain name from example.com to your domain name.

We are now setup for CORS.

Roles & Permissions

Most of the time, having an admin user that can see everything on the site is fine and if we need a second or 3^rd user, adding them in as admin is fine. As your website grows you may have to look at giving more people access and to parts of the site, but taking access to other parts away.

There is a security principle of least privilege (PoLP) that means only give access to exactly what is needed, no more. This is not just a security principle, it removes confusing parts of a system. Out of the box, Drupal gives us roles for:

Anonymous
Authenticated
Content editor
Administrator

I try to use these as much as possible, so for a user that will simply edit content, I will give the role Content Editor, not Administrator, then they will only see the links to content and editing content.

To add and remove permissions:

Click people on the left.
Click the Permissions tab at the top.
There is a table with every permission on the site (including modules) on the left and across the top are the roles. Slowly scroll down and tick each permission a role should have.
Click the ‘Save permissions’ button at the bottom.

This takes time and should be done carefully. There is a high chance you will miss something so when an editor says something is missing, this is usually the cause. You can create a few users with different permissions and login using a separate browser to test workflows work correctly. There are also test frameworks that can help with this, but it is out of scope of this tutorial.

Robots

Let’s stop all robots from seeing all pages in our CMS, except our images.

In your file browser go to the root of your CMS.
Open the file robots.txt.

Delete all the code from here and add:

User-agent: *
Allow: /sites/default/files/
Disallow: /

Save and close.

Now we won’t have Google or Bing trying to index our CMS, they shouldn’t even show up on search engines. Our Frontend is where we need to push the search engines.

Git VCS

Once we have installed the system and tested it’s all working we must make sure we have version control setup so we can rollback should we have an issue and to share code with other users should they need it. I work with Github to keep my repository online, but you can choose any repository as long as it supports Git. Create a new repo in GitHub for your CMS and add your remote to the repo on your local. For more on how to do this have a look here, but the script is:

git remote add origin https://github.com/OWNER/REPOSITORY.git

Once you add the remote, push the repository up to the remote and check the code is in your repo. Back in Hostinger go to Advanced on the left then tap GIT. Under Create new Repository add your new repo url, make sure the Directory is set to ‘cms’ and branch is set to ‘master’.

If it’s a private repo you’ll need to add in the SSH key to Github under Account -> SSH and GPG keys. Copy the key from Hostinger, click New SSH key, add the Title Hostinger and paste the key. Click Add SSH key. When you add the Repository to Hostinger you will need to add the URL found under Code -> local -> SSH on GitHub.

If its public repo, you won’t need the key, simply copy the URL from Code -> local -> HTTPS and paste it to Hostinger.

Auto Deployment

We want to auto deploy every time a change is made to the master branch so let’s set that up. The docs on Hostinger are out of date, but it all seems to work fine as long as the directory is empty.

Under Advanced and GIT in Hostinger click the Auto Deployment button.

A popup is shown, copy the URL and click the link under ‘Setup webhook on Github’

Paste the URL into the Payload URL.
Change the content type to application/json.
Make sure Enable SSL verification is enabled.
Select just the push event.
Create the webhook.

We now have a path from our local (or any local) to Github for any code changes. We can then check the changes with peer reviews, manual or automated testing and if is all fine we can merge into master, pushing the changes to live.

Finishing up

We now have our CMS setup both locally and on our production hosting. We can see the CMS and login and we are ready to start adding content. If the goal was not to go headless, we could add a Frontend theme and we would be finished here and able to use this CMS as-is. However, we are looking to go headless.

In the next part we’ll create the Frontend and add content that can be seen by visitors.

Comment if I’ve missed anything or made any mistakes or you have anything you'd like to add.

Going Headless: A CMS & Hosting Tutorial – Part 2

Dave Slack | Thursday, September 19, 2024