envy

README

envy

Envy manages Docker Compose files. It validates and lints them, manages Compose profiles, audits secrets, generates and diffs .env files, and produces documentation that can be deployed as a static website.

All env variables are always treated as strings to avoid type casting issues with Docker and environment variables in general.

Install

Envy is a single Go binary, available for download from the releases page. Download the binary for your platform (Linux, Mac, Windows; X86 or ARM architecture), and place it in your PATH. Linux packages in deb, rpm and apk formats are also available from the releases page.

Go

To install envy using Go, run:

go install github.com/front-matter/envy@latest

Homebrew

To install envy on macOS using Homebrew, run:

brew tap front-matter/envy
brew install envy

Usage

envy [command] [flags]

Commands:
  import      Import .env files and generate compose.yml
  validate    Validate a compose.yml (using docker compose config)
  lint        Lint compose.yml for warnings
  diff        Show variables missing from or extra in a .env file
  generate    Generate a .env file from compose.yml
  secrets     List or audit secret environment variables
  build       Generate documentation site for compose.yml file
  server      Run local documentation site generated from compose.yml
  deploy      Deploy documentation site to GitHub Pages
  completion  Generate shell completion scripts

Global flags:
  -f, --file string       Path to compose file (auto-detected if not given)
  -v, --version           version for envy

Workflow

# Import env files into compose.yml
# Auto-detects one env file: .env preferred over .env.example
envy import

# Or import a specific file/directory via positional arg
envy import .env
envy import ./config

# --file accepts a folder and writes ./generated/compose.yml
envy import .env --file ./generated

# Safety: if target file already exists, import prints a warning and does not overwrite it

# Lint compose.yml and run go-ruleguard checks
envy lint

# See what's missing or undocumented
envy diff .env.prod

# Initial setup — generate a safe template to commit
envy generate --no-secrets > .env.example

# Create your local .env from the template
cp .env.example .env
# ... fill in secrets ...

# Validate before deploying
envy validate .env.prod

# List all secret variables
envy secrets

# Scan git-tracked files for exposed secrets
envy secrets --check

# Print envy version
envy --version

# Build documentation site for compose.yml
# If docs/index.md exists next to compose.yml, it is used as the docs home page.
envy build --destination public

# Run local documentation site
envy server --bind 0.0.0.0

# Deploy documentation site to GitHub Pages
envy deploy --target production

Persistent Content Workflow

envy build writes generated Markdown into the local .envy folder.

• Generated pages are written under .envy/sets, .envy/services, and .envy/profiles
• Generated home pages are written to .envy/_index.md and localized variants
• Each envy build run refreshes the contents of .envy and rewrites generated pages deterministically
• Existing files in .envy are treated as build output, not as user-managed content

compose.yml format

envy reads a single compose.yml file as its source of truth:

x-envy:
  HUGO_TITLE: InvenioRDM Starter
  HUGO_PARAMS_DESCRIPTION: >
    InvenioRDM is the open source turn-key research data management platform,   with detailed documentation available [here](https://inveniordm.docs.cern.ch).  InvenioRDM Starter facilitates deployment and configuration of InvenioRDM,  allowing you to run InvenioRDM on your local computer within 15 min.
  HUGO_LANGUAGE_CODE: en-US
x-set-application: &application
  # INVENIO_SECRET_KEY defines the Flask secret key. 
  # 
  # Generate with: python -c "import secrets; print(secrets.token_hex(32))"
  INVENIO_SECRET_KEY:

  # INVENIO_DEBUG describes debug mode, which should never be true in production.
  INVENIO_DEBUG: '${INVENIO_DEBUG:-false}'

services:
  # web describes the frontend and API service, which serves the web UI and API endpoints.
  web:
    image: ghcr.io/front-matter/invenio-rdm-starter:latest
    platform: linux/amd64
    entrypoint: ["/entrypoint.sh"]
    command: ["celery", "-A", "invenio_app.celery", "worker", "--loglevel=INFO"]
    env: :<< [*application]

Var fields

sets is a map keyed by a stable slug (for example application, database). Top-level services reference these slugs to define per-service config sets. Each service can also define image and platform. If platform is omitted, compose generation falls back to linux/amd64. If platform is set, it should use the form os/arch or os/arch/variant. image should be a Docker image reference such as ghcr.io/front-matter/invenio-rdm-starter:latest. Optional entrypoint and command values are string lists and are emitted into compose when set.

Field	Description
key	Environment variable name
description	Human-readable description
default	Default value for generated .env
required	Fail validation if missing
secret	Omit from .env.example, flag in git audit
readonly	Prevent variable from being exported to generated .env when "true" (default: "false")
example	Example value shown in comments

Shell Completion

envy provides completion scripts for bash, zsh, fish, and PowerShell via the built-in completion command.

zsh

envy completion zsh > "${fpath[1]}/_envy"
# restart your shell or run: autoload -U compinit && compinit

bash

envy completion bash > /etc/bash_completion.d/envy
# or for a single user:
envy completion bash >> ~/.bashrc

fish

envy completion fish > ~/.config/fish/completions/envy.fish

PowerShell

envy completion powershell | Out-String | Invoke-Expression

Meta

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

License: MIT