path: root/README.md

# Introduction

[ansible](https://github.com/ansible/ansible) roles and scripts used
for rgoncalves.se's homelab. This repository is a rewrite of the now deprecated
`_infrastructure/ansible`.

# Quickstart

Setup your development environment and run you first playbooks with the
following commands:

```
$ poetry install
$ poetry shell
$ . ./bin/env
# ansible-playbook playbooks/workstation.yml -e workstation_user=$USER
$ ansible-playbook playbooks/site.yml
```

# Getting started

## Poetry environment

[poetry](https://github.com/python-poetry/poetry) is used for managing the
`ansible` and `mitogen` packages.

```
poetry install
```

## Mitogen

[mitogen](https://github.com/mitogen-hq/mitogen) is a really fast executor
plugin for Ansible. It is not enabled by default, and that's the reason
`poetry` and the following script are used.

You have to source the `env` script if you want to execute playbooks with
`mitogen`, preferably inside a `poetry` environment. It is important because
`mitogen` upstream is currently set to master, allowing compatibility with
`ansible` 2.12.

```
poetry shell
. ./bin/env
```

## Development machine

A new development workstation can be scaffolded thanks to the workstation
playbook and role.

```
# ansible-playbook playbooks/workstation.yml
```