newspack-docker

Newspack helper Repository for running local environments using Docker.

The main idea is to have all the dependecies we need to run the projects, and its tests, inside the container so we don't depend on anything in our local machine.

Getting started

Clone this repository

git clone https://github.com/Automattic/newspack-docker.git

Set up your local vars

Make a copy of default.env to .env

cp default.env .env

Edit the file and choose your own variables

You can change the password and username of your WordPress user.

Linux users might want to configure apache to run as the same user as the host machine. You can do that in this file

Build the Docker image

You only need to run this the first time you set up your env.

./build-image.sh

The default builds using PHP 8.1. You can also call ./build-image-7.4.sh or ./build-image-80.sh to build an image with PHP 7.4 or 8.0. It's a good idea to have both.

Clone all repos

This will clone all Newspack repos inside the repos folder. Assumes your host machine is authenticated with GitHub. Default git protocol is SSH. Add -h or --https to clone using HTTPS instead.

./clone-repos.sh

Lauch the container and install WordPress

Now we are going to use the n script. (Tip: Create an alias in your .bashrc so you can call it from anywhere)

Launch the container

n start

(n start 8.0 or n start 7.4 will start the image with php 8.0 or 7.4 if you built them)

When you are done, you can stop the containers with n stop.

You can also stop and start in one command with n restart (or n restart 8.1 or n restart 7.4).

At this point you should be able to see your site in https://localhost.

Install WordPress

n install

Build the projects

The first time you set up your environment you might want to build all the projects. You can do this by:

n build all

The N script

The n script will help you perform actions inside the containers. Some examples:

Build one specific project:

n build theme # Builds the newspack-theme repo
n build newspack-plugin # Builds the main plugin
n build newsletters # You can also omit the 'newspack-' prefix from plugins
n build # Bulds the project you are currently in

Watch and run tests on projects:

These commands will automatically run in the repo folder you are currently in

n watch # Runs npm watch on the project you are currently in
n test-php # Runs phpunit tests on the project you are currently in
n test-js # Runs js tests on the project you are currently in

Run composer commands inside one of the projects

n composer dump-autoload # Runs `composer dump-autload` inside the current repo
n composer update # Runs `composer update` inside the current repo

Run npm commands inside one of the projects

n npm run release:archive # Runs `npm run release:archive` inside the current repo

Run WP CLI interactive shell

n shell

Enter the container bash

n sh # as the apache user, if USE_CUSTOM_APACHE_USER was set in your .env
n rsh # as root

Other commands:

• n db: Launches the MySQL interactive shell
• n wp: runs any arbitraty WP CLI command. e.g. n wp option get blogname
• n tail: Tails the apache error log file
• n uninstall: Uninstalls WordPress
• jncp, jninit & secrets: See Jurassic Ninja section below.
• n secrets-import: Import all your secrets from a secrets.json file (see details on the Jurassic Ninha section below)
• n snapshot $name: Creates a snapshot of the current site and gives it a name
• n snapshot-load $name: Drops the current site and override it with the data from a snapshot
• n reset-site: Drops the current site and creates a new one from scratch
• n pull: Pull every git repository inside repos/
• sites-add, sites-drop, sites-list: See Additional Sites section below
• n setup-newspack-network: Sets up the connections of Newspack Network and Distributor plugins between all active sites
• n cd-install: Install the handy ncd function to your terminal. See section below.

Navigating between projects (the ncd command)

Many of the n commands will act on the project you are currently in. For example, if you are in the main plugin folder, n build will build the plugin. If you are inside the folder of one of your additional sites, n shell will launch the WP Shell for that particular site.

But navigating between all these directories might become tiring, since you have to go to the repos folder, and then down to additional-sites-html and sometimes inside one particular plugin you want to debug.

To make navigating easier, use the ncd terminal command.

ncd will take you to the directory you want, no matter where you are at when you type it. When you type ncd plugin, it will:

• Look for an exact match in the repos folder: ... /repos/plugin
• Look for a repo with the newspack- prefix: ... /repos/newspack-plugin
• Look for an additional site with that name ... /additional-sites-html/plugin
• Look for a plugin installed in the main site ... /html/wp-content/plugins/plugin

So when you arrive at your home folder and want to go to the newspack-newsletters project, instead of typing something like cd my-project/newspack-docker/repos/newspack-newsletters, all you need to do is ncd newsletters!

To start using it, you need to add it to your terminal by running n cd-install and then inform the loader file you want to add the script to, for example .bashrc, .zshrc, etc.

Jurassic Ninja

There are some commands to help you work with Jurassic Ninja

Initialize and Sets up a new JN Site

n jninit user domain.jurassic.ninja

This command Sets up a new Jurassic Ninja site. It will

• Upload the newspack-plugin from your machine to JN
• Run wp newspack setup
• Copy your secrets to the JN site

Setting up your Secrets

If you want your secrets to be copied over to the JN site, create a secrets.json file inside the bin folder.

You can copy the secrets.json.sample file and manually edit it, or you can use n secrets to output the secrets you currently have on your local site.

If you want to directly copy the secrets into the file you can run n secrets > bin/secrets.json.

Copy plugins to a JN Site

n jncp user domain.jurassic.ninja

This command will allow you to copy one or many plugins from your local env to the JN site at once.

This is useful if you want to replace the plugin in the site with the custom branch you have checked out, or if you want to upload any other plugin you have.

Mailhog

Mailhog is running by default so you can see all the emails that are sent from your WordPress site.

Visit http://localhost:8025 to see it.

Adminer

Adminer is available at http://localhost:8088

Connect to Server db, user root and password defined in your local .env file.

Memcached

By default, Memcached plugin is enabled. If you want to disable it, simply delete the html/wp-content/object-cache.php file.

X-Debug

X-debug is configured by default. In order to use it:

• Set you browser extension to use the DOCKERDEBUG IDE Key.
• Configure your IDE to use the same IDE Key, listen to port 9003 and add the necessary path mappings.

Here's an example of a launch.json file for VSCode to be used for the newspack-plugin repo:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Newspack Docker",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "log": false,
      "maxConnections": 1, // @see  https://github.com/xdebug/vscode-php-debug/issues/604
      "xdebugSettings": {
        "resolved_breakpoints": "0", // @see https://github.com/xdebug/vscode-php-debug/issues/629 and https://stackoverflow.com/a/69925257/3059883
        "max_data": 512,
        "show_hidden": 1,
        "max_children": 128
      },
      "pathMappings": {
        "/newspack-repos/newspack-plugin": "${workspaceRoot}"
      },
    }
  ]
}

Newspack Manager

This Docker environment will launch two sites by default. One is the site you will be working on to develop all plugins, and the other is the one that will run the Newspack Manager Client.

In order to be able to access the Newspack Manager site, there are a few additional steps:

Setup the manager by installing WordPress, creating the key pairs, adding the constants to both sites and activate the plugins. All this is done by:

n setup-manager

Configure the manager.com domain to point to your localhost by adding it to the hosts file.

In your favorite text editor, open the /etc/hosts file and add a line with 127.0.0.1 manager.com. Or run the following command:

echo "127.0.0.1 manager.com" | sudo tee -a /etc/hosts

If you haven't done it yet, build the Manager Client plugin:

n build manager-client

(Note that you can also use watch here while developing)

That's it!

Now visit manager.com/wp-admin, go to Newspack Manager, and add the URL for you other site there.

Note about the site domain when running CLI commands

By default, the docker environment provides a dynamic site url, so you can access the site either via localhost or a tunneled domain, required for some actions. This is useful because it allows you to run your site without the tunnel when you don't need it.

Because of that, when running commands via CLI, the returned site url is localhost. This will create issues when communicating with the manager, as the keys are tied to the site domain.

Use the NEWSPACK_DOCKER_SITE_URL_CLI_OVERRIDE to override the site url for CLI commands.

In your dev site (not the manager.com instance), add the following

define( 'NEWSPACK_DOCKER_SITE_URL_CLI_OVERRIDE', 'https://my-domain.my-tunnel.com' );

Additional Sites

If you need to run a couple of additional sites, we got you covered.

You can have a number of additional sites running under you-name-it.local. They will live in their own local domain, such as site1.local and another-site.local.

n sites-add $site_name will launch a new site. The site will come with Newpack already initialized and all the plugins linked. Your secrets will also be copied. It's basically the same result as running n reset-site for your main site.

• n sites-list - Lists the current existing sites
• n sites-drop $sitename - Will completely erase the site and its database

Interacting with the sites via command line

You can use the same n commands to interact with these sites. If you run the n script from inside a site's folder, it will interact with this specific site. If run it from anywhere else, it will interact with the main site.

The sites live under additional-sites-html folder. cd into one of the sites folder to interact with them.

Newspack Network and Distributor

If you want to play with Newspack's Federated sites features, there's a handy comment that will set everything up for you.

• First, create as many sites you like with n sites-add (see docs above)
• Run n setup-newspack-network
• That's it!
• Whenever you add a new site, you can run this command again and it will get added to the network

This command will:

• Make sure Newspack Network and Distributor plugins are enable in all sites
• Register the Nodes in the Newspack Network Hub (this will be your main site)
• Configure the each Node with the Hub's key
• Set up Distributor external connections between all sites

SSL

A certificate will be generated, so HTTPS is available immediately. However, the CA (Certificate Authority) certificate is installed on the Docker machine, so a browser will warn about a ERR_CERT_AUTHORITY_INVALID error. To make the certificate recognisable on the host machine, run the following commands (for macOS):

• $ docker exec newspack_dev bash -c 'eval cat $(mkcert -CAROOT)/rootCA.pem' > rootCA.pem to copy the CA certificate from the Docker machine
• $ sudo security add-trusted-cert -d -r trustRoot -k "/Library/Keychains/System.keychain" ./rootCA.pem to trust this CA certificate (import to KeyChain). Alternatively, double-click on the .pem file.
• remove the rootCA.pem, it's no longer needed