@venizia/ignis-docs 0.0.3 → 0.0.4-1

package/wiki/references/components/socket-io.md

@@ -125,3 +125,21 @@ import { SocketIOServerHelper, SocketIOBindingKeys, inject } from '@venizia/igni
     });
   }
 ```
+
+## See Also
+
+- **Related Concepts:**
+  - [Components Overview](/guides/core-concepts/components) - Component system basics
+  - [Application](/guides/core-concepts/application/) - Registering components
+
+- **Other Components:**
+  - [Components Index](./index) - All built-in components
+
+- **References:**
+  - [Socket.IO Helper](/references/helpers/socket-io) - Socket.IO utilities
+
+- **External Resources:**
+  - [Socket.IO Documentation](https://socket.io/docs/) - WebSocket library
+
+- **Tutorials:**
+  - [Real-Time Chat](/guides/tutorials/realtime-chat) - Building a chat app with Socket.IO

package/wiki/references/components/static-asset.md

@@ -264,7 +264,6 @@ this.bind({
 this.component(StaticAssetComponent);
 ```
 
----
 
 ## MetaLink: Database File Tracking
 
@@ -530,7 +529,6 @@ DELETE /uploads/buckets/user-uploads/objects/document.pdf
 - Deletes MetaLink record from database
 - Returns `{ "success": true }`
 
----
 
 ## Storage Helpers
 
@@ -573,7 +571,6 @@ app_data/storage/
 - Metadata stored in file stats
 - Stream-based file operations
 
----
 
 ### MinioHelper (S3-Compatible Storage)
 
@@ -603,7 +600,6 @@ const minioHelper = new MinioHelper({
 });
 ```
 
----
 
 ## IStorageHelper Interface
 
@@ -640,7 +636,6 @@ interface IStorageHelper {
 }
 ```
 
----
 
 ## API Endpoints
 
@@ -663,7 +658,6 @@ GET /{basePath}/buckets
 ]
 ```
 
----
 
 #### **Get Bucket by Name**
 
@@ -683,7 +677,6 @@ GET /{basePath}/buckets/:bucketName
 { "name": "my-bucket", "creationDate": "2025-01-01T00:00:00.000Z" }
 ```
 
----
 
 #### **Create Bucket**
 
@@ -699,7 +692,6 @@ POST /{basePath}/buckets/:bucketName
 { "name": "my-bucket", "creationDate": "2025-12-13T00:00:00.000Z" }
 ```
 
----
 
 #### **Delete Bucket**
 
@@ -715,7 +707,6 @@ DELETE /{basePath}/buckets/:bucketName
 { "success": true }
 ```
 
----
 
 #### **Upload Files**
 
@@ -777,7 +768,6 @@ const result = await response.json();
 console.log(result[0].metaLink); // Database record (if MetaLink enabled)
 ```
 
----
 
 #### **Get Object (Stream)**
 
@@ -799,7 +789,6 @@ GET /{basePath}/buckets/:bucketName/objects/:objectName
 - Content-Length: File size in bytes
 - X-Content-Type-Options: `nosniff`
 
----
 
 #### **Download Object**
 
@@ -822,7 +811,6 @@ const downloadUrl = `/assets/buckets/uploads/objects/${encodeURIComponent('docum
 window.open(downloadUrl, '_blank');
 ```
 
----
 
 #### **Delete Object**
 
@@ -839,7 +827,6 @@ DELETE /{basePath}/buckets/:bucketName/objects/:objectName
 { "success": true }
 ```
 
----
 
 #### **List Objects**
 
@@ -864,7 +851,6 @@ GET /{basePath}/buckets/:bucketName/objects
 ]
 ```
 
----
 
 #### **Delete Object**
 
@@ -905,7 +891,6 @@ await fetch(`/assets/buckets/${bucketName}/objects/${encodeURIComponent(objectNa
 // MetaLink record deleted from database (if enabled)
 ```
 
----
 
 #### **Sync MetaLink** (MetaLink only)
 
@@ -996,7 +981,6 @@ for (const obj of objects) {
 }
 ```
 
----
 
 ## Security Features
 
@@ -1049,7 +1033,6 @@ X-Content-Type-Options: nosniff
 Content-Disposition: attachment; filename="..."
 ```
 
----
 
 ## Usage Examples
 
@@ -1146,7 +1129,6 @@ async function listFiles(bucketName: string, prefix?: string) {
 }
 ```
 
----
 
 ## Custom Storage Implementation
 
@@ -1188,7 +1170,6 @@ this.bind<TStaticAssetsComponentOptions>({
 });
 ```
 
----
 
 ## Troubleshooting
 
@@ -1243,7 +1224,6 @@ extra: {
 }
 ```
 
----
 
 ## Docker Setup for Development
 
@@ -1279,11 +1259,19 @@ docker-compose up -d
 http://localhost:9001
 ```
 
----
 
-## Related Documentation
+## See Also
+
+- **Related Concepts:**
+  - [Components Overview](/guides/core-concepts/components) - Component system basics
+  - [Controllers](/guides/core-concepts/controllers) - File upload endpoints
+
+- **Other Components:**
+  - [Components Index](./index) - All built-in components
+
+- **References:**
+  - [Storage Helpers](/references/helpers/storage) - DiskHelper, MinIOHelper, BaseStorageHelper
+  - [Request Utilities](/references/utilities/request) - File upload utilities
 
-- [Storage Helpers](../helpers/storage.md) - DiskHelper, MinioHelper, BaseStorageHelper
-- [Request Utilities](../utilities/request.md) - `parseMultipartBody`, `createContentDispositionHeader`
-- [Components Overview](./index.md)
-- [Controllers](../base/controllers.md)
+- **Best Practices:**
+  - [Security Guidelines](/best-practices/security-guidelines) - File upload security

package/wiki/references/components/swagger.md

@@ -173,3 +173,20 @@ By default, the documentation is available at the following endpoints:
 -   **/doc/openapi.json**: The raw OpenAPI specification.
 
 These paths can be configured by providing custom `ISwaggerOptions`. This feature provides a powerful and flexible way to document your APIs, making them easier to consume and understand.
+
+## See Also
+
+- **Related Concepts:**
+  - [Components Overview](/guides/core-concepts/components) - Component system basics
+  - [Controllers](/guides/core-concepts/controllers) - Defining OpenAPI routes
+
+- **Other Components:**
+  - [Components Index](./index) - All built-in components
+
+- **References:**
+  - [Schema Utilities](/references/utilities/schema) - Response schema helpers
+  - [JSX Utilities](/references/utilities/jsx) - HTML response schemas
+
+- **External Resources:**
+  - [OpenAPI Specification](https://swagger.io/specification/) - OpenAPI standard
+  - [Scalar Documentation](https://github.com/scalar/scalar) - API documentation UI

package/wiki/references/configuration/environment-variables.md

@@ -0,0 +1,427 @@
+# Environment Variables Reference
+
+Complete reference of all environment variables used by Ignis framework.
+
+
+## Overview
+
+Ignis uses the `APP_ENV_` prefix for all framework-specific environment variables. This prevents conflicts with system variables like `PATH`, `HOME`, etc.
+
+```bash
+# ✅ Ignis variables
+APP_ENV_POSTGRES_HOST=localhost
+
+# ❌ Might conflict with system
+POSTGRES_HOST=localhost
+```
+
+### Accessing Environment Variables
+
+```typescript
+// Direct access
+const host = process.env.APP_ENV_POSTGRES_HOST;
+
+// Using applicationEnvironment helper (recommended)
+import { applicationEnvironment, EnvironmentKeys } from '@venizia/ignis';
+const host = applicationEnvironment.get<string>(EnvironmentKeys.APP_ENV_POSTGRES_HOST);
+```
+
+
+## Quick Start Template
+
+Create a `.env` file in your project root:
+
+```bash
+# .env
+
+# =====================
+# APPLICATION
+# =====================
+APP_ENV_APPLICATION_NAME=my-app
+APP_ENV_APPLICATION_TIMEZONE=UTC
+
+# =====================
+# SERVER
+# =====================
+APP_ENV_SERVER_HOST=0.0.0.0
+APP_ENV_SERVER_PORT=3000
+APP_ENV_SERVER_BASE_PATH=/api
+
+# =====================
+# DATABASE (PostgreSQL)
+# =====================
+APP_ENV_POSTGRES_HOST=localhost
+APP_ENV_POSTGRES_PORT=5432
+APP_ENV_POSTGRES_USERNAME=postgres
+APP_ENV_POSTGRES_PASSWORD=your_password_here
+APP_ENV_POSTGRES_DATABASE=my_database
+
+# =====================
+# AUTHENTICATION
+# =====================
+APP_ENV_APPLICATION_SECRET=generate-a-strong-random-secret
+APP_ENV_JWT_SECRET=generate-another-strong-random-secret
+APP_ENV_JWT_EXPIRES_IN=86400
+
+# =====================
+# LOGGING
+# =====================
+APP_ENV_LOGGER_FOLDER_PATH=./logs
+```
+
+> **Important:** Add `.env` to your `.gitignore` to prevent committing secrets.
+
+
+## Application Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `APP_ENV_APPLICATION_NAME` | No | `APP` | Application name, used in logs and identification |
+| `APP_ENV_APPLICATION_TIMEZONE` | No | `Asia/Ho_Chi_Minh` | Default timezone for date operations |
+| `APP_ENV_APPLICATION_ROLES` | No | - | Comma-separated list of application roles |
+
+### Example
+
+```bash
+APP_ENV_APPLICATION_NAME=ignis-backend
+APP_ENV_APPLICATION_TIMEZONE=UTC
+APP_ENV_APPLICATION_ROLES=api,worker
+```
+
+
+## Server Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `APP_ENV_SERVER_HOST` | No | `localhost` | Server bind address |
+| `APP_ENV_SERVER_PORT` | No | `3000` | Server port |
+| `APP_ENV_SERVER_BASE_PATH` | No | `/` | Base path for all routes |
+| `HOST` | No | - | Alternative to `APP_ENV_SERVER_HOST` |
+| `PORT` | No | - | Alternative to `APP_ENV_SERVER_PORT` |
+
+### Example
+
+```bash
+# Development
+APP_ENV_SERVER_HOST=localhost
+APP_ENV_SERVER_PORT=3000
+APP_ENV_SERVER_BASE_PATH=/api
+
+# Production
+APP_ENV_SERVER_HOST=0.0.0.0
+APP_ENV_SERVER_PORT=8080
+APP_ENV_SERVER_BASE_PATH=/v1/api
+```
+
+### Priority Order
+
+The server configuration uses this priority:
+1. Explicit config in `appConfigs`
+2. `APP_ENV_SERVER_*` variables
+3. `HOST`/`PORT` variables (for cloud platforms)
+4. Default values
+
+
+## Database Variables (PostgreSQL)
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `APP_ENV_POSTGRES_HOST` | Yes* | `localhost` | Database host |
+| `APP_ENV_POSTGRES_PORT` | No | `5432` | Database port |
+| `APP_ENV_POSTGRES_USERNAME` | Yes* | `postgres` | Database username |
+| `APP_ENV_POSTGRES_PASSWORD` | Yes* | - | Database password |
+| `APP_ENV_POSTGRES_DATABASE` | Yes* | - | Database name |
+| `APP_ENV_DATASOURCE_NAME` | No | - | DataSource identifier |
+
+*Required when using PostgreSQL DataSource.
+
+### Example
+
+```bash
+# Local development
+APP_ENV_POSTGRES_HOST=localhost
+APP_ENV_POSTGRES_PORT=5432
+APP_ENV_POSTGRES_USERNAME=postgres
+APP_ENV_POSTGRES_PASSWORD=password
+APP_ENV_POSTGRES_DATABASE=my_app_dev
+
+# Production
+APP_ENV_POSTGRES_HOST=db.example.com
+APP_ENV_POSTGRES_PORT=5432
+APP_ENV_POSTGRES_USERNAME=app_user
+APP_ENV_POSTGRES_PASSWORD=strong_password_here
+APP_ENV_POSTGRES_DATABASE=my_app_prod
+```
+
+### DataSource Configuration
+
+```typescript
+@datasource({ driver: 'node-postgres' })
+export class PostgresDataSource extends BaseDataSource {
+  constructor() {
+    super({
+      name: PostgresDataSource.name,
+      config: {
+        host: process.env.APP_ENV_POSTGRES_HOST ?? 'localhost',
+        port: +(process.env.APP_ENV_POSTGRES_PORT ?? 5432),
+        database: process.env.APP_ENV_POSTGRES_DATABASE ?? 'mydb',
+        user: process.env.APP_ENV_POSTGRES_USERNAME ?? 'postgres',
+        password: process.env.APP_ENV_POSTGRES_PASSWORD ?? '',
+      },
+    });
+  }
+}
+```
+
+
+## Authentication Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `APP_ENV_APPLICATION_SECRET` | **Yes** | - | Secret for encrypting JWT payload |
+| `APP_ENV_JWT_SECRET` | **Yes** | - | Secret for signing JWT tokens |
+| `APP_ENV_JWT_EXPIRES_IN` | No | `86400` | Token expiration in seconds (24h default) |
+
+### Security Requirements
+
+Both `APP_ENV_APPLICATION_SECRET` and `APP_ENV_JWT_SECRET` are **mandatory** when using the authentication component. The application will fail to start if these are missing or empty.
+
+### Generate Strong Secrets
+
+```bash
+# Generate random secrets
+openssl rand -base64 32  # For APP_ENV_APPLICATION_SECRET
+openssl rand -base64 32  # For APP_ENV_JWT_SECRET
+```
+
+### Example
+
+```bash
+APP_ENV_APPLICATION_SECRET=K8sX2mP9qR4tV7wZ1aD3fG6hJ9kL2nO5
+APP_ENV_JWT_SECRET=M3nB6vC9xZ2aS5dF8gH1jK4lP7oI0uY
+APP_ENV_JWT_EXPIRES_IN=86400
+```
+
+### Common Expiration Values
+
+| Value | Duration |
+|-------|----------|
+| `3600` | 1 hour |
+| `86400` | 24 hours (1 day) |
+| `604800` | 7 days |
+| `2592000` | 30 days |
+
+
+## Logging Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `APP_ENV_LOGGER_FOLDER_PATH` | No | `./` | Directory for log files |
+| `APP_ENV_LOGGER_DGRAM_HOST` | No | - | UDP log transport host |
+| `APP_ENV_LOGGER_DGRAM_PORT` | No | - | UDP log transport port |
+| `APP_ENV_LOGGER_DGRAM_LABEL` | No | - | Label for UDP logs |
+| `APP_ENV_LOGGER_DGRAM_LEVELS` | No | - | Comma-separated log levels for UDP |
+| `APP_ENV_EXTRA_LOG_ENVS` | No | - | Extra env vars to include in logs |
+
+### Example
+
+```bash
+# File logging
+APP_ENV_LOGGER_FOLDER_PATH=./app_data/logs
+
+# UDP logging (for log aggregators)
+APP_ENV_LOGGER_DGRAM_HOST=127.0.0.1
+APP_ENV_LOGGER_DGRAM_PORT=5000
+APP_ENV_LOGGER_DGRAM_LABEL=my-app
+APP_ENV_LOGGER_DGRAM_LEVELS=error,warn,info
+```
+
+
+## Storage Variables (MinIO/S3)
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `APP_ENV_MINIO_HOST` | Yes* | - | MinIO/S3 endpoint |
+| `APP_ENV_MINIO_API_PORT` | No | `9000` | MinIO API port |
+| `APP_ENV_MINIO_ACCESS_KEY` | Yes* | - | Access key |
+| `APP_ENV_MINIO_SECRET_KEY` | Yes* | - | Secret key |
+| `APP_ENV_MINIO_USE_SSL` | No | `false` | Enable SSL |
+
+*Required when using StaticAsset component.
+
+### Example
+
+```bash
+# Local MinIO
+APP_ENV_MINIO_HOST=localhost
+APP_ENV_MINIO_API_PORT=9000
+APP_ENV_MINIO_ACCESS_KEY=minioadmin
+APP_ENV_MINIO_SECRET_KEY=minioadmin
+APP_ENV_MINIO_USE_SSL=false
+
+# AWS S3
+APP_ENV_MINIO_HOST=s3.amazonaws.com
+APP_ENV_MINIO_API_PORT=443
+APP_ENV_MINIO_ACCESS_KEY=AKIAIOSFODNN7EXAMPLE
+APP_ENV_MINIO_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+APP_ENV_MINIO_USE_SSL=true
+```
+
+
+## Mail Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `APP_ENV_MAIL_HOST` | Yes* | `smtp.gmail.com` | SMTP host |
+| `APP_ENV_MAIL_PORT` | No | `465` | SMTP port |
+| `APP_ENV_MAIL_SECURE` | No | `true` | Use TLS |
+| `APP_ENV_MAIL_USER` | Yes* | - | SMTP username/email |
+| `APP_ENV_MAIL_CLIENT_ID` | Yes* | - | OAuth2 client ID |
+| `APP_ENV_MAIL_CLIENT_SECRET` | Yes* | - | OAuth2 client secret |
+| `APP_ENV_MAIL_REFRESH_TOKEN` | Yes* | - | OAuth2 refresh token |
+
+*Required when using Mail component with OAuth2.
+
+### Example (Gmail with OAuth2)
+
+```bash
+APP_ENV_MAIL_HOST=smtp.gmail.com
+APP_ENV_MAIL_PORT=465
+APP_ENV_MAIL_SECURE=true
+APP_ENV_MAIL_USER=your-email@gmail.com
+APP_ENV_MAIL_CLIENT_ID=your-oauth2-client-id
+APP_ENV_MAIL_CLIENT_SECRET=your-oauth2-client-secret
+APP_ENV_MAIL_REFRESH_TOKEN=your-oauth2-refresh-token
+```
+
+
+## DataSource Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `APP_ENV_APPLICATION_DS_MIGRATION` | No | - | DataSource name for migrations |
+| `APP_ENV_APPLICATION_DS_AUTHORIZE` | No | - | DataSource name for auth |
+| `APP_ENV_APPLICATION_DS_OAUTH2` | No | - | DataSource name for OAuth2 |
+
+
+## Debug Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `DEBUG` | No | - | Enable debug mode |
+| `NODE_ENV` | No | `development` | Environment mode |
+| `ALLOW_EMPTY_ENV_VALUE` | No | `false` | Allow empty env values |
+
+### Example
+
+```bash
+# Development
+NODE_ENV=development
+DEBUG=true
+
+# Production
+NODE_ENV=production
+```
+
+
+## Environment-Specific Files
+
+Create environment-specific `.env` files:
+
+```
+project/
+├── .env                 # Default (development)
+├── .env.local           # Local overrides (gitignored)
+├── .env.production      # Production values
+├── .env.test            # Test environment
+└── .env.example         # Template for team (committed)
+```
+
+### Loading Priority
+
+1. `.env.local` (highest priority, gitignored)
+2. `.env.{NODE_ENV}` (e.g., `.env.production`)
+3. `.env` (default)
+
+
+## Custom Environment Prefix
+
+You can customize the prefix from `APP_ENV_` to something else:
+
+```typescript
+// Set custom prefix
+process.env.APPLICATION_ENV_PREFIX = 'MY_APP';
+
+// Now use MY_APP_ prefix
+// MY_APP_POSTGRES_HOST=localhost
+```
+
+
+## Validation
+
+Ignis validates `APP_ENV_*` variables on startup. Missing required variables will cause the application to fail with a clear error message.
+
+### Disable Validation
+
+```bash
+# Allow empty env values (not recommended for production)
+ALLOW_EMPTY_ENV_VALUE=true
+```
+
+
+## Security Best Practices
+
+1. **Never commit `.env` files** - Add to `.gitignore`
+2. **Use strong secrets** - Generate with `openssl rand -base64 32`
+3. **Rotate secrets regularly** - Especially `JWT_SECRET`
+4. **Use different values per environment** - Don't reuse dev secrets in production
+5. **Use secret managers in production** - AWS Secrets Manager, HashiCorp Vault, etc.
+
+
+## Complete .env.example
+
+```bash
+# ===========================================
+# IGNIS ENVIRONMENT VARIABLES
+# ===========================================
+# Copy this file to .env and fill in values
+
+# APPLICATION
+APP_ENV_APPLICATION_NAME=my-app
+APP_ENV_APPLICATION_TIMEZONE=UTC
+
+# SERVER
+APP_ENV_SERVER_HOST=0.0.0.0
+APP_ENV_SERVER_PORT=3000
+APP_ENV_SERVER_BASE_PATH=/api
+
+# DATABASE
+APP_ENV_POSTGRES_HOST=localhost
+APP_ENV_POSTGRES_PORT=5432
+APP_ENV_POSTGRES_USERNAME=postgres
+APP_ENV_POSTGRES_PASSWORD=
+APP_ENV_POSTGRES_DATABASE=
+
+# AUTHENTICATION (Required for auth component)
+APP_ENV_APPLICATION_SECRET=
+APP_ENV_JWT_SECRET=
+APP_ENV_JWT_EXPIRES_IN=86400
+
+# LOGGING
+APP_ENV_LOGGER_FOLDER_PATH=./logs
+
+# STORAGE (Optional - MinIO/S3)
+# APP_ENV_MINIO_HOST=localhost
+# APP_ENV_MINIO_API_PORT=9000
+# APP_ENV_MINIO_ACCESS_KEY=
+# APP_ENV_MINIO_SECRET_KEY=
+# APP_ENV_MINIO_USE_SSL=false
+
+# MAIL (Optional)
+# APP_ENV_MAIL_HOST=smtp.gmail.com
+# APP_ENV_MAIL_PORT=465
+# APP_ENV_MAIL_USER=
+# APP_ENV_MAIL_CLIENT_ID=
+# APP_ENV_MAIL_CLIENT_SECRET=
+# APP_ENV_MAIL_REFRESH_TOKEN=
+```

package/wiki/references/configuration/index.md

@@ -0,0 +1,73 @@
+# Configuration Reference
+
+Configuration options and environment variables for Ignis applications.
+
+## Quick Reference
+
+| Category | Purpose | Key Variables |
+|----------|---------|---------------|
+| Application | App identity and timezone | `APP_ENV_APPLICATION_NAME`, `APP_ENV_APPLICATION_TIMEZONE` |
+| Server | HTTP server settings | `APP_ENV_SERVER_HOST`, `APP_ENV_SERVER_PORT` |
+| Database | PostgreSQL connection | `APP_ENV_POSTGRES_HOST`, `APP_ENV_POSTGRES_DATABASE` |
+| Authentication | JWT tokens and secrets | `APP_ENV_JWT_SECRET`, `APP_ENV_APPLICATION_SECRET` |
+| Logging | Log file paths and transports | `APP_ENV_LOGGER_FOLDER_PATH` |
+| Storage | MinIO/S3 file storage | `APP_ENV_MINIO_HOST`, `APP_ENV_MINIO_ACCESS_KEY` |
+| Mail | SMTP email sending | `APP_ENV_MAIL_HOST`, `APP_ENV_MAIL_USER` |
+
+## Environment Variable Prefix
+
+Ignis uses the `APP_ENV_` prefix to avoid conflicts with system variables:
+
+```bash
+# ✅ Ignis variables
+APP_ENV_POSTGRES_HOST=localhost
+
+# ❌ Might conflict with system
+POSTGRES_HOST=localhost
+```
+
+## Quick Start
+
+Create a `.env` file in your project root:
+
+```bash
+# .env
+APP_ENV_APPLICATION_NAME=my-app
+APP_ENV_SERVER_HOST=0.0.0.0
+APP_ENV_SERVER_PORT=3000
+APP_ENV_POSTGRES_HOST=localhost
+APP_ENV_POSTGRES_DATABASE=my_database
+```
+
+## What's in This Section
+
+- [Environment Variables](./environment-variables.md) - Complete reference of all `APP_ENV_*` variables
+
+## Configuration Patterns
+
+### 1. Accessing Variables
+
+```typescript
+// 1. Direct access
+const host = process.env.APP_ENV_POSTGRES_HOST;
+
+// 2. Using helper (recommended)
+import { applicationEnvironment, EnvironmentKeys } from '@venizia/ignis';
+const host = applicationEnvironment.get<string>(EnvironmentKeys.APP_ENV_POSTGRES_HOST);
+```
+
+### 2. Environment Files
+
+```
+project/
+├── .env                 # Default (development)
+├── .env.local           # Local overrides (gitignored)
+├── .env.production      # Production values
+└── .env.example         # Template (committed)
+```
+
+### 3. Validation on Startup
+
+Ignis validates required variables on startup. Missing values cause clear error messages.
+
+> **Related:** [Environment Variables Reference](./environment-variables.md) | [DataSources Guide](../../guides/core-concepts/persistent/datasources)