Document runtime configuration and secrets

Author: ekrov

.env.example

@@ -0,0 +1,24 @@
+# Copy this file to .env for local Docker Compose use.
+# This file contains demo values only. Never put real credentials here.
+
+POSTGRES_DB=factoryvision
+POSTGRES_USER=factoryvision
+POSTGRES_PASSWORD=factoryvision
+
+# Compose service names are used inside the Docker network.
+FACTORYVISION_DATABASE_URL=postgresql+psycopg://factoryvision:factoryvision@postgres:5432/factoryvision
+FACTORYVISION_ONNX_MODEL=/app/artifacts/models/factoryvision-segmentation.onnx
+FACTORYVISION_MODEL_NAME=factoryvision-segmentation
+FACTORYVISION_MODEL_ALIAS=candidate
+FACTORYVISION_THRESHOLD=0.5
+FACTORYVISION_MAX_UPLOAD_BYTES=10000000
+FACTORYVISION_BATCH_IMAGE_DIR=/app/data/batch/incoming
+FACTORYVISION_BATCH_ARTIFACT_DIR=/app/artifacts/batch
+FACTORYVISION_BATCH_MAX_IMAGES=
+
+AIRFLOW__CORE__SIMPLE_AUTH_MANAGER_USERS=airflow:admin
+AIRFLOW__CORE__SIMPLE_AUTH_MANAGER_PASSWORDS_FILE=/opt/airflow/simple_auth_manager_passwords.json
+MLFLOW_BACKEND_STORE_URI=postgresql://factoryvision:factoryvision@postgres:5432/mlflow
+
+GRAFANA_ADMIN_USER=admin
+GRAFANA_ADMIN_PASSWORD=factoryvision

.gitignore

@@ -1,6 +1,9 @@
 # Local learning instructions; keep them out of the public repository.
 instructions.md
 factoryvision-notion.md
+.env
+.env.*
+!.env.example
 .venv/
 __pycache__/
 *.py[cod]

README.md

@@ -510,6 +510,8 @@ The ONNX model is intentionally not stored in Git because it is a generated arti
 .venv\Scripts\python.exe scripts\export_onnx.py
 ```
 
+Configuration is documented in [`docs/configuration.md`](docs/configuration.md), with a safe [`.env.example`](.env.example) template. Copy it to `.env` for local overrides; `.env` is ignored by Git and must never contain committed credentials.
+
 Then build and start the stack:
 
 ```powershell

docker-compose.yml

@@ -2,15 +2,15 @@ services:
   postgres:
     image: postgres:16
     environment:
-      POSTGRES_DB: factoryvision
-      POSTGRES_USER: factoryvision
-      POSTGRES_PASSWORD: factoryvision
+      POSTGRES_DB: ${POSTGRES_DB:-factoryvision}
+      POSTGRES_USER: ${POSTGRES_USER:-factoryvision}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-factoryvision}
     ports:
       - "5432:5432"
     volumes:
       - postgres_data:/var/lib/postgresql/data
     healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U factoryvision -d factoryvision"]
+      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER:-factoryvision} -d $${POSTGRES_DB:-factoryvision}"]
       interval: 5s
       timeout: 5s
       retries: 10
@@ -20,8 +20,12 @@ services:
       context: .
       dockerfile: Dockerfile
     environment:
-      FACTORYVISION_DATABASE_URL: postgresql+psycopg://factoryvision:factoryvision@postgres:5432/factoryvision
-      FACTORYVISION_ONNX_MODEL: /app/artifacts/models/factoryvision-segmentation.onnx
+      FACTORYVISION_DATABASE_URL: ${FACTORYVISION_DATABASE_URL:-postgresql+psycopg://factoryvision:factoryvision@postgres:5432/factoryvision}
+      FACTORYVISION_ONNX_MODEL: ${FACTORYVISION_ONNX_MODEL:-/app/artifacts/models/factoryvision-segmentation.onnx}
+      FACTORYVISION_MODEL_NAME: ${FACTORYVISION_MODEL_NAME:-factoryvision-segmentation}
+      FACTORYVISION_MODEL_ALIAS: ${FACTORYVISION_MODEL_ALIAS:-candidate}
+      FACTORYVISION_THRESHOLD: ${FACTORYVISION_THRESHOLD:-0.5}
+      FACTORYVISION_MAX_UPLOAD_BYTES: ${FACTORYVISION_MAX_UPLOAD_BYTES:-10000000}
     ports:
       - "8000:8000"
     volumes:
@@ -38,13 +42,15 @@ services:
   postgres-init:
     image: postgres:16
     environment:
-      PGPASSWORD: factoryvision
+      PGPASSWORD: ${POSTGRES_PASSWORD:-factoryvision}
+      PGUSER: ${POSTGRES_USER:-factoryvision}
+      PGDATABASE: ${POSTGRES_DB:-factoryvision}
     entrypoint: ["/bin/sh", "-c"]
     command:
       - >-
-        until pg_isready -h postgres -U factoryvision -d factoryvision; do sleep 1; done;
-        psql -h postgres -U factoryvision -d postgres -tAc "SELECT 1 FROM pg_database WHERE datname='mlflow'" | grep -q 1 ||
-        psql -h postgres -U factoryvision -d postgres -c "CREATE DATABASE mlflow"
+        until pg_isready -h postgres -U $${POSTGRES_USER:-factoryvision} -d $${POSTGRES_DB:-factoryvision}; do sleep 1; done;
+        psql -h postgres -U $${POSTGRES_USER:-factoryvision} -d postgres -tAc "SELECT 1 FROM pg_database WHERE datname='mlflow'" | grep -q 1 ||
+        psql -h postgres -U $${POSTGRES_USER:-factoryvision} -d postgres -c "CREATE DATABASE mlflow"
     depends_on:
       postgres:
         condition: service_healthy
@@ -55,16 +61,17 @@ services:
       dockerfile: docker/Dockerfile.airflow
     environment: &airflow-environment
       AIRFLOW__CORE__EXECUTOR: LocalExecutor
-      AIRFLOW__DATABASE__SQL_ALCHEMY_CONN: postgresql+psycopg2://factoryvision:factoryvision@postgres:5432/factoryvision
+      AIRFLOW__DATABASE__SQL_ALCHEMY_CONN: ${AIRFLOW__DATABASE__SQL_ALCHEMY_CONN:-postgresql+psycopg2://factoryvision:factoryvision@postgres:5432/factoryvision}
       AIRFLOW__CORE__LOAD_EXAMPLES: "false"
       AIRFLOW__CORE__DAGS_ARE_PAUSED_AT_CREATION: "true"
       AIRFLOW__CORE__AUTH_MANAGER: airflow.api_fastapi.auth.managers.simple.simple_auth_manager.SimpleAuthManager
-      AIRFLOW__CORE__SIMPLE_AUTH_MANAGER_USERS: airflow:admin
-      AIRFLOW__CORE__SIMPLE_AUTH_MANAGER_PASSWORDS_FILE: /opt/airflow/simple_auth_manager_passwords.json
-      FACTORYVISION_DATABASE_URL: postgresql+psycopg://factoryvision:factoryvision@postgres:5432/factoryvision
-      FACTORYVISION_ONNX_MODEL: /app/artifacts/models/factoryvision-segmentation.onnx
-      FACTORYVISION_BATCH_IMAGE_DIR: /app/data/batch/incoming
-      FACTORYVISION_BATCH_ARTIFACT_DIR: /app/artifacts/batch
+      AIRFLOW__CORE__SIMPLE_AUTH_MANAGER_USERS: ${AIRFLOW__CORE__SIMPLE_AUTH_MANAGER_USERS:-airflow:admin}
+      AIRFLOW__CORE__SIMPLE_AUTH_MANAGER_PASSWORDS_FILE: ${AIRFLOW__CORE__SIMPLE_AUTH_MANAGER_PASSWORDS_FILE:-/opt/airflow/simple_auth_manager_passwords.json}
+      FACTORYVISION_DATABASE_URL: ${FACTORYVISION_DATABASE_URL:-postgresql+psycopg://factoryvision:factoryvision@postgres:5432/factoryvision}
+      FACTORYVISION_ONNX_MODEL: ${FACTORYVISION_ONNX_MODEL:-/app/artifacts/models/factoryvision-segmentation.onnx}
+      FACTORYVISION_BATCH_IMAGE_DIR: ${FACTORYVISION_BATCH_IMAGE_DIR:-/app/data/batch/incoming}
+      FACTORYVISION_BATCH_ARTIFACT_DIR: ${FACTORYVISION_BATCH_ARTIFACT_DIR:-/app/artifacts/batch}
+      FACTORYVISION_BATCH_MAX_IMAGES: ${FACTORYVISION_BATCH_MAX_IMAGES:-}
     volumes: &airflow-volumes
       - airflow_home:/opt/airflow
       - ./airflow/dags:/opt/airflow/dags
@@ -125,7 +132,7 @@ services:
       - --port
       - "5000"
       - --backend-store-uri
-      - postgresql://factoryvision:factoryvision@postgres:5432/mlflow
+      - ${MLFLOW_BACKEND_STORE_URI:-postgresql://factoryvision:factoryvision@postgres:5432/mlflow}
       - --artifacts-destination
       - /mlartifacts
       - --serve-artifacts
@@ -160,8 +167,8 @@ services:
   grafana:
     image: grafana/grafana:11.1.0
     environment:
-      GF_SECURITY_ADMIN_USER: admin
-      GF_SECURITY_ADMIN_PASSWORD: factoryvision
+      GF_SECURITY_ADMIN_USER: ${GRAFANA_ADMIN_USER:-admin}
+      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_ADMIN_PASSWORD:-factoryvision}
       GF_USERS_ALLOW_SIGN_UP: "false"
     ports:
       - "3000:3000"

docs/configuration.md

@@ -0,0 +1,67 @@
+# Configuration and secrets
+
+FactoryVision reads runtime configuration from environment variables. The
+repository includes [`.env.example`](../.env.example) as a safe template for
+local Docker Compose use. Copy it to `.env` and edit the values locally:
+
+```powershell
+Copy-Item .env.example .env
+docker compose --env-file .env up -d
+```
+
+The real `.env` file is ignored by Git. The example file contains only local
+demo values and is safe to publish; replace those values before using a real
+database or monitoring system.
+
+## Application variables
+
+| Variable | Purpose | Example or default |
+| --- | --- | --- |
+| `FACTORYVISION_DATABASE_URL` | SQLAlchemy connection string used for prediction storage | Compose: `postgresql+psycopg://...@postgres:5432/factoryvision` |
+| `FACTORYVISION_ONNX_MODEL` | Path to the ONNX model inside the running environment | `/app/artifacts/models/factoryvision-segmentation.onnx` |
+| `FACTORYVISION_MODEL_NAME` | Logical model name stored in predictions and metrics | `factoryvision-segmentation` |
+| `FACTORYVISION_MODEL_ALIAS` | Serving alias, such as `candidate` or `production` | `candidate` |
+| `FACTORYVISION_THRESHOLD` | Probability threshold used to turn pixels into defect/not-defect | `0.5` |
+| `FACTORYVISION_MAX_UPLOAD_BYTES` | Maximum accepted upload size | `10000000` |
+| `FACTORYVISION_BATCH_IMAGE_DIR` | Directory scanned by batch inference | `/app/data/batch/incoming` in Compose |
+| `FACTORYVISION_BATCH_ARTIFACT_DIR` | Directory for batch hand-off and summary artifacts | `/app/artifacts/batch` in Compose |
+| `FACTORYVISION_BATCH_MAX_IMAGES` | Optional limit for one batch run | Empty means no limit |
+
+For direct local API execution, use host paths and `localhost` in the database
+URL. For Docker Compose, use container paths and the service name `postgres`.
+The same distinction applies to Kubernetes, where paths must exist inside the
+pod and the database hostname must be a Kubernetes Service.
+
+## Service configuration
+
+| Variable | Used by | Sensitive? |
+| --- | --- | --- |
+| `POSTGRES_DB` | PostgreSQL container | No, but database details should still be environment-specific |
+| `POSTGRES_USER` | PostgreSQL and clients | No for the local demo |
+| `POSTGRES_PASSWORD` | PostgreSQL initialization | Yes outside local development |
+| `MLFLOW_BACKEND_STORE_URI` | MLflow metadata database | Contains credentials when using authenticated SQL |
+| `GRAFANA_ADMIN_USER` | Grafana login | No for the username |
+| `GRAFANA_ADMIN_PASSWORD` | Grafana login | Yes outside local development |
+| `AIRFLOW__CORE__SIMPLE_AUTH_MANAGER_USERS` | Local Airflow demo login | Contains a demo credential |
+| `AIRFLOW__CORE__SIMPLE_AUTH_MANAGER_PASSWORDS_FILE` | Airflow password-file location | No; the generated file is runtime state |
+
+Compose reads `.env` automatically; `docker-compose.yml` also supplies local
+defaults when a variable is absent. Use `docker compose config` to inspect the
+resolved configuration, but do not paste resolved output into a public issue
+or commit it because it may contain passwords.
+
+## Where secrets belong
+
+- Local development: `.env`, kept outside Git.
+- GitHub Actions: the automatically provided `GITHUB_TOKEN` is used for GHCR;
+  do not create a password line in `.env` for it.
+- Kubernetes: use a Kubernetes `Secret` for database URLs, passwords, and
+  registry credentials. Keep ordinary model and threshold settings in a
+  `ConfigMap`. The current local manifests use demo values and document where
+  a Secret should replace them.
+- Cloud deployment: use the cloud provider's secret store or managed
+  environment-variable mechanism rather than committing credentials.
+
+Never commit `.env`, access tokens, database passwords, private keys, or
+resolved deployment output. If a credential is exposed, rotate it rather than
+only deleting it from the working tree.