Roots Example Project
This repository is an example of how to integrate and use the following projects together:
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:
- Create a new project directory:
$ mkdir example.com && cd example.com - Clone Trellis:
$ git clone --depth=1 git@github.com:roots/trellis.git && rm -rf trellis/.git - Clone Bedrock:
$ composer create-project roots/bedrock site - 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
- Clone this repository into a working directory (e.g.,
~/Sites)
$ git clone git@github.com:roots/roots-example-project.com.git
- Install theme components
# @ roots-example-project.com/site/web/app/themes/sage
$ composer install
$ yarn && yarn build
- 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
- 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