Browse Source

update README and dev documentation

les 3 years ago
parent
commit
ee97b7acc1
2 changed files with 60 additions and 20 deletions
  1. 51 9
      README.md
  2. 9 11
      dev/README.md

+ 51 - 9
README.md

@@ -1,14 +1,56 @@
-## Silicone
-Un angolo ragionato per facilitare la messa in opera di servizi autogestiti di prossimità
+### Silicone
+Un angolo ragionato per facilitare la messa in opera di servizi autogestiti di prossimità.
 
 #### Come si usa
-Si imposta il proprio inventory (inventory.yml) e il proprio playbook (infra.yml) 
+Silicone è una raccolta di ruoli [ansible](https://docs.ansible.com/ansible/latest/index.html) fatti a modino e basati su debian stable, un tentativo di fissare alcune scelte tecniche ragionate e poterle ridiscutere in un posto comodo.  
+È molto utile anche per chi vuole tirare su un pad o gancio o altro senza dover necessariamente mettere le mani troppo nella marmellata dei file di configurazione di nginx, ricordarsi di aggiungere il cron per certbot, capire quale versione di nodejs bisogna usare per installare etherpad o trovare un sistema per fare i backup di tutto questo. Qui dentro abbiamo fatto delle scelte.
 
-  
-#### Password
-Per le password si usa pass, il path usato e' specificato nell'inventory 
+Per usarlo velocemente e conoscendo un minimo ansible, imposta il tuo inventory ([inventory.yml](./inventory.yml)) il tuo playbook ([infra.yml](./infra.yml)) e lancia `ansible-playbook`.
 
+#### Ansible in breve
+Ansible è uno strumento a cui si fornisce una lista di macchine da gestire (specificate dentro un file inventory) e si descrive quali ruoli assegnare ad ogni macchina. Ad esempio, diciamo che su ogni server/vm che gestiamo vogliamo installare 3 pacchetti (git, sudo e python3), ecco bisognerà scrivere nel playbook qualcosa come:
 
-#### Creare nuovi ruoli:
-Ci sono varie possibilità, si può usare docker o vagrant, sono dentro
-`dev/`, per docker c'e' un README.md
+```yaml
+# test_playbook.yml
+---
+- name: Generic servers operation
+  hosts: all
+  tasks:
+    - name: Install generic packages
+      apt:
+        pkg:
+          - sudo
+          - git
+          - python3
+```
+
+A questo punto lanciando `./ansible-playbook test_playbook.yml` tutti i server specificati nel file di inventory verranno contattati da ansible via ssh che provvederà ad eseguire le operazioni descritte nel task.
+
+Un ruolo ansible quindi non è nient'altro che una lista di operazioni.
+
+#### Password / Keys
+Per le informazioni sensibili (password del database, dell'account di admin, una chiave ssh) viene usato [passwordstore](https://www.passwordstore.org/), il path usato è specificato nell'inventory con la variabile `passwordstore_path`.
+
+#### Backup
+Per i backup usiamo [restic](https://restic.net/).
+ogni servizio che vuole supportare i backup deve controllare la variabile `with_backup` e specificare di quali database e directory fare i backup (`restic_databases` e `restic_folders`). Le configurazioni sono dentro l'inventory (che le cerca dentro il passwordstore).
+
+#### Monitoring
+
+#### Creare nuovi ruoli e testarne di vecchi:
+Ci sono varie possibilità, si può usare docker o vagrant, sono dentro `dev/`, per Docker c'e' un [README](./dev/README.md)
+
+
+### Servizi
+I servizi di alto livello dipendono dai ruoli base, ad esempio etherpad dipende tra gli altri da nodejs, postgresql e opzionalmente anche da nginx e restic. Le dipendenze di un ruolo sono specificate dentro `meta/main.yml` alla voce `dependencies` (vedi le dipendenze del ruolo etherpad come esempio [qui](./roles/stable/etherpad/meta/main.yml))
+
+<!-- 
+#### [Etherpad](https://etherpad.org/)
+> Un editor di testi collaborativo.  
+=> nginx, certbot, nodejs, restic, etherpad.  
+[Docs](./roles/stable/etherpad/README.md)
+
+#### [Gancio](https://gancio.org)
+> 
+
+#### [goploader](https://gpldr.in/) -->

+ 9 - 11
dev/README.md

@@ -1,15 +1,13 @@
-# only once
-docker network create --subnet=172.172.0.0/16 silicone
-docker build -t silicone:base .
+### Create a subnet for our test and build the image (debian stable-slim with openssh server and python3 -> ansible dependencies)
+`docker network create --subnet=172.172.0.0/16 silicone`  
+`docker build -t silicone:base .`
 
-# for each service to test
-# create a container with static ip
-docker run --name etherpad  -d --net silicone --ip 172.172.0.2 -it silicone:base 
+### Create a container with static ip for each service to test (e.g. __etherpad__ here)
+`docker run --name etherpad -d --net silicone --ip 172.172.0.2 -it silicone:base`
 
-# copy your ssh key
-docker cp ~/.ssh/id_rsa.pub etherpad:/root/.ssh/authorized_keys
-docker exec -it etherpad chown root.root /root/.ssh/authorized_keys
+### Copy your ssh key
+`docker cp ~/.ssh/id_rsa.pub etherpad:/root/.ssh/authorized_keys`  
+`docker exec -it etherpad chown root.root /root/.ssh/authorized_keys`
 
 
-# then you can go with ansible using 172.172.0.2 as your host inside
-  inventory
+### Then you can go with ansible using 172.172.0.2 as your host inside  inventory.