Unless your host machine is missing most of the prerequisite setting up Tide locally should take around 5-10 minutes and consists of the following steps:
- Install all the required prerequisite software.
- Create a new Firebase Project.
- Clone the Tide repository.
- Install the Firebase CLI.
- Execute the initial setup commands.
- Generate the API Docs.
- Run the Firebase Emulator Suite.
- Start the Proxy Server.
- Finally, start the Cloud Run Servers.
If you run into any issues while getting Tide installed please
contact us, so we can address it and update the documentation for
others. If you only want to contribute to the documentation read about the
npm run docs:serve command in the API Docs section first.
There are several CLI tools that need to be installed on your system before you can
meaningfully contribute to the Tide Component. Docker is optional, but required if you plan
to build the images and test them locally, as well,
make and the Google Cloud SDK are
needed if you are building images and/or deploying to GCP. It's assumed you have installed
node 16, which is required, or are using
nvm to install and use a different versions
of node then is installed on your computer.
- Install Composer (opens new window)
- Install Node (opens new window)
- Install Node Version Manager (opens new window) (optional)
- Install Firebase CLI (opens new window)
- Install Google Cloud SDK (opens new window) (optional)
- Install Docker (opens new window) (optional)
- Install Make for Windows (opens new window) (optional) (Windows only)
# Firebase Project
If you don't have a Firebase project, then start by creating a new project from the Firebase Console (opens new window). Later we'll connect your cloned version of Tide to your Firebase project—we don't need to actually use the project, just authenticate with it. Setting up a Firebase project will not cost you anything, it just needs to exist for authentication purposes. Make a note of the Project ID you choose, you will need it later.
# Clone Tide
Tide can be cloned anywhere on your computer, but avoid putting it in a directory path with
spaces as that can break
Clone the repository:
git clone email@example.com:wptide/wptide.org.git
# Firebase CLI
The Firebase Emulator Suite is part of the Firebase CLI (command-line interface) which can be installed on your machine with the following command:
npm install -g firebase-tools
Log in to the Firebase CLI:
Optionally you can run the following command to create a project alias. First, select your project from the list. When asked what alias you want to use, choose default.
firebase use --add
The output should look like the following example. Remember to choose your actual Firebase project from the list:
? Which project do you want to add? YOUR_PROJECT_ID ? What alias do you want to use for this project? (e.g. staging) default Created alias default for YOUR_PROJECT_ID. Now using alias default (YOUR_PROJECT_ID)
After running the following commands you should be able to generate the docs, run the emulators, and setup all the various services that make up the Tide Component.
If any of the
localhost ports for the Tide services below are in use on your host machine
there will be a port collision, and you will need to stop the running services on the
required ports for Tide to function correctly.
Copy the hidden files:
The following command should only be used once.
npm run copy
.env is for the Firebase Functions API and the
.env.server is for the Docker
based Cloud Run Servers. Both files are for local development only and likely do not require
any changes, except for the project ID that you previously created should now be used as the
value for the
GOOGLE_CLOUD_PROJECT environment variable.
Also, make sure to update
.firebaserc with the project ID after this command is executed.
The project ID will be the value associated to the
default key in
npm run setup
# API Docs
The API Docs are generated with VuePress (opens new window), which is a Vue-powered Static Site Generator that converts the Markdown files into a searchable static site. There is also a Firebase Function that converts the OpenAPI v3 Specification into an interactive visualization of the API’s resources using Swagger UI. However, the API Specification is run with the Firebase Emulator Suite and doesn't require any additional setup.
If you are doing development on Tide, not just the documentation, you will need to run the
build command each time you make changes in the
web directory, and the first time you
start Tide. The
serve command will not refresh the emulator because it hosts the
statically generated files i.e. the output of the
Build the front-end:
npm run docs:build
Serve the front-end:
The front-end dev server runs on
npm run docs:serve
# Firebase Emulator Suite
The Firebase Emulator Suite is required to emulate Firebase Hosting, Cloud Functions, Cloud Firestore, and Cloud Pub/Sub. These emulators must be running in order for Tide to process WordPress.org themes and plugins.
Firebase Hosting runs on
npm run start:emulator
# Proxy Server
The Proxy Server proxies emulated Pub/Sub messages to their respective HTTP endpoints and must be executed anytime you start the Firebase Emulator Suite, ideally before starting the Cloud Run Severs, so you don't accidentally forget to add the local proxy and wonder why audits are not running.
Start the local Pub/Sub Proxy:
npm run start:server:proxy
# Cloud Run Servers
When doing local development each server is running within an instance of the Functions Framework for Node.js (opens new window) inside a continuously running shell. This way we can remove the need to build Docker images. Meaning you will need to open a new shell for each server and run these commands in isolation.
Start the Lighthouse server:
The Lighthouse server runs on
npm run start:server:lighthouse
Start the PHPCS server:
The PHPCS server runs on
npm run start:server:phpcs
Start the Sync server:
The Sync server runs on
npm run start:server:sync
You can open
http://localhost:5012/ from your browser to start the sync process. However,
running the Sync Server will ingest more than 50k themes and plugins from WP.org, and
several previous versions. This means the Sync Server will add thousands of messages to the
Pub/Sub queue, which will take a very long time to process locally and potentially lock
up all your computers resources. For this reason you should stop the execution of this
command after fetching a couple of messages (a few seconds at most), which you can do by
Ctrl+C on your keyboard within the shell you started the server from.