Skip to content

Latest commit

 

History

History
117 lines (83 loc) · 7.94 KB

quick-start.md

File metadata and controls

117 lines (83 loc) · 7.94 KB
Raw

Quick Start Guide

Overview

This guide is designed to get you up and running working with the Jetpack Monorepo quickly following recommended and supported guidelines.

This guide assumes you are using MacOS or a Linux machine and are an Automattician. For more detailed information, including setting up local dev environments for all contributors, running unit tests, best coding practices, and more, you can use the full Development Environment guide here.

Installation

Using the installation script

To speed up the installation process, you may use our monorepo installation script. To do so:

  • Clone the Jetpack Monorepo:
    • Using a public SSH key (recommended): git clone [email protected]:Automattic/jetpack.git
      • Or use HTTPS: git clone https://github.com/Automattic/jetpack.git
    • Note that the monorepo should not be cloned into the WordPress plugins directory. If you plan on not using the provided Docker environment, read the full Development Environment guide here to find out how to add symlinks.
  • cd into the cloned jetpack folder.
  • Run tools/install-monorepo.sh from the monorepo root.
  • You can use the environment checker script to confirm that all required tools are installed.

Once the installation is complete, continue onto the section Running Jetpack locally.

Installing manually

Prior to installation, we recommend using Homebrew to manage installations and nvm to manage Node.js versions. If you don't already have those installed, you can do so by copy/pasting each of the following commands and running them in your terminal:

  • Homebrew: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  • nvm: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

The Jetpack Monorepo requires various software to be installed on your machine.

  • Clone the Jetpack Monorepo:
    • Using a public SSH key (recommended): git clone [email protected]:Automattic/jetpack.git
      • Or use HTTPS: git clone https://github.com/Automattic/jetpack.git
    • Note that the monorepo should not be cloned into the WordPress plugins directory. If you plan on not using the provided Docker environment, read the full Development Environment guide here to find out how to add symlinks.
  • This software needs to be installed or updated system-wide:
    • Bash (will need to be updated from default Mac version): brew install bash
    • jq (JSON processor used in scripts): brew install jq
  • To install or update the following software, cd into the Jetpack directory that was created when cloning the repo: cd jetpack:
    • Node.js (used for build process and our CLI): nvm install && nvm use
    • PNPM (a Node.js package manager): npm install -g pnpm
    • PHP (the language at the core of the WordPress ecosystem): source .github/versions.sh && brew install php@$PHP_VERSION
    • Composer (our PHP package manager): brew install composer
    • Jetpack CLI (an internal tool that assists with development): pnpm install && pnpm jetpack cli link

Check if your environment is ready for Jetpack development

We provide a script to help you in assessing if everything's ready on your system to contribute to Jetpack.

tools/check-development-environment.sh

Running the script will tell you if you have your environment already set up and what you need to do in order to get it ready for Jetpack development:

  • All green YES or OK messages mean you're ready to start
  • Red NO messages mean something is wrong or missing, and a link will be provided to help you with a fix.
  • Yellow messages indicate something optional is broken or missing.

Running Jetpack locally

After everything is installed, you're ready to run Jetpack locally! While there are other supported methods of doing this, we recommend and support using Docker containers.

To setup Docker:

  • Install Docker:
    • Mac: brew install --cask docker (This will take a while!)
    • Linux: brew install docker
    • open -a Docker (or open the app from your Applications folder) to open the GUI application. You will likely need to enter your device password and accept their terms for a first time setup.
  • Copy the settings file from within the monorepo root: cp tools/docker/default.env tools/docker/.env
  • Open tools/docker/.env and make any modifications you'd like.
    • It's strongly recommend you at least change WP_ADMIN_PASSWORD to something more secure.
  • Start the Docker container using jetpack docker up -d (this may take some time for the first setup)
  • Install WordPress in your Docker container using jetpack docker install
  • Open up http://localhost to see your site!

For more in depth Docker instructions, follow the Docker environment for Jetpack Development guide.

Setting up Jurassic Tube

In order to test features that require a WordPress.com connection and other network related Jetpack features, you'll need a test site that can create local HTTP tunnels. If you're an Automattician, we recommend using Jurassic Tube.

Note: This is for Automattician use only. For other methods, check out ngrok or another similar service.

Warning: This creates a tunnel to your local machine which should not be trusted as secure. If it is compromised, so is your computer and everything it has access to. Only jetpack docker jt-up when needed for testing things that require the site to be publicly accessible, and jetpack docker jt-down when completed.

  • Visit the jurassic.tube homepage to create a subdomain
  • Make sure you've run pnpm install && pnpm jetpack cli link
  • Make sure Docker is running jetpack docker up -d
  • Stand on the monorepo root in your terminal and run mkdir tools/docker/bin/jt
  • Stop and restart the docker env: jetpack docker stop && jetpack docker up -d
  • Download and run the installation script: curl "https://jurassic.tube/get-installer.php?env=jetpack" -o tools/docker/bin/jt/installer.sh && chmod +x tools/docker/bin/jt/installer.sh && tools/docker/bin/jt/installer.sh
  • Set your username: jetpack docker jt-config username [your-username-here e.g david]
  • Set your subdomain: jetpack docker jt-config subdomain [your-subdomain-here e.g. spaceman]
  • Now, you can start your site with jetpack docker jt-up
  • Your site should be available at https://custom-subdomain.jurassic.tube

Development Workflow

Once you have a local copy of Jetpack and all development tools installed, you can start developing.

  1. Make sure the plugin you're developing is activated on your WordPress site.
  2. Build your project using jetpack build [type/project] and including its dependencies, such as jetpack build plugins/jetpack --deps
  3. Access the plugin's dashboard in your browser.

By default the development build above will run once and if you change any of the files, you need to run jetpack build again to see the changes on the site. If you want to avoid that, you can run a continuous build that will rebuild anytime it sees any changes on your local filesystem. To run it, use:

jetpack watch

Running Tests

To run PHP, JS, and coverage tests, you can use the Jetpack CLI: jetpack test and then choose the project and type of test you'd like to run.

That's all!