1+ <p align =" center " >
2+ <img src =" ./assets/Logo.svg " alt =" Dockermint " width =" 240 " />
3+ </p >
4+
15# Dockermint
26
3- Automated, recipe-driven Docker image pipeline for Cosmos SDK blockchains
4- and their sidecars. Define a chain once in TOML — Dockermint handles the
5- Dockerfile, cross-compilation, and registry push without touching Rust code.
7+ The first CI/CD Pipeline for Cosmos SDK.
8+
9+ ---
10+
11+ ## What is Dockermint?
12+
13+ Building and maintaining Docker images for blockchain nodes is repetitive
14+ work: tracking upstream releases, writing multi-stage Dockerfiles, managing
15+ cross-compilation for ` amd64 ` and ` arm64 ` , pushing to a registry, and
16+ keeping everything consistent across a fleet of chains. Teams usually end up
17+ with a collection of bespoke shell scripts that diverge over time.
18+
19+ Dockermint replaces that with a single, uniform pipeline. Define a chain once
20+ in a TOML ** recipe** file and Dockermint handles the rest — Dockerfile
21+ generation, cross-compilation via BuildKit, release polling, registry push,
22+ persistence, and notifications. Adding a new chain requires no code changes:
23+ only a new recipe file.
24+
25+ ** Who is Dockermint for?** Infrastructure engineers and DevOps teams running
26+ Cosmos SDK validator nodes or RPC infrastructure who need reproducible,
27+ multi-architecture Docker images without maintaining a separate build system
28+ per chain.
29+
30+ > ** Status:** Phase 0 (all architecture specs confirmed). No production code
31+ > has been written yet. All features below are planned for the phases indicated.
632
733---
834
9- ## Overview
35+ ## Resources
1036
11- Dockermint is an open-source CI/CD pipeline written in Rust. It standardizes
12- multi-architecture Docker image creation for Cosmos SDK nodes across three
13- operating modes:
37+ | Resource | URL |
38+ | :--------------- | :------------------------------------------- |
39+ | Main site | https://dockermint.io |
40+ | Documentation | https://docs.dockermint.io/ |
41+ | GitHub | https://github.com/Dockermint/dockermint |
42+ | Related project | [ Pebblify] ( https://github.com/Dockermint/pebblify ) |
43+
44+ ---
45+
46+ ## Operating Modes
47+
48+ Dockermint runs in three modes depending on your use case:
1449
1550- ** CLI** — one-shot build, locally or via a remote BuildKit endpoint. Errors
1651 cause an immediate dump, log, and exit.
@@ -19,23 +54,14 @@ operating modes:
1954- ** RPC** — daemon with an optional gRPC server, accepting remote build
2055 requests from a CLI client. On error: log and return idle.
2156
22- The central abstraction is the ** Recipe** : a TOML file that fully describes
23- how to build a chain's Docker image — what flavors are available, which are
24- default, how to clone the source, how to generate the Dockerfile, and what
25- OCI labels to attach. New chains are onboarded by adding a recipe file; no
26- Rust code changes are required.
27-
28- > ** Status:** Phase 0 (all architecture specs confirmed). No production code
29- > has been written yet. All features below are planned for the phases indicated.
30-
3157---
3258
3359## Planned Features
3460
3561### Recipe-driven extensibility
3662
3763Each chain is described by a single TOML file in ` recipes/ ` . Adding a chain
38- requires no Rust code changes — only a new recipe file.
64+ requires no code changes — only a new recipe file.
3965
4066### Flavor system
4167
@@ -65,19 +91,9 @@ Incompatible flavor combinations produce an error before the build starts.
6591### Multi-architecture builds (planned: Phase 1)
6692
6793BuildKit cross-compilation targeting ` linux/amd64 ` and ` linux/arm64 ` .
68- Per-platform builder instances (` dockermint-amd64 ` , ` dockermint-arm64 ` ) are
69- managed by Dockermint — created on first use and optionally destroyed after
70- each build. Both local and remote BuildKit endpoints are supported.
71-
72- ### Template engine (planned: Phase 1)
73-
74- Dockerfile content is produced by a template engine that resolves two classes
75- of variables from the recipe:
76-
77- - ` {{UPPERCASE}} ` — host variables injected by Dockermint (e.g. ` {{HOST_ARCH}} ` ,
78- ` {{SEMVER_TAG}} ` , ` {{CREATION_TIMESTAMP}} ` )
79- - ` {{lowercase}} ` — build variables resolved at build time, including
80- shell-captured values (e.g. ` {{golang_version}} ` , ` {{wasmvm_version}} ` )
94+ Per-platform builder instances are managed by Dockermint — created on first
95+ use and optionally destroyed after each build. Both local and remote BuildKit
96+ endpoints are supported.
8197
8298### OCI registry push (planned: Phase 1)
8399
@@ -104,24 +120,56 @@ Authentication supports both mTLS and token-based auth. Configured via the
104120
105121### Phase 1 targets
106122
107- | Chain | Binary | Sidecars |
108- | :---------- | :---------- | :--------------- |
109- | Cosmos Hub | ` gaiad ` | — |
110- | Axelar | ` axelard ` | Tofnd, Vald |
111- | Fetch | ` fetchd ` | — |
112- | Injective | ` injectived ` | Peggo |
113- | Osmosis | ` osmosisd ` | — |
123+ | Chain | Binary | Sidecars |
124+ | :---------- | :----------- | :--------------- |
125+ | Cosmos Hub | ` gaiad ` | — |
126+ | Axelar | ` axelard ` | Tofnd, Vald |
127+ | Fetch | ` fetchd ` | — |
128+ | Injective | ` injectived ` | Peggo |
129+ | Osmosis | ` osmosisd ` | — |
114130
115131### Current recipes (available now)
116132
117- | Chain | Binary | Recipe file |
118- | :--------- | :------ | :----------------------- |
119- | Cosmos Hub | ` gaiad ` | ` recipes/cosmos-gaiad.toml ` |
120- | Kyve | ` kyved ` | ` recipes/kyve-kyved.toml ` |
133+ | Chain | Binary | Recipe file |
134+ | :--------- | :------ | :--------------------------- |
135+ | Cosmos Hub | ` gaiad ` | ` recipes/cosmos-gaiad.toml ` |
136+ | Kyve | ` kyved ` | ` recipes/kyve-kyved.toml ` |
137+
138+ ---
139+
140+ ## Configuration
141+
142+ Dockermint is configured via ` config.toml ` . Secrets (GitHub PAT, registry
143+ credentials, notifier tokens) are stored exclusively in ` .env ` and are never
144+ written to ` config.toml ` .
145+
146+ All configuration files carry a ` config_version ` field. Unknown fields are
147+ rejected at startup to prevent silent misconfiguration.
148+
149+ Full schema reference: [ docs.dockermint.io/configuration] ( https://docs.dockermint.io/configuration )
150+ or ` docs/specs/config.md ` in this repository.
151+
152+ ---
153+
154+ ## Project Status
155+
156+ | Phase | Target | Scope | Status |
157+ | :---- | :------ | :--------------------------------------------- | :------- |
158+ | 0 | N/A | Architecture specs (all modules) | Complete |
159+ | 1 | v0.1.0 | CLI mode, 5 chains, BuildKit, OCI push | Planned |
160+ | 2 | v0.2.0 | Daemon mode, persistence, metrics, notifier | Planned |
161+ | 3 | v0.3.0 | gRPC server and authenticated CLI client | Planned |
162+ | 4 | v1.0.0 | Chain expansion, C-FFI library, security audit | Planned |
163+
164+ See ` docs/ROADMAP.md ` for the full phase breakdown.
121165
122166---
123167
124- ## Architecture
168+ ## Technical Overview
169+
170+ This section covers internals relevant to contributors and operators.
171+
172+ ### Architecture
125173
126174```
127175dockermint-cli dockermint-daemon
@@ -141,8 +189,9 @@ dockermint-cli dockermint-daemon
141189 CROSS-CUTTING: logger, commands
142190```
143191
144- All modules are described in ` docs/specs/ ` . The full architecture reference is
145- ` docs/specs/architecture-overview.md ` .
192+ All module specs are in ` docs/specs/ ` . The full reference is
193+ [ docs.dockermint.io/architecture] ( https://docs.dockermint.io/architecture )
194+ or ` docs/specs/architecture-overview.md ` in this repository.
146195
147196### Module summary
148197
@@ -161,73 +210,55 @@ All modules are described in `docs/specs/`. The full architecture reference is
161210| ` logger ` | Structured logging with log rotation |
162211| ` commands ` | Shell command execution shared by all modules |
163212
164- ### Compile-time feature modules
165-
166- Dockermint modules are selectable at compile time. Default implementations:
213+ ### Template engine variables
167214
168- | Concern | Default implementation |
169- | :--------- | :-------------------------- |
170- | Database | RedB |
171- | Notifier | Telegram |
172- | VCS | GitHub |
173- | SSL | OpenSSL (vendored) |
174- | Registry | OCI |
175- | Builder | BuildKit |
176- | Metrics | Prometheus |
177-
178- ---
179-
180- ## Configuration
181-
182- Dockermint is configured via ` config.toml ` . Secrets (GitHub PAT, registry
183- credentials, notifier tokens) are stored exclusively in ` .env ` and are never
184- written to ` config.toml ` .
185-
186- All configuration files carry a ` config_version ` field. Unknown fields are
187- rejected at startup to prevent silent misconfiguration.
188-
189- See ` docs/specs/config.md ` for the full schema.
190-
191- ---
215+ Dockerfile content is produced by a template engine that resolves two classes
216+ of variables from the recipe:
192217
193- ## Compilation Targets
218+ - ` {{UPPERCASE}} ` — host variables injected by Dockermint (e.g. ` {{HOST_ARCH}} ` ,
219+ ` {{SEMVER_TAG}} ` , ` {{CREATION_TIMESTAMP}} ` )
220+ - ` {{lowercase}} ` — build variables resolved at build time, including
221+ shell-captured values (e.g. ` {{golang_version}} ` , ` {{wasmvm_version}} ` )
194222
195- Dockermint must compile and run on all five toolchains:
223+ ### Compile-time feature modules
196224
197- | Target |
198- | :----------------------------- |
199- | ` x86_64-unknown-linux-gnu ` |
200- | ` x86_64-unknown-linux-musl ` |
201- | ` aarch64-unknown-linux-gnu ` |
202- | ` aarch64-unknown-linux-musl ` |
203- | ` aarch64-apple-darwin ` |
225+ Key modules are selectable at compile time. Defaults:
204226
205- ---
227+ | Concern | Default implementation |
228+ | :------- | :--------------------- |
229+ | Database | RedB |
230+ | Notifier | Telegram |
231+ | VCS | GitHub |
232+ | SSL | OpenSSL (vendored) |
233+ | Registry | OCI |
234+ | Builder | BuildKit |
235+ | Metrics | Prometheus |
206236
207- ## Project Status
237+ ### Compilation targets
208238
209- | Phase | Target | Scope | Status |
210- | :---- | :------ | :--------------------------------------------- | :-------- |
211- | 0 | v0.1.0 | Architecture specs (all modules) | Complete |
212- | 1 | v0.2.0 | CLI mode, 5 chains, BuildKit, OCI push | Planned |
213- | 2 | v0.3.0 | Daemon mode, persistence, metrics, notifier | Planned |
214- | 3 | v0.4.0 | gRPC server and authenticated CLI client | Planned |
215- | 4 | v1.0.0 | Chain expansion, C-FFI library, security audit | Planned |
239+ Dockermint compiles and runs on all five toolchains:
216240
217- See ` docs/ROADMAP.md ` for the full phase breakdown.
241+ | Target |
242+ | :--------------------------- |
243+ | ` x86_64-unknown-linux-gnu ` |
244+ | ` x86_64-unknown-linux-musl ` |
245+ | ` aarch64-unknown-linux-gnu ` |
246+ | ` aarch64-unknown-linux-musl ` |
247+ | ` aarch64-apple-darwin ` |
218248
219249---
220250
221251## Contributing
222252
223- Development follows a structured workflow defined in ` CLAUDE.md ` :
224- architecture spec confirmed by the team, GitHub issue created, code
225- implemented against the spec, test suite and mutation testing passed, code
226- review approved, then committed and opened as a pull request. No step may be
227- skipped.
253+ Dockermint follows a design-first engineering workflow. Every feature begins
254+ with an architecture spec that is reviewed and confirmed before any code is
255+ written. A GitHub issue is opened to track the work, code is implemented
256+ against the spec, and the change must pass the full test suite — including
257+ mutation testing — before a pull request is opened. Code review is required
258+ before merge. No step may be skipped.
228259
229- See [ CLAUDE.md ] ( ./CLAUDE.md ) for the complete development workflow, agent
230- responsibilities, and contribution guidelines .
260+ See [ docs.dockermint.io/contributing ] ( https://docs.dockermint.io/contributing )
261+ or ` docs/ ` in this repository for the full contribution guide .
231262
232263---
233264
0 commit comments