washpost/fusion-cache-proxy repository overview

⁠PageBuilder Engine (Fusion)

PageBuilder Engine is a server-side + client-side rendering engine. It is designed for sites that consist of many separate pages that share a small number of templates that may be constantly changing.

⁠REQUIRED: GitHub Token

Since PageBuilder Engine relies on private @wpmedia scoped packages, you must set an environment variable GITHUB_TOKEN during many of the installation or build steps. Ensure the token has at least read_packages enabled, and that it has already been authorized with the WPMedia SSO.

• GitHub Tokens are managed from your Developer Settings⁠
• More information on generating a GitHub Token can be found here⁠.
• More information on authorizing a GitHub Token with SSO can be found here⁠

⁠Versioning

PageBuilder Engine uses a single master branch to produce multiple versions of the software that are identical except for the version of Node they are running on. This is intended to simplify the upgrade process for customers, who have historically been shy to upgrade because of the tendency for breaking code and configuration changes in major-version releases. To ensure backward/forward compatibility, all automated tests are run against all supported and upcoming Node versions.

Since the minor and patch versions of various Engine versions will not always align, their versions can be incremented separately. This process is managed with the @changesets/cli package, which operates against the dummy-packages in the .versions folder. Each dummy-package corresponds to one supported Engine version, and the version numbers are automatically calculated and assigned in the GitHub Actions CI processes.

• NOTE: For technical information on how to maintain the dummy-packages, read .versions/README.md.

Merging into the master branch will trigger an official production release if (and only if) there are no changeset files in the repo. If changeset files are detected, this will trigger a canary release instead.

⁠Running Engine Locally

You can run Engine either straight from this repo or using fusion-cli⁠. Each have differences in setup, but same result runtime is achievable with minimal configuration. The steps below describe running Engine from this repo

1. Download Docker (docker-compose is required)
2. Run npm i from the root ~/fusion
3. Run npm run start:admin

⁠Testing

Unit tests use Jest and will use a mix of packages installed from the root package.json and packages installed from the package.json files within each image (engine, resolver, etc). If you are seeing unexpected errors, make sure you run npm i in each folder.

⁠Architecture

⁠Routing

Routing in Engine involves two primary components:

• origin⁠
• resolver⁠

A third component is the resolver-generator⁠, which creates the resolver Lambda when Resolvers are modified in the PageBuilder UI, but does not perform any actual routing.

⁠Engine

The Fusion engine contains the core rendering functionality.

• engine⁠

⁠Admin

The Admin provides end users with website curation functionality. The end goal is to replace pb-web with pb-admin.

• pb-admin⁠

⁠Developer Experience

The Engine developer experience mostly consists of:

• documentation⁠
• fusion-cli⁠

⁠Metrics

Below is a list of available metrics emitted by Fusion components

⁠Fusion Origin

⁠Fusion Cache Proxy

⁠Fusion Engine

⁠Releases

PageBuilder Engine releases are documented in confluence here (internal)⁠ and displayed to our clients publically in ALC here⁠.

For details on publishing new Engine version, see ./documentation/maintainers/PUBLISH.md⁠.

⁠Build Server

⁠Release using the Build Server

1. Make sure you're on VPN with AnyConnect
2. Go to http://jenkins.fusion.aws.arc.pub/⁠
3. Make sure your branch has Jenkinsfile (see example below)

pipeline {
    agent any

    stages {
        stage('Hello') {
            steps {
                echo 'Hello from repo branch'
            }
        }
    }
}

1. Commit on your branch and push.
2. See your branch in Jenkins multi-pipeline option. Each branch name will have its own pipeline run on push

⁠SSH into Build Server

Prerequisite: To SSH into the Build Server you will need a pem certificate. Ask someone on the engine team for it.

1. (You should only need to do this once) Add 400 permissions to your pem file by running chmod 400 [path to pem file]
2. Connect to Arc's Cisco VPN
3. Open your terminal
4. ssh -i [path to pem file] [email protected]
5. The following command grants you standard access to the Jenkins image. If you need root access to the Jenkins image skip to step 5. docker exec -ti jenkins bash
6. If you require root access to the image (f.e. for installing a package) run the following command:

sudo docker exec -it --user root jenkins bash
/data/jenkins/
/var/jenkins_home