Roots Example Project

This repository is an example of how to integrate and use the following projects together:

• Bedrock
• Trellis
• Sage (with Soil)

For more background, see this blog post.

This project is a complete working example that's deployed on a Digital Ocean $5 droplet.

You can view it at https://roots-example-project.com/.

Requirements

Make sure you have installed all of the dependencies for Trellis, Bedrock and Sage before moving on.

At a minimum you need to have:

• Ansible 2.5.3-2.7.5
• Virtualbox >= 4.3.10
• Vagrant >= 2.1.0
• Node.js >= 8.0.0
• Yarn

See our Getting Started docs:

• Development Environment Recommendations
• macOS Basic Setup
• macOS Development Environment: Sage
• macOS Development Environment: Trellis
• Ubuntu Linux Basic Setup
• Ubuntu Linux Development Environment: Sage
• Ubuntu Linux Development Environment: Trellis
• Windows Basic Setup
• Windows Development Environment: Sage
• Windows Development Environment: Trellis

Instructions

Here's how this example project was created:

1. Create a new project directory: $ mkdir example.com && cd example.com
2. Clone Trellis: $ git clone --depth=1 [email protected]:roots/trellis.git && rm -rf trellis/.git
3. Clone Bedrock: $ composer create-project roots/bedrock site
4. Install Sage: $ composer create-project roots/sage site/web/app/themes/sage
   • During theme setup, specify "https://roots-example-project.test" as the "Local development URL"

example.com/      # → Root folder for the project
├── trellis/      # → System management & deployment
└── site/         # → A Bedrock-based WordPress site
    └── web/
        ├── app/  # → WordPress content directory (themes, plugins, etc.)
        └── wp/   # → WordPress core (don't touch!)

Local development setup

1. Clone this repository into a working directory (e.g., ~/Sites)

$ git clone [email protected]:roots/roots-example-project.com.git

2. Install theme components

# @ roots-example-project.com/site/web/app/themes/sage
$ composer install
$ yarn && yarn build

3. Fire up the server (be patient, but watch the console––it may prompt for your system password)

# @ roots-example-project.com/trellis
$ vagrant up

Note: to shut down the server: vagrant halt

4. Test the install at roots-example-project.test

Remote server setup (staging/production)

Provision server:

# @ roots-example-project.com/trellis
$ ansible-playbook server.yml -e env=<environment>

Deploy:

# @ roots-example-project.com/trellis
./deploy.sh <environment> roots-example-project.com

# OR
ansible-playbook deploy.yml -e "site=roots-example-project.com env=<environment>"

To rollback a deploy:

ansible-playbook rollback.yml -e "site=roots-example-project.com env=<environment>"

Theme development

In development, run yarn start for live updates at localhost:3000. Important: always use the roots-example-project.test URL to access the WordPress admin.

# @ roots-example-project.com/site/web/app/themes/sage
$ yarn start

Production assets (minified CSS, JavaScript, images, fonts, etc.) need to be compiled. Run yarn build:production. The resulting files will be saved in themes/sage/dist/. Never edit files in the dist directory.

# @ roots-example-project.com/site/web/app/themes/sage
$ yarn build:production

Contributing

Contributions are welcome from everyone. We have contributing guidelines to help you get started.

Community

Keep track of development and community news.

• Participate on the Roots Discourse
• Follow @rootswp on Twitter
• Read and subscribe to the Roots Blog
• Subscribe to the Roots Newsletter
• Listen to the Roots Radio podcast