denver Logo
1.6.4-2-gee27748

Introduction

  • About denver
    • What problem does denver solve?
    • Why denver and not writing your own scripts?
    • What is a denver environment?
    • Is denver flexible?
  • Install denver
    • Run from source (no install)
    • From PyPI
    • Prebuilt binary
    • Editable install
    • Vendor with git-nested

Quickstart

  • denver in 5 minutes
    • Have a look first
    • Run the environment
    • What just happened
    • Pre-conditions for a real project
    • The handful of flags you’ll use daily
  • denver in 30 minutes
    • The use case
    • What you need before starting
    • Step 0 — the skeleton
    • Step 1 — declare the stages
    • Step 2 — the docker-base stage
      • The files the docker stage needs
      • Check it — the container
    • Step 3 — the uv-packages stage
    • Step 4 — the nvim-setup stage
      • The files the nvim stage needs
      • Check it — nvim on PATH
    • Step 5 — the ninja-setup stage
    • Step 6 — the conan-packages stage
      • The files the conan stage needs
      • Keeping conan’s cache
      • By hand, download or conan?
    • Step 7 — the best-practices stage
    • Step 8 — the default command
    • The finished denver.toml
    • Prove it, rather than hope
    • Everyday use
  • Examples
    • Overview
    • Running the bundled examples

Concepts

  • Glossary
    • The core model
    • Configuration
    • Execution
  • Philosophy
    • Genericity
    • Explicit over implicit
    • Central default resolution
    • Fail loud on the unexpected
    • Fast by default, never at the cost of correctness
    • Reproducibility as a first-class goal

denver command

  • Arguments
    • Control the stages: Choosing what runs
    • Control the config: Change values for one run
    • An env’s own flags: denver-custom-args:
    • Control the speed: Trading speed against freshness
    • Inspect an environment
    • Hand the built env to something else
    • Remove an environment’s state
      • denver clean <env>
    • Output and version
  • Shell completion
    • Works no matter how you invoke it
    • What gets completed
    • Inside a docker-relocated shell, automatically
  • Environment variables
    • What denver reads
    • What denver exports
    • Where an environment’s state lives

Configuration

  • Configuration
    • Overview
      • denver.yml vs. denver.toml
    • Core model
    • The denver.toml schema
      • Top-level keys
      • Requiring a denver version
      • Generic stage keys
      • Variable interpolation
      • The prompt marker
    • Config resolution
    • Layering
    • Command-line overrides
    • Command-line environment variables
    • Environment-specific CLI arguments
    • Hooks and scripts
    • Fast by default
    • Previewing a run (--dry-run)
    • Stage filtering
    • Wrapper / relocation
      • How the inner run knows where it is
    • One run per environment at a time
    • Quiet levels and –verbose
    • Performance tracing

Providers

  • uv provider
    • Requires
    • Key reference
    • One venv, one interpreter
    • Design notes
  • conan provider
    • Requires
    • Key reference
    • Design notes
  • docker provider
    • Requires
    • Setting up Docker
    • Key reference
    • Design notes
  • zephyr provider
    • Requires
    • Key reference
    • Design notes
  • download provider
    • Key reference
      • Package keys
    • Authenticated downloads
    • Where things go
    • What runs, and what is skipped
    • Unpacking
    • Design notes
  • git provider
    • Key reference
    • What runs, and what is skipped
    • Unreachable commits
    • Where things go
    • Design notes
  • nix provider
    • Key reference
    • What runs, and what is skipped
    • The cache
    • shellHook
    • Design notes
  • custom provider
    • Key reference
    • Worked example: bringing a prebuilt binary in by hand
    • Design notes

Architecture (arc42)

  • Architecture (arc42)
    • 1. Introduction and Goals
      • 1.1 Requirements overview
      • 1.2 Quality goals
      • 1.3 Stakeholders
    • 2. Architecture Constraints
      • 2.1 Technical constraints
      • 2.2 Organizational constraints
      • 2.3 Conventions
    • 3. Context and Scope
      • 3.1 Business context
      • 3.2 Technical context
      • 3.3 Scope boundaries
    • 4. Solution Strategy
      • 4.1 Declarative config, generic providers
      • 4.2 An ordered pipeline of stages
      • 4.3 One central place for every default
      • 4.4 Nothing is inferred from the directory layout
      • 4.5 Two ways to inherit config
      • 4.6 Loud failure over a silent guess
      • 4.7 Fast by default, and the container is only a relocation
    • 5. Building Block View
      • 5.1 Level 1: whitebox denver
      • 5.2 Level 2: inside the orchestrator
      • 5.3 Level 2: inside the provider package
      • 5.4 Level 2: Context
      • 5.5 Level 3
    • 6. Runtime View
      • 6.1 Cold run on the host
      • 6.2 Warm run
      • 6.3 Relocation into a container
      • 6.4 Inspecting instead of running
      • 6.5 Failing early
    • 7. Deployment View
      • 7.1 Where denver runs
      • 7.2 How denver itself is shipped
      • 7.3 Where state lives
      • 7.4 CI
      • 7.5 Network
    • 8. Cross-cutting Concepts
      • 8.1 Error handling
      • 8.2 Fail loud
      • 8.3 Config merging
      • 8.4 Path resolution
      • 8.5 Central defaults
      • 8.6 Interpolation
      • 8.7 Hooks and scripts
      • 8.8 Stage selection
      • 8.9 Runtime toggles
      • 8.10 Fingerprinting
      • 8.11 Dry-run and testability, from one seam
      • 8.12 Concurrency
      • 8.13 Output and tracing
      • 8.14 Isolation
    • 9. Architecture Decisions
      • ADR-0001: Central default resolution
      • ADR-0002: No path is inferred from the directory layout
      • ADR-0003: YAML is the default config format, TOML optional
      • ADR-0004: A container is a wrapper stage that relocates the run
      • ADR-0005: provider is mandatory, never guessed from the stage id
      • ADR-0006: stages and providers as the two names
      • ADR-0007: lists append instead of replacing
      • ADR-0008: die() raises DenverError instead of exiting
      • ADR-0009: state lives with the env
      • ADR-0010: one run per environment
      • ADR-0011: fingerprint content, not absolute paths
      • ADR-0012: extension providers instead of forks
      • ADR-0013: download and git as providers
      • ADR-0014: subcommand CLI
      • ADR-0015: top-level package names that do not squat
      • ADR-0016: pip provider renamed to uv
    • 10. Quality Scenarios
      • 10.1 Quality tree
      • 10.2 Scenarios
    • 11. Technical Risks and Debt
    • 12. Glossary

Contributing

  • Development
    • Quick start
    • Test suite
    • Coverage
    • Linting / formatting / types
    • Adding a new provider
    • CI
    • Releasing
    • Known limitations
      • denver has exactly one runtime dependency: PyYAML
      • More PyYAML, unrelated to denver’s own config
denver
  • Search

© Copyright Thorsten Klein.

Built with Sphinx using a theme provided by Read the Docs.