From c5f0b50b30a6557a717db0fce017a5cf69ad1153 Mon Sep 17 00:00:00 2001
From: Simon Hornby <simon@getunleash.io>
Date: Tue, 11 Nov 2025 17:10:27 +0200
Subject: [PATCH] chore: slightly simpler quick start setup (#10933)

Co-authored-by: Melinda Fekete <melinda.fekete@getunleash.io>
---
 docker-compose.postgres.yml                   | 21 ++++++++++++++++
 docker/local-postgres/Dockerfile              |  3 +++
 docker/local-postgres/init-unleash.sql        | 24 +++++++++++++++++++
 website/docs/contributing/backend/overview.md | 14 ++++++++++-
 4 files changed, 61 insertions(+), 1 deletion(-)
 create mode 100644 docker-compose.postgres.yml
 create mode 100644 docker/local-postgres/Dockerfile
 create mode 100644 docker/local-postgres/init-unleash.sql

diff --git a/docker-compose.postgres.yml b/docker-compose.postgres.yml
new file mode 100644
index 0000000000..6e39b22933
--- /dev/null
+++ b/docker-compose.postgres.yml
@@ -0,0 +1,21 @@
+services:
+  unleash-postgres:
+    build:
+      context: ./docker/local-postgres
+    container_name: unleash-postgres
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: password
+      POSTGRES_DB: postgres
+    ports:
+      - "5432:5432"
+    volumes:
+      - unleash-postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 5s
+      retries: 12
+
+volumes:
+  unleash-postgres-data:
diff --git a/docker/local-postgres/Dockerfile b/docker/local-postgres/Dockerfile
new file mode 100644
index 0000000000..d3c02c8ab6
--- /dev/null
+++ b/docker/local-postgres/Dockerfile
@@ -0,0 +1,3 @@
+FROM postgres:15
+
+COPY init-unleash.sql /docker-entrypoint-initdb.d/init-unleash.sql
diff --git a/docker/local-postgres/init-unleash.sql b/docker/local-postgres/init-unleash.sql
new file mode 100644
index 0000000000..98ebf6e5fc
--- /dev/null
+++ b/docker/local-postgres/init-unleash.sql
@@ -0,0 +1,24 @@
+\set ON_ERROR_STOP on
+
+DO
+$$
+BEGIN
+   IF NOT EXISTS (SELECT 1 FROM pg_catalog.pg_roles WHERE rolname = 'unleash_user') THEN
+      CREATE ROLE unleash_user LOGIN PASSWORD 'password';
+   END IF;
+END
+$$;
+
+ALTER ROLE unleash_user CREATEDB;
+
+SELECT 'CREATE DATABASE unleash WITH OWNER unleash_user'
+ WHERE NOT EXISTS (SELECT 1 FROM pg_database WHERE datname = 'unleash');
+\gexec
+
+SELECT 'CREATE DATABASE unleash_test WITH OWNER unleash_user'
+ WHERE NOT EXISTS (SELECT 1 FROM pg_database WHERE datname = 'unleash_test');
+\gexec
+
+SELECT 'ALTER DATABASE unleash_test SET timezone TO ''UTC'''
+ WHERE EXISTS (SELECT 1 FROM pg_database WHERE datname = 'unleash_test');
+\gexec
diff --git a/website/docs/contributing/backend/overview.md b/website/docs/contributing/backend/overview.md
index 3fba0ef5db..237b14e74c 100644
--- a/website/docs/contributing/backend/overview.md
+++ b/website/docs/contributing/backend/overview.md
@@ -30,7 +30,19 @@ To run and develop Unleash, you need to have PostgreSQL 14.0+ locally.
 
 Unleash currently also works with PostgreSQL v14.0+, but this might change in a future feature release, and we have stopped running automatic integration tests below PostgreSQL 14. The current recommendation is to use a role with Owner privileges since Unleash uses Postgres functions to simplify our database usage.
 
-### Create a local unleash databases in postgres {#create-a-local-unleash-databases-in-postgres}
+### Create a local Unleash database in Postgres
+
+Start the ready-to-use Postgres container (first run builds a small image that
+executes the required SQL automatically):
+
+```bash
+$ docker compose -f docker-compose.postgres.yml up -d
+```
+
+The container exposes Postgres on `localhost:5432` with the expected role and
+databases already created. Stop it with `docker compose -f docker-compose.postgres.yml down`.
+
+If you prefer to run the SQL manually outside of Docker, you can execute:
 
 ```bash
 $ psql postgres <<SQL