.. _readme:
+..
+ # Copyright (C) The Arvados Authors. All rights reserved.
+ #
+ # SPDX-License-Identifier: Apache-2.0
+
arvados-formula
================
-|img_travis| |img_sr|
-
-.. |img_travis| image:: https://travis-ci.com/saltstack-formulas/arvados-formula.svg?branch=master
- :alt: Travis CI Build Status
- :scale: 100%
- :target: https://travis-ci.com/saltstack-formulas/arvados-formula
-.. |img_sr| image:: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
- :alt: Semantic Release
- :scale: 100%
- :target: https://github.com/semantic-release/semantic-release
-
A SaltStack formula to install and configure an `Arvados cluster <https://arvados.org>`_.
.. contents:: **Table of Contents**
See the full `SaltStack Formulas installation and usage instructions
<https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html>`_.
-If you are interested in writing or contributing to formulas, please pay attention to the `Writing Formula Section
-<https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#writing-formulas>`_.
-
-If you want to use this formula, please pay attention to the ``FORMULA`` file and/or ``git tag``,
-which contains the currently released version. This formula is versioned according to `Semantic Versioning <http://semver.org/>`_.
-
-See `Formula Versioning Section <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#versioning>`_ for more details.
-
If you need (non-default) configuration, please pay attention to the ``pillar.example`` file and/or `Special notes`_ section.
Contributing to this repo
Please see `How to contribute <https://github.com/saltstack-formulas/.github/blob/master/CONTRIBUTING.rst>`_ for more details.
+Special notes
+-------------
+
+In the `Arvados repository <https://github.com/arvados/arvados/>`_ you can find `a provision script <https://github.com/arvados/arvados/tree/master/tools/salt-install>`_
+to deploy a single-node, all-in-one Arvados cluster (The script uses this formula to get a cluster up and running in Saltstack's master-less mode).
+
+The `single-node` install does not include SLURM: it is intended for an `all-in-one-host` installation,
+so it uses `crunch-dispatch-local` to run containers in the same instance.
+
+The provision script can be run anywhere, so you can run it in an AWS instance and you'll get a `single-node` Arvados cluster there.
+
+The Arvados formula allows you to `install any dispatcher available <https://github.com/saltstack-formulas/arvados-formula/blob/master/pillar.example#L182-L191>`_,
+provided you configure the pillars the way you need them.
+
+Arvados currently has three dispatchers:
+
+* **crunch-dispatch-local** (for single node installations and testing purposes, not suitable for production),
+* **arvados-dispatch-cloud** (for dynamic compute on AWS or Azure) and
+* **crunch-dispatch-slurm** (for SLURM integration).
+
Requisites
----------
the `nginx-formula <https://github.com/saltstack-formulas/nginx-formula/>`_ and the
`letsencrypt-formula <https://github.com/saltstack-formulas/letsencrypt-formula/>`_ to satisfy these dependencies.
In the **test/salt/pillar/examples/** directory there are example pillar YAMLs to set up these packages, using the mentioned formulas
-as Arvados needs them.
+as Arvados needs them.a
+
+In the **test/salt/states/examples/** directory there are some example helper states to set up a few requirements for single-node
+(all-in-one) Arvados host.
Usage
-----