VIP Go platform specific
This document is for sites running on VIP Go.
The VIP Platform has first-class support for hosting Node.js (Node) applications.
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 #
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:
Note: that npm 5.2 or higher is required for the preflight checks 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
200status 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
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
dependenciesmust 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
buildstep, feel free to just
echo "No build needed; skipping...")
- 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.
We also recommend following these best practices:
- Keep the “dependencies” list small and lean.
- Node.js containers will run
npm install --productionevery 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 6.x, 8.x, and 10.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 #
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.
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.