refactor(env): update environment variables and improve documentation for local development

Author: GravityDarkLab

.env.example

@@ -4,22 +4,60 @@
 ###############################################
 # - To use: `./copy-env.sh .env.dev.example .env`
 ###############################################
+# - ONLY FOLLOWING ENV VARIABLES ARE REQUIRED
+#    - JWT_SECRET
+#    - OPENAI_API_KEY
+#    - OPENAI_MODEL ( Not required but recommended)
+#    - MONGO_URL (Local or on Atlas)
+#    - GRAFANA_ADMIN_USER (defaut is admin, but recommended to change it)
+#    - GRAFANA_ADMIN_PASSWORD (defaut is admin, but recommended to change it)
+###############################################
+
 
 ##########################
 # 📦 Application Version
 ##########################
 
 APP_VERSION=1.0.0-dev      # Version of the SkillForge application (used in metrics and service info)
 
+##########################
+# (OPTIONAL) For Traefik Reverse Proxy (Emulate Production mode)
+##########################
+CLIENT_HOST=client.localhost
+SERVER_HOST=server.localhost
+GENAI_HOST=genai.localhost
+PROMETHEUS_HOST=prometheus.localhost
+ALERTMANAGER_HOST=alertmanager.localhost
+GRAFANA_HOST=grafana.localhost
+MAILHOG_HOST=mail.localhost
+#
+
+# > NOTE: They must be set in (/etc/hosts) using 
+# echo "127.0.0.1 client.localhost" >> /etc/hosts
+# echo "127.0.0.1 server.localhost" >> /etc/hosts
+# echo "127.0.0.1 genai.localhost" >> /etc/hosts
+# echo "127.0.0.1 prometheus.localhost" >> /etc/hosts
+# echo "127.0.0.1 grafana.localhost" >> /etc/hosts
+# echo "127.0.0.1 alertmanager.localhost" >> /etc/hosts
+# echo "127.0.0.1 mail.localhost" >> /etc/hosts
+
+
+##########################
+# 🍏 Spring Boot Profile
+##########################
+
+SPRING_PROFILES_ACTIVE=docker # (default: docker)
+
+
 ##########################
 # 🗃️  MongoDB Settings
 ##########################
 
 # MongoDB exposed port (defaults to 27017)
 MONGODB_EXPOSED_PORT=27017      # (default: 27017)
 MONGODB_DATABASE=skillforge_dev # Name of the database to create/use
-MONGODB_USERNAME=dev_user       # MongoDB username (choose any)
-MONGODB_PASSWORD=dev_password   # MongoDB password (choose any)
+MONGODB_USERNAME=dev_user       # MongoDB username (choose any) - default is root
+MONGODB_PASSWORD=dev_password   # MongoDB password (choose any) - default is password
 MONGO_URL=mongodb://dev_user:dev_password@mongo:27017/skillforge-dev?authSource=admin
 
 ##########################
@@ -28,36 +66,42 @@ MONGO_URL=mongodb://dev_user:dev_password@mongo:27017/skillforge-dev?authSource=
 
 # Port for the gateway service (defaults to 8081)
 SERVER_PORT_GATEWAY=8081        # (default: 8081)
-# Spring Boot active profile
-SPRING_PROFILE_ACTIVES=docker   # (default: docker)
+JWT_SECRET=dev-secret           # 🔑 JWT signing secret (REQUIRED!)
 
 ##########################
 # 👤 User Service
 ##########################
 
 # Port for user service (defaults to 8082)
 SERVER_PORT_USER=8082           # (default: 8082)
-# User service connects to MongoDB (host: mongo, matches compose service name)
-MONGODB_HOST=mongo
 JWT_SECRET=dev-secret           # 🔑 JWT signing secret (generate one)
 JWT_EXPIRATION_MS=3600000       # JWT expiration (ms, default: 1h = 3600000)
 
+##########################
+# 📘 Course Service
+##########################
+
+# Port for course service (defaults to 8083)
+SERVER_PORT_COURSE=8083         # (default: 8083)
+
+
 ##########################
 # 🖥️  Client Frontend (Vite/React)
 ##########################
 
 # Vite dev server port (defaults to 3000)
 VITE_PORT=3000                  # (default: 3000)
+BUILD_MODE=production           # (default: production)
 VITE_APP_NAME=SkillForge.ai     # (default: SkillForge.ai)
-VITE_APP_VERSION=1.0.0          # (default: 1.0.0)
+VITE_APP_VERSION=1.0.0-dev          # (default: 1.0.0)
 VITE_API_BASE_URL=/api          # (default: /api)
 VITE_API_VERSION=v1             # (default: v1)
-BUILD_MODE=production           # (default: production)
 
 # Used for Nginx/Reverse proxy
 VITE_API_INTERNAL_HOST=server-gateway         # (default: server-gateway, matches docker service)
 VITE_API_INTERNAL_PORT=8081                   # (default: 8081)
-VITE_PUBLIC_API_URL=http://server.localhost:8081/api # (default: http://server.localhost:8081/api)
+VITE_PUBLIC_API_URL=http://server.localhost:8081/api # (default: http://server.localhost:8081/api) (SHOULD BE SETUP IN YOUR YOUR local HOSTS FILE (/etc/hosts))
+
 
 ##########################
 # 🧠 GenAI Service
@@ -71,42 +115,41 @@ CORS_ALLOW_ORIGINS=*            # (default: *)
 SERVER_HOST_GENAI=skillforge-genai
 SERVER_PORT_GENAI=8888
 
+############################
+# 💡 Weaviate Vector Database
+############################
+
+# Weaviate exposed port (defaults to 8080)
+WEAVIATE_HOST=skillforge-weaviate # (default: skillforge-weaviate)
+WEAVIATE_HTTP_PORT=8080 # (default: 8080)
+WEAVIATE_GRPC_PORT=50051 # (default: 50051)
+
 ##########################
-# 🤖 LLM Provider (OpenAI or other)
+# 🤖 Genai Service
 ##########################
-
+GENAI_PORT=8888                 # (default: 8888)
+GENAI_APP_NAME=SkillForge GenAI # (default: SkillForge GenAI)
+GENAI_APP_VERSION=1.0.0         # (default: 1.0.0)
+UVICORN_WORKERS=2               # (default: 2)
+CORS_ALLOW_ORIGINS=*            # (default: *)
 LLM_PROVIDER=openai             # (default: openai)
 OPENAI_API_BASE=https://api.openai.com/v1 # (default: https://api.openai.com/v1)
 OPENAI_API_KEY=sk-xxxxxxxxxxxxxx          # 🔑 OpenAI API key (get from https://platform.openai.com)
-OPENAI_MODEL=gpt-4o-mini        # (default: gpt-4o-mini)
-
-##########################
-# 🦾 Weaviate Vector DB
-##########################
+OPENAI_MODEL=gpt-4o-mini        # (default: gpt-4o)
 
-WEAVIATE_HOST=weaviate-db       # (default: weaviate-db, matches compose service)
-WEAVIATE_EXPOSED_HTTP_PORT=8080 # (default: 8080)
-WEAVIATE_EXPOSED_GRPC_PORT=50051 # (default: 50051)
 
 ##########################
-# 📊 Monitoring Ports
+# 📊 Monitoring
 ##########################
 # Host-side ports for monitoring stack services
 PROMETHEUS_PORT=9090        # (default: 9090)
 ALERTMANAGER_PORT=9093      # (default: 9093)
 GRAFANA_EXPOSED_PORT=3001   # (default: 3001)
 LOKI_PORT=3100              # (default: 3100)
 MONGO_EXPORTER_PORT=9216    # (default: 9216)
+MAILHOG_PORT=8025           # (default: 8025)
 
-##########################
-# For Production mode
-##########################
-CLIENT_HOST=client.localhost
-SERVER_HOST=server.localhost
-GENAI_HOST=genai.localhost
-###############################################
-# ⚠️  Notes:
-# - Secrets like JWT_SECRET and OPENAI_API_KEY should NEVER be committed!
-# - All defaults match those in docker-compose and Dockerfiles.
-# - To use: `./copy-env.sh .env.dev.example .env`
-###############################################
+
+
+GRAFANA_ADMIN_USER=admin    # (default: admin)
+GRAFANA_ADMIN_PASSWORD=admin     # (default: admin)