[Docs]: Add comprehensive environment variables documentation

[Copilot]

User description

Addresses the recurring issue where users are unaware that Preevy fully supports Docker Compose environment variable features. This PR adds comprehensive documentation to help users understand how to pass environment variables to their preview environments.

Problem

As noted in issue #XXX and confirmed by @Yshayy, users frequently ask about passing environment variables to preevy up, not realizing that Preevy already supports all Docker Compose environment variable capabilities. This is purely a documentation gap rather than a missing feature.

Solution

Added comprehensive documentation across multiple locations:

1. Enhanced README.md

Added a new "Environment Variables" section in the Configuration chapter that covers:

• Setting environment variables directly in compose files with examples
• Using .env files for configuration management
• Passing variables from host environment or CI systems
• GitHub Actions integration examples

2. Updated CLI Documentation

Enhanced the preevy up command documentation with:

• Dedicated "ENVIRONMENT VARIABLES" section
• Practical examples showing shell exports, compose file substitution, and .env files
• Clear guidance on the three main usage patterns

3. Created Comprehensive Recipe Guide

Added site/docs/recipes/environment-variables.md containing:

• Complete guide covering all environment variable methods
• Best practices and troubleshooting sections
• Advanced usage examples and CI/CD integration patterns
• Real-world scenarios for different deployment environments

Examples Added

The documentation now clearly shows users how to use environment variables in multiple ways:

services:
  web:
    environment:
      # Fixed values
      - NODE_ENV=production
      
      # Host environment variables with defaults
      - DATABASE_URL=${DATABASE_URL:-sqlite://localhost/dev.db}
      
      # Direct pass-through from host
      - API_KEY
    
    env_file:
      - .env
      - .env.production

And how to pass them from CI:

- uses: livecycle/[email protected]
  env:
    DATABASE_URL: ${{ secrets.DATABASE_URL }}
    API_KEY: ${{ secrets.API_KEY }}

Impact

This documentation eliminates the confusion around environment variable support and provides clear guidance for:

• Local development with different environment configurations
• CI/CD integration with secrets management
• Environment-specific deployments (dev, staging, production)
• All standard Docker Compose environment variable features

No code changes were required as Preevy already supports all Docker Compose environment variable capabilities through its underlying Docker Compose integration.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Feat]: Passing ENV variables to preevy up</issue_title>
<issue_description>### What feature?

Maybe I missed it in the doc, and in the example the docker-compose has hardcoded env. In most setups we need to specify differente ENV based on the environment. Is there a way to do this?

Describe the solution you'd like

Ability to pass environment variables or file to the preevy up command and/or GitHub action

Describe alternatives you've considered

Configuring env on third party service and retrieve them on startup. Not sutable for every project

Additional context

No response

Add screenshots

No response

Record

• I agree to follow this project's Code of Conduct</issue_description>

Comments on the Issue (you are @copilot in this section)

@Yshayy Hey @matteobad, in Docker Compose, you can pass environment variables in multiple ways. Preevy supports them all: ```yaml environment: # Assign a fixed value to MY_ENV_VAR - MY_ENV_VAR=abc

Load the value of EXTERNAL_ENV_VAR from the host environment

and assign it to MY_ENV_VAR in the container

• MY_ENV_VAR=${EXTERNAL_ENV_VAR}

Pass MY_ENV_VAR directly from the host environment to the container

(equivalent to MY_ENV_VAR=${MY_ENV_VAR} if MY_ENV_VAR exists in the host environment)

• MY_ENV_VAR

Set MY_ENV_VAR to the value from the host if it exists,

otherwise use "abc" as a default value in the container

• MY_ENV_VAR=${MY_ENV_VAR:-abc}

In addition, docker compose support loading .env files:
```yaml
env_file:
      - .env              # Base environment variables
      - .env.override     # Override specific values
      - ${ENV_NAME}.env   # Environment-specific variables (e.g., dev.env, prod.env)

You can also see more examples here #221 and in https://docs.docker.com/compose/how-tos/environment-variables/set-environment-variables</comment_new>
<comment_new>@Yshayy
Since it's a recurring issue, it might indeed worth addressing it in our docs.
Would you like to submit a PR?</comment_new>

Fixes #541

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

---

PR Type

Documentation

---

Description

• Add comprehensive environment variables documentation across multiple locations

• Enhance README.md with new Environment Variables section

• Update CLI documentation with practical examples

• Create detailed recipe guide for environment variable usage

---

Diagram Walkthrough

flowchart LR
  A["README.md"] --> B["Environment Variables Section"]
  C["CLI Documentation"] --> D["Enhanced up command docs"]
  E["New Recipe Guide"] --> F["Complete usage examples"]
  B --> G["User Understanding"]
  D --> G
  F --> G

Loading

File Walkthrough

Relevant files

Documentation

README.md Add Environment Variables configuration section                    README.md Add new "Environment Variables" section with comprehensive examples Cover Docker Compose syntax, .env files, and host environment passing Include GitHub Actions integration examples Provide clear guidance on three main usage patterns +65/-0    up.md Enhance up command with environment variables documentation packages/cli/docs/up.md Add dedicated "ENVIRONMENT VARIABLES" section to up command docs Include practical examples for shell exports and compose file usage Document .env file support with clear examples +27/-0    up.md Update CLI reference with environment variables section    site/docs/cli-reference/up.md Mirror CLI documentation updates for consistency Add "ENVIRONMENT VARIABLES" section with examples Document shell, compose file, and .env file usage patterns +27/-0    environment-variables.md Create complete environment variables recipe guide              site/docs/recipes/environment-variables.md Create comprehensive 279-line recipe guide for environment variables Cover all Docker Compose environment variable methods Include best practices, troubleshooting, and advanced usage sections Provide real-world CI/CD integration examples +279/-0

---

[qodo-merge-pro]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Possible Misleading Example The examples repeatedly set the same variable name on the left-hand side (e.g., MY_ENV_VAR) for different patterns, which could confuse readers about how Compose resolves duplicates and precedence. Consider clarifying that these are alternative patterns, not additive entries, or use distinct variable names per example. web: environment: # Assign a fixed value to MY_ENV_VAR - MY_ENV_VAR=production # Load the value of EXTERNAL_ENV_VAR from the host environment # and assign it to MY_ENV_VAR in the container - MY_ENV_VAR=${EXTERNAL_ENV_VAR} # Pass MY_ENV_VAR directly from the host environment to the container # (equivalent to MY_ENV_VAR=${MY_ENV_VAR} if MY_ENV_VAR exists in the host environment) - MY_ENV_VAR # Set MY_ENV_VAR to the value from the host if it exists, # otherwise use "production" as a default value in the container - MY_ENV_VAR=${MY_ENV_VAR:-production} </details> <details><summary><a href='https://github.com/livecycle/preevy/pull/602/files#diff-69eca933dd1df6fd255532b73fe9444d6bcb4c0df52b7e7704879d853d16ca4bR125-R151'><strong>Consistency With CLI Output</strong></a> The section heading and bullets are added to CLI docs; ensure formatting (bullet characters and indentation) matches the style of other sections produced by the CLI help generator to avoid rendering issues in terminals. </summary> ```markdown ENVIRONMENT VARIABLES Preevy supports all Docker Compose environment variable features: • Environment variables set in your shell are automatically available to Docker Compose • Use .env files to define environment variables • Set environment variables directly in your compose files Examples: 1. Pass environment variables from your shell: $ export DATABASE_URL=postgres://localhost/mydb $ preevy up 2. Use environment variable substitution in compose files: services: web: environment: - DATABASE_URL=${DATABASE_URL} - NODE_ENV=${NODE_ENV:-production} 3. Use .env files: services: web: env_file: - .env - .env.production Security Best Practice Clarification While best practices advise not hardcoding secrets, consider explicitly warning against committing .env files with secrets and recommend using .env.example with placeholders and CI secrets. Add a note on secret rotation and using Docker/Swarm/Compose secrets where applicable. ### 3. Document required environment variables Create a `.env.example` file to document required variables: ```bash # .env.example DATABASE_URL=postgres://user:password@host:5432/database API_SECRET=your-secret-key-here NODE_ENV=development DEBUG=false 4. Use environment-specific configurations For different environments, use different approaches: # Development: use .env file with defaults env_file: - .env # Staging/Production: use host environment variables environment: - DATABASE_URL=${DATABASE_URL} - API_SECRET=${API_SECRET} </details> </td></tr> </table>

[qodo-merge-pro]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Improve debugging command for environment variables Update the debugging command to include Preevy-specific compose files (e.g., compose.preevy.yaml) when running docker-compose config. This ensures the output accurately reflects the final configuration Preevy uses. site/docs/recipes/environment-variables.md [240-248] ### Debugging environment variables -Use `docker-compose config` to see the resolved configuration: +To see the resolved configuration with interpolated variables, you can use `docker-compose config`. Since Preevy may use its own compose file (e.g., `compose.preevy.yaml`), you should include it for an accurate view: ```bash # See the resolved compose configuration with interpolated variables export NODE_ENV=production -docker-compose config +docker-compose -f compose.preevy.yaml -f docker-compose.yml config +Adjust the file names (docker-compose.yml, compose.preevy.yaml) to match your project's setup. + - [ ] **Apply / Chat** <!-- /improve --apply_suggestion=0 --> <details><summary>Suggestion importance[1-10]: 8</summary> __ Why: This suggestion provides a more accurate debugging command by accounting for Preevy-specific compose files, preventing a common user error and making the troubleshooting advice significantly more effective. </details></details></td><td align=center>Medium </td></tr><tr><td rowspan=1>General</td> <td> <details><summary>Clarify compose file environment variable examples</summary> ___ **To improve clarity in the Docker Compose example, use distinct environment <br>variable names for each method shown, instead of repeatedly redefining <br><code>MY_ENV_VAR</code>. This will prevent confusion about how variables are overwritten.** [README.md [320-336]](https://github.com/livecycle/preevy/pull/602/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R320-R336) ```diff services: web: environment: - # Assign a fixed value to MY_ENV_VAR - - MY_ENV_VAR=production + # Assign a fixed value + - STATIC_VAR=production # Load the value of EXTERNAL_ENV_VAR from the host environment # and assign it to MY_ENV_VAR in the container - MY_ENV_VAR=${EXTERNAL_ENV_VAR} - # Pass MY_ENV_VAR directly from the host environment to the container - # (equivalent to MY_ENV_VAR=${MY_ENV_VAR} if MY_ENV_VAR exists in the host environment) - - MY_ENV_VAR + # Pass HOST_VAR directly from the host environment to the container + # (equivalent to HOST_VAR=${HOST_VAR} if HOST_VAR exists on the host) + - HOST_VAR - # Set MY_ENV_VAR to the value from the host if it exists, - # otherwise use "production" as a default value in the container - - MY_ENV_VAR=${MY_ENV_VAR:-production} + # Set ANOTHER_VAR from the host if it exists, otherwise use a default + - ANOTHER_VAR=${ANOTHER_VAR:-default_value} Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies that reusing MY_ENV_VAR in the example is confusing for documentation purposes, and the proposed change with distinct variable names significantly improves clarity.	Low
More

[Yshayy]

Try to minimize it and a link to recpies example you've created (and docker compose relevant documentation)

[Yshayy]

This file is generated, so no need to add it here

[Yshayy]

No need to be strongly opinionated about the practices, there's docker compose documentation for that, try to emphasis simple common simple cases, preevy is used for preview environments not production environments.