docs/README.rst

   1 .. _readme:
   2
   3 arvados-formula
   4 ================
   5
   6 |img_travis| |img_sr|
   7
   8 .. |img_travis| image:: https://travis-ci.com/saltstack-formulas/arvados-formula.svg?branch=master
   9    :alt: Travis CI Build Status
  10    :scale: 100%
  11    :target: https://travis-ci.com/saltstack-formulas/arvados-formula
  12 .. |img_sr| image:: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
  13    :alt: Semantic Release
  14    :scale: 100%
  15    :target: https://github.com/semantic-release/semantic-release
  16
  17 A SaltStack formula to install and configure an `Arvados cluster <https://arvados.org>`_.
  18
  19 .. contents:: **Table of Contents**
  20
  21 General notes
  22 -------------
  23
  24 See the full `SaltStack Formulas installation and usage instructions
  25 <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html>`_.
  26
  27 If you are interested in writing or contributing to formulas, please pay attention to the `Writing Formula Section
  28 <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#writing-formulas>`_.
  29
  30 If you want to use this formula, please pay attention to the ``FORMULA`` file and/or ``git tag``,
  31 which contains the currently released version. This formula is versioned according to `Semantic Versioning <http://semver.org/>`_.
  32
  33 See `Formula Versioning Section <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#versioning>`_ for more details.
  34
  35 If you need (non-default) configuration, please pay attention to the ``pillar.example`` file and/or `Special notes`_ section.
  36
  37 Contributing to this repo
  38 -------------------------
  39
  40 **Commit message formatting is significant!!**
  41
  42 Please see `How to contribute <https://github.com/saltstack-formulas/.github/blob/master/CONTRIBUTING.rst>`_ for more details.
  43
  44 Special notes
  45 -------------
  46
  47 Arvados **requires** a Postgres database for its API server and SSL for communications. If you don't satisfy these two requirements, things
  48 won't work. It also uses an Nginx server as a redirector but probably almost any other webserver/redirector can be used instead.
  49
  50 We suggest you use the `postgres-formula <https://github.com/saltstack-formulas/postgres-formula/>`_,
  51 the `nginx-formula <https://github.com/saltstack-formulas/nginx-formula/>`_ and the
  52 `letsencrypt-formula <https://github.com/saltstack-formulas/letsencrypt-formula/>`_ to install satisfy these dependencies.
  53 In the FIXME directory there are some example pillar YAMLs to set up these packages as Arvados needs it.
  54
  55 Also, please note that the individual subcomponents `clean` states **won't remove the config**: as the config is common to all the suite
  56 components and they can be installed in the same host, removing it with a subcomponent might break others.
  57
  58 If you want to remove the config in a host where you're removing a subcomponent, use the `arvados.config.clean` state after the
  59 `arvados.<subcomponent>.clean` state.
  60
  61 The `arvados.clean` state will remove everything, config included, and can be used in any host to remove all of arvados files.
  62
  63 Available states
  64 ----------------
  65
  66 .. contents::
  67    :local:
  68
  69 ``arvados``
  70 ^^^^^^^^^^^^
  71
  72 *Meta-state (This is a state that includes other states)*.
  73
  74 This installs the WHOLE arvados suite in a single host,
  75 manages the arvados configuration file and then
  76 starts the associated arvados services.
  77
  78 ``arvados.clean``
  79 ^^^^^^^^^^^^^^^^^^
  80
  81 *Meta-state (This is a state that includes other states)*.
  82
  83 this state will undo everything performed in the ``arvados`` meta-state in reverse order, i.e.
  84 stops the services, removes the configuration file and then uninstalls the packages.
  85
  86 ``arvados.config``
  87 ^^^^^^^^^^^^^^^^^^^
  88
  89 This state will configure the arvados cluster. As all the arvados components use the same config
  90 file, any of the following components will include this state and you will rarely need to call it
  91 independently. You can still do, as to get a parsed config file to use somewhere else.
  92
  93 ``arvados.repo``
  94 ^^^^^^^^^^^^^^^^
  95
  96 This state will configure the arvados repository.
  97
  98 ``arvados.repo.clean``
  99 ^^^^^^^^^^^^^^^^^^^^^^^
 100
 101 This state will remove the arvados repository configuration.
 102
 103 ``arvados.shell``
 104 ^^^^^^^^^^^^^^^^^
 105
 106 *Meta-state (This is a state that includes other states)*.
 107
 108 This state installs an `arvados shell node <https://doc.arvados.org/master/install/install-shell-server.html>`_.
 109
 110 ``arvados.shell.clean``
 111 ^^^^^^^^^^^^^^^^^^^^^^^
 112
 113 *Meta-state (This is a state that includes other states)*.
 114
 115 this state will undo everything performed in the ``arvados.shell`` meta-state in reverse order, i.e.
 116 uninstalls the packages and gems.
 117
 118 ``arvados.shell.package``
 119 ^^^^^^^^^^^^^^^^^^^^^^^^^
 120
 121 This state will install the arvados shell packages and gems only.
 122
 123 ``arvados.shell.package.clean``
 124 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 125
 126 This state will remove the packages and gems of the arvados shell node.
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144 ``arvados.service``
 145 ^^^^^^^^^^^^^^^^^^^^
 146
 147 This state will start the arvados service and has a dependency on ``arvados.config``
 148 via include list.
 149
 150 ``arvados.service.clean``
 151 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 152
 153 This state will stop the arvados service and disable it at boot time.
 154
 155 ``arvados.config.clean``
 156 ^^^^^^^^^^^^^^^^^^^^^^^^^
 157
 158 This state will remove the configuration of the arvados service and has a
 159 dependency on ``arvados.service.clean`` via include list.
 160
 161 ``arvados.package.clean``
 162 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 163
 164 This state will remove the arvados package and has a depency on
 165 ``arvados.config.clean`` via include list.
 166
 167 Testing
 168 -------
 169
 170 Linux testing is done with ``kitchen-salt``.
 171
 172 Requirements
 173 ^^^^^^^^^^^^
 174
 175 * Ruby
 176 * Docker
 177
 178 .. code-block:: bash
 179
 180    $ gem install bundler
 181    $ bundle install
 182    $ bin/kitchen test [platform]
 183
 184 Where ``[platform]`` is the platform name defined in ``kitchen.yml``,
 185 e.g. ``debian-10-3000-1-py3``.
 186
 187 ``bin/kitchen converge``
 188 ^^^^^^^^^^^^^^^^^^^^^^^^
 189
 190 Creates the docker instance and runs the ``arvados`` main state, ready for testing.
 191
 192 ``bin/kitchen verify``
 193 ^^^^^^^^^^^^^^^^^^^^^^
 194
 195 Runs the ``inspec`` tests on the actual instance.
 196
 197 ``bin/kitchen destroy``
 198 ^^^^^^^^^^^^^^^^^^^^^^^
 199
 200 Removes the docker instance.
 201
 202 ``bin/kitchen test``
 203 ^^^^^^^^^^^^^^^^^^^^
 204
 205 Runs all of the stages above in one go: i.e. ``destroy`` + ``converge`` + ``verify`` + ``destroy``.
 206
 207 ``bin/kitchen login``
 208 ^^^^^^^^^^^^^^^^^^^^^
 209
 210 Gives you SSH access to the instance for manual testing.
 211