Run local development and CI on PostgreSQL with pgvector

.env.example

@@ -13,19 +13,21 @@ CSRF_TRUSTED_ORIGINS=
 # Set when serving from a subpath, e.g. /coderr
 FORCE_SCRIPT_NAME=
 
-# PostgreSQL. Without DB_NAME the project falls back to local SQLite.
-# DB_NAME=coderr
-# DB_USER=coderr
-# DB_PASSWORD=
-# DB_HOST=localhost
-# DB_PORT=5432
+# PostgreSQL. These values match the local container from compose.yml.
+# On the server use the real credentials and port 5432.
+# Without DB_NAME the project falls back to local SQLite.
+DB_NAME=coderr
+DB_USER=coderr
+DB_PASSWORD=coderr
+DB_HOST=127.0.0.1
+DB_PORT=5433
 
 # HSTS. Only enable once HTTPS is verified and working.
 # HSTS_SECONDS=31536000
 # HSTS_INCLUDE_SUBDOMAINS=True
 
-# E-Mail fuer das Kontaktformular. Ohne EMAIL_HOST_USER schreibt Django
-# ausgehende Mails nur in die Konsole, statt sie zu versenden.
+# Email for the contact form. Without EMAIL_HOST_USER Django only writes
+# outgoing mail to the console instead of sending it.
 # EMAIL_HOST=mail.gmx.net
 # EMAIL_PORT=587
 # EMAIL_USE_TLS=True

.github/workflows/ci.yml

@@ -42,11 +42,11 @@ jobs:
     name: Tests
     runs-on: ubuntu-latest
 
-    # PostgreSQL 16 matches the server. Locally the suite runs on SQLite,
-    # so this is where it meets the production database engine.
+    # Same image as compose.yml: PostgreSQL 16 with the pgvector version
+    # the server installs from Ubuntu 24.04.
     services:
       db:
-        image: postgres:16
+        image: pgvector/pgvector:0.6.0-pg16
         # Throwaway credentials: the container exists only for this run and
         # cannot be reached from outside the runner.
         env:

README.md

@@ -57,7 +57,7 @@ Akademie; everything behind `/api/` is this project.
 | Language   | Python 3.12+ (required by Django 6)          |
 | Framework  | Django 6.0.6                                 |
 | API        | Django REST Framework 3.17.1                 |
-| Database   | SQLite (development) / PostgreSQL (production)|
+| Database   | PostgreSQL 16 with pgvector (Docker locally) |
 | Auth       | DRF Token Authentication                     |
 | API Docs   | drf-spectacular 0.30.0 (OpenAPI 3)           |
 | Serving    | Gunicorn behind Nginx (Ubuntu 24.04)         |
@@ -91,6 +91,7 @@ coderr_backend/
 
 - Python 3.12 or newer
 - `pip` and `venv`
+- Docker with Docker Compose, for the local PostgreSQL database
 
 ### Installation
 
@@ -147,19 +148,28 @@ coderr_backend/
    python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"
    ```
 
-5. **Apply the database migrations**
+5. **Start the database**, PostgreSQL 16 with pgvector in Docker:
+
+   ```bash
+   docker compose up -d
+   ```
+
+   It listens on `127.0.0.1:5433` and matches the values in `.env.example`.
+   Wait until `docker compose ps` shows the container as `healthy`.
+
+6. **Apply the database migrations**
 
    ```bash
    python manage.py migrate
    ```
 
-6. **(Optional) Create an admin user** to use the Django admin at `/admin/`:
+7. **(Optional) Create an admin user** to use the Django admin at `/admin/`:
 
    ```bash
    python manage.py createsuperuser
    ```
 
-7. **(Optional) Seed demo data**, six offers, five reviews and the guest
+8. **(Optional) Seed demo data**, six offers, five reviews and the guest
    accounts the frontend expects:
 
    ```bash
@@ -169,7 +179,7 @@ coderr_backend/
    The command is idempotent and runs in a transaction, so it can be repeated
    safely.
 
-8. **Run the development server**
+9. **Run the development server**
 
    ```bash
    python manage.py runserver
@@ -178,7 +188,8 @@ coderr_backend/
    The API is now available at `http://127.0.0.1:8000/`.
 
 Without any environment variables set, the project runs in development mode:
-`DEBUG=True` and a local SQLite file. Production settings are switched on
+`DEBUG=True` and a local SQLite file. The SQLite fallback cannot hold vector
+data, so the setup above uses PostgreSQL. Production settings are switched on
 purely through the `.env` file.
 
 ---

compose.yml

@@ -0,0 +1,27 @@
+# Local development only. Production runs PostgreSQL natively on the server;
+# this container mirrors its major version and adds pgvector.
+services:
+  db:
+    # Pinned to the pgvector version Ubuntu 24.04 ships for the server.
+    # This tag also freezes PostgreSQL at 16.1. Minor releases only carry
+    # fixes, so the pgvector version is the one that has to match.
+    image: pgvector/pgvector:0.6.0-pg16
+    # Throwaway credentials, applied only when the volume is first created.
+    environment:
+      POSTGRES_DB: coderr
+      POSTGRES_USER: coderr
+      POSTGRES_PASSWORD: coderr
+    ports:
+      # Host port 5433 because a native PostgreSQL may already hold 5432.
+      # Bound to 127.0.0.1 so the database is not reachable from the network.
+      - "127.0.0.1:5433:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U coderr -d coderr"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  pgdata: