Merge pull request #97 from fboucher/docs-update-keycloak

Refactors Docker Compose and updates deployment guides

Author: fboucher

.env-sample

@@ -1,22 +1,29 @@
-# NoteBookmark Docker Compose Environment Variables
-# Copy this file to .env and replace all placeholder values with your actual configuration
+# Copy to docker-compose/.env and set values.
 
-# Keycloak Admin Credentials
-KEYCLOAK_ADMIN_PASSWORD=your-secure-admin-password
+# Keycloak
+KEYCLOAK_USER=admin
+KEYCLOAK_PASSWORD=admin
 
-# Keycloak Client Configuration
+# Keycloak host (local default).
+KEYCLOAK_URL=localhost
+
+# Postgres for Keycloak.
+POSTGRES_USER=keycloak
+POSTGRES_PASSWORD=change-me
+
+# App auth (OIDC)
 KEYCLOAK_AUTHORITY=http://localhost:8080/realms/notebookmark
 KEYCLOAK_CLIENT_ID=notebookmark
-KEYCLOAK_CLIENT_SECRET=your-keycloak-client-secret
+KEYCLOAK_CLIENT_SECRET=replace-with-client-secret
 
-# Azure Storage - Table Storage Connection
-NB_STORAGE_OUTPUTS_TABLEENDPOINT=https://your-storage-account.table.core.windows.net/
+# Optional
+# Keycloak__RequireHttpsMetadata=false
 
-# Azure Storage - Blob Storage Connection
+# AI
+REKA_API_KEY=replace-with-reka-api-key
+
+# Storage
+NB_STORAGE_OUTPUTS_TABLEENDPOINT=https://your-storage-account.table.core.windows.net/
 NB_STORAGE_OUTPUTS_BLOBENDPOINT=https://your-storage-account.blob.core.windows.net/
 
-# Notes:
-# - Never commit the .env file to version control
-# - Keep credentials secure and rotate them regularly
-# - For local development, you can use "admin" as KEYCLOAK_ADMIN_PASSWORD
-# - For production, use strong passwords and proper Azure Storage connection strings
+# Do not commit docker-compose/.env.

README.md

@@ -15,6 +15,17 @@ NoteBookmark is composed of three main sections:
 
 ![Slide show of all NoteBookmark Screens](gh/images/NoteBookmark-Tour_hd.gif)
 
+## Run Options
+
+- Development: running the Aspire project is the easiest path and everything is wired automatically.
+- Production-style: run with containers and deploy to Azure.
+
+Run locally with Aspire:
+
+```bash
+dotnet run --project src/NoteBookmark.AppHost
+```
+
 ## How to deploy Your own NoteBookmark
 
 ### Get the code on your machine
@@ -52,8 +63,9 @@ Voila! Your app is now secure.
 ## Documentation
 
 For detailed setup guides and configuration information:
+- [Keycloak Container Setup](/docs/keycloak-container-setup.md) - Start a local Keycloak instance if you do not already have one
 - [Keycloak Authentication Setup](/docs/keycloak-setup.md) - Complete guide for setting up Keycloak authentication
-- [Docker Compose Deployment](/docs/docker-compose-deployment.md) - Deploy with Docker Compose (generate from Aspire or use provided files)
+- [Docker Compose Deployment](/docs/docker-compose-deployment.md) - Deploy NoteBookmark containers (assumes a healthy Keycloak + configured realm)
 
 ## Contributing
 

docker-compose/build-and-push.ps1

@@ -0,0 +1,51 @@
+name: notebookmark-keycloak
+
+services:
+  keycloak_postgres:
+    container_name: keycloak-postgres
+    image: postgres:14.18
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: keycloak
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    networks:
+      - notebookmark
+
+  keycloak:
+    container_name: notebookmark-keycloak
+    image: quay.io/keycloak/keycloak:26.5.4
+    restart: unless-stopped
+    command:
+      - start
+    environment:
+      KC_BOOTSTRAP_ADMIN_USERNAME: ${KEYCLOAK_USER}
+      KC_BOOTSTRAP_ADMIN_PASSWORD: ${KEYCLOAK_PASSWORD}
+      KC_HOSTNAME: ${KEYCLOAK_URL}
+      KC_DB: postgres
+      KC_DB_URL: jdbc:postgresql://keycloak_postgres:5432/keycloak
+      KC_DB_USERNAME: ${POSTGRES_USER}
+      KC_DB_PASSWORD: ${POSTGRES_PASSWORD}
+      KC_PROXY_ADDRESS_FORWARDING: "true"
+      KC_HTTP_ENABLED: "true"
+      KC_LOG_LEVEL: info
+      KC_FEATURES: "token-exchange"
+    ports:
+      - "8080:8080"
+    # Optional production TLS setup: place cert/key under docker-compose/data/certs.
+    # These values can remain unset for local HTTP usage.
+    volumes:
+      - ./data/certs:/etc/x509/https:ro
+    depends_on:
+      - keycloak_postgres
+    networks:
+      - notebookmark
+
+networks:
+  notebookmark:
+    external: true
+
+volumes:
+  postgres-data:

docker-compose/docker-compose.yaml

@@ -0,0 +1,53 @@
+name: notebookmark-app
+
+services:
+  api:
+    image: fboucher/notebookmark-api:alpha-latest
+    container_name: notebookmark-api
+    restart: unless-stopped
+    environment:
+      OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES: "true"
+      OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES: "true"
+      OTEL_DOTNET_EXPERIMENTAL_OTLP_RETRY: "in_memory"
+      ASPNETCORE_FORWARDEDHEADERS_ENABLED: "true"
+      HTTP_PORTS: "8000"
+      ConnectionStrings__nb-tables: ${NB_STORAGE_OUTPUTS_TABLEENDPOINT}
+      ConnectionStrings__nb-blobs: ${NB_STORAGE_OUTPUTS_BLOBENDPOINT}
+    ports:
+      - "8001:8000"
+      - "8003:8002"
+    networks:
+      - notebookmark
+
+  blazor-app:
+    image: fboucher/notebookmark-blazor:alpha-latest
+    container_name: notebookmark-blazor
+    restart: unless-stopped
+    environment:
+      OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES: "true"
+      OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES: "true"
+      OTEL_DOTNET_EXPERIMENTAL_OTLP_RETRY: "in_memory"
+      ASPNETCORE_FORWARDEDHEADERS_ENABLED: "true"
+      HTTP_PORTS: "8004"
+      services__api__http__0: "http://api:8000"
+      services__keycloak__http__0: "http://keycloak:8080"
+      ConnectionStrings__nb-tables: ${NB_STORAGE_OUTPUTS_TABLEENDPOINT}
+      ConnectionStrings__nb-blobs: ${NB_STORAGE_OUTPUTS_BLOBENDPOINT}
+      REKA_API_KEY: ${REKA_API_KEY}
+      Keycloak__Authority: ${KEYCLOAK_AUTHORITY}
+      Keycloak__ClientId: ${KEYCLOAK_CLIENT_ID}
+      Keycloak__ClientSecret: ${KEYCLOAK_CLIENT_SECRET}
+    volumes:
+      - ./dataprotection-keys:/root/.aspnet/DataProtection-Keys
+    ports:
+      - "8005:8004"
+      - "8007:8006"
+    depends_on:
+      api:
+        condition: service_started
+    networks:
+      - notebookmark
+
+networks:
+  notebookmark:
+    external: true