doc(readme): how to use the formula

Only with `salt-ssh` for now.

README.rst

+.. _readme:
+
+Setup discourse with `SaltStack`_
+=================================
+
+Setup and configure `discourse`_ container deployed with `discourse_docker`_ repository.
+
+.. contents:: **Table of Contents**
+
+.. _deployment-using-salt-ssh:
+
+Deployment using `salt-ssh`_
+----------------------------
+
+If your distribution does not provide a recent enough `salt-ssh`_ you can configure an `additional repository`_.
+
+First, you need to `configure salt-ssh <#configuring-salt-ssh>`_.
+
+To work around a `bug in salt-ssh that prevent using gitfs`_, we need to manually clone the formula.
+
+.. code-block:: bash
+
+    git clone https://gitlab.mim-libre.fr/la-crise/discourse-formula.git ``~/.salt/srv/formulas/``
+
+Then, we make the formula available to minions by linking it's directory in the `salt fileserver`_
+
+.. code-block:: bash
+
+    ln -s ~/.salt/srv/formula/discourse-formula/discourse ~/.salt/srv/salt/discourse
+
+.. code-block:: bash
+
+    salt-ssh forum.example.net state.apply discourse
+
+
+You can can execute ``laucher`` command directly with `salt-ssh`_ or apply ``states`` one by one, for more information on which ``states`` are available you should read the `formula documentation`_.
+
+
+Configuring ``salt-ssh``
+------------------------
+
+Then, to be able to `use salt-ssh as non root user`_, you need to configure several files.
+
+Here is the configuration `based on mine <https://gist.github.com/baby-gnu/8a198629161fe8fc60bd2b33a8321012>`_.
+
+
+``Saltfile`` to tell `salt-ssh`_ where is the configuration directory
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Create the file ``~/.salt/Saltfile`` with the following content
+
+.. code-block:: yaml
+
+    # -*- yaml -*-
+
+    # Expanding ~ is working here
+    salt-ssh:
+      config_dir: ~/.salt
+
+
+``master`` configuration file
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This file will set different parameters to tell `salt-ssh`_:
+
+- to not create files outside our home directory
+- to look for `states`_ and `pillars`_ under our home directory ``~/.salt/srv/``
+
+.. code-block:: yaml
+
+    # -*- mode: yaml; coding: utf-8 -*-
+
+    ####
+    #### Global parameters
+    ####
+
+    # Unfortunately, salt does not support ~ expension
+    # We need to use absolute path for `root_dir`
+    root_dir: /home/me/.salt
+    pki_dir: pki
+    cachedir: cache
+    sock_dir: run
+    pidfile: pids
+
+    log_file: logs/master.log
+    key_logfile: logs/key.log
+
+    # Global level logged in file
+    log_level_logfile: debug
+
+    ##
+    ## file server
+    ##
+    fileserver_backend:
+      - roots
+
+    # Unfortunately, salt does not support ~ expension
+    # We need to use absolute path for `file_roots` and `pillar_roots`
+    file_roots:
+      base:
+        - /home/me/.salt/srv/salt/
+
+    pillar_roots:
+      base:
+        - /home/me/.salt/srv/pillar/
+
+    ####
+    #### Salt-SSH specific configuration
+    ####
+    ssh_log_file: logs/ssh.log
+    ssh_use_home_key: True
+    ssh_timeout: 5
+
+
+`roster`_ file declares the list of minions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This file is associate several parameters to a host:
+
+- a ``name`` to use as `target`_
+- a ``user``
+- use ``sudo`` if the ``user`` is not ``root``
+
+.. code-block:: yaml
+
+    # -*- yaml -*-
+    
+        minion1:
+          host: minion1.example.net
+          user: debian
+          sudo: True
+
+
+.. _SaltStack: https://www.saltstack.com
+.. _salt-ssh: https://docs.saltstack.com/en/latest/topics/ssh
+.. _additional repository: https://repo.saltstack.com/
+.. _bug in salt-ssh that prevent using gitfs: https://github.com/saltstack/salt/issues/23576
+.. _salt fileserver: https://docs.saltstack.com/en/latest/ref/configuration/master.html#std:conf_master-fileserver_backend
+
+.. _use salt-ssh as non root user:
+.. _use-salt-ssh-non-root: https://docs.saltstack.com/en/latest/topics/ssh/#running-salt-ssh-as-non-root-user
+
+.. _formula documentation: docs/README.rst
+.. _states: https://docs.saltstack.com/en/latest/topics/tutorials/starting_states.html
+.. _pillars: https://docs.saltstack.com/en/latest/topics/tutorials/pillar.html
+.. _roster: https://docs.saltstack.com/en/latest/topics/ssh/index.html#salt-ssh-roster
+.. _target: https://docs.saltstack.com/en/latest/topics/ssh/index.html#targeting-with-salt-ssh
+.. _discourse: https://www.discourse.org
+.. _discourse_docker: https://github.com/discourse/discourse_docker