# docuconf

> docuconf is an open-source project for typed configuration contracts between an application and the Kubernetes platform that runs it. Each language SDK extends that language's leading config library and exports a ConfigContract (apiVersion docuconf.dev/v1alpha1) in CUE. The platform validates the values, files and secrets it will supply against the contract before deploying (docuconf CLI, CUE/Crossplane, or a Helm values schema), and the SDK validates the real environment again at boot.

docuconf covers environment variables (9 types), file inputs (config files, TLS key pairs, CA bundles, keystores, text, binary), Kubernetes value and file sources, runtime secret injection (Bank-Vaults, Vault Agent) and config-file overlays (.NET appsettings, Spring, Rails). It is not a feature-flag system; flags belong in OpenFeature.

## Specification

- [Core specification](http://docuconf.dev/spec/): overview, the three checks, FAQ
- [Inputs](http://docuconf.dev/spec/inputs/): variable types, value sources, injection, file types and sources, overlays, wire encodings, profiles
- [Outputs](http://docuconf.dev/spec/outputs/): every generation target and its status
- [Generated docs](http://docuconf.dev/spec/generated-docs/): description and details, the docs model, `docuconf docs`, CONFIG.md for developers and CONFIG.agents.md for agents, and where each SDK takes the text from
- [SDK requirements](http://docuconf.dev/spec/sdk-requirements/): what every language SDK must support, error codes, SDK status
- [Full specification as plain text](http://docuconf.dev/llms-full.txt)
- [Normative SPEC.md](https://github.com/Docuconf/docuconf-go/blob/main/spec/SPEC.md)

## Get started

- [Get started: pick a language](http://docuconf.dev/languages/)
- [Example apps](http://docuconf.dev/examples/): the same "orders" service in every SDK, side by side

No SDK is on a package registry yet (all are v0.1 alphas), so each installs from its main branch. Each line: the Get started page (install, declare, boot error, test, export), the install command, the raw README and the example's declaration.

- [docuconf for Go](http://docuconf.dev/languages/go/): on caarlos0/env v11. Install: `go get github.com/docuconf/docuconf-go@main && go install github.com/docuconf/docuconf-go/cmd/docuconf@main`. [README](https://raw.githubusercontent.com/Docuconf/docuconf-go/main/README.md), [orders example](https://github.com/Docuconf/docuconf-go/tree/main/examples/orders). Your config struct stays a caarlos0/env struct. docuconf adds struct tags for secrets and constraints, takes descriptions from doc comments, and ships the docuconf CLI that exports and vets contracts.
- [docuconf for TypeScript (T3 Env)](http://docuconf.dev/languages/typescript/): on T3 Env + Zod 4. Install: `git clone https://github.com/Docuconf/docuconf-js ../docuconf-js && (cd ../docuconf-js && npm ci && npm run build && npm pack -w @docuconf/core -w @docuconf/t3) && npm install ../docuconf-js/docuconf-core-0.1.0.tgz ../docuconf-js/docuconf-t3-0.1.0.tgz @t3-oss/env-core zod`. [README](https://raw.githubusercontent.com/Docuconf/docuconf-js/main/packages/t3/README.md), [orders example](https://github.com/Docuconf/docuconf-js/tree/main/examples/orders-t3). You keep writing createEnv({ server }) with Zod 4. docuconf re-exports T3's createEnv and adds helpers for what Zod has no word for: secret, url({ schemes }), duration and list.
- [docuconf for TypeScript (NestJS)](http://docuconf.dev/languages/nestjs/): on @nestjs/config + class-validator. Install: `git clone https://github.com/Docuconf/docuconf-js ../docuconf-js && (cd ../docuconf-js && npm ci && npm run build && npm pack -w @docuconf/core -w @docuconf/nestjs) && npm install ../docuconf-js/docuconf-core-0.1.0.tgz ../docuconf-js/docuconf-nestjs-0.1.0.tgz @nestjs/config class-validator class-transformer`. [README](https://raw.githubusercontent.com/Docuconf/docuconf-js/main/packages/nestjs/README.md), [orders example](https://github.com/Docuconf/docuconf-js/tree/main/examples/orders-nestjs). You keep the class-validator class from the NestJS docs and ConfigModule.forRoot({ validate }). docuconf adds decorators for descriptions, secrets, URL schemes, durations and lists, and a validate function that checks everything at boot.
- [docuconf for .NET](http://docuconf.dev/languages/dotnet/): on Options pattern + appsettings. Install: `git clone https://github.com/Docuconf/docuconf-dotnet ../docuconf-dotnet && dotnet pack ../docuconf-dotnet/src/Docuconf -c Release -o ../docuconf-packages && dotnet add package Docuconf.Options --prerelease --source ../docuconf-packages`. [README](https://raw.githubusercontent.com/Docuconf/docuconf-dotnet/main/README.md), [orders example](https://github.com/Docuconf/docuconf-dotnet/tree/main/examples/orders). Your options class, with the DataAnnotations you already use, plus [Secret], [UrlSchemes] and [Description]. AddDocuconf<T>() binds it, loads its files and validates everything on start.
- [docuconf for Python](http://docuconf.dev/languages/python/): on pydantic-settings 2. Install: `pip install "docuconf-pydantic @ git+https://github.com/Docuconf/docuconf-python@main"`. [README](https://raw.githubusercontent.com/Docuconf/docuconf-python/main/README.md), [orders example](https://github.com/Docuconf/docuconf-python/tree/main/examples/orders). Your BaseSettings class stays as it is: descriptions from Field(description=...), bounds from ge/le, secrets from SecretStr. docuconf adds URL schemes, CSV lists and file inputs, and checks everything at boot.
- [docuconf for Ruby](http://docuconf.dev/languages/ruby/): on anyway_config 2. Install: `bundle install` plus the Gemfile lines on the page. [README](https://raw.githubusercontent.com/Docuconf/docuconf-ruby/main/README.md), [orders example](https://github.com/Docuconf/docuconf-ruby/tree/main/examples/orders). You keep your Anyway::Config classes, and anyway_config keeps loading YAML, credentials and the environment. docuconf adds describe, secret and file inputs, checks everything when the config loads, and exports the contract with a rake task.
- [docuconf for Java (Spring Boot)](http://docuconf.dev/languages/java/): on Spring Boot 3 / 4 @ConfigurationProperties. Install: `git clone https://github.com/Docuconf/docuconf-java ../docuconf-java && mvn -f ../docuconf-java install -DskipTests` plus the pom.xml: dependencies and pom.xml: maven-compiler-plugin configuration lines on the page. [README](https://raw.githubusercontent.com/Docuconf/docuconf-java/main/README.md), [orders example](https://github.com/Docuconf/docuconf-java/tree/main/examples/orders). Your @ConfigurationProperties records, with the Bean Validation annotations you already use, marked @Docuconf. An annotation processor writes the contract at compile time, and an auto-configuration checks everything before any bean binds.
- [docuconf for Kotlin](http://docuconf.dev/languages/kotlin/): on Hoplite 3. Install: `git clone https://github.com/Docuconf/docuconf-kotlin ../docuconf-kotlin` plus the settings.gradle.kts and build.gradle.kts lines on the page. [README](https://raw.githubusercontent.com/Docuconf/docuconf-kotlin/main/README.md), [orders example](https://github.com/Docuconf/docuconf-kotlin/tree/main/examples/orders). You keep writing a Hoplite data class. docuconf adds annotations for descriptions, bounds, URL schemes and file inputs, checks every variable and file before Hoplite binds the class, and exports the contract.
- [docuconf for Rust](http://docuconf.dev/languages/rust/): on figment + serde. Install: `cargo add docuconf --git https://github.com/Docuconf/docuconf-rust && cargo add serde --features derive`. [README](https://raw.githubusercontent.com/Docuconf/docuconf-rust/main/README.md), [orders example](https://github.com/Docuconf/docuconf-rust/tree/main/examples/orders). Keep your #[derive(Deserialize)] config struct and add #[derive(Docuconf)]. Doc comments are the descriptions, the Rust type picks the contract type, and figment's files and profiles become the contract's defaults and profiles.
- [docuconf for Swift](http://docuconf.dev/languages/swift/): on swift-configuration. Install: `swift build` plus the Package.swift lines on the page. [README](https://raw.githubusercontent.com/Docuconf/docuconf-swift/main/README.md), [orders example](https://github.com/Docuconf/docuconf-swift/tree/main/Examples/Orders). Values are read through Apple's swift-configuration, with its key names and parsing. docuconf adds the declaration it lacks: @Env and @FileInput property wrappers with descriptions, secrets and constraints.
- [docuconf for Elixir](http://docuconf.dev/languages/elixir/): on config/runtime.exs. Install: `mix deps.get` plus the mix.exs lines on the page. [README](https://raw.githubusercontent.com/Docuconf/docuconf-elixir/main/README.md), [orders example](https://github.com/Docuconf/docuconf-elixir/tree/main/examples/orders). You keep config/runtime.exs. docuconf gives it one declaration, in the NimbleOptions style, of every variable and file the app reads, checks them all at boot, and exports the contract with mix docuconf.export.
- [docuconf for Gleam](http://docuconf.dev/languages/gleam/): on envoy + gleam/dynamic/decode. Install: `gleam deps download` plus the gleam.toml lines on the page. [README](https://raw.githubusercontent.com/Docuconf/docuconf-gleam/main/README.md), [orders example](https://github.com/Docuconf/docuconf-gleam/tree/main/examples/orders). Gleam has no macros or reflection, so docuconf follows the decoder idiom: typed builders combined with use. One declaration loads the environment at boot, on Erlang or JavaScript, and writes the contract.
- [docuconf for C++](http://docuconf.dev/languages/cpp/): on CLI11. Install: `cmake -S . -B build && cmake --build build` plus the CMakeLists.txt lines on the page. [README](https://raw.githubusercontent.com/Docuconf/docuconf-cpp/main/README.md), [orders example](https://github.com/Docuconf/docuconf-cpp/tree/main/examples/orders). You keep your CLI11 app. docuconf adds a Declaration next to it: add_var binds each environment variable to a C++ variable, the C++ type picks the contract type, and the app exports its own contract with --docuconf-export.
- [docuconf for PHP (Laravel)](http://docuconf.dev/languages/laravel/): on Laravel config + vlucas/phpdotenv. Install: `composer config repositories.docuconf vcs https://github.com/Docuconf/docuconf-php && composer require docuconf/docuconf:dev-main`. [README](https://raw.githubusercontent.com/Docuconf/docuconf-php/main/README.md), [orders example](https://github.com/Docuconf/docuconf-php/tree/main/examples/orders). In config/*.php, Env::int(...), Env::url(...) and the other helpers replace env(): each returns the typed value where env() did, and records the variable for the boot check and the contract.
- [docuconf for PHP (Symfony)](http://docuconf.dev/languages/symfony/): on Symfony config + %env()% processors. Install: `composer config repositories.docuconf vcs https://github.com/Docuconf/docuconf-php && composer require docuconf/docuconf:dev-main`. [README](https://raw.githubusercontent.com/Docuconf/docuconf-php/main/README.md), [orders example](https://github.com/Docuconf/docuconf-php/tree/main/examples/orders-symfony). Declare the variables in config/packages/docuconf.yaml, written as in the contract, and read them with the docuconf env processor instead of int: and bool:, or from the Docuconf\Values service. The kernel checks them all at boot.
- [docuconf for COBOL](http://docuconf.dev/languages/cobol/): on GnuCOBOL copybooks + docuconf exec. Install: `go install github.com/docuconf/docuconf-cobol/cmd/docuconf-cobol@main && go install github.com/docuconf/docuconf-go/cmd/docuconf@v0.0.0-20261008010717-a84031e0174b`. [README](https://raw.githubusercontent.com/Docuconf/docuconf-cobol/main/README.md), [orders example](https://github.com/Docuconf/docuconf-cobol/tree/main/examples/orders). The configuration record your program already uses is the declaration: an annotated copybook. docuconf-cobol generate writes the contract and a loader program your code CALLs, and docuconf exec checks the environment and files against the contract before the job starts.

## Project

- [Vision](http://docuconf.dev/vision/)
- [How it works](http://docuconf.dev/how-it-works/)
- [Config is not feature flags](http://docuconf.dev/feature-flags/)
- [Roadmap](http://docuconf.dev/roadmap/)
- [Get involved](http://docuconf.dev/community/)

## Optional

- [Structured data (JSON-LD)](http://docuconf.dev/docuconf.jsonld)