Merge branch 'main' into fix_create_operations

.gitignore

@@ -1,2 +1,12 @@
 /target
 dbml-error.log
+
+# Mac OS files
+.DS_Store
+
+# workspace files
+*.code-workspace
+.vscode/
+
+# environment files
+.env*

Cargo.toml

@@ -10,13 +10,13 @@ members = [".", "entity_api", "entity", "migration", "service", "web"]
 
 [dependencies]
 service = { path = "service" }
-entity_api = {path = "entity_api" }
+entity_api = { path = "entity_api" }
 web = { path = "web" }
 
 clap = { version = "4.5.20", features = ["cargo", "derive", "env"] }
 log = "0.4.22"
 simplelog = { version = "0.12.2", features = ["paris"] }
-tokio = "1.40"
+tokio = "1.41.0"
 
 [[bin]]
 name = "seed_db"

Dockerfile

@@ -0,0 +1,74 @@
+# Stage 1: Build Stage
+FROM rust:latest AS builder
+
+# Set the working directory inside the container
+WORKDIR /usr/src/app
+
+# Install necessary packages
+RUN apt-get update && apt-get install -y \
+    bash \
+    build-essential \
+    libssl-dev \
+    pkg-config \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install the necessary Rust target for ARM64 (Raspberry Pi 5)
+RUN rustup target add aarch64-unknown-linux-gnu
+
+# Copy the main workspace Cargo.toml and Cargo.lock to define workspace structure
+COPY Cargo.toml Cargo.lock ./
+
+# Copy each module's Cargo.toml to maintain the workspace structure
+COPY ./entity/Cargo.toml ./entity/Cargo.toml
+COPY ./entity_api/Cargo.toml ./entity_api/Cargo.toml
+COPY ./migration/Cargo.toml ./migration/Cargo.toml
+COPY ./service/Cargo.toml ./service/Cargo.toml
+COPY ./web/Cargo.toml ./web/Cargo.toml
+
+# Copy the complete source code into the container's working directory
+COPY . .
+
+# Build the project
+RUN cargo build --release --workspace
+
+# logs the contents of the /usr/src/app directory to the docker build log and outputs them to the console
+RUN ls -la /usr/src/app/target/release/
+
+RUN file /usr/src/app/target/release/*
+
+# Stage 2: Runtime Stage
+FROM debian:stable-slim AS runtime
+
+# Install necessary runtime dependencies
+RUN apt-get update && apt-get install -y \
+    libssl3 \
+    libpq5 \
+    postgresql-client-15 \
+    bash \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set the working directory
+WORKDIR /usr/src/app
+
+# Copy the compiled binaries from the builder stage
+COPY --from=builder /usr/src/app/target/release/refactor_platform_rs /usr/local/bin/refactor_platform_rs
+COPY --from=builder /usr/src/app/target/release/migration /usr/local/bin/migration
+COPY --from=builder /usr/src/app/target/release/seed_db /usr/local/bin/seed_db
+
+# Create a non-root user for running the application
+RUN useradd -m appuser && \
+    chown -R appuser:appuser /usr/src/app /usr/local/bin && \
+    chmod +x /usr/local/bin/*
+
+# Switch to the non-root user
+USER appuser
+
+# Expose the necessary ports
+EXPOSE 4000
+
+# Default command starts an interactive bash shell
+# Set ENTRYPOINT to default to run the Rust binary with arguments
+ENTRYPOINT ["/bin/bash", "-c", "/usr/local/bin/refactor_platform_rs -l DEBUG -i \"$SERVICE_INTERFACE\" -p \"$SERVICE_PORT\" -d \"$DATABASE_URL\""]
+
+# Default CMD allows overriding with custom commands
+CMD ["bash"]

README.md

@@ -1,7 +1,8 @@
 [![Build & Tests (backend)](https://github.com/Jim-Hodapp-Coaching/refactor-platform-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/Jim-Hodapp-Coaching/refactor-platform-rs/actions/workflows/ci.yml)
 
 # Refactor Coaching & Mentoring Platform
-### Backend
+
+## Backend
 
 ## Intro
 
@@ -90,6 +91,7 @@ DATABASE_URL=postgres://refactor:password@localhost:5432/refactor_platform sea-o
 ```
 
 ### Generate a new Entity from Database
+
 Note that to generate a new Entity using the CLI you must ignore all other tables using the `--ignore-tables` option. You must add the option for _each_ table you are ignoring.
 
 ```bash
@@ -106,6 +108,73 @@ cargo run  -- -l DEBUG -d postgres://refactor:password@localhost:5432/refactor_p
 
 This will start the backend with log level DEBUG and attempt to connect to a Postgres DB server on the same machine with user `refactor` and password `password` on port `5432` and selecting the database named `refactor_platform`.
 
+---
+
+## Basic Container DB Setup and Management
+
+_This Rust-based backend/web API connects to a PostgreSQL database. It uses Docker and Docker Compose for local development and deployment, including utilities for database management and migrations. You can run PostgreSQL locally (via Docker) or remotely by configuring environment variables._
+
+---
+
+### Quickstart
+
+1. **Install Prerequisites**:
+   - [Docker](https://www.docker.com/products/docker-desktop) (20+)
+   - [Docker Compose](https://docs.docker.com/compose/install/) (1.29+)
+
+2. **Clone the Repository**:
+
+   ```bash
+   git clone <repository-url>
+   cd <repository-directory>
+   ```
+
+3. **Set Environment Variables**:
+   - For **local PostgreSQL**, create a `.env.local` file and set `POSTGRES_HOST=postgres`.
+   - For **remote PostgreSQL**, use a `.env.remote-db` file with `POSTGRES_HOST` pointing to the external database.
+
+4. **Build and Start the Platform**:
+   - Local PostgreSQL:
+
+     ```bash
+     docker-compose --env-file .env.local up --build
+     ```
+
+   - Remote PostgreSQL:
+
+     ```bash
+     docker-compose --env-file .env.remote-db up --build
+     ```
+
+5. **Access the API**:
+   - Visit `http://localhost:<SERVICE_PORT>` in your browser or API client.
+
+### Key Commands
+
+- **Stop all containers**:
+
+  ```bash
+  docker-compose down
+  ```
+  
+   **Note**: This will stop all containers, including the database.
+  
+- **Rebuild and restart**:
+
+  ```bash
+  docker-compose up --build
+  ```
+
+- **View logs**:
+
+  ```bash
+  docker-compose logs <service>
+  ```
+
+_For additional commands, database utilities, and debugging tips, check the [Container README](docs/runbooks/Container-README.md)._
+
+---
+
 ## Project Directory Structure
 
 `docs` - project documentation including architectural records, DB schema, API docs, etc

docker-compose.yaml

@@ -0,0 +1,51 @@
+services:
+  # Local PostgreSQL container (used for local development when needed)
+  postgres:
+    image: postgres:17  # Use PostgreSQL version 17
+    container_name: postgres  # Name the container "postgres"
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER}  # Set PostgreSQL user from environment variable
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}  # Set PostgreSQL password from environment variable
+      POSTGRES_DB: ${POSTGRES_DB}  # Set PostgreSQL database name from environment variable
+    ports:
+      - "${POSTGRES_PORT}:5432"  # Map host port to container's PostgreSQL port
+    volumes:
+      - postgres_data:/var/lib/postgresql/data  # Persist PostgreSQL data
+      - ./migration/src/setup.sql:/docker-entrypoint-initdb.d/0-setup.sql  # Initialize database with setup.sql
+      - ./migration/src/refactor_platform_rs.sql:/docker-entrypoint-initdb.d/1-refactor_plaform_rs.sql  # Initialize with refactor_platform_rs.sql
+    networks:
+      - backend_network  # Connect to backend_network
+
+  # Rust application that connects to either local or remote PostgreSQL
+  rust-app:
+    image: rust-backend  # Use the built image
+    build:
+      context: .  # Build context is current directory
+      dockerfile: Dockerfile  # Use specified Dockerfile
+      target: runtime  # Use runtime target
+    platform: ${PLATFORM}  # Specify the platform
+    container_name: ${CONTAINER_NAME}  # Name the container, default is "rust-app"
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER}  # Set PostgreSQL user from environment variable
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}  # Set PostgreSQL password from environment variable
+      POSTGRES_DB: ${POSTGRES_DB}  # Set PostgreSQL database name from environment variable
+      POSTGRES_SCHEMA: ${POSTGRES_SCHEMA}  # Set PostgreSQL schema from environment variable
+      POSTGRES_HOST: postgres  # Set PostgreSQL host to "postgres" service
+      POSTGRES_PORT: ${POSTGRES_PORT}  # Set PostgreSQL port from environment variable
+      DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:${POSTGRES_PORT}/${POSTGRES_DB}  # Configure database URL
+      SERVICE_PORT: ${SERVICE_PORT}  # Set service port from environment variable
+      SERVICE_INTERFACE: ${SERVICE_INTERFACE}  # Set service interface from environment variable
+    ports:
+      - "${SERVICE_PORT}:${SERVICE_PORT}"  # Map host port to container's service port
+    depends_on:
+      - postgres  # Ensure postgres service starts before rust-app
+    networks:
+      - backend_network  # Connect to backend_network
+    command: ["sh", "-c", "sleep 5 && /usr/local/bin/refactor_platform_rs"]  # Wait for Postgres and run the app
+
+networks:
+  backend_network:
+    driver: bridge  # Use bridge network driver
+
+volumes:
+  postgres_data:  # Define postgres_data volume