diff --git a/README.md b/README.md index 7f6c6df..9ca3437 100644 --- a/README.md +++ b/README.md @@ -1,150 +1,5 @@ -# Ansible Starter Kit +# Only for people that hate wasting time -Easy way for my homies to start up an ansible project for their homelab or local machine. +This is how I deploy all my self-hosted infrastructure. Declare everything, commit everything, know nothing. -# 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