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 that is empty. It has dummy content to help with a quick
  18 start on a new formula and it serves as a style guide.
  19
  20 .. contents:: **Table of Contents**
  21
  22 General notes
  23 -------------
  24
  25 See the full `SaltStack Formulas installation and usage instructions
  26 <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html>`_.
  27
  28 If you are interested in writing or contributing to formulas, please pay attention to the `Writing Formula Section
  29 <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#writing-formulas>`_.
  30
  31 If you want to use this formula, please pay attention to the ``FORMULA`` file and/or ``git tag``,
  32 which contains the currently released version. This formula is versioned according to `Semantic Versioning <http://semver.org/>`_.
  33
  34 See `Formula Versioning Section <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#versioning>`_ for more details.
  35
  36 If you need (non-default) configuration, please pay attention to the ``pillar.example`` file and/or `Special notes`_ section.
  37
  38 Contributing to this repo
  39 -------------------------
  40
  41 **Commit message formatting is significant!!**
  42
  43 Please see `How to contribute <https://github.com/saltstack-formulas/.github/blob/master/CONTRIBUTING.rst>`_ for more details.
  44
  45 Special notes
  46 -------------
  47
  48 None
  49
  50 Available states
  51 ----------------
  52
  53 .. contents::
  54    :local:
  55
  56 ``arvados``
  57 ^^^^^^^^^^^^
  58
  59 *Meta-state (This is a state that includes other states)*.
  60
  61 This installs the arvados package,
  62 manages the arvados configuration file and then
  63 starts the associated arvados service.
  64
  65 ``arvados.package``
  66 ^^^^^^^^^^^^^^^^^^^^
  67
  68 This state will install the arvados package only.
  69
  70 ``arvados.config``
  71 ^^^^^^^^^^^^^^^^^^^
  72
  73 This state will configure the arvados service and has a dependency on ``arvados.install``
  74 via include list.
  75
  76 ``arvados.service``
  77 ^^^^^^^^^^^^^^^^^^^^
  78
  79 This state will start the arvados service and has a dependency on ``arvados.config``
  80 via include list.
  81
  82 ``arvados.clean``
  83 ^^^^^^^^^^^^^^^^^^
  84
  85 *Meta-state (This is a state that includes other states)*.
  86
  87 this state will undo everything performed in the ``arvados`` meta-state in reverse order, i.e.
  88 stops the service,
  89 removes the configuration file and
  90 then uninstalls the package.
  91
  92 ``arvados.service.clean``
  93 ^^^^^^^^^^^^^^^^^^^^^^^^^^
  94
  95 This state will stop the arvados service and disable it at boot time.
  96
  97 ``arvados.config.clean``
  98 ^^^^^^^^^^^^^^^^^^^^^^^^^
  99
 100 This state will remove the configuration of the arvados service and has a
 101 dependency on ``arvados.service.clean`` via include list.
 102
 103 ``arvados.package.clean``
 104 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 105
 106 This state will remove the arvados package and has a depency on
 107 ``arvados.config.clean`` via include list.
 108
 109 ``arvados.subcomponent``
 110 ^^^^^^^^^^^^^^^^^^^^^^^^^
 111
 112 *Meta-state (This is a state that includes other states)*.
 113
 114 This state installs a subcomponent configuration file before
 115 configuring and starting the arvados service.
 116
 117 ``arvados.subcomponent.config``
 118 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 119
 120 This state will configure the arvados subcomponent and has a
 121 dependency on ``arvados.config`` via include list.
 122
 123 ``arvados.subcomponent.config.clean``
 124 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 125
 126 This state will remove the configuration of the arvados subcomponent
 127 and reload the arvados service by a dependency on
 128 ``arvados.service.running`` via include list and ``watch_in``
 129 requisite.
 130
 131 Testing
 132 -------
 133
 134 Linux testing is done with ``kitchen-salt``.
 135
 136 Requirements
 137 ^^^^^^^^^^^^
 138
 139 * Ruby
 140 * Docker
 141
 142 .. code-block:: bash
 143
 144    $ gem install bundler
 145    $ bundle install
 146    $ bin/kitchen test [platform]
 147
 148 Where ``[platform]`` is the platform name defined in ``kitchen.yml``,
 149 e.g. ``debian-9-2019-2-py3``.
 150
 151 ``bin/kitchen converge``
 152 ^^^^^^^^^^^^^^^^^^^^^^^^
 153
 154 Creates the docker instance and runs the ``arvados`` main state, ready for testing.
 155
 156 ``bin/kitchen verify``
 157 ^^^^^^^^^^^^^^^^^^^^^^
 158
 159 Runs the ``inspec`` tests on the actual instance.
 160
 161 ``bin/kitchen destroy``
 162 ^^^^^^^^^^^^^^^^^^^^^^^
 163
 164 Removes the docker instance.
 165
 166 ``bin/kitchen test``
 167 ^^^^^^^^^^^^^^^^^^^^
 168
 169 Runs all of the stages above in one go: i.e. ``destroy`` + ``converge`` + ``verify`` + ``destroy``.
 170
 171 ``bin/kitchen login``
 172 ^^^^^^^^^^^^^^^^^^^^^
 173
 174 Gives you SSH access to the instance for manual testing.
 175