Ansible Debian (buildfiles)

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.

Table of Contents

1. TL;DR
2. Features
   1. Available tools
   2. Fonts / Themes
   3. Sensible customizations
3. Create custom profiles
   1. Assumption
   2. Add a new profile
   3. Add a profile configuration
   4. Customize your profile
   5. Provision your profile
4. Test your profile
   1. Docker
   2. Vagrant
5. Options
   1. Enable / Disable Management
   2. Package options
   3. Encrypt config
6. Requirements
   1. Install system requirements
   2. Sudo permissions
7. Stability
8. Other OS
9. Contributing
10. License

TL;DR

Make sure your system meets the requirements before you start.

Fully provision your system from scratch

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/kalos/ansible-debian-workstation/master/bootstrap | bash

# Provision profile 'generic-all'
curl https://raw.githubusercontent.com/kalos/ansible-debian-workstation/master/bootstrap | bash -s generic-all

Manually provision your system from scratch

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/kalos/ansible-debian-workstation
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 the tools installation

# 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

Features

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.

Available tools

Tool	Description
autorunner	Configurable and notification aware autostart helper for minimalistic window managers like i3, openbox and others
chromium	Sets up Chromium, additional packages as well as specified extensions from Chrome webstore
clipmenu	Clipboard manager with dmenu or rofi integration
dbeaver	Universal SQL Client
diff-highlight	Tool for awesome git diff output
docker	Docker repo and package and also making sure user is added to docker group
docker-compose	Downloads latest docker-compose binary
dotfiles	Install personal dotfiles
ffscreencast	FFmpeg wrapper for desktop-recording with video overlay and multi monitor support
firefox	Firefox Quantum
fzf	Command line fuzzy finder
gimp	Gimp with Photoshop theme and keybindings
i3	i3wm
i3-gaps	i3wm on steroids
i3-utils-bin	Tools for i3wm
i3-utils-systemd	Systemd files for i3wm
i3blocks-modules	Awesome i3blocks modules
kops	Kubernetes operations command line tool
kubectl	Kubernetes command line tool
libreoffice	LibreOffice 6 with MsOffice 2013 Icon theme
lxdm	Leight-weight login manager
neovim	vim on steroids
network-manager	Gnome's LAN and WIFI network manager with optional system tray
oh-my-zsh	A delightful community-driven framework for managing your zsh configuration.
packer	HashiCorp's packer to build automated machines
pinta	Open source Paint.Net / MsPaint clone.
ranger	Command line file manager with inline image preview (can also be used as vim file manager)
skype	Skype repo and package
sublime	Sublime repo and package
sxiv	Small, fast and low-dependency image viewer with vim binding
systemd	Manage enabled, disabled and masked systemd services
telegram	Telegram desktop repo and package
terraform	HashiCorp's Infrastructure as Code provisioner
thunar	Thunar and its requirements to handle external disks as well as encrypted disks
thunar-custom-actions	Thunar custom actions
thunderbird	Thunderbird and globally defined add-ons
timemachine	OSX like timemachine for the command line
urxvt	Small, fast and leight-weight 256 color unicode terminal emulator
virtualbox	VirtualBox upstream repository and packages
xbacklight	Modern cross-GPU xbacklight replacement
xdg-mime-meta	Defines default applications for xdg-open
xorg	Xorg and its dependencies as well as GPU and touchpad configurations
zathura	Small, fast and low-dependency pdf viewer with vim bindings

Fonts / Themes

Tool	Description
font-droid-sans-mono	DroidSansMono Nerdfont with many glyphs and unicode symbols
font-font-awesome	FontAwesome as a system font
font-san-francisco	OSX Yosemite San Francisco font
font-terminus	Terminus Nerdfont with many glyphcs and unicode symbols
font-ubuntu	Ubuntu's official font
icon-moka	Moka icon themes (for thunar or nautilus)
theme-arc	Arc theme for GTK2, GTK3, Chrome and others

See roles/ directory for all available packages. If you are missing one, open up an issue or a pull request.

Sensible customizations

Additionally you can (but don't have to) manage the following:

• Xdg default applications
• Custom apt packages can be added per profile
• Custom pip packages can be added per profile
• Custom Debian repositories can be added per profile
• Debian distribution (stable is upgraded to testing)

Create custom profiles

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:

Assumption

For the sake of this example, let's assume your profile is called dell-xps-i3wm.

Add a new profile

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.

Add a profile configuration

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

Customize your profile

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.

Provision your profile

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

Test your profile

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.

Docker

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

Vagrant

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

Options

Enable / Disable Management

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'
...

Package options

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'
...

Encrypt config

Inizialize vault:

dd bs=512 count=4 iflag=fullblock if=/dev/random of=.vaultfile

(ensure you have vault_password_file option configured in ansible.cfg)

Encrypt file:

ansible-vault encrypt .gitconfig --output .gitconfig_encrypt

Dotfiles module auto-decrypt all file "*_encrypt".

You also use encrypted var for example in jinja2 template. Create encrypted var:

ansible-vault encrypt_string --vault-password-file .vaultfile 'mysecret' --name 'secret_var_name'

Insert output in file 'host_vars/kalos-jiji.yml':

secret_var_name: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          65346139663638613663653235386632346630626631353231623461623862393333383638383638
          6235396634663766626637393066653137373663376162610a613764366538303631643837333239
          62313662626134323437393662626461313831663838366662313030303032663537303465396364
          6136643362663861370a646561346662656434303235336333316562616365666265656663346239
          3730

Rekey all encrypted files:

export debian_workstation=/home/kalos/projects/devops/debian_workstation

cd $HOME/.dotfiles 
dd bs=512 count=4 iflag=fullblock if=/dev/random of=$debian_workstation/.vaultfile_new

for dotfile_encrypted in $(git ls-files | grep _encrypted)
do
  ansible-vault rekey --vault-password-file $debian_workstation/.vaultfile --new-vault-password-file $debian_workstation/.vaultfile_new $dotfile_encrypted
done
mv $debian_workstation/.vaultfile_new $debian_workstation/.vaultfile

Requirements

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.

Install system requirements

apt-get update
apt-get install --no-install-recommends --no-install-suggests -y \
  make \
  sudo

Sudo permissions

Make sure your user is allowed run sudo

usermod -aG sudo <username>

Stability

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:

• Each run is done randomized and in order as well as for each role separately
• Each run is done for Debian stable and upgraded to testing
• Each run is done against all defined profiles (repositories: main vs main, extra and non-free)

Other OS

If you are running a different OS and still want to provision your system with Ansible, have a look at the following similar projects:

• Ubuntu - ansible-linux-laptop
• Ubuntu - ansible-ubuntu
• Fedora - laptop_install

Contributing

Please feel free to contribute and add new roles as desired. When doing so have a look at CONTRIBUTING.md for required best-practices.

License

MIT License

Copyright (c) 2019 cytopia, kalos