# How Dream Server Manages Environment Validation During Installation

> Discover how Dream Server uses a Bash script to validate your environment configuration against a JSON Schema during installation, ensuring a smooth setup.

- Repository: [Light Heart Labs/DreamServer](https://github.com/Light-Heart-Labs/DreamServer)
- Tags: how-to-guide
- Published: 2026-05-18

---

**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
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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/.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:

```bash

# 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:

```dotenv

# 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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/dream-server/lib/safe-env.sh) to load variables without code injection risks. Other scripts can safely import validated variables:

```bash
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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/dream-server/scripts/validate-env.sh)**: Core validator implementing safe parsing and schema checking
- **[`dream-server/.env.schema.json`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/dream-server/.env.schema.json)**: JSON Schema defining required keys, types, enums, and ranges
- **[`dream-server/lib/safe-env.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/dream-server/lib/safe-env.sh)**: Helper library for safely loading `.env` files without `eval`
- **[`dream-server/installers/phases/06-directories.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/dream-server/installers/phases/06-directories.sh)**: Installer phase that triggers validation and handles failures
- **[`dream-server/tests/test-validate-env.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/06-directories.sh) installer phase detects the non-zero exit code from [`validate-env.sh`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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`](https://github.com/Light-Heart-Labs/DreamServer/blob/main/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.