|
| 1 | + |
| 2 | +# Linux Developer VM Example / Template |
| 3 | + |
| 4 | +[](https://circleci.com/gh/Zuehlke/linux-developer-vm-with-ansible/tree/master) |
| 5 | + |
| 6 | +A minimal example / template project for an Ansible-managed Linux Developer VM. |
| 7 | + |
| 8 | + |
| 9 | + |
| 10 | +It's meant to be copy/pasted and filled with life. The `roles/` directory contains the roles |
| 11 | +for setting up the VM, the `spec/` directory contains the tests that come along with it. |
| 12 | +All your specific customizations go in there! |
| 13 | + |
| 14 | +**NOTE: This is just a bare skeleton template project.** |
| 15 | + |
| 16 | +For the Chef-based equivalent of it, see https://github.com/Zuehlke/linux-developer-vm |
| 17 | + |
| 18 | + |
| 19 | +## What's included? |
| 20 | + |
| 21 | +### Main tools |
| 22 | + |
| 23 | +These are the main tools included in this developer VM (see CHANGELOG for the specific versions): |
| 24 | + |
| 25 | + * [Ansible](https://docs.ansible.com/ansible/latest/index.html) - for managing / installing this developer VM |
| 26 | + * [Ansible-lint](https://github.com/ansible/ansible-lint) - to ensure best practices when adding more Ansible roles |
| 27 | + * [TestInfra](https://testinfra.readthedocs.io/en/latest/) - for verifying that the developer VM is set up correctly |
| 28 | + |
| 29 | +### Tweaks and Settings |
| 30 | + |
| 31 | +Other tweaks and settings worth mentioning: |
| 32 | + |
| 33 | + * places a `README.md` file on the Desktop to guide first time users after they logged in to the VM |
| 34 | + * symlinks [`update-vm.sh`](scripts/update-vm.sh) to `/usr/local/bin/update-vm` so it's in the `$PATH` and can be used for updating the VM from the inside (see below) |
| 35 | + |
| 36 | + |
| 37 | +## Usage |
| 38 | + |
| 39 | +### Obtaining and Starting the VM Image |
| 40 | + |
| 41 | +The latest version of this developer VM can be downloaded as a VM image from here: |
| 42 | + |
| 43 | + * https://github.com/Zuehlke/linux-developer-vm-with-ansible/releases |
| 44 | + |
| 45 | +After downloading the .ova file you can import it into VirtualBox via `File -> Import Appliance...`. |
| 46 | +Once imported, you can simply start the VM and log in: |
| 47 | + |
| 48 | + * username: "user" |
| 49 | + * password: "user" |
| 50 | + |
| 51 | +From then on just open a terminal and you will have all of the tools available (see "What's included?"). |
| 52 | + |
| 53 | +### Updating the VM |
| 54 | + |
| 55 | +You can run these commands from anywhere inside the developer VM: |
| 56 | + |
| 57 | + * `update-vm` - update the VM by applying the Ansible roles from the locally checked out repo at `~/vm-setup` |
| 58 | + * `update-vm --pull` - same as above, but update repo before by pulling the latest changes |
| 59 | + * `update-vm --verify-only` - don't update the VM, only run the TestInfra tests |
| 60 | + * `update-vm --provision-only` - don't run the TestInfra tests, only update the vm |
| 61 | + |
| 62 | +### Further Usage Instructions |
| 63 | + |
| 64 | +For further instructions, please refer to the README.md that is placed on the Desktop of the Developer VM: |
| 65 | + |
| 66 | +* https://github.com/Zuehlke/linux-developer-vm-with-ansible/blob/master/roles/readme/files/README.md |
| 67 | + |
| 68 | + |
| 69 | +## Development |
| 70 | + |
| 71 | +### Prerequisites |
| 72 | + |
| 73 | +You only need [VirtualBox](http://virtualbox.org/wiki/Downloads) and [Vagrant](http://www.vagrantup.com/) |
| 74 | +installed. |
| 75 | + |
| 76 | +All other requirements, including Ansible will be installed *inside the Vagrant VM* during provisioning, i.e. you don't need them installed on your host machine. |
| 77 | + |
| 78 | +### Basic Development Workflow |
| 79 | + |
| 80 | +Bring up the developer VM: |
| 81 | +``` |
| 82 | +$ vagrant up |
| 83 | +``` |
| 84 | + |
| 85 | +This will take a while, as it will do quite a few things inside the VM: |
| 86 | + |
| 87 | + 1. set up a new user account using the `setup-vm-user.sh` script |
| 88 | + 1. update the VM using `update-vm.sh` script |
| 89 | + 1. installs Ansible from PyPi |
| 90 | + 1. runs the `site.yml` playbook to install the toolchain and configure the developer VM |
| 91 | + 1. checks the roles via `ansible-lint` to ensure best practices |
| 92 | + 1. verifies the configuration of the VM via TestInfra |
| 93 | + |
| 94 | +Watch the vagrant output on the console for seeing progress. At the end you |
| 95 | +should see all tests passing: |
| 96 | + |
| 97 | +``` |
| 98 | +... |
| 99 | + default: ============================= test session starts ============================== |
| 100 | + default: platform linux -- Python 3.8.2, pytest-5.4.1, py-1.8.1, pluggy-0.13.1 -- /usr/bin/python3 |
| 101 | + default: cachedir: .pytest_cache |
| 102 | + default: rootdir: /home/user/vm-setup |
| 103 | + default: plugins: testinfra-5.0.0, spec-2.0.0 |
| 104 | + default: collecting ... |
| 105 | + default: collected 8 items |
| 106 | + default: |
| 107 | + default: spec/test_ansible.py: |
| 108 | + default: ✓ Ansible is installed at version 2 9 6 [local] |
| 109 | + default: ✓ Ansible commands are found [local] |
| 110 | + default: ✓ Ansible version command reports version 2 9 6 [local] |
| 111 | + default: |
| 112 | + default: spec/test_ansible_lint.py: |
| 113 | + default: ✓ Ansible lint is installed at version 4 2 0 [local] |
| 114 | + default: ✓ Ansible lint command is found [local] |
| 115 | + default: ✓ Ansible lint version command reports version 4 2 0 [local] |
| 116 | + default: |
| 117 | + default: spec/test_testinfra.py: |
| 118 | + default: ✓ Testinfra is installed at version 5 0 0 [local] |
| 119 | + default: ✓ Pytest spec is installed at version 2 0 0 [local] |
| 120 | + default: |
| 121 | + default: ============================== 8 passed in 4.05s =============================== |
| 122 | +``` |
| 123 | + |
| 124 | +If these are passing as expected, you can continue developing on the Ansible roles within this repo. |
| 125 | +Please don't forget to add a test for each new feature you add (see "Contributing") |
| 126 | + |
| 127 | +### Packaging |
| 128 | + |
| 129 | +Whenever you feel like distributing a fat VM image rather than a Vagrantfile, |
| 130 | +you can package / export it as a VirtualBox image. This might be useful |
| 131 | +for distributing the initial version of the developer VM to your dev team, |
| 132 | +or simply for preserving checkpoint releases as a binary images. |
| 133 | + |
| 134 | +Let's start from a clean state: |
| 135 | +``` |
| 136 | +$ vagrant destroy -f |
| 137 | +$ vagrant up |
| 138 | +``` |
| 139 | + |
| 140 | +This will provision the VM as usual. Once the provisioning succeeded, we will |
| 141 | +do a few cleanup steps before packaging the VM. |
| 142 | + |
| 143 | +First, unmount the /vagrant shared folder: |
| 144 | +``` |
| 145 | +$ vagrant ssh -c "sudo umount /vagrant -f" |
| 146 | +``` |
| 147 | + |
| 148 | +Finally, shutdown the VM, remove the sharedfolder, and export the VM as an .ova file: |
| 149 | +``` |
| 150 | +$ vagrant halt |
| 151 | +$ VBoxManage sharedfolder remove "Linux Developer VM" --name "vagrant" |
| 152 | +$ VBoxManage modifyvm "Linux Developer VM" --name "Linux Developer VM v0.1.0" |
| 153 | +$ VBoxManage export "Linux Developer VM v0.1.0" --output "linux-developer-vm-v0.1.0.ova" --options manifest,nomacs |
| 154 | +``` |
| 155 | + |
| 156 | +Don't forget to throw away the VM when you are done: |
| 157 | +``` |
| 158 | +$ vagrant destroy -f |
| 159 | +``` |
| 160 | + |
| 161 | + |
| 162 | +## Contributing |
| 163 | + |
| 164 | + 1. Fork the repository on Github |
| 165 | + 1. Create a named feature branch (like `feature/add-xyz`) |
| 166 | + 1. Implement your changes, add tests |
| 167 | + 1. Commit and push |
| 168 | + 1. Submit a Pull Request via Github |
0 commit comments