pg

docs/docs/self-hosting/troubleshooting/docker.md

@@ -70,3 +70,61 @@ services.postgres.healthcheck Additional property start_interval is not allowed
 
 You will need to upgrade your Docker compose version to a newer version that
 supports the `start_interval` property on the health check.
+
+## Postgres authentication failed
+
+If you're getting Postgres password authentication failures when starting your
+cluster, then you might be using a stale Docker volume.
+
+In more detail, if you're getting an error of the following form (pasting a full
+example for easier greppability):
+
+```
+museum-1    | panic: pq: password authentication failed for user "pguser"
+museum-1    |
+museum-1    | goroutine 1 [running]:
+museum-1    | main.setupDatabase()
+museum-1    |   /etc/ente/cmd/museum/main.go:846 +0x338
+museum-1    | main.main()
+museum-1    |   /etc/ente/cmd/museum/main.go:124 +0x44c
+museum-1 exited with code 2
+```
+
+Then the issue is that the password you're using is not the password postgres is
+expecting (duh), and a potential scenario where that can happen is something
+like this:
+
+1. On a machine, you create a new cluster with `quickstart.sh`.
+
+2. Later you delete that folder, but then create another cluster with
+   `quickstart.sh`. Each time `quickstart.sh` runs, it creates new credentials,
+   and then when it tries to spin up the docker compose cluster, use them to
+   connect to the postgres running within.
+
+3. However, you would already have a docker volume from the first run of
+   `quickstart.sh`. Since the folder name is the same in both cases `my-ente`,
+   Docker will reuse the existing volumes. So your postgres is running off the
+   old credentials, and you're trying to connect to it using the new ones, and
+   the error arises.
+
+The solution is to delete the stale docker volume. **Be careful**, this will
+delete all data in those volumes (any thing you uploaded etc), so first
+understand if this is the exact problem you are facing before deleting those
+volumes.
+
+If you're sure of what you're doing, the volumes can be deleted by
+
+```
+docker volume ls
+```
+
+to list them, and then delete the ones that begin with `my-ente` using `docker
+volume rm`. You can delete all stale volumes by using `docker system prune` with
+the `--volumes` flag, but be _really_ careful, that'll delete all volumes (Ente
+or otherwise) on your machine that are not currently in use by a running docker
+container.
+
+If you're unsure about removing volumes, another alternative is to rename your
+`my-ente` folder. Docker uses the folder name to determine the volume name
+prefix, so giving it a different name will cause Docker to create a volume
+afresh for it.