Skip to content

Commit

Permalink
docs(readme): move to docs/ directory and modify accordingly
Browse files Browse the repository at this point in the history
  • Loading branch information
myii committed Oct 17, 2019
1 parent 1bad58d commit c17382b
Showing 1 changed file with 116 additions and 41 deletions.
157 changes: 116 additions & 41 deletions README.rst → docs/README.rst
Original file line number Diff line number Diff line change
@@ -1,176 +1,206 @@
======
.. _readme:

apache
======

|img_travis| |img_sr|

.. |img_travis| image:: https://travis-ci.com/saltstack-formulas/apache-formula.svg?branch=master
:alt: Travis CI Build Status
:scale: 100%
:target: https://travis-ci.com/saltstack-formulas/apache-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

Formulas to set up and configure the Apache HTTP server.

.. note::
.. 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 the full `Salt Formulas installation and usage instructions
<http://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html>`_.
See `Formula Versioning Section <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#versioning>`_ for more details.

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

**Commit message formatting is significant!!**

Please see :ref:`How to contribute <CONTRIBUTING>` for more details.

Available states
================
----------------

.. contents::
:local:
:local:

``apache``
----------
^^^^^^^^^^

Installs the Apache package and starts the service.

``apache.config``
-----------------
^^^^^^^^^^^^^^^^^

Configures apache based on os_family

``apache.certificates``
-----------------
^^^^^^^^^^^^^^^^^^^^^^^

Deploy SSL certificates from pillars

``apache.mod_mpm``
------------------
^^^^^^^^^^^^^^^^^^

Configures the apache mpm modules on Debian ``mpm_prefork``, ``mpm_worker`` or ``mpm_event`` (Debian Only)

``apache.modules``
------------------
^^^^^^^^^^^^^^^^^^

Enables and disables Apache modules.

``apache.mod_rewrite``
----------------------
^^^^^^^^^^^^^^^^^^^^^^

Enabled the Apache module mod_rewrite (Debian and FreeBSD only)

``apache.mod_proxy``
-------------------
^^^^^^^^^^^^^^^^^^^^

Enables the Apache module mod_proxy. (Debian and FreeBSD only)

``apache.mod_proxy_http``
-------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^

Enables the Apache module mod_proxy_http and requires the Apache module mod_proxy to be enabled. (Debian Only)

``apache.mod_proxy_fcgi``
-------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^

Enables the Apache module mod_proxy_fcgi and requires the Apache module mod_proxy to be enabled. (Debian Only)

``apache.mod_wsgi``
-------------------
^^^^^^^^^^^^^^^^^^^

Installs the mod_wsgi package and enables the Apache module.

``apache.mod_actions``
----------------------
^^^^^^^^^^^^^^^^^^^^^^

Enables the Apache module mod_actions. (Debian Only)

``apache.mod_headers``
----------------------
^^^^^^^^^^^^^^^^^^^^^^

Enables the Apache module mod_headers. (Debian Only)

``apache.mod_pagespeed``
------------------------
^^^^^^^^^^^^^^^^^^^^^^^^

Installs and Enables the mod_pagespeed module. (Debian and RedHat Only)

``apache.mod_perl2``
-------------------
^^^^^^^^^^^^^^^^^^^^

Installs and enables the mod_perl2 module (Debian and FreeBSD only)

``apache.mod_geoip``
-------------------
^^^^^^^^^^^^^^^^^^^^

Installs and enables the mod_geoIP (RedHat only)

``apache.mod_php5``
-------------------
^^^^^^^^^^^^^^^^^^^

Installs and enables the mod_php5 module

``apache.mod_cgi``
---------------------
^^^^^^^^^^^^^^^^^^

Enables mod_cgi. (FreeBSD only)

``apache.mod_fcgid``
--------------------
^^^^^^^^^^^^^^^^^^^^

Installs and enables the mod_fcgid module (Debian only)

``apache.mod_fastcgi``
--------------------
^^^^^^^^^^^^^^^^^^^^^^

Installs and enables the mod_fastcgi module

``apache.mod_dav_svn``
--------------------
^^^^^^^^^^^^^^^^^^^^^^

Installs and enables the mod_dav_svn module (Debian only)

``apache.mod_security``
----------------------
^^^^^^^^^^^^^^^^^^^^^^^

Installs an enables the `Apache mod_security2 WAF`<http://modsecurity.org/>`_
using data from Pillar. (Debian and RedHat Only)

Allows you to install the basic Core Rules (CRS) and some basic configuration for mod_security2

``apache.mod_security.rules``
-----------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This state can create symlinks based on basic Core Rules package. (Debian only)
Or it can distribute a mod_security rule file and place it /etc/modsecurity/

``apache.mod_socache_shmcb``
---------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Enables mod_socache_shmcb. (FreeBSD only)

``apache.mod_ssl``
----------------------
^^^^^^^^^^^^^^^^^^

Installs and enables the mod_ssl module (Debian, RedHat and FreeBSD only)

``apache.mod_suexec``
---------------------
^^^^^^^^^^^^^^^^^^^^^

Enables mod_suexec. (FreeBSD only)

``apache.mod_vhost_alias``
----------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^

Enables the Apache module vhost_alias (Debian Only)

``apache.mod_remoteip``
----------------------
^^^^^^^^^^^^^^^^^^^^^^^

Enables and configures the Apache module mod_remoteip using data from Pillar. (Debian Only)

``apache.mod_xsendfile``
----------------------
^^^^^^^^^^^^^^^^^^^^^^^^

Installs and enables mod_xsendfile module. (Debian Only)

``apache.own_default_vhost``
--------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Replace default vhost with own version. By default, it's 503 code. (Debian Only)

``apache.no_default_vhost``
--------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Remove the default vhost. (Debian Only)

``apache.vhosts.standard``
--------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^

Configures Apache name-based virtual hosts and creates virtual host directories using data from Pillar.

Expand All @@ -194,22 +224,22 @@ of interfaces to bind to. For example, to bind both IPv4 and IPv6:
interface: '1.2.3.4 [2001:abc:def:100::3]'
``apache.manage_security``
--------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^

Configures Apache's security.conf options by reassinging them using data from Pillar.

``apache.server_status``
--------------------------
^^^^^^^^^^^^^^^^^^^^^^^^

Configures Apache's server_status handler for localhost

``apache.debian_full``
----------------------
^^^^^^^^^^^^^^^^^^^^^^

Installs and configures Apache on Debian and Ubuntu systems.

``apache.uninstall``
----------
^^^^^^^^^^^^^^^^^^^^

Stops the Apache service and uninstalls the package.

Expand Down Expand Up @@ -238,3 +268,48 @@ Example Pillar:
name: 'my name'
path: 'salt://path/to/sites-available/conf/file'
state: 'enabled'
Testing
-------

Linux testing is done with ``kitchen-salt``.

Requirements
^^^^^^^^^^^^

* Ruby
* Docker

.. code-block:: bash
$ gem install bundler
$ bundle install
$ bin/kitchen test [platform]
Where ``[platform]`` is the platform name defined in ``kitchen.yml``,
e.g. ``debian-9-2019-2-py3``.

``bin/kitchen converge``
^^^^^^^^^^^^^^^^^^^^^^^^

Creates the docker instance and runs the ``template`` main state, ready for testing.

``bin/kitchen verify``
^^^^^^^^^^^^^^^^^^^^^^

Runs the ``inspec`` tests on the actual instance.

``bin/kitchen destroy``
^^^^^^^^^^^^^^^^^^^^^^^

Removes the docker instance.

``bin/kitchen test``
^^^^^^^^^^^^^^^^^^^^

Runs all of the stages above in one go: i.e. ``destroy`` + ``converge`` + ``verify`` + ``destroy``.

``bin/kitchen login``
^^^^^^^^^^^^^^^^^^^^^

Gives you SSH access to the instance for manual testing.

0 comments on commit c17382b

Please sign in to comment.