From: Stephen Finucane Date: Fri, 28 Apr 2017 23:46:55 +0000 (+0100) Subject: docs: Add a configuration guide X-Git-Tag: v2.0.0-rc1~13 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b1aca0bbc176f680d8773dd2b5bc02aa1a9ad7ce;p=thirdparty%2Fpatchwork.git docs: Add a configuration guide This should simplify matters for folks that don't have much experience with Django. It also serves to highlight the 'ENABLE_REST_API' option. A release note is also added to capture the rename of DEFAULT_PATCHES_PER_PAGE that has occurred during this cycle. Signed-off-by: Stephen Finucane --- diff --git a/docs/deployment/configuration.rst b/docs/deployment/configuration.rst new file mode 100644 index 00000000..34748563 --- /dev/null +++ b/docs/deployment/configuration.rst @@ -0,0 +1,108 @@ +Configuration +============= + +This document describes the various configuration options available in +Patchwork. These options can be used for both :doc:`development +<../development/installation>` and :doc:`deployment ` +installations. + +The ``settings.py`` File +------------------------ + +Patchwork is a Django application and, as such, relies on Python-based settings +files. Refer to the `Django documentation`__ for more information on the +general format. + +Patchwork provides three settings files: + +``base.py`` + + A base settings file that should not be used directly. + +``dev.py`` + + A settings file for development use. **This file is horribly insecure and + must not be used in production**. + +``production.example.py`` + + A sample settings file for production use. This will likely require some + heavy customization. The :ref:`deployment guide ` + provides more information. + +__ https://docs.djangoproject.com/en/1.8/topics/settings/ + +Patchwork-specific Settings +--------------------------- + +Patchwork utilizes a number of Patchwork-only settings in addition to the +`Django`__ and `Django REST Framework`__ settings. + +``DEFAULT_ITEMS_PER_PAGE`` +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The default number of items to display in the list pages for a project +(``/project/{projectID}/list``) or bundle (``/bundle/{userID}/{bundleName}``). + +This is customizable on a per-user basis from the user configuration page. + +.. versionchanged:: 2.0 + + This option was previously named ``DEFAULT_PATCHES_PER_PAGE``. It was + renamed as cover letters are now supported also. + +``CONFIRMATION_VALIDITY_DAYS`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The number of days to consider an account confirmation request valid. After +this interval, the :ref:`cron management command ` will +delete the request. + +``NOTIFICATION_DELAY_MINUTES`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The number of minutes to wait before sending any notifications to a user. An +notification generated during this time are gathered into a single digest +email, ensuring users are not spammed with emails from Patchwork. + +``NOTIFICATION_FROM_EMAIL`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The email address that notification emails should be sent from. + +``ENABLE_XMLRPC`` +~~~~~~~~~~~~~~~~~ + +Enable the :doc:`XML-RPC API <../api/xmlrpc>`. + +``ENABLE_REST_API`` +~~~~~~~~~~~~~~~~~~~ + +Enable the :doc:`REST API <../api/rest>`. + +.. versionadded:: 2.0 + +``REST_RESULTS_PER_PAGE`` +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The number of items to include in REST API responses by default. This can be +overridden by the ``per_page`` parameter for some endpoints. + +.. versionadded:: 2.0 + +``COMPAT_REDIR`` +~~~~~~~~~~~~~~~~ + +Enable redirections of URLs from previous versions of Patchwork. + +.. TODO(stephenfin) Deprecate this in favor of SECURE_SSL_REDIRECT + +``FORCE_HTTPS_LINKS`` +~~~~~~~~~~~~~~~~~~~~~ + +Force use of ``https://`` links instead of guessing the scheme based on current +access. This is useful if SSL protocol is terminated upstream of the server +(e.g. at the load balancer) + +__ https://docs.djangoproject.com/en/1.8/ref/settings/ +__ http://www.django-rest-framework.org/api-guide/settings/ diff --git a/docs/deployment/installation.rst b/docs/deployment/installation.rst index 3b3636d8..1b472233 100644 --- a/docs/deployment/installation.rst +++ b/docs/deployment/installation.rst @@ -4,7 +4,7 @@ Installation This document describes the necessary steps to configure Patchwork in a production environment. This requires a significantly "harder" deployment than the one used for development. If you are interested in developing Patchwork, -refer to the **development guide** instead. +refer to the :doc:`development guide <../development/installation>` instead. This document describes a two-node installation of Patchwork, consisting of a database sever and an application server. It should be possible to combine @@ -187,6 +187,8 @@ corresponding distro package for each of these requirements. For example: __ https://pkgs.org/ +.. _deployment-settings: + Configure Patchwork ~~~~~~~~~~~~~~~~~~~ @@ -409,6 +411,8 @@ at boot: __ https://uwsgi-docs.readthedocs.io/en/latest/Systemd.html __ https://uwsgi-docs.readthedocs.io/en/latest/Upstart.html +.. _deployment-final-steps: + Final Steps ~~~~~~~~~~~ diff --git a/docs/index.rst b/docs/index.rst index 29f2c9d3..623b683a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -36,6 +36,7 @@ of community projects. :caption: Deployment Documentation deployment/installation + deployment/configuration deployment/upgrading .. _development-docs: diff --git a/releasenotes/notes/rename-default_patches_per_page-4ff3ad6dc1c82af7.yaml b/releasenotes/notes/rename-default_patches_per_page-4ff3ad6dc1c82af7.yaml new file mode 100644 index 00000000..0d3b9851 --- /dev/null +++ b/releasenotes/notes/rename-default_patches_per_page-4ff3ad6dc1c82af7.yaml @@ -0,0 +1,6 @@ +--- +upgrade: + - | + The ``DEFAULT_PATCHES_PER_PAGE`` has been renamed as + ``DEFAULT_ITEMS_PER_PAGE`` as it is now possible to list cover letters in + addition to patches.