@tanglemedia/directus-extension-whm-preview-hook

When a collection data is deleted, created, or updated, it will trigger the scripts that builds the hugo site for preview.

Installation

npm i @tanglemedia/directus-extension-whm-preview-hook

How to enable the preview server

Prerequisite

• A website account on WHM server.
• Directus ^10.x.x
• Node ^18.x.x
• Git

Configuration

Follow the steps in order:

1. Set up SSH Keys to pull repo from Bitbucket

We need to create an ssh key for the server to pull a repo from bitbucket

• On the WHM server, go to List Accounts
• Search for the domain you want to add preview.
• Go to that domain's CPanel
• Using a terminal, cd .ssh to your domain/site account
• ssh-keygen -t ed25519 -b 256
• Enter name of the file for your ssh key. Recommended: <project_name>_bitbucket
• Leave passphrase blank
• Once ssh key file is generate, copy contents of the public key to the bitbucket repository of the hugo site (Repository Settings > Security > Access keys).
• Enter Directus Preview Key as the label of the SSH Key for consistency (you can also name it whatever you like).

2. Authorize your Bitbucket SSH Key

• On your site CPanel account, go to Security > SSH Access
• If there is a Manage SSH Keys button, click it
• Under Public Keys, on the bitbucket ssh key you just created from the previous step, click Manage
• The click Authorize

3. Add the following env variables on Directus

4. Setting up Preview Domain

• On your site account CPanel, go to Domains
• Click Create A New Domain
• Enter the desired domain. By convention, it's usually preview.<CURRENT_DOMAIN_ADMIN_URL> example: preview.admin.example.org.
• Enter the document root, which is the folder containing the files you want to deploy. It's usually /public_html/preview
• Then submit

5. Add the preview domain to the site DNS

• On your dns provider (in this case, Netlify), add a new A record to the domain
• Enter the preview domain as the name
• Enter the IP address of the site account on whm XXX.XXX.XX.XX

6. Enable SSL certificate to the preview domain

• This steps depends on your dns provider
• On your CPanel account, go to Security > SSL/TLS Status
• Select the domain you want to run the SSL on
• Click Run AutoSSL

6. Install and load this extension

7. Add 404 page

• When the extension first loaded, it will create a 404 HTML file in the public_html/404. Simply provide the path of the preview logo by adding the PREVIEW_SERVER_404_LOGO variable in the env file. Preview logo is usually the site logo.
• In the .htaccess file, append the following:

ErrorDocument 404 {DIRECTUS_BASE_URL}/404/404.html?base_url={PREVIEW_SITE_BASE_URL}&url_req=%{REQUEST_URI}

8. Adding Preview Buttons

When the extension is first loaded, it will copy a migration script from this package to the migrations folder on Directus.

9. Reload the extension

You can rerun the build on the ci/cd or disable/enable the extension in the Directus project extension page. Either way should work.

10. Run the migration script

To run the migration script, run the following command in the Directus root folder: npx directus bootstrap

Folder Structure

By the end of the above steps, you should end up with the following folder structure. For it to work, make sure package-lock.json is not included in the hugo folder

account-root/
   hugo/
      .
      .
      .
      migrations/
               .
               .
      package.json
      .env-local
      node_modules/
         .bin/
            dotenv
            hugo
   preview/
      error.log
      hugo-git-initializer.sh
      preview.sh
   public_html/
      404/
         404.html
         preview-404.{ext}
         .
         .
      preview/
      .htaccess

Known Issues

• Preview server not being able to pull the repo from Bitbucket
  • Check if the hugo/.git folder has the correct user account permission and not root
  • Check if the env variables are accurate