Node.js Applications on VIP Go

VIP Go platform specific

This document is for sites running on VIP Go.

Learn more

Overview #

The VIP Platform has first-class support for hosting Node.js (Node) applications.

↑ Top ↑

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).

↑ Top ↑

(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.

↑ Top ↑

Preparing your Application #

↑ Top ↑

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

Note: that npm 5.2 or higher is required for the preflight checks package.

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.
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.

↑ Top ↑

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.

↑ Top ↑

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 6.x, 8.x, and 10.x
  • Any environment variables that should be added.
  • Any data stores you’ll need alongside the application.
    • We currently support MariaDB and Redis.

↑ Top ↑

More about your Node.js Application #

↑ Top ↑

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.

↑ Top ↑

Using Redis #

If using Redis for your application, you need to use the following env variables to create the connection:

  • REDIS_MASTER: This will contain the IP of the master host alongside the PORT. Before using it, make sure to split it with ‘:’ to get the IP and the port.
  • REDIS_PASSWORD: This will contain the password of the Redis containers. This password is automatically generated and passed as an environment variable by the VIP Platform.

This will be simplified in a future version of the @automattic/vip-go package.

Ready to get started?

Drop us a note.

No matter where you are in the planning process, we’re happy to help, and we’re actual humans here on the other side of the form. 👋 We’re here to discuss your challenges and plans, evaluate your existing resources or a potential partner, or even make some initial recommendations. And, of course, we’re here to help any time you’re in the market for some robust WordPress awesomeness.