diff --git a/.env.example b/.env.example index 1d3cdbd..13723a2 100644 --- a/.env.example +++ b/.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 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 393b61c..cec6a80 100644 --- a/.github/workflows/ci.yml +++ b/.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: diff --git a/README.md b/README.md index ca5d14f..a909c54 100644 --- a/README.md +++ b/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. --- diff --git a/compose.yml b/compose.yml new file mode 100644 index 0000000..289daaf --- /dev/null +++ b/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: