Prerequisites

Node (8.9.3), preferrably via NVM

Docker CE

MacOS

Download and install the latest STABLE version of the native Docker client for your platform.

Linux

Linux users can use their package manager of your distribution of choice. Either STABLE or EDGE channels are fine.

Windows

Download and install the latest STABLE release as EDGE is broken with the tribe-proxy container.

Enable Hyper-V and Bash. If you're on an older Windows version or don't want the Linux subsystem for some weird reason, install Cygwin.

If you have issues with Bash, use babun and install babun-docker.

Configuring your OS

DNS Configuration

Ensure that...

dnsmasq is uninstalled.
Your etc/hosts/ file does not include .tribe domains

Then, update your computer's primary DNS server to 127.0.0.1 and the secondary to 1.1.1.1. Here's a link to instructions for your...

Mac
Linux
Windows
- You may need to change the DNS servers on the vEthernet (Default Switch) adapter instead of your main adapter.

Note that a full restart may be necessary to resolve *.tribe domains.

Note for Linux, if you run in to problems with DNS resolution, it might be caused by systemd-resolved on newer Linux versions. To workaround the issue, you might need to do the following steps (be aware that disabling systemd-resolvd might break name resolution in VPN for some users):

Run the following commands:

sudo systemctl disable systemd-resolved.service
sudo service systemd-resolved stop

Open the file /etc/NetworkManager/NetworkManager.conf and add to the main section:
```
dns=default
```
Delete the symlink /etc/resolv.conf :
```
rm /etc/resolv.conf
```
Restart network manager:
```
sudo service network-manager restart
```

Docker image setup

Start by cloning the Square One repo to your development machine. Open a terminal in the repo's directory and ensure that bash is installed:

command -v bash # => /bin/bash

Linux users

You'll need to configure your this project's .env file. Start by duplicating the sample config:
cp dev/docker/global/.env{.sample,}
Use ifconfig to determine your Docker service IP address. The output should include an \interface named Docker0 or Docker1 or similar. Take note of the inet addr; that IP address should replace 0.0.0.0 in your .env file. Tell Daniel or Jonathan what that IP is, maybe we can find some commonalities and automate the process for Linux too.

Install the image

npm run docker:global:start

The start command will take a while the first time. You may run into an issue that reads like this:

Starting docker-compose project: global
Creating network "global_proxy" with driver "bridge"
ERROR: Pool overlaps with other one on this address space

This might happen if you are using, or used, a number of Docker-managed local development stacks; running docker network prune should solve the issue.

Note be aware that there are 2 parts to running a Square One application: global and local. The global Square One portion is required for all Square One projects and is the part that should be running up to this moment if you've been following the above steps. The local docker setup is specific to your project and should be started via:

npm run docker:start

SSL certificates

The first-run of the start command will install Central Authority on your local machine. to sign trusted SSL certificates. You'll need to configure your OS to trust self-signed certificates.

MacOS

Congratulations. You're done. Use this time to send Jonathan (@jbrinley) a taco for automating it for you.

Windows

Import trusted certificates

Linux

Adding a self-signed certificate to the “trusted list”

MySQL Database

Host	Port	Username	Password
`mysql.tribe`	`3306`	`root`	`password`

Verify that your Docker image's MySQL server is accessible with the following command:

docker exec -it tribe-mysql mysql -uroot -p
$ Enter password:

If you prefer a GUI client, consider SequelPro or HeidiSQL.

Fixing permission errors on MacOS (MySQL installed via Brew)

Installing MySQL with Brew may prevent password logins for the root user. Enable password login with the following:

echo '[mysqld]\ndefault-authentication-plugin=mysql_native_password' >> ~/.my.cnf

Web server (.tribe domains)

Verify that you're able to navigate to http://mailhog.tribe in your web browser. If the domain isn't resolvable, consider...

Clearing your DNS cache
Restarting your machine
Verifying that your DNS primary and secondary are configured
Verifying npm run docker:global:start executes without error
Submitting a bug report (ie: talk to Jonathan (@jbrinley))

Connected successfully? You're done! You can go back to the terminal and run npm run docker:global:stop or just leave global running if you're planning on doing some work.

Setup ctop (optional)

You can install ctop to monitor all your containers and get real time metrics.
docker run -ti --name ctop --rm -v /var/run/docker.sock:/var/run/docker.sock quay.io/vektorlab/ctop:latest -i
Check out the ctop for more details.

Clone a new Square One derived project

Start by cloning the repo for the new project, then initializing the submodules.

git clone git@github.com:moderntribe/{{some-project-name}}.git
cd {{some-project-name}}
git submodule update --init

Next, find the domain your BE lead chose for the project when they set it up the first time in dev/docker/docker-compose.yml.

*nix users can run the following:

cat ./dev/docker/docker-compose.yml | grep VIRTUAL_HOST

Windows users, search for a the line - VIRTUAL_HOST={{something}}.tribe.

Create a new terminal window in your main Square One repo, then create a certificate for the project's domain:

npm run docker:global:cert {{something}}.tribe

Connect to MySQL and create (or import) a database for the project. The connection info for your project is defined in local-config.php, though is commonly:

Host	Port	Username	Password
`mysql.tribe`	`3306`	`root`	`password`

Setup Browsersync (optional)

Front-end developers can follow the instructions in local-config-sample.json. The certs_path property is the full path to your square-one/dev/docker/global/certs directory.

Daily usage

Start by running your global containers from your main Square One clone:

cd {{your-projects-directory}}/square-one
npm run docker:global:start

It's generally recommended to leave the container running until you're finished working for the day:

npm run docker:global:stop

Next, navigate to the project directory you're developing in. Start its Docker instance:

cd {{your-projects-directory}}/{{some-project-name}}
npm run docker:start

That's it. You should be able to load the project in the browser.

Notes

Accessing project logs

npm run docker:log

Or to access the global container logs

npm run docker:global:log

We recommend always logging while developing to see important information — most notably, PHP errors.

WP-CLI

To use WP-CLI commands from outside of the project container, use wp.sh from dev/docker. Usage example: bash wp.sh media regenerate. This script can handle all commands and arguments available from WP-CLI. --allow-root is a default flag executed from within the script.

Configure your local to use a remote media library

Many clients have 20gb+ uploads folders, edit nginx.conf and update the proxy_pass https://livedomain.tld/$uri; line to your live domain as well as commenting out try_files $uri =404; and replacing it with try_files $uri $uri/ @images; under the /wp-content location.

Backend leads

docker-compose up doesn't look for changes on the PHP Dockerfile, so if you change how the PHP image is built (ie: add an extension or update PHP version) you need to instruct your team to go to the docker folder on the project and run docker-compose build. This is probably not going to happen often.

Creating a new project (ie: forking Square One)

git clone git@github.com:moderntribe/square-one.git {{some-project-name}}
cd {{some-project-name}}
./dev/bin/convert-project-to-fork.sh

Changing the Dockerfile (Optional)

Open docker-compose.yml and locate your service:

services:
  php-fpm:
    build:
      context: .
      dockerfile: phpdocker/php-fpm/Dockerfile
    image: tribe-phpfpm:7.0-rev5

Then, increment the revision number.

Multisite setup on a new project

After installing WordPress, run the wp-cli command

For projects that use paths

npm run wp core multisite-convert

For projects that use subdomains

npm run wp core multisite-convert --subdomains

Next, copy the output from the command into your local-config.php file and visit /wp-admin/network/setup.php to copy the changes you need in your .htaccess file.

In your wp-config.php change

'WP_ALLOW_MULTISITE' => tribe_getenv( 'WP_ALLOW_MULTISITE', false ),

to:

'WP_ALLOW_MULTISITE' => tribe_getenv( 'WP_ALLOW_MULTISITE', true ),

In dev/docker/phpdocker/nginx/nginx.conf, uncomment the two lines below by removing the # symbol at the beginning

location @rewrites {
    rewrite /wp-admin$ $scheme://$host$uri/ permanent;
    #rewrite ^(/[^/]+)?(/wp-(admin|includes|content).*) $2 last;
    #rewrite ^(/[^/]+)?(/.*\.php) $2 last;
    rewrite ^ /index.php last;
}

You may need to update this in your local-config.php and use your local domain which will be your projectID.tribe most likely:

define( 'DOMAIN_CURRENT_SITE', '{{your-project-domain}}.tribe' );

In your wp-config.php you will need to define the domain for the production site.

In your wp-config.php you also need to set:

'MULTISITE' => tribe_getenv( 'WP_MULTISITE', true ),

If you are using subdomains instead of paths set:

'SUBDOMAIN_INSTALL' => tribe_getenv( 'SUBDOMAIN_INSTALL', true ),

Finally, restart your project's docker container:

npm run docker:stop
npm run docker:start

You should now have a fully functioning multisite setup.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Prerequisites

Docker CE

MacOS

Linux

Windows

Configuring your OS

DNS Configuration

Docker image setup

Linux users

Install the image

SSL certificates

MacOS

Windows

Linux

MySQL Database

Fixing permission errors on MacOS (MySQL installed via Brew)

Web server (.tribe domains)

Setup `ctop` (optional)

Clone a new Square One derived project

Setup Browsersync (optional)

Daily usage

Notes

Accessing project logs

WP-CLI

Configure your local to use a remote media library

Backend leads

Creating a new project (ie: forking Square One)

Changing the Dockerfile (Optional)

Multisite setup on a new project

For projects that use paths

For projects that use subdomains

Files

README.md

Latest commit

History

README.md

File metadata and controls

Prerequisites

Docker CE

MacOS

Linux

Windows

Configuring your OS

DNS Configuration

Docker image setup

Linux users

Install the image

SSL certificates

MacOS

Windows

Linux

MySQL Database

Fixing permission errors on MacOS (MySQL installed via Brew)

Web server (.tribe domains)

Setup ctop (optional)

Clone a new Square One derived project

Setup Browsersync (optional)

Daily usage

Notes

Accessing project logs

WP-CLI

Configure your local to use a remote media library

Backend leads

Creating a new project (ie: forking Square One)

Changing the Dockerfile (Optional)

Multisite setup on a new project

For projects that use paths

For projects that use subdomains

Setup `ctop` (optional)