Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/cytopia/ansible-debian

Buildfiles: Ansible automated leight-weight and sensible Debian provisioning
https://github.com/cytopia/ansible-debian

ansible ansible-roles buildfiles debian dotfiles dotfiles-install dotfiles-resources font i3 i3-gaps i3wm inventory profile provision provisioning provisioning-scripts python workstations

Last synced: 3 months ago
JSON representation

Buildfiles: Ansible automated leight-weight and sensible Debian provisioning

Host: GitHub
URL: https://github.com/cytopia/ansible-debian
Owner: cytopia
License: mit
Created: 2017-12-10T00:13:34.000Z (over 6 years ago)
Default Branch: master
Last Pushed: 2022-06-11T19:44:37.000Z (about 2 years ago)
Last Synced: 2024-02-20T05:32:53.833Z (4 months ago)
Topics: ansible, ansible-roles, buildfiles, debian, dotfiles, dotfiles-install, dotfiles-resources, font, i3, i3-gaps, i3wm, inventory, profile, provision, provisioning, provisioning-scripts, python, workstations
Language: Jinja
Homepage:
Size: 1.9 MB
Stars: 90
Watchers: 9
Forks: 19
Open Issues: 3
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md

Lists

awesome-list-ansible - ansible-debian - weight and sensible Debian provisioning (python)

README

# Ansible Debian (buildfiles)

[![travis](https://travis-ci.org/cytopia/ansible-debian.svg?branch=master)](https://travis-ci.org/cytopia/ansible-debian)

Well-tested and customizable **[Ansible](https://www.ansible.com)** 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](https://github.com/cytopia/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.

[![asciicast](https://asciinema.org/a/153924.png)](https://asciinema.org/a/153924)

#### Table of Contents

1. **[TL;DR](#tldr)**
2. **[Features](#features)**
1. [Available tools](#available-tools)
2. [Fonts / Themes](#fonts--themes)
3. [Sensible customizations](#sensible-customizations)
3. **[Create custom profiles](#create-custom-profiles)**
1. [Assumption](#assumption)
2. [Add a new profile](#add-a-new-profile)
3. [Add a profile configuration](#add-a-profile-configuration)
4. [Customize your profile](#customize-your-profile)
5. [Provision your profile](#provision-your-profile)
4. **[Test your profile](#test-your-profile)**
1. [Docker](#docker)
1. [Vagrant](#vagrant)
5. **[Options](#options)**
1. [Enable / Disable Management](#enable--disable-management)
2. [Package options](#package-options)
6. **[Requirements](#requirements)**
1. [Install system requirements](#install-system-requirements)
2. [Sudo permissions](#sudo-permissions)
7. **[Stability](#stability)**
8. **[Other OS](#other-os)**
9. **[Contributing](#contributing)**
10. **[License](#license)**

## TL;DR

Make sure your system meets the **[requirements](#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.

```bash
# 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
```

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

```bash
# 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 the tools installation

```bash

# 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](https://github.com/cytopia/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

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/](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](https://wiki.archlinux.org/index.php/Default_applications) 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](inventory) file automatically represents one **profile**.

By the way Ansible works, each profile inherits all settings from [group_vars/all.yml](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/](host_vars/) by the same name you have specified in [inventory](inventory). You can copy [group_vars/all.yml](group_vars/all.yml) directly or use an already existing profile from `host_vars`, such as [host_vars/generic-all.yml](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](inventory):
```bash
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](group_vars/all.yml) or an already existing `host_vars` file.

Use group_vars/all.yml as a default template:
```bash
cp group_vars/all.yml host_vars/dell-xps-i3wm.yml
```
Use an already existing host_vars file as a default template:
```bash
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:
```bash
ansible-playbook -i inventory playbook.yml --diff --limit dell-xps-i3wm --ask-become-pass --check
```
Run the following command to actually apply your profile:
```bash
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`:
```bash
make test-docker-full PROFILE=generic-all
```
Run a full test of profile `generic-all` in a random order:
```bash
make test-docker-random PROFILE=generic-all
```
Only run `i3-gaps` role in profile `generic-all`
```bash
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.

```bash
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.
```bash
$ vi host_vars/.yml
```
```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:
```bash
$ vi host_vars/.yml
```
```yml
...
python_2: yes
python_3: yes
...
```

Another customization could be the default program to use when opening speficif file types:
```bash
$ vi host_vars/.yml
```
```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`
```bash
$ vi host_vars/.yml
```
```yml
...
lxdm_dpi: 132
lxdm_gtk_theme: Arc-Darker
lxdm_show_user_list: no
...
```

Choose your GPU and touchpad driver:
```bash
$ vi host_vars/.yml
```
```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'
...
```

## 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
```

## Stability

In order to guarantee the most possible stability of this setup, extensive [travis-ci](https://travis-ci.org/cytopia/ansible-debian) 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](https://github.com/dyindude/ansible-linux-laptop)**
* Ubuntu - **[ansible-ubuntu](https://github.com/Benoth/ansible-ubuntu)**
* Fedora - **[laptop_install](https://github.com/e-minguez/laptop_install)**

## Contributing

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

## License

**[MIT License](LICENSE.md)**