Tide

# Installation

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:

  1. Install all the required prerequisite software.
  2. Create a new Firebase Project.
  3. Clone the Tide repository.
  4. Install the Firebase CLI.
  5. Execute the initial setup commands.
  6. Generate the API Docs.
  7. Run the Firebase Emulator Suite.
  8. Start the Proxy Server.
  9. 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.

# Prerequisites

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.

# 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 npm compilers.

Clone the repository:

git clone git@github.com:wptide/wptide.org.git

Change directories:

cd wptide.org

# 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:

firebase login

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)

# Setup

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.

WARNING

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:

IMPORTANT

The following command should only be used once.

npm run copy

The new .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 .firebaserc.

Install the npm and composer dependencies:

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.

IMPORTANT

When contributing to the documentation only, you can run the serve command and ignore the rest of the commands on this page except in the Clone Tide, and Setup sections.

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

Build the front-end:

npm run docs:build

Serve the front-end:

IMPORTANT

The front-end dev server runs on localhost port 8000.

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.

Start Emulator:

IMPORTANT

Firebase Hosting runs on localhost port 5000, Firestore 5001, Functions 5002, and Pub/Sub 5003

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:

IMPORTANT

The Lighthouse server runs on localhost port 5010.

npm run start:server:lighthouse

Start the PHPCS server:

IMPORTANT

The PHPCS server runs on localhost port 5011.

npm run start:server:phpcs

Start the Sync server:

IMPORTANT

The Sync server runs on localhost port 5012.

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 pressing Ctrl+C on your keyboard within the shell you started the server from.

← Google Cloud →