feat(postgres): replace CouchDB with PostgreSQL

.env.example

@@ -10,13 +10,12 @@
 # CSAF_CMS_BACKEND_PORT=8081
 # CSAF_CMS_BACKEND_CSRF_ENABLED=true
 
-# CouchDB connection used by the backend when running standalone (./mvnw spring-boot:run).
-# CSAF_COUCHDB_HOST=localhost
-# CSAF_COUCHDB_PORT=5984
-# CSAF_COUCHDB_SSL=false
-# CSAF_COUCHDB_DBNAME=csaf
-# CSAF_COUCHDB_USER=admin
-# CSAF_COUCHDB_PASSWORD=admin
+# PostgreSQL connection used by the backend when running standalone (./mvnw spring-boot:run).
+# CSAF_DB_HOST=localhost
+# CSAF_DB_PORT=5432
+# CSAF_DB_NAME=csaf
+# CSAF_DB_USER=csaf
+# CSAF_DB_PASSWORD=csaf
 
 # keycloak
 # CSAF_OIDC_ISSUER_URL=http://localhost/realms/csaf

README.md

@@ -19,7 +19,7 @@ It offers a REST service for listing, searching, deleting, creating, commenting
 ## Getting started
 
 > **Just want to run/try the backend locally?** This section describes a manual/production
-> setup (building the jar yourself, providing your own Keycloak/CouchDB/proxy infrastructure).
+> setup (building the jar yourself, providing your own Keycloak/PostgreSQL/proxy infrastructure).
 > If you just want to develop against or try out the backend locally with Docker, you don't
 > need any of the steps below — skip straight to [Developing](#developing) and follow
 > [docker/README.md](docker/README.md) instead.
@@ -28,7 +28,7 @@ To run the CSAF CMS server you need the following:
 
 - [Keycloak](https://www.keycloak.org/)
 - A proxy like [oauth2-proxy](https://oauth2-proxy.github.io/oauth2-proxy/)
-- [CouchDB](https://couchdb.apache.org/)
+- [PostgreSQL](https://www.postgresql.org/)
 
 You can find an example setup for local development in the 'compose.yaml' and
 an example configuration for Keycloak in 'docker/config/keycloak/csaf-realm.json'. You can
@@ -97,7 +97,7 @@ Duplicates are identified by their tracking ID and not imported again.
 
 ## Developing
 
-For the full, step-by-step guide to running the whole stack (CouchDB, Keycloak, oauth2-proxy,
+For the full, step-by-step guide to running the whole stack (PostgreSQL, Keycloak, oauth2-proxy,
 validator service, Secvisogram and the backend) locally with Docker Compose — including the
 required `.env` setup, cookie secret generation, default users and how to debug the backend
 on the host — see **[docker/README.md](docker/README.md)**.
@@ -148,8 +148,8 @@ OpenAPI specification
 
 http://localhost:8081/api-docs
 
-For accessing CouchDB when running the local Docker setup, see
-[Accessing CouchDB](docker/README.md#accessing-couchdb) in `docker/README.md`.
+For accessing PostgreSQL when running the local Docker setup, see
+[Accessing PostgreSQL](docker/README.md#accessing-postgresql) in `docker/README.md`.
 
 ## Contributing
 
@@ -173,7 +173,7 @@ You can find our guidelines here [CONTRIBUTING.md](https://github.com/secvisogra
 For further reference, please consider the following sections:
 
 * [Mustache](https://docs.spring.io/spring-boot/docs/2.6.2/reference/htmlsingle/#boot-features-spring-mvc-template-engines)
-* [Spring Data Couchbase](https://docs.spring.io/spring-boot/docs/2.6.2/reference/htmlsingle/#boot-features-couchbase)
+* [Spring Data JPA](https://docs.spring.io/spring-boot/docs/2.6.2/reference/htmlsingle/#boot-features-jpa-and-spring-data)
 * [Spring Web](https://docs.spring.io/spring-boot/docs/2.6.2/reference/htmlsingle/#boot-features-developing-web-applications)
 
 [(back to top)](#bsi-secvisogram-csaf-backend)

docker/.env.example

@@ -10,16 +10,16 @@ CSAF_CMS_BACKEND_HOST=backend-cms
 # csaf-cms-backend service and as the port oauth2-proxy forwards to).
 CSAF_CMS_BACKEND_PORT=8081
 
-# CouchDB container credentials.
-CSAF_COUCHDB_PORT=5984
-CSAF_COUCHDB_SSL=false
-CSAF_COUCHDB_DBNAME=csaf
-CSAF_COUCHDB_USER=admin
-CSAF_COUCHDB_PASSWORD=admin
+# PostgreSQL (CMS Backend)
+CSAF_DB_HOST=cms-db.csaf.internal
+CSAF_DB_PORT=5432
+CSAF_DB_NAME=csaf
+CSAF_DB_USER=csaf
+CSAF_DB_PASSWORD=csaf
 
 # Keycloak
 CSAF_KEYCLOAK_PORT=9000
-CSAF_KEYCLOAK_DATABASE_PORT=5432
+CSAF_KEYCLOAK_DATABASE_PORT=5433
 CSAF_KEYCLOAK_DATABASE_NAME=keycloak
 CSAF_KEYCLOAK_DATABASE_USER=keycloak
 CSAF_KEYCLOAK_DATABASE_PASSWORD=keycloak
@@ -40,3 +40,28 @@ CSAF_CLIENT_ID=secvisogram
 CSAF_CLIENT_SECRET=dev-only-3f8a1c7e2b9d4f6a0e5c8b3d7a1f9e2c
 # https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview/#generating-a-cookie-secret
 CSAF_COOKIE_SECRET=
+
+# document templates
+CSAF_TEMPLATES_FILE=./src/test/resources/de/bsi/secvisogram/csaf_cms_backend/couchdb/model/template/allTemplates.json
+CSAF_COMPANY_LOGO_PATH=./src/test/resources/eXXcellent_solutions.png
+
+# versioning strategy: Integer or Semantic
+CSAF_VERSIONING=Semantic
+
+# revision history summary an workflow changes
+CSAF_SUMMARY_PUBLICATION=Initial Publication
+
+# validation server url for call from backend
+CSAF_VALIDATION_BASE_URL=http://localhost:8082/api/v1
+
+# max. levenshtein distance between changed values in the csaf document to decide whether a change is a patch or a minor change
+CSAF_VERSIONING_LEVENSHTEIN=4
+
+# generation of /document/tracking/id's
+
+# Base URL (of the server hosting the documents)
+CSAF_REFERENCES_BASE_URL=https://example.com
+# Company code in the temporary tracking id
+CSAF_TRACKINGID_COMPANY=exmpl
+# Number of digits of the sequential number of the tracking id. Missing digits are filled with zeros
+CSAF_TRACKINGID_DIGITS=7

docker/README.md

@@ -1,6 +1,6 @@
 # Local development with Docker
 
-This guide describes how to run the whole CSAF CMS Backend stack (CouchDB,
+This guide describes how to run the whole CSAF CMS Backend stack (PostgreSQL,
 Keycloak, oauth2-proxy, the validator service, Secvisogram and the backend
 itself) locally with Docker Compose. **This is the only guide you need if you
 just want to try out or develop against the backend locally** — you do not
@@ -31,7 +31,7 @@ should not be used in production.
 
             Container_Boundary(c1, "Backend") {
                 Container(backend, "CSAF-CMS-Backend", "Spring Boot")
-                ContainerDb(backend-db, "CouchDB", "CMS-Backend-Database")
+                ContainerDb(backend-db, "PostgreSQL", "CMS-Backend-Database")
             }
         }
 
@@ -60,12 +60,12 @@ Configuration is split across two **.env** files, each with its own
 **.env.example** template:
 
 - **`.env`** (repo root): configuration for the backend application itself
-  (CouchDB connection, OIDC issuer, document templates, versioning, tracking
+  (PostgreSQL connection, OIDC issuer, document templates, versioning, tracking
   IDs, workflow flags, ...). This is read both when running the backend on
   the host (`./mvnw spring-boot:run`) and by the containerized
   `backend-cms` compose service.
 - **`docker/.env`**: configuration needed only to orchestrate the local
-  docker compose stack itself (Keycloak, oauth2-proxy, CouchDB container
+  docker compose stack itself (Keycloak, oauth2-proxy, PostgreSQL container
   credentials, ports, ...).
 
 Follow these steps **in order**:
@@ -77,7 +77,7 @@ Follow these steps **in order**:
    cp docker/.env.example docker/.env
    ```
 
-   A few values (e.g. CouchDB credentials, the backend port) intentionally
+   A few values (e.g. PostgreSQL credentials, the backend port) intentionally
    appear in both files, with comments cross-referencing each other — keep
    them in sync if you change them.
 
@@ -87,17 +87,13 @@ Follow these steps **in order**:
 
 3. Start the stack: run `docker compose up -d --build` in folder `docker`.
 
-4. Set up your CouchDB server: open `http://127.0.0.1:5984/_utils/#/setup`
-   log in with the credentials from `docker/.env` (CSAF_COUCHDB_USER /
-   CSAF_COUCHDB_PASSWORD) and run the
-   [Single Node Setup](https://docs.couchdb.org/en/stable/setup/single-node.html).
-   This creates databases like **_users** and stops CouchDB from spamming
-   our logs (admin credentials from `docker/.env`).
+   The `cms-db` PostgreSQL container creates its database, user and password
+   from `CSAF_DB_NAME` / `CSAF_DB_USER` / `CSAF_DB_PASSWORD` in `docker/.env`
+   on first start — no manual setup step is needed. The backend then applies
+   its schema automatically via Flyway migrations on startup (see
+   [documents/couchdb-to-postgres-migration.md](../documents/couchdb-to-postgres-migration.md)).
 
-5. Create a database in CouchDB with the name specified in
-   `CSAF_COUCHDB_DBNAME`.
-
-6. Keycloak is initialized automatically: on startup it imports the `csaf`
+4. Keycloak is initialized automatically: on startup it imports the `csaf`
    realm, the `secvisogram` client, all client roles and the development
    test users from `docker/config/keycloak/csaf-realm.json` (via
    `--import-realm`). There is no manual setup step and no need to copy the
@@ -106,33 +102,34 @@ Follow these steps **in order**:
       value** (see `docker/.env.example`). Keycloak imports the realm with
       this secret and oauth2-proxy is configured with the same value, so
       both sides always match. If you change it after the first start,
-      delete the Keycloak database volume (`docker/data/keycloak-db`) so
-      the realm gets re-imported with the new secret.
+      delete the Keycloak database volume (`docker compose down` and
+      `docker volume rm docker_keycloak-db-data`) so the realm gets
+      re-imported with the new secret.
     - Note: `--import-realm` only imports the realm if it does not already
       exist. If you change the realm file later and want it re-imported,
       remove the Keycloak database volume first: `docker compose down` and
-      delete `docker/data/keycloak-db`.
+      `docker volume rm docker_keycloak-db-data`.
 
-7. (optional) Initialize the trusted CSAF provider:
+5. (optional) Initialize the trusted CSAF provider:
    `docker compose up trusted-provider-setup`.
     - The folder `docker/config/trustedprovider` contains example /
       development PGP keys.
     - More details on configuring the trusted provider can be found at
       [GoCSAF](https://github.com/gocsaf/csaf).
 
-8. (required for exports) Install
+6. (required for exports) Install
    [pandoc (tested with version 2.18)](https://pandoc.org/installing.html)
    as well as [weasyprint (tested with version 56.0)](https://weasyprint.org/)
    and make sure both are in your PATH.
 
-9. (optional for exports) Define the path to a company logo that should be
+7. (optional for exports) Define the path to a company logo that should be
    used in the exports through the environment variable
    `CSAF_COMPANY_LOGO_PATH`. The path can either be relative to the project
    root or absolute. See `.env.example` for an example.
 
-10. `backend-cms` is now running. If you are actively working on backend
-    code, see [Debugging the backend](#debugging-the-backend) below for the
-    faster host-based workflow with IDE debugging.
+8. `backend-cms` is now running. If you are actively working on backend
+   code, see [Debugging the backend](#debugging-the-backend) below for the
+   faster host-based workflow with IDE debugging.
 
 You should now be able to navigate to `http://localhost/api/v1/about`, log in
 with one of the users below and get a response from the server.
@@ -164,12 +161,15 @@ To run/debug the backend on the host (e.g. from an IDE) instead of in its contai
 To switch back to the containerized backend, set `CSAF_CMS_BACKEND_HOST` back to
 `backend-cms` and run `docker compose up -d` again.
 
-## Accessing CouchDB
+## Accessing PostgreSQL
 
-The port is defined in `docker/.env` (`CSAF_COUCHDB_PORT`, default 5984).
+The port is defined in `docker/.env` (`CSAF_DB_PORT`, default 5432). Connect
+with `psql` or any PostgreSQL client using the host/port and the credentials
+from `docker/.env` (`CSAF_DB_USER` / `CSAF_DB_PASSWORD` / `CSAF_DB_NAME`), e.g.:
 
-- CouchDB admin UI: [http://localhost:5984/_utils/#login](http://localhost:5984/_utils/#login)
-- CouchDB info: [http://localhost:5984/](http://localhost:5984/)
+```shell
+psql -h localhost -p 5432 -U csaf -d csaf
+```
 
 ## Building images and running from local source
 

docker/compose.yaml

@@ -3,19 +3,20 @@
 ###############################################################################
 
 services:
-  cms-couchdb:
-    image: couchdb:3.4
+  cms-db:
+    image: postgres:17-alpine
     restart: on-failure
     env_file: .env
     environment:
-      COUCHDB_USER: ${CSAF_COUCHDB_USER}
-      COUCHDB_PASSWORD: ${CSAF_COUCHDB_PASSWORD}
+      POSTGRES_DB: ${CSAF_DB_NAME}
+      POSTGRES_USER: ${CSAF_DB_USER}
+      POSTGRES_PASSWORD: ${CSAF_DB_PASSWORD}
     volumes:
-      - ./data/cms-db:/opt/couchdb/data
+      - cms-db-data:/var/lib/postgresql/data
     ports:
-      - "${CSAF_COUCHDB_PORT}:5984"
+      - "${CSAF_DB_PORT}:5432"
     healthcheck:
-      test: ["CMD-SHELL", "curl http://127.0.0.1:5984/_up || exit 1"]
+      test: ["CMD-SHELL", "pg_isready -U ${CSAF_DB_USER}"]
       interval: 10s
       timeout: 10s
       retries: 10
@@ -25,7 +26,7 @@ services:
     image: postgres:17-alpine
     container_name: keycloak-db
     volumes:
-      - ./data/keycloak-db:/var/lib/postgresql/data
+      - keycloak-db-data:/var/lib/postgresql/data
     env_file: .env
     environment:
       POSTGRES_DB: ${CSAF_KEYCLOAK_DATABASE_NAME}
@@ -165,7 +166,7 @@ services:
       test: ["CMD-SHELL", "wget -O /dev/null http://127.0.0.1:8082/health || exit 1"]
       interval: 10s
       timeout: 10s
-      retries: 10 
+      retries: 10
 
   backend-cms:
     image: ghcr.io/secvisogram/csaf-cms-backend:1.1.6
@@ -174,7 +175,7 @@ services:
       # Internal service names, only reachable from inside this container. The values in ../.env
       # (localhost-based) remain correct for running the backend on the host via
       # "./mvnw spring-boot:run" during debugging.
-      CSAF_COUCHDB_HOST: cms-couchdb
+      CSAF_DB_HOST: cms-db
       CSAF_VALIDATION_BASE_URL: "http://validator:8082/api/v1"
       CSAF_OIDC_JWKS_URL: "http://keycloak:8080/realms/${CSAF_REALM}/protocol/openid-connect/certs"
       CSAF_AUTOPUBLISH_URL: "http://reverse-proxy/cgi-bin/csaf_provider.go/api/upload"
@@ -191,7 +192,7 @@ services:
       retries: 10
       start_period: 30s
     depends_on:
-      cms-couchdb:
+      cms-db:
         condition: service_healthy
       keycloak:
         condition: service_healthy
@@ -235,7 +236,7 @@ services:
     build:
       context: ./container/trustedprovider
       dockerfile: Dockerfile
-    env_file: 
+    env_file:
       - .env
     environment:
       - PUID=1000
@@ -269,4 +270,10 @@ services:
     depends_on:
       trusted-provider:
         condition: service_healthy
-
+
+volumes:
+  # Named (Docker-managed) volumes rather than host bind-mounts: Postgres's initdb
+  # hard-requires chmod 0700 on its data directory. Named volumes live in Docker's own Linux-side
+  # filesystem instead, avoiding any issues with Windows.
+  cms-db-data:
+  keycloak-db-data: