Add documentation on the minimal health check

docs/admin.rst

@@ -256,6 +256,35 @@ Schema Reloading
 
 Changing the schema while the server is running can lead to errors due to a stale schema cache. To learn how to refresh the cache see :ref:`schema_reloading`.
 
+.. _health_check:
+
+Health Check
+------------
+
+You can enable a minimal health check to verify if PostgREST is available for client requests and to check the status of its internal state.
+
+To do this, set the configuration variable :ref:`admin-server-port` to the port number of your preference. Two endpoints ``live`` and ``ready`` will then be available.
+
+The ``live`` endpoint verifies if PostgREST is running on its configured port. A request will return ``200 OK`` if PostgREST is alive or ``503`` otherwise.
+
+The ``ready`` endpoint also checks the state of both the Database Connection and the :ref:`schema_cache`. A request will return ``200 OK`` if it is ready or ``503`` if not.
+
+For instance, to verify if PostgREST is running at ``localhost:3000`` while the ``admin-server-port`` is set to ``3001``:
+
+.. tabs::
+
+  .. code-tab:: http
+
+    GET localhost:3001/live HTTP/1.1
+
+  .. code-tab:: bash Curl
+
+    curl -I "http://localhost:3001/live"
+
+.. code-block:: http
+
+  HTTP/1.1 200 OK
+
 
 Daemonizing
 ===========

docs/configuration.rst

@@ -105,6 +105,7 @@ It's not possible to change :ref:`env_variables_config` for a running process an
 
   The following settings will not be reloaded. You will need to restart PostgREST to change those.
 
+    * :ref:`admin-server-port`
     * :ref:`db-uri`
     * :ref:`db-pool`
     * :ref:`db-pool-timeout`
@@ -145,6 +146,7 @@ List of parameters
 ======================== ======= ================= ==========
 Name                     Type    Default           Reloadable
 ======================== ======= ================= ==========
+admin-server-port        Int
 app.settings.*           String                    Y
 db-anon-role             String                    Y
 db-channel               String  pgrst             Y
@@ -174,6 +176,18 @@ server-unix-socket       String
 server-unix-socket-mode  String  660
 ======================== ======= ================= ==========
 
+.. _admin-server-port:
+
+admin-server-port
+-----------------
+
+  =============== =======================
+  **Environment** PGRST_ADMIN_SERVER_PORT
+  **In-Database** `n/a`
+  =============== =======================
+
+Specifies the port for the :ref:`health_check` endpoints.
+
 .. _app.settings.*:
 
 app.settings.*
@@ -589,7 +603,7 @@ server-host
 
   =============== =================
   **Environment** PGRST_SERVER_HOST
-  **In-Database** pgrst.server_host
+  **In-Database** `n/a`
   =============== =================
 
   Where to bind the PostgREST web server. In addition to the usual address options, PostgREST interprets these reserved addresses with special meanings:
@@ -607,7 +621,7 @@ server-port
 
   =============== =================
   **Environment** PGRST_SERVER_PORT
-  **In-Database** pgrst.server_port
+  **In-Database** `n/a`
   =============== =================
 
   The TCP port to bind the web server.
@@ -619,7 +633,7 @@ server-unix-socket
 
   =============== =================
   **Environment** PGRST_SERVER_UNIX_SOCKET
-  **In-Database** pgrst.server_unix_socket
+  **In-Database** `n/a`
   =============== =================
 
   `Unix domain socket <https://en.wikipedia.org/wiki/Unix_domain_socket>`_ where to bind the PostgREST web server.
@@ -636,7 +650,7 @@ server-unix-socket-mode
 
   =============== =================
   **Environment** PGRST_SERVER_UNIX_SOCKET_MODE
-  **In-Database** pgrst.server_unix_socket_mode
+  **In-Database** `n/a`
   =============== =================
 
   `Unix file mode <https://en.wikipedia.org/wiki/File_system_permissions>`_ to be set for the socket specified in :ref:`server-unix-socket`