README.rst 7.26 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51
.. _readme:

discourse
=========

Setup and configure `discourse`_ container deployed with `discourse_docker`_ repository

.. contents:: **Table of Contents**

General notes
-------------

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.

More information `SALT AS A CLOUD CONTROLLER
<https://docs.saltstack.com/en/latest/topics/tutorials/cloud_controller.html>`_.

Contributing to this repo
-------------------------

**Commit message formatting is significant!!**

Please see `How to contribute <https://github.com/saltstack-formulas/.github/blob/master/CONTRIBUTING.rst>`_ for more details.

Available states
----------------

.. contents::
   :local:

``discourse``
^^^^^^^^^^^^^

*Meta-state (This is a state that includes other states)*.

- install dependencies
- configure deployment of ``discourse`` container
- deploy the ``discourse`` application container

``discourse.config``
^^^^^^^^^^^^^^^^^^^^

52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73
*Meta-state (This is a state that includes other states)*.

This state will configure the deployment of ``discourse``.


``discourse.config.tls``
^^^^^^^^^^^^^^^^^^^^^^^^

This state will configure a personal TLS certificate and key instead
of using Let's Encrypt if the ``discourse:tls:enabled`` is ``true``
and ``discourse:letsencrypt:enabled`` is false.

It requires two private pillar values:

- ``discourse.tls.cert``
- ``discourse.tls.key``

It hooks as a dependency of ``discourse.config.file``.

``discourse.config.file``
^^^^^^^^^^^^^^^^^^^^^^^^^

74 75 76
This state will configure the deployement by generating the
``containers/app.yml`` file.

77
It depends on ``discourse.sources.hack``.
78 79 80 81 82 83 84

``discourse.service``
^^^^^^^^^^^^^^^^^^^^^

*Meta-state (This is a state that includes other states)*.

This state will rebuild the ``discourse`` application container if the
85
``discourse.config`` has changes.
86

87 88 89 90 91 92 93 94
``discourse.setup``
^^^^^^^^^^^^^^^^^^^

*Meta-state (This is a state that includes other states)*.

This state will initialize the ``discourse`` application with sane
defaults.

95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121
``discourse.setup.settings``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*Meta-state (This is a state that includes other states)*.

This state will load series of settings.

``discourse.setup.settings.global``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This state will configure some ``discourse`` `site settings`_ with
values from salt configuration.

It depends on ``discourse.service.running``.

``discourse.setup.settings.oauth2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This state will configure the ``discourse`` `OAuth2 plugin settings`_ with
values from salt configuration.

Note that the values from salt configuration are named like the
`OAuth2 pluging settings`_ except that the ``oauth2_`` prefix is
removed. See `pillar.example`_.

It depends on ``discourse.service.running``.

122 123 124 125 126 127 128 129 130 131
``discourse.setup.users``
^^^^^^^^^^^^^^^^^^^^^^^^^

This state will manage a set of users:

- create them if they don't exists
- send password reset email by default or set their password if defined
- set them active or not
- set them ``admin`` or not.

132 133 134 135 136 137 138 139 140 141 142 143 144 145
``discourse.setup.themes``
^^^^^^^^^^^^^^^^^^^^^^^^^^

*Meta-state (This is a state that includes other states)*.

This state will install a list of themes.

``discourse.setup.themes.install``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This state will install the themes.

It depends on ``discourse.service.running``.

146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224
``discourse.clean``
^^^^^^^^^^^^^^^^^^^

*Meta-state (This is a state that includes other states)*.

- stop ``discourse`` container

``discourse.config.clean``
^^^^^^^^^^^^^^^^^^^^^^^^^^

This state will remove the generated ``containers/app.yml`` deployment
configuration file.

It depends on ``discourse.service.dead``.

``discourse.service.clean``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

This state will stop the ``discourse`` application container.


Launcher states
^^^^^^^^^^^^^^^

The following states wrap the ``discourse`` launcher commands which
avoid to use either:

- a direct SSH connection to execute the command locally
- ``salt-ssh minion cmd.run './launcher <command> app' cwd='/srv/discourse'``

``disourse.launcher.rebuild``
`````````````````````````````

Execute the ``./laucher rebuild app`` command in the directory defined
by the ``discourse.directory`` configuration.

``disourse.launcher.bootsrap``
``````````````````````````````

Execute the ``./laucher bootstrap app`` command in the directory
defined by the ``discourse.directory`` configuration.

``disourse.launcher.start``
```````````````````````````

Execute the ``./laucher start app`` command in the directory defined
by the ``discourse.directory`` configuration.

``disourse.launcher.stop``
``````````````````````````

Execute the ``./laucher stop app`` command in the directory defined by
the ``discourse.directory`` configuration.

``disourse.launcher.restart``
`````````````````````````````

Execute the ``./laucher restart app`` command in the directory defined
by the ``discourse.directory`` configuration.

``disourse.launcher.cleanup``
`````````````````````````````

Execute the ``./laucher cleanup app`` command in the directory defined
by the ``discourse.directory`` configuration.

``disourse.launcher.destroy``
`````````````````````````````

Execute the ``./laucher destroy app`` command in the directory defined
by the ``discourse.directory`` configuration.


Utility states
^^^^^^^^^^^^^^

The following states are used by the previous states to setup the
environment.

225 226
``discourse.sources``
`````````````````````
227 228 229 230 231

*Meta-state (This is a state that includes other states)*.

- install the git package
- clone the latest `discourse_docker`_ repository
232
- install new rake tasks
233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280

``discourse.docker``
````````````````````

*Meta-state (This is a state that includes other states)*.

Install docker package and start the service.

``discourse.docker.clean``
``````````````````````````

*Meta-state (This is a state that includes other states)*.

Stop the docker service and remove the packages.

``discourse.docker.package``
````````````````````````````

This state install the docker package only.

``discourse.docker.package.clean``
``````````````````````````````````

This state remove the docker package only and depends on
``discourse.docker.service.clean``.

``discourse.docker.service``
````````````````````````````

Starts the docker service.

``discourse.docker.service.clean``
``````````````````````````````````

Disable and stop the docker service.

``discourse.netcat``
````````````````````

Install the ``netcat`` package required by the deployment of ``discourse``.

``discourse.net-tools``
```````````````````````

Install the ``net-tools`` package required by the deployment of ``discourse``.

.. _discourse: https://www.discourse.org
.. _discourse_docker: https://github.com/discourse/discourse_docker