From 6933f0e42766011741664278867647ded9674362 Mon Sep 17 00:00:00 2001 From: Imran Iqbal Date: Thu, 17 Oct 2019 08:58:44 +0100 Subject: [PATCH] docs(readme): move to `docs/` directory and modify accordingly --- README.rst => docs/README.rst | 157 +++++++++++++++++++++++++--------- 1 file changed, 116 insertions(+), 41 deletions(-) rename README.rst => docs/README.rst (60%) diff --git a/README.rst b/docs/README.rst similarity index 60% rename from README.rst rename to docs/README.rst index 0e8b4b5..6a2ae5d 100644 --- a/README.rst +++ b/docs/README.rst @@ -1,122 +1,152 @@ -====== +.. _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** - See the full `Salt Formulas installation and usage instructions - `_. +General notes +------------- + +See the full `SaltStack Formulas installation and usage instructions +`_. + +If you are interested in writing or contributing to formulas, please pay attention to the `Writing Formula Section +`_. + +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 `_. + +See `Formula Versioning Section `_ for more details. + +Contributing to this repo +------------------------- + +**Commit message formatting is significant!!** + +Please see `How to contribute `_ 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``_ using data from Pillar. (Debian and RedHat Only) @@ -124,53 +154,53 @@ 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. @@ -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. @@ -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.