Node.js Applications on VIP

Types of Applications

We currently support two types of Node.js applications on VIP.

Decoupled / Headless Frontend

The REST API allows WordPress to operate in a decoupled / headless manner. Rather than a traditional PHP-driven theme, sites can be run as a static single-page application (SPA) or a fully isomorphic application (with server-side rendering).

(Companion) Microservices

WordPress is flexible enough to support many different use cases, but not all of them. A companion microservice can be used to offload tasks that may not be well-suited for a typical WordPress app, such as a proxy for another API or service or a middleware layer like a GraphQL API.

Preparing your Application

Requirements

For your Node.js application to work on the VIP Platform, it must adhere to the following requirements.

You can automate these checks as part of your CI process by running the following command on the application root directory:

npx @automattic/vip-go-preflight-checks

Use the @automattic/vip-go package

Our helper package simplifies some of the boilerplate and makes it easier to integrate with platform features like logging. It currently handles the following:

• Starts an HTTP server listening on process.env.PORT, which is dynamically assigned to each container.
• Responds to GET /cache-healthcheck? with a 200 status code, which is used by our monitoring systems to verify the health of your application.
• It also includes helpers for logging and integrating New Relic and Redis.

Use a CI Service

If your application requires any build processes like transpiling, compiling, etc. you must use a CI service (like CircleCI or GitHub Actions) to generate a built copy of the application.

The service should transpile, compile, and verify a build of your app and then push that to a “built” branch. Learn more about setting up Automated Build & Deploy.

Included npm scripts

On VIP Go, every time you push a new change to your application, we pull the latest code from the deployment branch and then run the commands below. Your application must respond with a non-error exit code.

• npm install --production
  • This is triggered to install any production dependencies needed for the app.
  • All required production dependencies must added to package.json, including any packages that were not included in the built copy. Note that devDependencies are not installed.
• npm run build
  • This is triggered to run any final build steps.
  • Any additional build steps that were not completed via CI should happen here.  If your app doesn’t need an additional build step, feel free to just echo something (e.g. echo "No build needed; skipping...")
• npm start
  • This is triggered to boot up the app.
  • This should boot up the HTTP server.

If any of these commands are missing or fail, the application will not work correctly.

Stateless and Multi-container

All applications on VIP Go must be able to run across multiple containers and processes at the same time.

This means that the app must largely be stateless. If any data is stored in memory it will be lost on deploy or if containers are added/removed. If data needs to be shared across containers/processes or you need guaranteed persistence, you can use a data store like MariaDB or Redis, which we can enable for your app.

No Process Monitors

For production deployment, your application does not need any process monitors (like nodemon, PM2) to handle restarts. This is handled automatically by the VIP platform.

Recommendations

We also recommend following these best practices:

• Keep the “dependencies” list small and lean.
  • Node.js containers will run npm install --production every time the app is deployed or a new container is added. This can take a significant amount of time if you’re using a large number of dependencies and slow down deployment time as a result.
• Use npm audit or a service like Renovate or Dependabot to automatically keep your dependencies up-to-date, especially for security updates.

Creating your Application

A member of the VIP team will work with you to get your application up-and-running in our environment.

You’ll want to make sure that your application is set up according to the Requirements and Recommendations noted above.

We’ll also need the following details:

• Domain name.
• GitHub users.
• The version of Node.js you’re hoping to use.
  • We currently support 10.x and 12.x
• Any environment variables that should be added.
  • You can share any sensitive data using a secure service like https://quickforget.com.
• Any data stores you’ll need alongside the application.
  • We currently support MariaDB and Redis.

More about your Node.js Application

Logging

For logs generated by the application, the @automattic/vip-go package provides a wrapper around Winston, a popular logging library. Using this library will ensure that logs are accessible by the VIP team which will allow us to better support your team in case of issues (and will be directly accessible to your team in the near future). If you’d like to log to your logging system of choice, Winston has adapters for many popular logging services and APIs such as Sentry.