@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

Env Variables	Description
SERVER_USER	User name of the account in the whm server. To allow creation of files and folders with the appropriate permission
SERVER_ACCOUNT_ROOT	Path to the account directory. Do not include trailing slashes.
DIRECTUS_PROJECT_ROOT	Path to the directus project. Do not include trailing slashes.
PREVIEW_HUGO_SITE_BUILD_FOLDER	Name of the folder where the hugo pages are being built (e.g. directus-build)
PREVIEW_SERVER_IDENTITY_FILE	Path to the bitbucket private ssh key in this account
PREVIEW_SERVER_HUGO_REPO_URL	Url of the bitbucket repo of the hugo site
PREVIEW_SERVER_HUGO_BRANCH_TO_PULL	Name of the branch to pull the repo from
PREVIEW_SERVER_404_LOGO	Path to preview logo. This is relative to the 404.html file. Please use relative path
PREVIEW_HUGO_CLOUDINARY_BASE_URL	Base url of the resources in cloudinary (if the resources are stored in cloudinary). Do not include trailing slashes.
PREVIEW_HUGO_CLOUDINARY_FOLDER	Name of the folder where the site's assets are located in cloudinary
PREVIEW_HUGO_DIRECTUS_API_URL	Base url of the directus admin portal. Do not include trailing slashes.
PREVIEW_HUGO_DIRECTUS_ACCESS_TOKEN	Directus access token (usually the access token related to the website role) to pull the Directus data and build them into pages
PREVIEW_HUGO_SITE_BASE_URL	Base url of the preview website. If not yet configured, please set up the preview subdomain first. Do not include trailing slashes.
PREVIEW_BUTTON_COLLECTIONS	Comma-separated names of the collections you want the preview buttons to be installed. For this to work, the collection should have the `url` field that contains the url of the page/collections. The url field should be configured with extension-wpslug interface. If the url is not yet configured that way, install the [WP Slug Interface](https://github.com/dimitrov-adrian/directus-extension-wpslug-interface) to your Directus project and set the url field interface to this extension.

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