Node.js Applications on VIP
Note
We currently recommend hosting WordPress components with VIP, and your Node.js application externally. This document is for pre-existing clients.
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
Note
Node 10 and npm 5.2 or higher are 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 a200
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 topackage.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 justecho
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.
- Node.js containers will run
- 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.