Add a skeleton backend

.env.example

@@ -0,0 +1,87 @@
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# Variables used to:
+# - create and configure 2 databases running inside a Docker container
+#   The postgres and web ap databases are created **once** when the postgres container
+#   (aka. learn-dev-postgres service) is run for **the first time**.
+# - configure the Docker external port mapping for the postgres container
+#
+# Procedure:
+# - Set a value for POSTGRES_PASSWORD, and LEARNDEV_DB_PASSWORD.
+# - Leave other variables unchanged because defaults are fine.
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+# ~~~ Postgres Docker container port mapping ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+# Host port mapped to the internal Postgres container's port 5432.
+# Only the host side is configurable here. 5432 is fixed inside the container.
+# Use a non-standard port (e.g. 5433) to avoid clashing with a local Postgres install.
+# See: https://docs.docker.com/engine/reference/commandline/run/#publish
+#
+POSTGRES_PORT=5433
+
+# Exposed postgres host network interface.
+# Docker accepts incoming requests on this interface and routes them
+#   to Postgres running in the Docker container.
+# Default value is 0.0.0.0 (IP v4)) and :: (IP V6),
+#   meaning all network interfaces.
+# See: https://docs.docker.com/engine/reference/commandline/run/#publish
+#
+POSTGRES_HOST=127.0.0.1
+
+## ~~~ Postgres  database and user ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+# Name of the Postgres superuser
+# Default value is postgres.
+# See: https://hub.docker.com/_/postgres#postgres_user
+#
+# POSTGRES_USER=postgres
+
+# Name of the default database.
+# Default value is the same as POSTGRES_USER (if set), otherwise postgres.
+# See: https://hub.docker.com/_/postgres#postgres_db
+#
+# POSTGRES_DB=postgres
+
+# Authentication method used for host connections.
+# Use scram-sha-256 for password authentication.
+# See: https://hub.docker.com/_/postgres#postgres_host_auth_method
+#
+POSTGRES_HOST_AUTH_METHOD=scram-sha-256
+
+# This is the superuser password.
+# This is NOT the application database user password.
+# See: https://hub.docker.com/_/postgres#postgres_password
+#
+POSTGRES_PASSWORD=TODO_SET_A_VALUE_HERE
+
+
+# ~~~ Application database and user  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# Created by docker/init/01-create-app-db-user.sh **on first** container start.
+# These variables are also referenced in Spring Boot's application.yaml
+# configuration file to configure the datasource.
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+# Name of the application database.
+#
+LEARNDEV_DB_NAME=learndev
+
+# Name of the application database "user" (regular role, not a superuser role).
+#
+LEARNDEV_DB_USER=learndev
+
+# Password for the application database user (role).
+# This is NOT the superuser password.
+#
+LEARNDEV_DB_PASSWORD=TODO_SET_A_VALUE_HERE
+
+
+# ~~~~ Spring Boot  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+# Default Spring Boot active profile: dev
+# Do not set SPRING_PROFILES_ACTIVE for test/staging/production environments,
+# because they will be set somewhere else.
+# Loads app configuration from application.yaml, then overrides it
+# with application-dev.yaml.
+# See: https://docs.spring.io/spring-boot/3.5/how-to/properties-and-configuration.html#howto.properties-and-configuration.set-active-spring-profiles
+#
+SPRING_PROFILES_ACTIVE=dev

.gitattributes

@@ -0,0 +1,2 @@
+/mvnw text eol=lf
+*.cmd text eol=crlf

.mvn/wrapper/maven-wrapper.properties

@@ -0,0 +1,3 @@
+wrapperVersion=3.3.4
+distributionType=only-script
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.15/apache-maven-3.9.15-bin.zip

CONTRIBUTING.md

@@ -230,13 +230,14 @@ learn-dev/
 │   │           │
 │   │           └── audit/
 │   │               └── AuditServiceTest.java
-│   │ 
-│   │ 
-│   └── postman/                            # Contains the Postman requests to test the REST endpoints
-│       ├── learndev.environment.json       # Postman environment file with placeholders (adjust to your local config.) 
-│       └── learndev.collection.json        # Collection of Postman requests, with folders per feature  
-│   
-│   
+│    
+│    
+├── docker/                         # Docker scripts
+│   └── init/
+│       └── 01-create-app-user.sh   # Runs once on first postgres:17 container start to create application database and user 
+└── postman/                        # Contains the Postman requests to test the REST endpoints
+    ├── learndev.environment.json   # Postman environment file with placeholders (adjust to your local config.) 
+    └── learndev.collection.json    # Collection of Postman requests, with folders per feature  
 ```
 
 The table below explains what each folder entails.
@@ -599,7 +600,7 @@ chore(git): Ignore IntelliJ IDEA configuration files
 
 ### Code Style and Formatting
 
-TODO: Document the code style and formatting
+: Document the code style and formatting
 
 
 ### Reset the Development Database

HELP.md

@@ -0,0 +1,38 @@
+# Getting Started
+
+### Reference Documentation
+
+For further reference, please consider the following sections:
+
+* [Official Apache Maven documentation](https://maven.apache.org/guides/index.html)
+* [Spring Boot Maven Plugin Reference Guide](https://docs.spring.io/spring-boot/3.5.14/maven-plugin)
+* [Create an OCI image](https://docs.spring.io/spring-boot/3.5.14/maven-plugin/build-image.html)
+* [Spring Boot Actuator](https://docs.spring.io/spring-boot/3.5.14/reference/actuator/index.html)
+* [Spring Data JPA](https://docs.spring.io/spring-boot/3.5.14/reference/data/sql.html#data.sql.jpa-and-spring-data)
+* [Liquibase Migration](https://docs.spring.io/spring-boot/3.5.14/how-to/data-initialization.html#howto.data-initialization.migration-tool.liquibase)
+* [Spring Security](https://docs.spring.io/spring-boot/3.5.14/reference/web/spring-security.html)
+* [Thymeleaf](https://docs.spring.io/spring-boot/3.5.14/reference/web/servlet.html#web.servlet.spring-mvc.template-engines)
+* [Spring Web](https://docs.spring.io/spring-boot/3.5.14/reference/web/servlet.html)
+
+### Guides
+
+The following guides illustrate how to use some features concretely:
+
+* [Building a RESTful Web Service with Spring Boot Actuator](https://spring.io/guides/gs/actuator-service/)
+* [Accessing Data with JPA](https://spring.io/guides/gs/accessing-data-jpa/)
+* [Securing a Web Application](https://spring.io/guides/gs/securing-web/)
+* [Spring Boot and OAuth2](https://spring.io/guides/tutorials/spring-boot-oauth2/)
+* [Authenticating a User with LDAP](https://spring.io/guides/gs/authenticating-ldap/)
+* [Handling Form Submission](https://spring.io/guides/gs/handling-form-submission/)
+* [Building a RESTful Web Service](https://spring.io/guides/gs/rest-service/)
+* [Serving Web Content with Spring MVC](https://spring.io/guides/gs/serving-web-content/)
+* [Building REST services with Spring](https://spring.io/guides/tutorials/rest/)
+
+### Maven Parent overrides
+
+Due to Maven's design, elements are inherited from the parent POM to the project POM.
+While most of the inheritance is fine, it also inherits unwanted elements like `<license>` and `<developers>` from the
+parent.
+To prevent this, the project POM contains empty overrides for these elements.
+If you manually switch to a different parent and actually want the inheritance, you need to remove those overrides.
+

README.md

@@ -71,6 +71,26 @@ See the [Tech Stack](#tech-stack) section.
 
 TODO
 
+#### Docker Setup
+
+From the project root folder.
+
+- Install Docker 
+  - on macOS (read [this for Windows or Linux install](https://docs.docker.com/get-started/get-docker/)):  
+    ```shell
+    brew install docker docker-compose docker-desktop
+    ```
+  - on [Windows and Linux](https://docs.docker.com/get-started/get-docker/)
+- Downloads the Docker images for this application,
+  then runs the containers configured in the  `docker-compose.yaml` configuration file:
+  ```shell
+  docker compose up -d
+  docker compose logs
+  ```
+  A Docker init script creates the application database and user when the `learn-dev-postgres` container 
+  is run for the first time.   
+- Run the application: TODO
+
 
 ## Project Status
 

docker-compose.yaml

@@ -0,0 +1,24 @@
+services:
+
+  db:
+    image: postgres:17
+    container_name: learn-dev-postgres
+
+    # Inject database credentials and config (db name, db user,
+    # and host port mapping) into the container.
+    # Reads from the same .env file passed to `docker compose --env-file ...`.
+    env_file:
+      - .env
+
+    volumes:
+      # Init scripts: run once on first container start (empty data dir).
+      - ./docker/init:/docker-entrypoint-initdb.d
+      # Named volume: preserves data across container stop/start cycles.
+      - pgdata:/var/lib/postgresql/data
+
+    ports:
+      # See src/main/resources/.env.example for details
+      - "${POSTGRES_HOST}:${POSTGRES_PORT}:5432"
+
+volumes:
+  pgdata:

docker/init/01-create-app-db-user.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# Postgres container init script — runs automatically on first container start
+# (when /var/lib/postgresql/data is empty).
+#
+# Creates:
+#   - a regular (non-superuser) database role: LEARNDEV_DB_USER
+#   - the application database:                LEARNDEV_DB_NAME
+#
+# Required container env vars (set via --env-file):
+#   LEARNDEV_DB_NAME      — name of the application database
+#   LEARNDEV_DB_USER      — name of the application role      (database "user" name")
+#   LEARNDEV_DB_PASSWORD  — password for the application role (database "user" password)
+#
+# See .env.example for details
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+# Exit on error
+set -e
+
+echo "Creating database '${LEARNDEV_DB_NAME}' and role (database user) '${LEARNDEV_DB_USER}'..."
+
+psql -v ON_ERROR_STOP=1 \
+     --username "$POSTGRES_USER" \
+     --dbname   "$POSTGRES_DB"   \
+<<-EOSQL
+    CREATE USER     "${LEARNDEV_DB_USER}" WITH PASSWORD '${LEARNDEV_DB_PASSWORD}';
+    CREATE DATABASE "${LEARNDEV_DB_NAME}" OWNER "${LEARNDEV_DB_USER}";
+    GRANT ALL PRIVILEGES ON DATABASE "${LEARNDEV_DB_NAME}" TO "${LEARNDEV_DB_USER}";
+EOSQL
+
+echo "SUCCESS: Created database '${LEARNDEV_DB_NAME}' and role (database user) '${LEARNDEV_DB_USER}' "