From f33bccbcdba45358b9399e71e0cb119d06631375 Mon Sep 17 00:00:00 2001
From: Wolfgang Walther <walther@technowledgy.de>
Date: Sun, 18 Feb 2024 16:30:45 +0100
Subject: [PATCH] docs: Use port 5432 in tutorial 0 to avoid connecting to the
 wrong server

Some users connect PostgREST to the wrong PostgreSQL instance - likely because they are
not even aware that another instance is running. By using the standard port 5432 instead
of 5433, we avoid this problem. The user will be made aware very early that they have
another postgresql instance running - and can solve the problem at this stage. If they
decide to change the port, they are much more likely to remember that in the later stages
of the tutorial, too.

Resolves https://github.com/PostgREST/postgrest-docs/issues/304
---
 docs/tutorials/tut0.rst | 21 ++++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/docs/tutorials/tut0.rst b/docs/tutorials/tut0.rst
index 0a26eb920..42ed6d947 100644
--- a/docs/tutorials/tut0.rst
+++ b/docs/tutorials/tut0.rst
@@ -29,11 +29,22 @@ If Docker is not installed, you can get it `here <https://www.docker.com/get-sta
 
 .. code-block:: bash
 
-  sudo docker run --name tutorial -p 5433:5432 \
+  sudo docker run --name tutorial -p 5432:5432 \
                   -e POSTGRES_PASSWORD=notused \
                   -d postgres
 
-This will run the Docker instance as a daemon and expose port 5433 to the host system so that it looks like an ordinary PostgreSQL server to the rest of the system.
+This will run the Docker instance as a daemon and expose port 5432 to the host system so that it looks like an ordinary PostgreSQL server to the rest of the system.
+
+.. note::
+
+  This only works if there is no other PostgreSQL instance running on the default port on your computer. If this port is already in use, you will receive a message similar to this:
+
+  .. code-block:: text
+
+    docker: Error response from daemon: [...]: Bind for 0.0.0.0:5432 failed: port is already allocated.
+
+  In this case, you will need to change the **first** of the two 5432 to something else, for example to :code:`5433:5432`. Remember to also adjust the port in your config file in Step 5!
+
 
 Step 3. Install PostgREST
 -------------------------
@@ -179,13 +190,17 @@ PostgREST can use a configuration file to tell it how to connect to the database
 
 .. code-block:: ini
 
-  db-uri = "postgres://authenticator:mysecretpassword@localhost:5433/postgres"
+  db-uri = "postgres://authenticator:mysecretpassword@localhost:5432/postgres"
   db-schemas = "api"
   db-anon-role = "web_anon"
 
 The configuration file has other :ref:`options <configuration>`, but this is all we need.
 If you are not using Docker, make sure that your port number is correct and replace `postgres` with the name of the database where you added the todos table.
 
+.. note::
+
+  In case you had to adjust the port in Step 2, remember to adjust the port here, too!
+
 Now run the server:
 
 .. code-block:: bash