# Ansible Starter Kit

Easy way for my homies to start up an ansible project for their homelab or local machine.

# Prerequisites

The ideal setup for a homelab is to have:

- The same username/password in all vms/hosts so you don't have to type a different password for each host
- SSH key auth on each host so you don't have to type a password at all

# Ansible basics

I'll explain the basic units of an ansible project. For this example we're going to assume you want to mount
an NFS share in all your hosts.

From bottom to top we have:

## Tasks

A task is the lowest unit in an ansible project. 

A task could be:

- Creating a directory
- Installing an os package (curl, docker, nfs-common, etc) 
- Starting a docker container

### Examples

```yml
- name: Add SSH key for remote user
  ansible.posix.authorized_key:
    user: javi
    state: present
    key: "{{ lookup('file', '/home/javi/.ssh/homelab_keypair_ed25519.pub') }}"
```

```yml
- name: Ensure NFS client is installed
  ansible.builtin.package:
    name: nfs-common
    state: present
  become: true
```

## Role

A role is a self contained, re-usable unit that will give a meaningful result. Think of it like a class in a program.

Roles have a list of tasks, as well as variables and files associated with those tasks. All contained in a folder.

A role can look like:

```
roles/
    portainer/
        ├── defaults/
        │   └── main.yml           # Default variables
        ├── files/
        │   └── ...                # Static files to be copied (e.g., configs, scripts)
        ├── handlers/
        │   └── main.yml           # Handlers (e.g., service restart)
        ├── meta/
        │   └── main.yml           # Role metadata (e.g., dependencies)
        ├── tasks/
        │   └── main.yml           # Main list of tasks to execute
        ├── templates/
        │   └── ...                # Jinja2 templates
        ├── vars/
        │   └── main.yml           # Non-overridable variables
        └── README.md              # Optional: Document what this role does
    sshkey/
        ├── defaults/
        │   └── main.yml           # Default variables
        ├── files/
        │   └── ...                # Static files to be copied (e.g., configs, scripts)
        ├── handlers/
        │   └── main.yml           # Handlers (e.g., service restart)
        ├── meta/
        │   └── main.yml           # Role metadata (e.g., dependencies)
        ├── tasks/
        │   └── main.yml           # Main list of tasks to execute
        ├── templates/
        │   └── ...                # Jinja2 templates
        ├── vars/
        │   └── main.yml           # Non-overridable variables
        └── README.md              # Optional: Document what this role does

```

However, only the `defaults` and `tasks` subfolders and subsequent `main.yml` are required. Everything else is optional.

A role can be:

- Mounting a share
- Deploying a docker container with all its requirements like a database and mapped volumes

# Playbook

A playbook combines roles and task to create a final state in a host or group of hosts.

A playbook can be:

- Make sure all your hosts have sshkey auth, portainer, docker and an nfs share mounted.
- Deploy a suite of apps to a host or multiple hosts

## Example

```yml
---
- name: Deploy apps to apps-1 node
  hosts: apps
  become: true
  roles:
  - role: apps/kan
    vars:
      port: 7070
  - role: apps/memos
    vars:
      port: 7071
  - role: apps/vaultwarden
    vars:
      port: 7072
  - role: apps/erugo
    vars:
      port: 7073
  - role: apps/tianji
    vars:
      port: 7074
  - role: apps/stirling-pdf o
    vars:
      port: 7075
  - role: apps/dumbware-todo
    vars:
      port: 7076
      pin: 8989
  - role: apps/dumbware-drop
    vars:
      port: 7077
      pin: "8989"
```

# Setup

1. Clone this repo `git clone git@gitgud.foo:javif89/ansible-starter-kit.git [your project name]`
2. Run `setup.sh` to set up the vault password and become password
3. Set up your hosts in `hosts.yml`
4. Start making your roles and playbooks