How Dream Server Manages Environment Validation During Installation

Dream Server validates environment configuration through a dedicated Bash script that parses the .env file without executing it, checks it against a JSON Schema for required keys, types, and constraints, and aborts installation immediately if any validation fails.

Dream Server treats environment configuration as a critical prerequisite for deployment. Before any Docker containers start, the installer ensures that the .env file is syntactically correct, semantically complete, and free of injection vulnerabilities. This fail-fast approach prevents runtime errors by catching misconfigurations during the installation phase.

The Validation Pipeline

The environment validation process is orchestrated across multiple installer phases to guarantee deterministic configuration. The pipeline separates concerns between file generation, schema validation, and error handling.

Triggering Validation in Phase 06-Directories

Validation is invoked during the 06-directories installation phase. After earlier phases (such as 02-preflight and 04-secrets) write the required keys into $INSTALL_DIR/.env, the installer explicitly calls the validator:

bash "$SCRIPT_DIR/scripts/validate-env.sh" "$INSTALL_DIR/.env" "$SCRIPT_DIR/.env.schema.json"

As implemented in dream-server/installers/phases/06-directories.sh at lines 69-76, this invocation passes the generated environment file and the schema definition to the validation script. If the validator returns a non-zero exit code, the installer aborts with the error message "Generated .env failed schema validation," forcing immediate correction before proceeding.

Safe Parsing Without Code Execution

The scripts/validate-env.sh script implements a defensive parser that reads the .env file line-by-line without using source or eval, preventing code injection attacks. According to the source code at lines 25-65, the parser:

• Ignores comments and blank lines
• Supports export KEY=VALUE syntax
• Trims whitespace and strips surrounding quotes
• Stores key-value pairs in associative arrays (ENV_MAP, ENV_LINE)

This safe parsing technique ensures that malicious values cannot execute arbitrary code during validation, treating the environment file as pure data rather than executable shell commands.

JSON Schema Constraint Checking

Validation logic relies on jq to parse .env.schema.json and enforce strict type safety. At lines 86-94, the script extracts schema metadata including required keys, property names, and per-key constraints (type, enum, minimum/maximum).

The validator performs six distinct checks:

1. Required Keys: Verifies every key listed in the schema's required array exists in ENV_MAP (lines 98-104)
2. Unknown Keys: Flags any keys present in .env but not defined in the schema as errors (lines 108-113)
3. Type Validation: Ensures values match declared JSON types (integer, number, boolean, string) (lines 118-140)
4. Enum Constraints: Validates that values match allowed strings when an enum is defined
5. Range Checks: Enforces minimum and maximum constraints for numeric types using awk (lines 141-173)
6. Duplicate Detection: Records errors if a key appears multiple times, with later values winning but flagged (lines 165-171)

Comprehensive Error Reporting

At lines 176-206, the validator aggregates all error arrays (missing, unknown, type_errors, enum_errors, range_errors, duplicate_errors) and prints detailed messages including line numbers. The script uses three distinct exit codes:

• 0: Validation successful (prints green ".env matches schema" message)
• 2: Validation errors detected (prints specific error list)
• 3: Missing dependencies (e.g., jq) or unreadable files

Manual Validation and Debugging

You can run the validator manually to debug environment issues without executing the full installer:

# From the repository root

bash dream-server/scripts/validate-env.sh path/to/.env path/to/.env.schema.json

Consider an example .env with missing required keys and type errors:

# Missing required WEBUI_SECRET

SEARXNG_SECRET=abc123
N8N_USER=admin@example.com
N8N_PASS=supersecret
LITELLM_KEY=llmkey
OPENCLAW_TOKEN=token

# Wrong type: CTX_SIZE should be integer

CTX_SIZE=big

Running the validator produces specific diagnostic output:

[ERROR] Missing required keys:
  - WEBUI_SECRET
[ERROR] Type validation errors:
  - CTX_SIZE: expected integer, got 'big' (line 9)

Safe Environment Loading

After validation, Dream Server uses dream-server/lib/safe-env.sh to load variables without code injection risks. Other scripts can safely import validated variables:

source "$(dirname "$0")/../lib/safe-env.sh"
load_env_file "$INSTALL_DIR/.env"

# Now all validated variables are exported for use

This library provides a secure mechanism for making validated environment variables available to the shell without re-parsing the file unsafely.

Key Source Files

• dream-server/scripts/validate-env.sh: Core validator implementing safe parsing and schema checking
• dream-server/.env.schema.json: JSON Schema defining required keys, types, enums, and ranges
• dream-server/lib/safe-env.sh: Helper library for safely loading .env files without eval
• dream-server/installers/phases/06-directories.sh: Installer phase that triggers validation and handles failures
• dream-server/tests/test-validate-env.sh: Test suite covering required keys, unknown keys, and duplicate detection

Summary

• Fail-fast validation: Dream Server validates .env during installation phase 06-directories before starting any services
• Injection-safe parsing: The validate-env.sh script parses files line-by-line without source or eval, using associative arrays to store data
• Schema-driven constraints: JSON Schema definitions enforce type safety, enum restrictions, and numeric ranges using jq
• Comprehensive error detection: The validator catches missing required keys, unknown properties, type mismatches, value ranges, and duplicate definitions
• Deterministic exit codes: Script returns 0 for success, 2 for validation errors, and 3 for system/dependency failures
• Manual debugging support: The validator can be executed independently of the installer for development and troubleshooting

Frequently Asked Questions

What happens if the .env file fails validation during installation?

If validation fails, the 06-directories.sh installer phase detects the non-zero exit code from validate-env.sh and immediately aborts the installation with an error message. The user must fix the reported issues in .env before the installation can proceed, preventing misconfigured services from starting.

How does Dream Server prevent code injection during environment validation?

The validate-env.sh script reads the .env file line-by-line using pure Bash string manipulation, storing values in associative arrays (ENV_MAP, ENV_LINE) without ever executing source or eval on the file contents. This treats the environment file as data rather than code, eliminating injection vectors.

Can I validate my .env file without running the full installer?

Yes. You can run the validator manually by executing bash dream-server/scripts/validate-env.sh path/to/.env path/to/.env.schema.json. This produces the same validation results and exit codes as the installer, making it useful for debugging configuration issues in development environments.

What types of constraints does the JSON Schema enforce?

The schema enforces required key presence, value types (string, integer, number, boolean), enum restrictions for allowed string values, and numeric ranges using minimum and maximum constraints. The validator uses jq to parse these rules and awk for numeric comparisons.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}