chartpress

= chartpress
:doctype: article
:description: A README template written in AsciiDoc markup
:toc: macro
:toclevels: 3
:source-highlighter: highlightjs
:imagesdir: docs/images
ifdef::env-github[]
:tip-caption: :rocket:
:!showtitle:
:icons: font
endif::[]

++++
<p align="center">
  <img width="275" height="275" src="docs/chartpress.png">
</p>
<p align="center">
    <h1 align="center">chartpress</h1>


    <!-- REPLACE THE FOLLOWING WITH YOUR REPOSITORY/PROJECT'S SHORT DESCRIPTION -->
    <h3 align="center">an Helm Chart scaffolding tool</h3>
        <p align="center">
      <img height=20 src="https://img.shields.io/badge/github%20actions-%232671E5.svg?style=for-the-badge&logo=githubactions&logoColor=white">
  <img height=20 src="https://img.shields.io/badge/Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black">
  <img height=20 src="https://img.shields.io/badge/Go-00ADD8?style=for-the-badge&logo=go&logoColor=white">

</p>
<br/>
++++

image:https://img.shields.io/github/languages/top/kriipke/chartpress[Top Language]
image:https://img.shields.io/github/repo-size/kriipke/chartpress[Repo Size]

Effortlessly scaffold umbrella Helm charts and their subcharts for your Kubernetes apps from a single config file. Chartpress streamlines CI/CD for cloud-native deployments—fast, flexible, and built for modern DevOps.

toc::[]

== Features

* Generate an umbrella Helm chart and its subcharts from a single config file
* Pick a workload type per subchart (Deployment, StatefulSet, or DaemonSet)
* Use it three ways: a CLI (`chartpress`), an HTTP API (`chartpress-server`), or the web wizard
* Ships reusable umbrella/subchart templates plus a Helm chart to self-host the service
* Written in Go and JavaScript

== Getting Started

=== Prerequisites

* link:https://golang.org/doc/install[Go] (1.18+ recommended)
* link:https://helm.sh/[Helm] (v3+)
* Docker (for containerized workflows; optional)

=== Installation

.Clone using Git
[source,sh]
----
git clone git@github.com:kriipke/chartpress.git
cd chartpress
----

.Build the binaries
[source,sh]
----
# CLI
go build -o chartpress ./cmd/chartpress
# HTTP server (optional)
go build -o chartpress-server ./cmd/server
----

.Run using Docker (optional)
[source,sh]
----
docker build -t chartpress .
docker run --rm -v $(pwd):/work chartpress [command] [options]
----

== Usage

=== Configuration

Chartpress reads a config file (default `./chartpress.yaml`) describing the
umbrella chart and its subcharts:

[source,yaml]
----
umbrellaChartName: saas-platform
subcharts:
  - name: api
    workload: deployment
  - name: cache
    workload: deployment
  - name: database
    workload: statefulset
----

`workload` must be one of `deployment`, `statefulset`, or `daemonset`.

=== Generate a Chart (CLI)

The `create` command renders the umbrella chart and subcharts into
`output/<umbrellaChartName>-<timestamp>/`:

[source,sh]
----
./chartpress create my-platform
----

Flags:

[cols="1,3"]
|===
| Flag | Description

| `-c, --config` | Path to the config file (default `./chartpress.yaml`)
| `--umbrella-template` | Path to the umbrella chart template (default `./templates/umbrella`)
| `--subchart-template` | Path to the subchart template (default `./templates/subchart`)
|===

Run `./chartpress --help` for all options.

=== Generate a Chart (HTTP server)

Start the server (listens on `$PORT`, default `8080`):

[source,sh]
----
./chartpress-server
----

Generation is asynchronous. `POST /generate` validates the config, applies it
to the cluster as a `ChartpressConfig` resource, and returns immediately with
`phase: "Pending"`; the operator renders the chart and uploads the archive to
object storage in the background:

[source,sh]
----
curl -X POST http://localhost:8080/generate \
  -H "Content-Type: application/json" \
  --data '{"umbrellaChartName":"saas-platform","subcharts":[{"name":"api","workload":"deployment"}]}'
# => {"name":"saas-platform","namespace":"chartpress","phase":"Pending","manifestYaml":"..."}
----

Poll `GET /charts` for status. Each row carries the current `phase`
(`Pending` → `Generating` → `Ready`/`Failed`); once `Ready`, `downloadUrl` holds
a short-lived presigned link to the generated chart archive:

[source,sh]
----
curl http://localhost:8080/charts
# => [{"name":"saas-platform","phase":"Ready","subchartCount":1,"downloadUrl":"https://..."}]
----

Other endpoints: `GET /charts/<name>` (single status), `GET /charts/<name>/files`
(read-only rendered file tree), `POST /text-to-config` (draft a config from a
natural-language prompt via OpenAI), and `/auth/*` (optional GitHub sign-in).

== Example CI/CD Integration

For GitHub Actions:

[source,yaml]
----
- name: Build chartpress
  run: go build -o chartpress ./cmd/chartpress

- name: Generate umbrella chart
  run: ./chartpress create my-platform --config ./chartpress.yaml
----

== Architecture Overview

[plantuml]
----
@startuml
actor User
participant "chartpress CLI / web wizard" as Client
participant "chartpress(-server)" as Engine
participant "Chart templates" as Templates
participant "output/ (chart + .zip)" as Output

User -> Client : Provide config (chartpress.yaml / JSON)
Client -> Engine : create / POST /generate
Engine -> Templates : Render umbrella + subcharts
Engine -> Output : Write generated chart (and archive)
@enduml
----

== Development

* Go code in `cmd/` (entrypoints) and `internal/` (server logic)
* Chart templates in `templates/umbrella` and `templates/subchart`
* React/Vite web wizard in `web/`
* Makefile for common tasks (`make build-api`, `make build-web`, `make tests`)

=== Running Tests

`make verify` is the canonical quality gate — Go tests and vet, frontend unit
tests and production build, Helm lint, generated-template validation, archive
validation, and dependency-license policy:

[source,sh]
----
make verify
----

`make tests` is a retained alias for the Go unit/regression suite only
(`test-go`). It is unrelated to `make smoke`, which posts a sample config to a
running `chartpress-server` (default port 8080) and saves the resulting
archive — a live-server check, not part of the required gate. See
link:DEVELOPMENT.md[DEVELOPMENT.md] for the full toolchain and hermetic
verification image.

== Contributing

See link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] for the project's contribution
policy.

== License

Licensed under the Apache License, Version 2.0. See the link:LICENSE[LICENSE]
file, and link:NOTICE[NOTICE] for attribution.

== Authors & Acknowledgements

* link:https://github.com/kriipke[@kriipke] - creator and primary maintainer

== See Also

* link:https://helm.sh/[Helm]
* link:https://github.com/helm/chart-testing[chart-testing]
* link:https://microservice-api-patterns.github.io/MDSL-Specification/tutorial[MDSL Specification]

== Security

If you discover any security-related issues, please email kriipke@users.noreply.github.com instead of using the issue tracker.

== Changelog

See link:CHANGELOG.adoc[CHANGELOG.adoc] for recent changes.