Expand the README with instructions for evolinux.yml

README.md

@@ -1,5 +1,49 @@
 # Ansible-public
 
+This repository contains some stuff related to Ansible (excpet roles, that are in an "ansible-roles repository").
+
+One the the main part is our Evolinux playbook, that we use to customize a Linux Debian server.
+It also contains our conventions for Ansible.
+
+## Evolinux
+
+To set up a server according to "The Evolix Way", you have to install a Debian Linux stable (currently Jessie, v8.7).
+
+### Install Debian
+
+With the "netinst" CD image, here are some key settings :
+
+* Language : English
+* Location : Other -> Europe -> France
+* Locales : en_US.UTF-8 UTF-8
+* Keyboard : French
+
+We recommend to install only the minimum packages. At the "tasksel" step, choose only the SSH server item.
+
+### evolinux.yml playbook
+
+When the server is installed and rebooted, with a functioning SSH access, make sure that those packages are installed, for Ansible to be able to run.
+
+```
+# apt install sudo dbus apt-python
+```
+
+You'll need a privileged user (preferably not root, but a regular user with full sudo permissions).
+You can customize the playbook or add command line options to specify with user to use for the ssh connection and which privilege escalation to use (we like to use "sudo").
+
+Then you'll have to populate the `vars/main.yml` file with values required by the "admin-users" and "evolinux-base" roles. You should refer to their respective documentation.
+
+You'll also need to confighure Ansible to include the location of the "ansible-rols" path in the `roles_path` value. We recommend using `$HOME/.ansible.cfg` with this :
+
+```
+[defaults]
+roles_path = /path/to/ansible-roles
+```
+
+You may want to configure the inventory to your needs. We usually put it in `inventory/hosts` along the conventionnal files for host and group vars.
+
+With all that, you can run the evolinux.yml playbook and have your Debian customized :
+
 ```
 $ ansible-playbook playbooks/evolinux.yml -i inventory/hosts -K
 ```

playbooks/evolinux.yml

@@ -1,30 +1,32 @@
 - hosts: ansible-test
   gather_facts: yes
   become: yes
-  vars:
-    roles: ~/GIT/ansible-roles
-    tasks: ~/GIT/ansible-public/tasks
-    minifirewall_trusted_ips: ["192.168.2.1"]
+
+  vars_files:
+  - vars/main.yml
 
   roles:
-  - "{{ roles }}/etc-git"
-  - "{{ roles }}/evolinux-base"
-  - "{{ roles }}/admin-users"
-  - "{{ roles }}/munin"
-  - "{{ roles }}/minifirewall"
-  - "{{ roles }}/squid"
-  - "{{ roles }}/fail2ban"
-  - "{{ roles }}/nagios-nrpe"
-  - "{{ roles }}/listupgrade"
-  - "{{ roles }}/evomaintenance"
+  - etc-git
+  - evolinux-base
+  - admin-users
+  - munin
+  - minifirewall
+  - squid
+  - fail2ban
+  - nagios-nrpe
+  - listupgrade
+  - evomaintenance
 # Consider enabling the ansible-managed role
-#  - "{{ roles }}/ansible-managed"
-
+#  - ansible-managed
 
   post_tasks:
-  - include: "{{ tasks }}/commit_etc_git.yml"
+  - include_role:
+      name: etc-git
+      tasks_from: commit.yml
     vars:
-      commit_message: "Ansible run evolinux.yml"
-  - include: "{{ tasks }}/run_evocheck.yml"
+      commit_message: "Ansible run evolinux playbook"
+  - include_role:
+      name: evocheck
+      tasks_from: exec.yml
 
 # vim:ft=ansible

vars/main.yml

@@ -0,0 +1,18 @@
+---
+## Add your admin users information
+# admin_users:
+#   foo:
+#     name: foo
+#     uid: 1001
+#     fullname: 'Mr Foo'
+#     password_hash: 'sdfgsdfgsdfgsdfg'
+#     ssh_key: 'ssh-rsa AZERTYXYZ'
+#   bar:
+#     name: bar
+#     uid: 1002
+#     fullname: 'Mr Bar'
+#     password_hash: 'gsdfgsdfgsdfgsdf'
+#     ssh_key: 'ssh-rsa QWERTYUIOP'
+#
+## Add your trusted IP addresses for the firewall
+# minifirewall_privilegied_ips: []