Ansible roles installation instructions removed from docs, should be re-added or placed elsewhere?

trellis
1

In the past couple of days the command line to install Ansible requirements has been removed from the installation documentation. Originally it was found here: https://roots.io/trellis/docs/installing-trellis/

Previously documentation asked for you to install Ansible requirements by running ansible-galaxy install -r requirements.yml from the Trellis directory.

In most cases a vagrant up would pull down your Ansible requirements and do this for you. However, if you have a lively working directory or are working with other people the chances are that at some point you’re going to lose the downloaded requirements and need to run this command again - not necessarily in tandem with vagrant up or vagrant provision. For example if you do a git stash and clean. Or if you’re provisioning / deploying from a machine you don’t have vagrant installed on.

I think this line should be re-added to the docs for this reason. As otherwise people struggling with role not found errors will have to resort to searching the discourse, when perhaps this should be in the installation documentation or troubleshooting documentation at minimum.

Happy to raise a PR if agreed, or alternatively the instruction was removed here: https://github.com/roots/docs/commit/4b38ada5dc493f7ae790bcd2782c31ed2bc5c540

2

Yeah I removed it because Vagrant takes care of it automatically now. We also removed it from the README months ago.

This was main concern about removing it but we figured if anyone knows Trellis/Ansible well enough to be doing this, they’d also know to install the Galaxy roles :thinking:

I’m not against adding it back though

1 Like
3

I understand, it’s not really needed for most cases particularly new setups so appreciate the removal from there. I do feel that this belongs in a troubleshooting section though, if you search this discourse for “ansible-galaxy install” there is a large amount of posts, problems, or commonly asked questions which depend on a user running the install command manually to resolve.

I guess future posts on discourse would be an indicator for that though if you’d prefer to have justification first

I suppose you could also argue the following too in hindsight:

  • There is no documentation to explain that vagrant up runs the install script / provision script
  • On the provisioning a remote server page there is no pre-requisite to installing ansible requirements
4

I vote for keeping the command somewhere in the docs. I’ll often clone down an older project to run updates and not vagrant up at all; just deploy to staging and then production unless there’s a problem. Having the ansible-galaxy command easily copy-and-pasteable is handy because I have the darndest time remembering it.

5

Bit off-topic but I find setting up aliases really helps! If you use Oh My Zsh, you can add something like alias galaxy-install="ansible-galaxy install -r requirements.yml" to the end of ~/.zshrc. Then you can just use your newly created galaxy-install command/alias :slight_smile: I also find this useful for encrypting/decrypting vault files:

alias encrypt-all="ansible-vault encrypt group_vars/all/vault.yml"
alias encrypt-dev="ansible-vault encrypt group_vars/development/vault.yml"
alias encrypt-prod="ansible-vault encrypt group_vars/production/vault.yml"
alias encrypt-staging="ansible-vault encrypt group_vars/staging/vault.yml"
alias decrypt-all="ansible-vault decrypt group_vars/all/vault.yml"
alias decrypt-dev="ansible-vault decrypt group_vars/development/vault.yml"
alias decrypt-prod="ansible-vault decrypt group_vars/production/vault.yml"
alias decrypt-staging="ansible-vault decrypt group_vars/staging/vault.yml"
alias provision-staging="ansible-playbook server.yml -e env=staging"
alias provision-prod="ansible-playbook server.yml -e env=production"

Then from the trellis directory, you can use decrypt-dev for example. Speedy!

You should be able to do the same if you use bash using permanent aliases: Terminal/Bash Command-Line Shortcuts with Aliases — Jonathan Suh.

2 Likes
6

Some good little snippets there, I think I’ll steal some of those! Thanks for sharing

I do feel that as existing Trellis users this is an easy concept to grasp, and we have the benefit of having been down this road before.

People who haven’t experienced this “issue” and are new to Trellis perhaps need a bit of a nudge or hint in the documentation though.

Those users will just expect a provision or deploy to just work all the time and follow the instructions in the docs. Of which in some edge cases a vagrant up won’t pull down the dependencies if the VM has already been provisioned. Which as we all know isn’t an unlikely occurrence

7

I agree with all of the above - a troubleshooting or FAQ type page would be great!

8

Keep in mind anyone can contribute to the docs and open a PR :slight_smile:

1 Like
9

I added this back for now anyway

1 Like
10

A side note on this: Not sure why, but I had to install Ansible to run ‘vagrant up’ locally. Without Ansible, ‘vagrant up’ would simply abort the installation with the following message:

==> default: Running provisioner: ansible_local...
    default: Installing Ansible...
    default: Installing pip... (for Ansible installation)
Vagrant has automatically selected the compatibility mode '2.0'
according to the Ansible version installed (2.4.0.0).

Alternatively, the compatibility mode can be specified in your Vagrantfile:
https://www.vagrantup.com/docs/provisioning/ansible_common.html#compatibility_mode

The requested Ansible version (2.4.0) was not found on the guest.
Please check the Ansible installation on your Vagrant guest system (currently: 2.4.0.0),
or adapt the provisioner `version` option in your Vagrantfile.
See https://docs.vagrantup.com/v2/provisioning/ansible_common.html#version
for more information.

If this is normal, I guess it should be added back to the the general requirements.