img

Setting up a Beta version of PostgreSQL in a docker container on MacOS.

Setting up PostgreSQL in a docker container on MacOS is not totally straightforward, but following this guide makes it easy. In this case we are installing Postgres 18 Beta 3, which is version-pinned in the Docker yml config file.
I used the Postgres Docker Official Image in this example, but it may work equally well with the official Postgis image, if they have updated that one to the same Beta version too.
In this walkthrough I assuming that you allready have Docker Desktop up and running. If not, set that up first.

Start by opening a terminal and creating and entering a working folder. 
cd ~/Documents
mkdir -P postgres.nosync/Database.one
cd postgres.nosync/Database.one
touch .nosync
Allready some points of attention here:
1: There is some software that has issues with spaces in paths. Except if you have a space in your username, that is easy to avoid.
2: icloud sync does not play very nice with docker, especially if you delete and recreate files quickly. The .nosync suffix warns icloud sync to mind its own business and stay out of this folder. Ugly, but it works.
3: update: icloud sync does not always respect the .nosync suffix anymore, the empty .nosync file may do the trick. A better solution is actually to place the database and its config files outside of any folder that is seen by icloud.

Clean up docker in a quite un-subtle way: trash everything that is not currently running. 
docker system prune -f
docker volume prune -f
tip: to throw away internal volumes you can look them up with info comands, but as long as the yml file is similar as to when it was started you may also use: 
docker compose -f specific_yml_file.yml down -v
this also works if the container is not running. The -v flag is the one killing the internal volumes. Do this if a container failed to properly start and you have trouble with stuff seeming to 'stick around' even after a prune.


Grab the zipfile with the configuration files that i prepared from here and unzip it into the working folder. There should now be a subdirectory with all the prepared configuration files in it.
If you are curious what is in these files without downloading them, head over to this page. The configuration that is explained there is not actually this one, but one that is a bit more complex, since it includes replication, but the explanation should cover the details of this configuration too.


Right, now that the fundament has been prepared, lets start for real.

in the terminal


Clean out the old working directories and re-create them. 
rm -rf postgres18b3

mkdir -p postgres18b3/config
mkdir -p postgres18b3/init
mkdir -p postgres18b3/dump/data

copy the files from the template folder to their proper places 
cp templates/init.* postgres18b3/init/ 
cp templates/*.conf postgres18b3/config/ 
cp postgres18b3/config/postgresql_s.conf postgres18b3/config/postgresql.conf 
cp templates/*.yml .
note that the database is built in a standalone config. (that is what the _s int the postgresql_s.conf template stands for)

Now lets test the node 
docker compose -f docker-compose-1.yml up
Yup, that is all there is to it!

Note that the database is running from an interactive terminal. The advantage of this is that you can immediately see the log and warning messages that are produced.
The downside is that you will have to keep this terminal open at all times, but it is for testing purposes, so that should be fine.

Important: The postgres port 5432 is mapped in the .yml file to port 5405 on the local host (to prevent clashes with other instances), and there are some more settings hardcoded in there, have a look.
Practically this means that in order to connect a databasetool or script to the instance, it has to connect to 
Host: localhost
Port: 5405
User: postgres18b3admin
Password: g_97Tgs2fjru857_dfh
Database: postgres18beta3
A word of warning: if you change things in there and then the container fails to start, then usually the best course of action is to throw it all away and start over. Its just a testing container after all.

Interested in getting replication to work in Docker on MasOS ? Check out this blogpost next!

Ellert van Koperen, August 2025.