Ensure that you've installed all prerequisites (including the Evolve generator).
Create and change to a directory for your Evolution site, and initialize it as a new git repository:
mkdir ~/Example.com
cd ~/Example.com
git init
Run the yeoman generator in said directory and follow the prompts:
yo evolve wordpress
The difference between public and private projects is important, and will affect where and how you version your project.
Add and commit your pristine generated site:
git add .
git commit -m "Newly generated Example.com"
Create a remote repository (eg, on Github or Gitlab), add it as a remote origin to your local repo, and push to it:
git remote add origin git@yourremoteprovider.com:yourusername/Example.com.git
git push origin master
Every Evolution site has three pre-configured "stages", environments with a specific purpose:
- local - where all of your development should happen, such as installing or editing themes and plugins
- staging - where quality assurance and review of new features should happen
- production - where your polished end product, the canonical "live site", should exist
Create a self-contained local environment for your site with vagrant. This may take several minutes to complete:
vagrant up
This creates a virtual server with the entire Evolution web stack, and your site codebase pre-deployed. You can ssh into the server:
vagrant ssh
As well as view the local site in your browser -- following our example, it would be:
On the first visit, you'll be presented with the Wordpress install page:
Follow the steps to configure your site. You should only need to do this once, and only on the local stage -- access to the install page is disabled for staging and production. We'll come back to that in a bit.
Evolution provides several Capistrano tasks that you can run for a given stage:
# tail the apache error logs in real time
# (ctrl+c to stop)
bundle exec cap local evolve:logs:apache:access
# restart the web stack
bundle exec cap local evolve:restart
For your remote environment (staging in this case), you will need:
- a web accessible server running Ubuntu 14.04
- a DNS or hostfile entry for said server, resolving to (in our example)
staging.example.com
For provisioning, you'll need a user on said server with password-based SSH access, and sudo privilege.
Many web hosts will provide you a root user with a private key for remote access. We will demonstrate how to prepare such a server for Evolution.
You may be asking, "My root user has password-based SSH access. Can I provision as root?" To which the anser is yes, you absolutely can!
That said, it is pretty universally recommended to disable password-based root access to a server -- either by setting up an ssh keypair for the root user, or setting the
PermitRootLoginoption of your ssh daemon tono.
Log into the server (with your provided ssh key), and create a unique user and password with the adduser command:
ssh -i ~/staging-key.pem root@staging.example.com
adduser jdoe
You'll also need to grant this user sudo privilege. On Ubuntu, this is most easily accomplished by adding the user to sudo group:
usermod -aG sudo jdoe
Evolution provides a capistrano task for provisioning your remote stage:
bundle exec cap staging evolve:provision
When running this against a never before provisioned server, you should be prompted for a username, password, and sudo password (typically the exact same password):
Unable to provision with SSH publickey for "deploy" user
Please enter user to provision as (root):
SSH password:
sudo password [defaults to SSH password]:
What follows is Ansible provisioning, which (among other things) sets up private key access for the newly created deploy user.
Any subsequent reprovisioning will use the deploy user, so it's a good idea at this point to remove or disable that jdoe user we added a couple steps back.
# lock user account
passwd -l jdoe
# or remove user altogether
deluser --remove-home jdoe
We'll need to configure your project's SSH public key (in lib/ansible/files/ssh/) as a deployment key:
And then deploy with capistrano:
bundle exec cap staging deploy
You should now be able to reach the remote environment in your web browser:
You'll notice that your remote environment produces a 403 Forbidden error, because access to the Wordpress install page is disabled for security concerns.
Sync your local database and uploaded files up to the remote environment, and restart it (to clear the varnish cache):
bundle exec cap staging evolve:up
bundle exec cap staging evolve:restart
You'll be prompted that this is a destructive operation and will overwrite any existing db and files on the remote server:
WARNING: You are about to destroy & override the "staging" database!
WARNING: You are about to overwrite "staging" files!
Try your browser again, and it should mirror your local environment.
Syncing a remote database and files down to the local environment is similarly straightforward:
bundle exec cap staging evolve:down
bundle exec cap local evolve:restart
Note that we're restarting local, because the previous command is overwriting the local database/files.
As you continue to develop your site, you'll want to commit and push future changes (including adding themes and plugins) to your git remote. Sending said committed changes to your remote environment is as simple as another deployment.
As you add content and uploaded files in Wordpress itself, you can send them between your local and remote with another sync.