Buildfiles: Ansible automated leight-weight and sensible Debian provisioning
MIT License
TL;DR | Features | Custom profiles | Test your profile | Options | Requirements | Stability | Other OS | License
Well-tested and customizable Ansible setup to provision your workstation with Debian.
Get your system back under control. Manage packages not provided by default and keep track of repositories as well as of installed software. Any bundled package offers the possibility to fully manage them, i.e. make sure they are installed or removed. Of course you can also simply ignore them, in case you want to manage them yourself.
It is designed to be a generic buildfiles (as opposed to dotfiles) manager. You can add as many profiles as you want (e.g.: for different hardware on different notebooks) and also have the choice to provision it locally or over the network.
Make sure your system meets the requirements before you start.
Use this to provision your system from scratch, when you have already submitted your profile upstream.
The only requirements are bash
and sudo
, everything else will be installed automatically.
# Provision default profile
curl https://raw.githubusercontent.com/cytopia/ansible-debian/master/bootstrap | bash
# Provision profile 'generic-all'
curl https://raw.githubusercontent.com/cytopia/ansible-debian/master/bootstrap | bash -s generic-all
Use this to provision your system from scratch, when you don't have a profile submitted to upstream yet.
# 1. Clone this project
git clone https://github.com/cytopia/ansible-debian
cd ansible-debian
# 2. Add your profile 'bob' (See 'Create custom profiles' section of this README)
# 3. Provision your system (with profile 'bob')
# Note when to use sudo and when not
sudo make deploy-init
make deploy-apt-sources PROFILE=bob
sudo make deploy-dist-upgrade
make deploy-tools PROFILE=bob
# Dry-run everything for profile 'generic-all'
make diff-tools PROFILE=generic-all
# Dry-run everything for profile 'generic-all' without role 'systemd'
make diff-tools PROFILE=generic-all IGNORE=systemd
# Dry-run a specific role 'i3-gaps'
make diff-tools PROFILE=generic-all ROLE=i3-gaps
This Ansible repository allows you to provision your Debian machines and keeping them up-to-date. It allows you to create different profiles for different machines and offers packages that are not available by any Debian repository.
This is a base idempotent provisioning with sensible defaults that can be slightly adjusted. It is only meant as a buildfiles bootstrap. In order to customize the applications itself, you will still have to apply your personal dotfiles on top of that.
See roles/ directory for all available packages. If you are missing one, open up an issue or a pull request.
Additionally you can (but don't have to) manage the following:
In order to customize your workstation or Debian infrastructure, you can create profiles for each of your machines. This might be necessary due to different hardware or software preferences. Each hostname (real or made up) in the inventory file automatically represents one profile.
By the way Ansible works, each profile inherits all settings from group_vars/all.yml. This file holds a sane default showing you all available options and with all packages unmanaged.
In order to actually customize your profile, you will have to create a file in host_vars/ by the same name you have specified in inventory. You can copy group_vars/all.yml directly or use an already existing profile from host_vars
, such as host_vars/generic-all.yml.
To better understand how it works, you can follow this step-by-step example for creating a new profile:
For the sake of this example, let's assume your profile is called dell-xps-i3wm
.
Add the following line to the bottom of inventory:
dell-xps-i3wm ansible_connection=local
ansible_connection=local
defines that your profile should be applied to your local computer. If you want to create a profile for a remote computer, your profile name must be a hostname or IP address by which the remote machine is reachable over the network.
As already mentioned earlier, you can copy group_vars/all.yml or an already existing host_vars
file.
Use group_vars/all.yml as a default template:
cp group_vars/all.yml host_vars/dell-xps-i3wm.yml
Use an already existing host_vars file as a default template:
cp host_vars/generic-all.yml host_vars/dell-xps-i3wm.yml
Simply edit host_vars/dell-xps-i3wm.yml
and adjust the values to your needs. If you have copied an already existing file, it will contain comments for all possible configuration options that let's you quickly see what and how to change.
If you want to test your profile in a Docker container prior actually provisioning your own system, skip to the next section, otherwise just run the following commands.
Run the following command to see what would happen:
ansible-playbook -i inventory playbook.yml --diff --limit dell-xps-i3wm --ask-become-pass --check
Run the following command to actually apply your profile:
ansible-playbook -i inventory playbook.yml --diff --limit dell-xps-i3wm --ask-become-pass
Before actually running any new profile on your own system, you can and you should test that beforehand. This can be done in a Docker container or in a Vagrant box in order to see if everything works as expected. This might also be very handy in case you are creating a new role and want to see if it works.
Note: The Docker image will always be auto-build before running the tests.
Before running you should be aware of a few arguments that can be applied to the make
commands. See the table below:
Variable | Required | Description |
---|---|---|
PROFILE |
yes | The inventory hostname (your profile) |
VERBOSE |
no | Ansible verbosity. Valid values: 0 , 1 , 2 or 3
|
ROLE |
no | Only run this specific tag (role name) |
Run a full test of profile generic-all
:
make test-docker-full PROFILE=generic-all
Run a full test of profile generic-all
in a random order:
make test-docker-random PROFILE=generic-all
Only run i3-gaps
role in profile generic-all
make test-docker-single PROFILE=generic-all ROLE=i3-gaps
If you don't trust the tests in Docker and want to see the end results graphically in a VM, you can also use Vagrant to do the same.
make test-vagrant PROFILE=generic-all
Look for the package section and set them to a desired state. install
or remove
or any other value to ignore them.
$ vi host_vars/<name>.yml
...
i3-gaps: 'install'
font_ubuntu: 'install'
diff_highlight: 'install'
docker: 'remove'
docker_compose: 'remove'
skype: 'ignore'
sublime: 'ignore'
...
Many packages also come with options that you can tweak. You can for example define the Python version your system should provide:
$ vi host_vars/<name>.yml
...
python_2: yes
python_3: yes
...
Another customization could be the default program to use when opening speficif file types:
$ vi host_vars/<name>.yml
...
xdg_mime_defaults:
- desktop_file: chromium.desktop
mime_types:
- text/html
- text/xml
- application/xhtml_xml
- application/x-mimearchive
- x-scheme-handler/http
- x-scheme-handler/https
...
Or to set your DPI and other options for lxdm
$ vi host_vars/<name>.yml
...
lxdm_dpi: 132
lxdm_gtk_theme: Arc-Darker
lxdm_show_user_list: no
...
Choose your GPU and touchpad driver:
$ vi host_vars/<name>.yml
# Supported values: 'amdgpu' 'ati' 'intel' 'modesetting' 'nouveau' 'nvidia' 'radeon'
xorg_gpu: modesetting
# Enable VDPAU_DRIVER=va_gl systemwide
xorg_gpu_vdpau_va_gl_enable: yes
# 'libinput' or 'synaptics'
xorg_touchpad_enable: yes
xorg_touchpad_driver: 'synaptics'
...
Before you can start there are a few tools required that must be present on the system. Just copy-paste those commands as root into your terminal.
apt-get update
apt-get install --no-install-recommends --no-install-suggests -y \
make \
sudo
Make sure your user is allowed run sudo
usermod -aG sudo <username>
In order to guarantee the most possible stability of this setup, extensive travis-ci checks have been defined which automatically run every night. Those tests are run inside a Docker container. The following test cases have been defined:
If you are running a different OS and still want to provision your system with Ansible, have a look at the following similar projects:
Please feel free to contribute and add new roles as desired. When doing so have a look at CONTRIBUTING.md for required best-practices.
Copyright (c) 2017 cytopia