# [[Chartmuseum]] _Created: 2025-12-18_ | #kubernetes #helm | [[Kubernetes]] Self-hosted Helm repository. - Docs: https://chartmuseum.com/docs/ - Github: https://github.com/helm/chartmuseum ## Installation While there is a Helm chart available to use it, I prefer to install it via Docker Compose. This is so that I am able to mirror charts used for bootstrapping Kubernetes cluster itself. e.g. Argocd, Metallb, etc. ### Docker Compose I used the following docker-compose on Portainer: ```yaml services: chartmuseum: image: chartmuseum/chartmuseum:latest container_name: chartmuseum restart: unless-stopped ports: - "4980:8080" environment: PORT: 8080 DEBUG: 1 # depth-based multitenancy DEPTH: "1" # storage backend STORAGE: amazon STORAGE_AMAZON_BUCKET: chartmuseum STORAGE_AMAZON_PREFIX: "" STORAGE_AMAZON_REGION: us-east-1 STORAGE_AMAZON_ENDPOINT: "https://minio.local" # Usually needed for S3-compatible endpoints unless you’ve set up # virtual-hosted-style + wildcard DNS/certs STORAGE_AMAZON_FORCEPATHSTYLE: "true" # MinIO credentials (S3-compatible) AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID} AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY} # Auth AUTH_ANONYMOUS_GET: 1 BASIC_AUTH_USER: ${BASIC_AUTH_USER} BASIC_AUTH_PASS: ${BASIC_AUTH_PASS} ``` >[!note] > - chartmuseum supports configuration via both env variables and command line parameters. > - The credentials are passed in via env variables > - I am using [basic auth](https://chartmuseum.com/docs/#basic-auth), but it also supports [JWT token auth](https://chartmuseum.com/docs/#bearer-token-auth) > - For storage I am using S3 compatible Minio, but we can [store the charts in local filesystem](https://chartmuseum.com/docs/#using-with-local-filesystem-storage) too. > - I am using `--depth=1` which enables a single level of [multi-tenancy](https://chartmuseum.com/docs/#multitenancy). ## Pushing and Pulling Charts The Helm method of using Chartmuseum is probably the more likely usecase. You can also just [hit the API by using Curl](https://chartmuseum.com/docs/#uploading-a-chart-package). >[!note] Helm3 in the snippets > There is an [issue open](https://github.com/chartmuseum/helm-push/issues/225) about Helm4 compatibility. Also in my experience, during `helm repo add`, there was a warning with Helm4. For this reason, I prefer using Helm3 for the commands below. Helm4 might also work, but I have not tested it. ### helm plugin Chartmuseum is not [oci compatible](https://helm.sh/docs/topics/registries/) (the new standard in Helm repositories). And therefore, if you want to use helm to push charts, you need to use this plugin. Helm push plugin: https://github.com/chartmuseum/helm-push ```shell-session helm3 plugin install https://github.com/chartmuseum/helm-push ``` ### Add repo to Helm With multitenancy, we have a unique repo per tenant. If I am mirroring bitnami charts for example, I will add a separate repo for it like this. ```shell-session $ helm3 repo add --username $CM_USER --password $CM_PASS bitnami-mirror https://charts.local/bitnami "bitnami-mirror" has been added to your repositories ``` - If you are not using multitenancy, drop the tenant path. - If you are not using auth, you don't need to provide the equivalent credential parameters. - I haven't tested it, but if, like me, you have allowed anonymous get (`AUTH_ANONYMOUS_GET` env variable), and you only intend to pull charts and not upload, you don't need to specify the credentials during `helm repo add`. - Even if you intend to push charts, you can drop the credentials in `helm repo add`, and provide them directly at the command line during `helm3 cm-push`. ### Pushing a chart Then I can push a chart to that repo using: ```shell-session $ helm3 cm-push sealed-secrets-2.17.9.tgz bitnami-mirror Pushing sealed-secrets-2.17.9.tgz to bitnami-mirror... Done. ``` ### Listing charts in repo Remember to update the repo if you are expecting to see a recently pushed chart. ```shell-session $ helm3 repo update bitnami-mirror ... Update Complete. ⎈Happy Helming!⎈ $ helm3 search repo bitnami-mirror NAME CHART VERSION APP VERSION DESCRIPTION bitnami-mirror/sealed-secrets 2.17.9 0.33.1 Helm chart for the sealed-secrets controller. ``` ## Web UI There is none, actually. If you try to go to the http endpoint, you will see a generic landing page. While you can access the metadata file at `$URL/$TENANT/index.yaml`, the browser is likely to force you to download that file instead of showing it natively in the browser. ## Alternatives and the future of Chartmuseum There is also the Harbor project. However, it handles more than just Helm charts, and looked more complex to install. I decided to consider it for a future upgrade. It is pretty like that Chartmuseum will be deprecated because its API is non-standard and requires a plugin to push charts. That is unless someone decides to make a new version which is OCI compatible.