Joplin Server: localhost override breaks documentation and expectations

[bernd-wechner]

Operating system

Linux

Joplin version

3.3.3

Desktop version info

No response

Current behaviour

If you do what the docs say to do, it doesn't work. Moreover, the docs are in the right and code in the wrong, IMHO.

Expected behaviour

I expect the code and docs to be in alignment, and I expect the behaviour that is documented. Not only because it's documented, but because it makes sense.

Logs

The docker log what reveals the issue. Here is an extract from the server's docker log:

06:05:30 0|app | 2025-05-24 06:05:30: App: DB Config: {
06:05:30 0|app | client: 'pg',
06:05:30 0|app | name: 'joplin',
06:05:30 0|app | slowQueryLogEnabled: false,
06:05:30 0|app | slowQueryLogMinDuration: 1000,
06:05:30 0|app | autoMigration: true,
06:05:30 0|app | user: 'joplin',
06:05:30 0|app | password: '********',
06:05:30 0|app | port: 5432,
06:05:30 0|app | host: 'host.docker.internal'
06:05:30 0|app | }

Not the definition of host ('host.docker.internal'). This is when the compose file specifies 'localhost' or '127.0.0.1'. The problem is that this function:

joplin/packages/server/src/config.ts

Line 23 in 88c95cc

function databaseHostFromEnv(runningInDocker: boolean, env: EnvVariables, slave: boolean): string {

maps localhost to host.docker.internal. This runs totally counter to the docs here:

https://github.com/laurent22/joplin/tree/88c95cc91cf7b71e02606288c87e01282efabe4b/packages/server#using-an-existing-postgresql-server

Which state that to use an existing postgresql server, which was my goal, which is in fact running on the same machine as the Joplin server, to specify localhost. And that makes sense, it is the localhost. I'm with the docs on this. But code maps it to and internal database, the precise thing we are not wanting to do.

Further, the connectis made from 172.18.0.2.

So in order to connect to an existing postgresql database we need to specify the IP address of the server on the LAN. Which has two negative consequences.

1. There is a slight difference in cost between communicating with 127.0.0.1 and the LAN IP. c.f.: https://g.co/gemini/share/b3ab2ea5b654
2. The existing postgres server needs to be configured to accept connections from 172.18.0.2. If the connection came from localhost or a LAN IP that would not be needed

But most importantly it's not documented and cost me some time to diagnose and discover and hence actually configure a docker image to use an existing postgresql server on same machine.

If there's a solid technical reason for the code to make this mapping, then the doc should include advice that localhost will not work and you need to specify the host explicitly even if hosted on the same machine and you'll need to configure it accept connections from 172.18.0.2 (or whatever IP ranges the docker image can adopt).

But if the docker image does not contain a postgresql server then this code should not execute so the question is can it be a) removed and simply document that host.docker.internal is the address of an in-image server or b) if it can be detected at run time whether there's an internal database or not make this mapping conditional on there being one.

[bernd-wechner]

It looks like this mapping was added in this commit:

0d2bf6d

in 2021. And in the same commit the use of localhost to connect to existing (so not internal) postgres server was documented. Curious. It's a large commit hitting 34 files.