# Local Development on Ubuntu

Following these instructions will give you a local development network of Pressbooks based on roots/bedrock (opens new window) and roots/trellis (opens new window), with the following features:

# 1. Dependencies

Concise directions for installing VirtualBox, Vagrant, and Ansible are available in the Trellis docs (opens new window).

# 2. Setup

Create a directory for your local development environment and cd there:

mkdir ~/Code/pressbooks-dev && cd ~/Code/pressbooks-dev

Clone pressbooks/trellis (opens new window) into ~/Code/pressbooks-dev/trellis:

git clone git@github.com:pressbooks/trellis.git

Clone pressbooks/bedrock (opens new window) or your preferred bedrock into ~/Code/pressbooks-dev/site:

git clone git@github.com:pressbooks/bedrock.git site

The generic Pressbooks bedrock already includes pressbooks/pressbooks (opens new window), pressbooks/pressbooks-aldine (opens new window) and the required themes (opens new window) as Composer dependencies. If you would like to add additional plugins or themes to your local development environment, add them to your Bedrock with composer require commands (for more information on this strategy, see this post (opens new window)). The commands needed to add the Pressbooks SAML SSO plugin, for example, are shown below:

cd ~/Code/pressbooks-dev/site
composer require pressbooks/pressbooks-saml-sso:dev-dev

# 3. Configuration

The file ~/Code/pressbooks-dev/trellis/group_vars/development/wordpress_sites.yml reflects your desired local development site URL. It looks like:

wordpress_sites:
  pressbooks.test:
    site_hosts:
      - canonical: pressbooks.test
        redirects:
          - www.pressbooks.test
    local_path: ../site # path targeting local Bedrock site directory (relative to Ansible root)
    admin_email: ops@pressbooks.test
    multisite:
      enabled: true
      subdomains: false
    ssl:
      enabled: true
      provider: self-signed
    cache:
      enabled: false

It should work out-of-the-box. If you want to setup staging or production environments, you will need to update all instances of example.com and pressbooks.test in ~/Code/pressbooks-dev/trellis/group_vars/ to a consistent value. For more info, consult the Trellis docs (opens new window).

# 4. Launch

Open the terminal. Change to the ~/Code/pressbooks-dev/trellis/ directory and run vagrant up:

cd %HOMEPATH%\\Code\\pressbooks-dev\\trellis
vagrant up

Fully provisioning your development environment may take up to 30 minutes.

# 5. Development Tools

# Login:

The default Pressbooks username:password is admin:admin

# Logs:

Access and error logs are located on the VM in following directory:

/srv/www/example.com/logs/

# Unit Testing and Coding Standards

Unit testing in the VM:

vagrant ssh
cd /srv/www/example.com/current
bin/install-wp-tests.sh pressbooks_tests pressbooks_test '' 127.0.0.1 latest true
composer test

Coding standards in the VM:

vagrant ssh
cd /srv/www/example.com/current
composer standards

# Asset Building

We use webpack (opens new window) wrapped in Laravel Mix (opens new window) to build plugin assets (CSS and JavaScript) for Pressbooks.

  1. At the command prompt from the Pressbooks plugin directory, e.g. ~/Code/pressbooks-dev/site/web/app/plugins/pressbooks, run npm install --no-save pressbooks-build-tools to install build tools.
  2. To lint your Javascript (opens new window) and SCSS (opens new window) assets, run npm run lint.
  3. Then, run npm run build or npm run build:production to build your plugin assets (npm run build:production will add a version hash to the asset manifest for browser cache busting).

# Updating Plugins & Themes

In the terminal:

cd ~/Code/pressbooks-dev/site
composer update pressbooks/pressbooks --with-dependencies
composer update pressbooks/pressbooks-aldine --with-dependencies
composer update pressbooks/pressbooks-book --with-dependencies

# Updating Trellis & Bedrock

To update Trellis, it's best to rename the origin remote to upstream and check out the upstream master branch as a new branch called upstream:

~/Code/pressbooks-dev/trellis
git remote rename origin upstream
git checkout -b upstream upstream/master

Then any time you wish to update Trellis, you can run the following commands:

git checkout upstream && git pull
git checkout master
git merge upstream

Then commit the merge.

For Bedrock, follow the same process:

~/Code/pressbooks-dev/site
git remote rename origin upstream
git checkout -b upstream upstream/master

Then any time you wish to update Bedrock, you can run the following commands:

git checkout upstream && git pull
git checkout master
git merge upstream

Then commit the merge. You may need to regenerate your composer.lock file before you can commit, as there will often be merge conflicts.