Initial commit: DevStack Core v1.3.0 with renamed CLI

Author: NormB

.env.example

@@ -0,0 +1,362 @@
+# DevStack Core Environment Configuration
+# Git Server (Forgejo) + Local Development Services
+#
+# Copy this file to .env and fill in the values
+# DO NOT commit .env to version control
+
+# ===========================================================================
+# HashiCorp Vault Configuration (Secrets Management & PKI)
+# ===========================================================================
+# Vault manages all service credentials and TLS certificates
+#
+# SETUP INSTRUCTIONS:
+#   1. Start services: ./devstack.sh start
+#   2. Vault auto-initializes and unseals
+#   3. Bootstrap PKI: ./devstack.sh vault-bootstrap
+#   4. Token saved to: ~/.config/vault/root-token
+#
+# After initial setup, set VAULT_TOKEN here for automatic integration
+
+VAULT_ADDR=http://vault:8200
+VAULT_TOKEN=
+
+# IMPORTANT: After running vault-init, copy the root token here:
+# VAULT_TOKEN=hvs.xxxxxxxxxxxxxxxxxxxxx
+#
+# Or leave empty and it will be read from ~/.config/vault/root-token
+
+# ===========================================================================
+# Docker Network IP Addresses (172.20.0.0/16)
+# ===========================================================================
+# Static IP addresses for services in the dev-services network
+# Change these if you need custom IP assignments or have conflicts
+#
+# Default assignments:
+POSTGRES_IP=172.20.0.10
+PGBOUNCER_IP=172.20.0.11
+MYSQL_IP=172.20.0.12
+REDIS_1_IP=172.20.0.13
+RABBITMQ_IP=172.20.0.14
+MONGODB_IP=172.20.0.15
+REDIS_2_IP=172.20.0.16
+REDIS_3_IP=172.20.0.17
+FORGEJO_IP=172.20.0.20
+VAULT_IP=172.20.0.21
+REFERENCE_API_IP=172.20.0.100
+PROMETHEUS_IP=172.20.0.101
+GRAFANA_IP=172.20.0.102
+LOKI_IP=172.20.0.103
+
+# ===========================================================================
+# TLS Configuration (Enabled by Default)
+# ===========================================================================
+# All services configured to accept BOTH encrypted and unencrypted connections
+# Certificates automatically generated by Vault PKI
+#
+# Set to 'true' to enable TLS for specific services:
+
+POSTGRES_ENABLE_TLS=true
+MYSQL_ENABLE_TLS=true
+REDIS_ENABLE_TLS=true
+RABBITMQ_ENABLE_TLS=true
+MONGODB_ENABLE_TLS=true
+FORGEJO_ENABLE_TLS=true
+
+# ===========================================================================
+# PostgreSQL Configuration (MIGRATED TO VAULT)
+# ===========================================================================
+# PostgreSQL credentials are now managed by Vault
+#
+# Credentials stored at: secret/data/postgres
+#   - user: dev_admin
+#   - password: <auto-generated by vault-bootstrap>
+#   - database: dev_database
+#
+# To retrieve password:
+#   vault kv get -field=password secret/postgres
+#
+# NOTE: POSTGRES_USER and POSTGRES_DB are still defined below (used for healthchecks
+# and Vault bootstrap), but POSTGRES_PASSWORD is intentionally empty and loaded from
+# Vault at runtime. These variables serve as service identifiers, not credentials.
+
+# PostgreSQL User Configuration (used by healthchecks and Vault bootstrap)
+POSTGRES_USER=dev_admin
+POSTGRES_DB=dev_database
+# PostgreSQL Password (loaded from Vault at runtime by manage-colima.sh)
+# Empty default to suppress docker-compose warnings (actual password loaded from Vault)
+# DO NOT set a password here - it will be loaded from Vault automatically
+POSTGRES_PASSWORD=
+
+# PostgreSQL Port Configuration
+POSTGRES_HOST_PORT=5432
+PGBOUNCER_HOST_PORT=6432
+
+# PostgreSQL Performance Tuning
+POSTGRES_MAX_CONNECTIONS=100
+POSTGRES_SHARED_BUFFERS=256MB
+POSTGRES_EFFECTIVE_CACHE_SIZE=1GB
+POSTGRES_WORK_MEM=8MB
+
+# PostgreSQL Healthcheck Configuration
+POSTGRES_HEALTH_INTERVAL=60s
+POSTGRES_HEALTH_TIMEOUT=5s
+POSTGRES_HEALTH_RETRIES=5
+POSTGRES_HEALTH_START_PERIOD=30s
+
+# ===========================================================================
+# MySQL Configuration (MIGRATED TO VAULT)
+# ===========================================================================
+# MySQL credentials are now managed by Vault
+#
+# Credentials stored at: secret/data/mysql
+#   - root_password: <auto-generated by vault-bootstrap>
+#   - user: dev_admin
+#   - password: <auto-generated by vault-bootstrap>
+#   - database: dev_database
+#
+# To retrieve password:
+#   vault kv get -field=password secret/mysql
+#   vault kv get -field=root_password secret/mysql
+
+# MySQL User Configuration (used by healthchecks and Vault bootstrap)
+MYSQL_USER=dev_admin
+MYSQL_DATABASE=dev_database
+
+# MySQL Port Configuration
+MYSQL_HOST_PORT=3306
+
+# MySQL Performance Tuning
+MYSQL_MAX_CONNECTIONS=100
+MYSQL_INNODB_BUFFER_POOL=256M
+
+# MySQL Healthcheck Configuration
+MYSQL_HEALTH_INTERVAL=60s
+MYSQL_HEALTH_TIMEOUT=5s
+MYSQL_HEALTH_RETRIES=5
+
+# ===========================================================================
+# Redis Configuration (MIGRATED TO VAULT)
+# ===========================================================================
+# Redis credentials are now managed by Vault
+#
+# Credentials stored at: secret/data/redis-1 (shared across all nodes)
+#   - password: <auto-generated by vault-bootstrap>
+#
+# To retrieve password:
+#   vault kv get -field=password secret/redis-1
+
+# Redis Port Configuration (3-node cluster)
+REDIS_1_HOST_PORT=6379
+REDIS_1_CLUSTER_PORT=16379
+REDIS_2_HOST_PORT=6380
+REDIS_2_CLUSTER_PORT=16380
+REDIS_3_HOST_PORT=6381
+REDIS_3_CLUSTER_PORT=16381
+
+# Redis Performance Tuning
+REDIS_MAXMEMORY=256mb
+
+# Redis Healthcheck Configuration
+REDIS_HEALTH_INTERVAL=60s
+REDIS_HEALTH_TIMEOUT=5s
+REDIS_HEALTH_RETRIES=5
+
+# Redis TLS Configuration
+# When REDIS_ENABLE_TLS=true, Redis runs in dual-mode accepting connections on:
+#
+# Host Port Mappings:
+#   Non-TLS (plain TCP):
+#     - localhost:6379 → redis-1:6379 (standard port)
+#     - localhost:6380 → redis-2:6379 (standard port)
+#     - localhost:6381 → redis-3:6379 (standard port)
+#
+#   TLS (encrypted):
+#     - localhost:6390 → redis-1:6380 (TLS port)
+#     - localhost:6391 → redis-2:6380 (TLS port)
+#     - localhost:6392 → redis-3:6380 (TLS port)
+#
+# Note: REDIS_ENABLE_TLS is already set in the main TLS Configuration section above
+# Certificates are pre-generated using: VAULT_ADDR=http://localhost:8200 VAULT_TOKEN=<token> ./scripts/generate-certificates.sh
+# Certificate locations: ~/.config/vault/certs/redis-{1,2,3}/
+#
+# TLS port mappings (when REDIS_ENABLE_TLS=true):
+REDIS_1_TLS_PORT=6390
+REDIS_2_TLS_PORT=6391
+REDIS_3_TLS_PORT=6392
+
+# ===========================================================================
+# RabbitMQ Configuration (MIGRATED TO VAULT)
+# ===========================================================================
+# RabbitMQ credentials are now managed by Vault
+#
+# Credentials stored at: secret/data/rabbitmq
+#   - user: dev_admin
+#   - password: <auto-generated by vault-bootstrap>
+#   - vhost: dev_vhost
+#
+# To retrieve password:
+#   vault kv get -field=password secret/rabbitmq
+
+# RabbitMQ Configuration
+RABBITMQ_VHOST=dev_vhost
+
+# RabbitMQ Port Configuration
+RABBITMQ_AMQP_PORT=5672
+RABBITMQ_MGMT_PORT=15672
+
+# RabbitMQ Healthcheck Configuration
+RABBITMQ_HEALTH_INTERVAL=60s
+RABBITMQ_HEALTH_TIMEOUT=10s
+RABBITMQ_HEALTH_RETRIES=5
+
+# ===========================================================================
+# MongoDB Configuration (MIGRATED TO VAULT)
+# ===========================================================================
+# MongoDB credentials are now managed by Vault
+#
+# Credentials stored at: secret/data/mongodb
+#   - user: dev_admin
+#   - password: <auto-generated by vault-bootstrap>
+#   - database: dev_database
+#
+# To retrieve password:
+#   vault kv get -field=password secret/mongodb
+#
+# NOTE: MONGODB_USER and MONGODB_DATABASE are still defined below (used for healthchecks
+# and Vault bootstrap). The password is fetched from Vault at container startup.
+# These variables serve as service identifiers, not credentials.
+
+# MongoDB User Configuration (used by healthchecks and Vault bootstrap)
+MONGODB_USER=dev_admin
+MONGODB_DATABASE=dev_database
+
+# MongoDB Port Configuration
+MONGODB_HOST_PORT=27017
+
+# MongoDB Healthcheck Configuration
+MONGODB_HEALTH_INTERVAL=60s
+MONGODB_HEALTH_TIMEOUT=5s
+MONGODB_HEALTH_RETRIES=5
+
+# ===========================================================================
+# Reference API (FastAPI) - Integration Testing & Examples
+# ===========================================================================
+# FastAPI reference application demonstrating infrastructure integration patterns
+# NOT production code - use as reference for implementing similar patterns
+#
+# Features:
+#   - Health checks for all infrastructure services
+#   - Vault integration examples
+#   - Database connectivity examples (PostgreSQL, MySQL, MongoDB)
+#   - Redis caching examples
+#   - RabbitMQ messaging examples
+#   - HTTPS/TLS support with Vault-managed certificates
+#
+# Access (HTTP):
+#   - API Docs: http://localhost:8000/docs
+#   - OpenAPI: http://localhost:8000/openapi.json
+#   - Health: http://localhost:8000/health/all
+#
+# Access (HTTPS - when TLS enabled):
+#   - API Docs: https://localhost:8443/docs
+#   - OpenAPI: https://localhost:8443/openapi.json
+#   - Health: https://localhost:8443/health/all
+
+REFERENCE_API_HTTP_PORT=8000
+REFERENCE_API_HTTPS_PORT=8443
+REFERENCE_API_ENABLE_TLS=true
+
+# ===========================================================================
+# Observability Stack (Prometheus, Grafana, Loki)
+# ===========================================================================
+# Prometheus: Metrics collection and time-series database
+# Grafana: Visualization and dashboarding
+# Loki: Log aggregation (API-only, query via Grafana)
+#
+# Access:
+#   - Prometheus: http://localhost:9090
+#   - Grafana: http://localhost:3001 (default: admin/admin)
+#   - Loki: API-only service (use Grafana Explore at http://localhost:3001/explore)
+#
+# Grafana Configuration:
+GRAFANA_ADMIN_USER=admin
+GRAFANA_ADMIN_PASSWORD=
+# IMPORTANT: Set a strong password! Default 'admin' is a security risk.
+# After first start, Grafana will prompt you to change the password.
+
+# Port Configuration:
+PROMETHEUS_PORT=9090
+GRAFANA_PORT=3001
+LOKI_PORT=3100
+
+# ===========================================================================
+# Forgejo Configuration (Git Server)
+# ===========================================================================
+FORGEJO_DOMAIN=localhost
+# For network access from UTM VMs, use: FORGEJO_DOMAIN=<COLIMA_IP>
+
+# ===========================================================================
+# HashiCorp Vault Configuration (Secrets Management)
+# ===========================================================================
+# Vault uses file storage backend (not dev mode)
+# Unseal keys and root token are stored in ~/.config/vault/
+#
+# IMPORTANT:
+#   - Vault will be automatically initialized on first start
+#   - Unseal keys saved to: ~/.config/vault/keys.json
+#   - Root token saved to: ~/.config/vault/root-token
+#   - BACKUP these files - they cannot be recovered if lost!
+#
+# Access Vault:
+#   - UI: http://localhost:8200/ui
+#   - CLI: export VAULT_ADDR=http://localhost:8200
+#          export VAULT_TOKEN=$(cat ~/.config/vault/root-token)
+#
+# Management:
+#   - Initialize: ./manage-colima.sh vault-init
+#   - Unseal: ./manage-colima.sh vault-unseal
+#   - Status: ./manage-colima.sh vault-status
+#   - Get token: ./manage-colima.sh vault-token
+
+# ===========================================================================
+# NOTES
+# ===========================================================================
+#
+# 1. Get Colima IP address:
+#    colima list | grep default | awk '{print $NF}'
+#
+# 2. Access services from Mac:
+#    - Forgejo: http://localhost:3000
+#    - Vault UI: http://localhost:8200/ui
+#    - PostgreSQL: localhost:5432
+#    - Redis: localhost:6379
+#    - RabbitMQ UI: http://localhost:15672
+#    - MongoDB: localhost:27017
+#    - Reference API: http://localhost:8000/docs (HTTPS: https://localhost:8443/docs)
+#    - Prometheus: http://localhost:9090
+#    - Grafana: http://localhost:3001
+#    - Loki: API-only (query via Grafana Explore)
+#
+# 3. Access from UTM VM (for development):
+#    Replace 'localhost' with Colima IP (e.g., 192.168.106.2)
+#
+# 4. Vault-Managed Secrets (All Services Migrated):
+#    - All database services now use Vault for credential management
+#    - Services: PostgreSQL, MySQL, Redis, RabbitMQ, MongoDB
+#    - Retrieve any password: vault kv get -field=password secret/<service>
+#    - List all secrets: vault kv list secret/
+#    - Example services: postgres, mysql, redis-1, rabbitmq, mongodb
+#
+# 5. TLS Certificates:
+#    - CA certificates exported to: ~/.config/vault/ca/
+#    - Trust CA on macOS: sudo security add-trusted-cert -d -r trustRoot \
+#                        -k /Library/Keychains/System.keychain \
+#                        ~/.config/vault/ca/ca-chain.pem
+#    - PostgreSQL with TLS: psql "postgresql://dev_admin@localhost:5432/dev_database?sslmode=verify-ca&sslrootcert=~/.config/vault/ca/ca-chain.pem"
+#
+# 6. Security:
+#    - Vault root token is highly sensitive - treat like master password
+#    - Backup ~/.config/vault/ directory securely
+#    - Use strong, unique passwords for each service
+#    - Different from UTM VM passwords
+#    - Store securely (e.g., password manager)