From 4f6fc66f84e62b6768b795e040c576d33481c3f5 Mon Sep 17 00:00:00 2001
From: Henry <henry_ball@hotmail.co.uk>
Date: Fri, 13 Mar 2026 22:26:04 +0000
Subject: [PATCH] chore: add LOG_LEVEL to docker compose and readme

---
 .env.example             |  3 +++
 AGENTS.md                | 20 +++++++++++++++++++-
 README.md                |  1 +
 cloud/docker-compose.yml |  3 +++
 docker-compose.yml       |  3 +++
 turbo.json               |  3 ++-
 6 files changed, 31 insertions(+), 2 deletions(-)

diff --git a/.env.example b/.env.example
index 4b8f89e4..2b4cd8d3 100644
--- a/.env.example
+++ b/.env.example
@@ -51,6 +51,9 @@ TRELLO_APP_SECRET=
 # If not provided, rate limiting will use in-memory storage
 REDIS_URL= # e.g. redis://default:your_password@your_host:6379
 
+# Logging (optional - debug, info, warn, error; defaults to debug in dev, info in prod)
+LOG_LEVEL=
+
 # OAuth providers (optional)
 BETTER_AUTH_TRUSTED_ORIGINS=
 # Optional: Restrict OIDC/Social sign-ins to specific email domains (comma-separated)
diff --git a/AGENTS.md b/AGENTS.md
index 99b22278..65e04c69 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -185,9 +185,17 @@ Use `assertUserInWorkspace` helper for workspace checks.
 
 - Use TRPCError with appropriate codes (UNAUTHORIZED, NOT_FOUND, etc.)
 - Provide user-friendly error messages
-- Log errors appropriately
+- Log errors appropriately using the `@kan/logger` package
 - Show popup notifications for user-facing errors
 
+### Logging
+
+- Import from `@kan/logger`: `import { createLogger } from "@kan/logger"`
+- Create a module-scoped logger: `const logger = createLogger("module-name")`
+- Log level is controlled by `LOG_LEVEL` env var (debug, info, warn, error)
+- Defaults to `debug` in development, `info` in production
+- Never use `console.log` — always use the logger
+
 ## Common Patterns
 
 ### Creating a Card
@@ -219,6 +227,16 @@ Use `assertUserInWorkspace` helper for workspace checks.
 5. **Frontend**: Add UI components in `apps/web/src/`
 6. **i18n**: Add translations for new strings
 
+## Adding a New Environment Variable
+
+Update all of the following:
+
+1. `.env.example` — add the variable with an empty value and a comment explaining it
+2. `turbo.json` — add to `globalEnv` (or `globalPassThroughEnv` for CI/platform vars)
+3. `docker-compose.yml` — add to the `web` service `environment` section
+4. `cloud/docker-compose.yml` — add to the `web` service `environment` section
+5. `README.md` — add a row to the Environment Variables table
+
 ## Database Changes
 
 - Always create migrations (never modify existing migrations)
diff --git a/README.md b/README.md
index 12c987d0..ea4527f9 100644
--- a/README.md
+++ b/README.md
@@ -213,6 +213,7 @@ pnpm dev
 | `NEXT_PUBLIC_DISABLE_SIGN_UP`             | Disable sign up                                           | For authentication                    | `false`                                                     |
 | `NEXT_PUBLIC_WHITE_LABEL_HIDE_POWERED_BY` | Hide “Powered by kan.bn” on public boards (self-host)     | For white labelling                   | `true`                                                      |
 | `KAN_ADMIN_API_KEY`                       | Admin API key for stats and admin endpoints               | For admin/monitoring                  | `your-secret-admin-key`                                     |
+| `LOG_LEVEL`                               | Log verbosity level (debug, info, warn, error)            | No (defaults to debug in dev, info in prod) | `info`                                                 |
 
 See `.env.example` for a complete list of supported environment variables.
 
diff --git a/cloud/docker-compose.yml b/cloud/docker-compose.yml
index ac069743..596875f8 100644
--- a/cloud/docker-compose.yml
+++ b/cloud/docker-compose.yml
@@ -37,6 +37,9 @@ services:
       - NEXT_PUBLIC_USE_STANDALONE_OUTPUT=${NEXT_PUBLIC_USE_STANDALONE_OUTPUT}
       - REDIS_URL=${REDIS_URL}
 
+      # Logging (optional - debug, info, warn, error; defaults to debug in dev, info in prod)
+      - LOG_LEVEL=${LOG_LEVEL}
+
       # Stripe
       - STRIPE_SECRET_KEY=${STRIPE_SECRET_KEY}
       - STRIPE_WEBHOOK_SECRET=${STRIPE_WEBHOOK_SECRET}
diff --git a/docker-compose.yml b/docker-compose.yml
index eaa56b81..f731cebe 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -37,6 +37,9 @@ services:
       # Redis (optional - for rate limiting)
       - REDIS_URL=${REDIS_URL}
 
+      # Logging (optional - debug, info, warn, error; defaults to debug in dev, info in prod)
+      - LOG_LEVEL=${LOG_LEVEL}
+
       # Admin API key (optional)
       - KAN_ADMIN_API_KEY=${KAN_ADMIN_API_KEY}
 
diff --git a/turbo.json b/turbo.json
index 47274710..d3f74541 100644
--- a/turbo.json
+++ b/turbo.json
@@ -129,7 +129,8 @@
     "BETTER_AUTH_TRUSTED_ORIGINS",
     "NOVU_API_KEY",
     "EMAIL_UNSUBSCRIBE_SECRET",
-    "REDIS_URL"
+    "REDIS_URL",
+    "LOG_LEVEL"
   ],
   "globalPassThroughEnv": [
     "NODE_ENV",