Move config section to install page

Document special host binding addresses Fixes #83
PostgREST · Sep 10, 2017 · 5185a92 · 5185a92
1 parent 0da8cb2
commit 5185a92
Show file tree

Hide file tree

Showing 3 changed files with 112 additions and 104 deletions.
diff --git a/admin.rst b/admin.rst
@@ -1,105 +1,3 @@
-.. _configuration:
-
-Configuration
-=============
-
-The PostgREST server reads a configuration file to determine information about the database and how to serve client requests. There is no predefined location for this file, you must specify the file path as the one and only argument to the server:
-
-.. code:: bash
-
-  postgrest /path/to/postgrest.conf
-
-The file must contain a set of key value pairs. At minimum you must include these keys:
-
-.. code::
-
-  # postgrest.conf
-
-  # The standard connection URI format, documented at
-  # https://www.postgresql.org/docs/current/static/libpq-connect.html#AEN45347
-  db-uri       = "postgres://user:pass@host:5432/dbname"
-
-  # The name of which database schema to expose to REST clients
-  db-schema    = "api"
-
-  # The database role to use when no client authentication is provided.
-  # Can (and probably should) differ from user in db-uri
-  db-anon-role = "anon"
-
-The user specified in the db-uri is also known as the authenticator role. For more information about the anonymous vs authenticator roles see the :ref:`roles`.
-
-Here is the full list of configuration parameters.
-
-================  ======  =======  ========
-Name              Type    Default  Required
-================  ======  =======  ========
-db-uri            String           Y
-db-schema         String           Y
-db-anon-role      String           Y
-db-pool           Int     10
-server-host       String  \*4
-server-port       Int     3000
-server-proxy-uri  String
-jwt-secret        String
-secret-is-base64  Bool    False
-max-rows          Int     ∞
-pre-request       String
-================  ======  =======  ========
-
-db-uri
-  The standard connection PostgreSQL `URI format <https://www.postgresql.org/docs/current/static/libpq-connect.html#AEN45347>`_. Symbols and unusual characters in the password or other fields should be percent encoded to avoid a parse error. On older systems like Centos 6, with older versions of libpq, a different db-uri syntax has to be used. In this case the URI is a string of space separated key-value pairs (key=value), so the example above would be :code:`"host=host user=user port=5432 dbname=dbname password=pass"`. Also allows connections over Unix sockets for higher performance.
-db-schema
-  The database schema to expose to REST clients. Tables, views and stored procedures in this schema will get API endpoints.
-db-anon-role
-  The database role to use when executing commands on behalf of unauthenticated clients.
-db-pool
-  Number of connections to keep open in PostgREST's database pool. Having enough here for the maximum expected simultaneous client connections can improve performance. Note it's pointless to set this higher than the :code:`max_connections` GUC in your database.
-server-host
-  Where to bind the PostgREST web server.
-server-port
-  The port to bind the web server.
-server-proxy-uri
-  Overrides the base URL used within the OpenAPI self-documentation hosted at the API root path. Use a complete URI syntax :code:`scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]`. Ex. :code:`https://postgrest.com`
-
-.. code:: json
-
-  {
-    "swagger": "2.0",
-    "info": {
-      "version": "0.4.0.0",
-      "title": "PostgREST API",
-      "description": "This is a dynamic API generated by PostgREST"
-    },
-    "host": "postgrest.com:443",
-    "basePath": "/",
-    "schemes": [
-      "https"
-    ]
-  }
-
-jwt-secret
-  The secret used to decode JWT tokens clients provide for authentication. If this parameter is not specified then PostgREST refuses authentication requests. Choosing a value for this parameter beginning with the at sign such as :code:`@filename` loads the secret out of an external file. This is useful for automating deployments. Note that any binary secrets must be base64 encoded.
-secret-is-base64
-  When this is set to :code:`true`, the value derived from :code:`jwt-secret` will be treated as a base64 encoded secret.
-max-rows
-  A hard limit to the number of rows PostgREST will fetch from a view, table, or stored procedure. Limits payload size for accidental or malicious requests.
-pre-request
-  A schema-qualified stored procedure name to call right after switching roles for a client request. This provides an opportunity to modify SQL variables or raise an exception to prevent the request from completing.
-
-Running the Server
-------------------
-
-PostgREST outputs basic request logging to stdout. When running it in an SSH session you must detach it from stdout or it will be terminated when the session closes. The easiest technique is redirecting the output to a logfile or to the syslog:
-
-.. code-block:: bash
-
-  ssh foo@example.com \
-    'postgrest foo.conf </dev/null >/var/log/postgrest.log 2>&1 &'
-
-  # another option is to pipe the output into "logger -t postgrest"
-
-(Avoid :code:`nohup postgrest` because the HUP signal is used for manual :ref:`schema_reloading`.)
-
 Hardening PostgREST
 ===================
 

diff --git a/conf.py b/conf.py
@@ -54,9 +54,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'4.1'
+version = u'4.3'
 # The full version, including alpha/beta/rc tags.
-release = u'4.1.0'
+release = u'4.3.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/install.rst b/install.rst
@@ -34,6 +34,116 @@ To use PostgREST you will need an underlying database (PostgreSQL version 9.5 or
 * `Instructions for Ubuntu 14.04 <https://www.digitalocean.com/community/tutorials/how-to-install-and-use-postgresql-on-ubuntu-14-04>`_
 * `Installer for Windows <http://www.enterprisedb.com/products-services-training/pgdownload#windows>`_
 
+.. _configuration:
+
+Configuration
+=============
+
+The PostgREST server reads a configuration file to determine information about the database and how to serve client requests. There is no predefined location for this file, you must specify the file path as the one and only argument to the server:
+
+.. code:: bash
+
+  postgrest /path/to/postgrest.conf
+
+The file must contain a set of key value pairs. At minimum you must include these keys:
+
+.. code::
+
+  # postgrest.conf
+
+  # The standard connection URI format, documented at
+  # https://www.postgresql.org/docs/current/static/libpq-connect.html#AEN45347
+  db-uri       = "postgres://user:pass@host:5432/dbname"
+
+  # The name of which database schema to expose to REST clients
+  db-schema    = "api"
+
+  # The database role to use when no client authentication is provided.
+  # Can (and probably should) differ from user in db-uri
+  db-anon-role = "anon"
+
+The user specified in the db-uri is also known as the authenticator role. For more information about the anonymous vs authenticator roles see the :ref:`roles`.
+
+Here is the full list of configuration parameters.
+
+================  ======  =======  ========
+Name              Type    Default  Required
+================  ======  =======  ========
+db-uri            String           Y
+db-schema         String           Y
+db-anon-role      String           Y
+db-pool           Int     10
+server-host       String  \*4
+server-port       Int     3000
+server-proxy-uri  String
+jwt-secret        String
+secret-is-base64  Bool    False
+max-rows          Int     ∞
+pre-request       String
+================  ======  =======  ========
+
+db-uri
+  The standard connection PostgreSQL `URI format <https://www.postgresql.org/docs/current/static/libpq-connect.html#AEN45347>`_. Symbols and unusual characters in the password or other fields should be percent encoded to avoid a parse error. On older systems like Centos 6, with older versions of libpq, a different db-uri syntax has to be used. In this case the URI is a string of space separated key-value pairs (key=value), so the example above would be :code:`"host=host user=user port=5432 dbname=dbname password=pass"`. Also allows connections over Unix sockets for higher performance.
+db-schema
+  The database schema to expose to REST clients. Tables, views and stored procedures in this schema will get API endpoints.
+db-anon-role
+  The database role to use when executing commands on behalf of unauthenticated clients.
+db-pool
+  Number of connections to keep open in PostgREST's database pool. Having enough here for the maximum expected simultaneous client connections can improve performance. Note it's pointless to set this higher than the :code:`max_connections` GUC in your database.
+server-host
+  Where to bind the PostgREST web server. In addition to the usual address options, PostgREST interprets these reserved addresses with special meanings:
+
+  * :code:`*` - any IPv4 or IPv6 hostname
+  * :code:`*4` - any IPv4 or IPv6 hostname, IPv4 preferred
+  * :code:`!4` - any IPv4 hostname
+  * :code:`*6` - any IPv4 or IPv6 hostname, IPv6 preferred
+  * :code:`!6` - any IPv6 hostname
+
+server-port
+  The port to bind the web server.
+server-proxy-uri
+  Overrides the base URL used within the OpenAPI self-documentation hosted at the API root path. Use a complete URI syntax :code:`scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]`. Ex. :code:`https://postgrest.com`
+
+.. code:: json
+
+  {
+    "swagger": "2.0",
+    "info": {
+      "version": "0.4.3.0",
+      "title": "PostgREST API",
+      "description": "This is a dynamic API generated by PostgREST"
+    },
+    "host": "postgrest.com:443",
+    "basePath": "/",
+    "schemes": [
+      "https"
+    ]
+  }
+
+jwt-secret
+  The secret used to decode JWT tokens clients provide for authentication. If this parameter is not specified then PostgREST refuses authentication requests. Choosing a value for this parameter beginning with the at sign such as :code:`@filename` loads the secret out of an external file. This is useful for automating deployments. Note that any binary secrets must be base64 encoded.
+secret-is-base64
+  When this is set to :code:`true`, the value derived from :code:`jwt-secret` will be treated as a base64 encoded secret.
+max-rows
+  A hard limit to the number of rows PostgREST will fetch from a view, table, or stored procedure. Limits payload size for accidental or malicious requests.
+pre-request
+  A schema-qualified stored procedure name to call right after switching roles for a client request. This provides an opportunity to modify SQL variables or raise an exception to prevent the request from completing.
+
+Running the Server
+------------------
+
+PostgREST outputs basic request logging to stdout. When running it in an SSH session you must detach it from stdout or it will be terminated when the session closes. The easiest technique is redirecting the output to a logfile or to the syslog:
+
+.. code-block:: bash
+
+  ssh foo@example.com \
+    'postgrest foo.conf </dev/null >/var/log/postgrest.log 2>&1 &'
+
+  # another option is to pipe the output into "logger -t postgrest"
+
+(Avoid :code:`nohup postgrest` because the HUP signal is used for manual :ref:`schema_reloading`.)
+
+
 Docker
 ======