feat(chart): add helm chart for kubernetes

.github/workflows/chart-ci.yml

@@ -0,0 +1,48 @@
+name: Chart CI
+
+on:
+  pull_request:
+    paths:
+      - charts/**
+      - .github/workflows/chart-ci.yml
+      - .github/workflows/chart-release.yml
+      - .kube-linter.yaml
+  push:
+    branches:
+      - dev
+    paths:
+      - charts/**
+      - .github/workflows/chart-ci.yml
+      - .github/workflows/chart-release.yml
+      - .kube-linter.yaml
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: azure/setup-helm@v4
+
+      - name: Lint chart
+        run: helm lint charts/explo --strict
+
+      - name: Render chart
+        run: |
+          helm template test charts/explo
+          helm template test charts/explo \
+            --set auth.username=admin \
+            --set auth.password=ci-only
+          helm template test charts/explo \
+            --set persistence.media.existingClaim=media-pvc \
+            --set persistence.media.subPath=explo
+          helm template test charts/explo \
+            --set ingress.enabled=true \
+            --set ingress.className=traefik \
+            --set-json 'ingress.hosts=[{"host":"explo.example.com","paths":[{"path":"/","pathType":"Prefix"}]}]'
+
+      - name: Lint manifests
+        uses: stackrox/kube-linter-action@v1
+        with:
+          directory: charts/explo
+          config: .kube-linter.yaml

.github/workflows/chart-release.yml

@@ -0,0 +1,112 @@
+name: Chart Release
+
+on:
+  workflow_run:
+    workflows:
+      - Latest Release
+    types:
+      - completed
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    if: github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.workflow_run.head_sha }}
+
+      - name: Resolve release tag
+        id: tag
+        run: |
+          SHA="${{ github.event.workflow_run.head_sha }}"
+          TAG=$(git tag -l 'v*' --points-at "$SHA" | sort -V | tail -1)
+          if [ -z "$TAG" ]; then
+            echo "No v* tag found for ${SHA}; skipping chart publish"
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          VERSION="${TAG#v}"
+          echo "skip=false" >> "$GITHUB_OUTPUT"
+          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+
+      - name: Skip when chart is missing
+        id: chart
+        if: steps.tag.outputs.skip != 'true'
+        run: |
+          if [ ! -f charts/explo/Chart.yaml ]; then
+            echo "present=false" >> "$GITHUB_OUTPUT"
+            echo "No chart at this tag"
+            exit 0
+          fi
+          echo "present=true" >> "$GITHUB_OUTPUT"
+
+      - uses: azure/setup-helm@v4
+        if: steps.tag.outputs.skip != 'true' && steps.chart.outputs.present == 'true'
+
+      - name: Package chart
+        if: steps.tag.outputs.skip != 'true' && steps.chart.outputs.present == 'true'
+        run: |
+          mkdir -p dist
+          helm package charts/explo \
+            --version "${{ steps.tag.outputs.version }}" \
+            --app-version "${{ steps.tag.outputs.tag }}" \
+            --destination dist
+          echo "package=${GITHUB_WORKSPACE}/dist/$(ls dist)" >> "$GITHUB_ENV"
+
+      - name: Upload release asset
+        if: steps.tag.outputs.skip != 'true' && steps.chart.outputs.present == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release upload "${{ steps.tag.outputs.tag }}" "$package" --clobber
+
+      - name: Publish gh-pages
+        if: steps.tag.outputs.skip != 'true' && steps.chart.outputs.present == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          PAGES_DIR="${RUNNER_TEMP}/gh-pages"
+          REPO="${{ github.repository }}"
+          PAGES_URL="https://lumepart.github.io/Explo"
+          TAG="${{ steps.tag.outputs.tag }}"
+
+          if git ls-remote --exit-code --heads "https://github.com/${REPO}.git" gh-pages >/dev/null 2>&1; then
+            git clone --branch gh-pages \
+              "https://x-access-token:${GH_TOKEN}@github.com/${REPO}.git" \
+              "$PAGES_DIR"
+          else
+            mkdir -p "$PAGES_DIR"
+            cd "$PAGES_DIR"
+            git init
+            git checkout -b gh-pages
+            git remote add origin "https://x-access-token:${GH_TOKEN}@github.com/${REPO}.git"
+          fi
+
+          cp "$package" "$PAGES_DIR/"
+          if [ -f pages/index.html ]; then
+            cp pages/index.html "$PAGES_DIR/index.html"
+          fi
+
+          if [ -f "$PAGES_DIR/index.yaml" ]; then
+            helm repo index "$PAGES_DIR" --url "$PAGES_URL" --merge "$PAGES_DIR/index.yaml"
+          else
+            helm repo index "$PAGES_DIR" --url "$PAGES_URL"
+          fi
+
+          cd "$PAGES_DIR"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add .
+          if git diff --staged --quiet; then
+            echo "No gh-pages changes for ${TAG}"
+            exit 0
+          fi
+          git commit -m "chore(chart): publish ${TAG}"
+          git push origin gh-pages

.gitignore

@@ -4,7 +4,7 @@
 tmp/
 .air.toml
 logs/
-explo
+/explo
 src/web/dist/
 src/web/frontend/node_modules/
 /cache

.kube-linter.yaml

@@ -0,0 +1,6 @@
+checks:
+  exclude:
+    - no-read-only-root-fs
+    - run-as-non-root
+    - unset-cpu-requirements
+    - unset-memory-requirements

README.md

@@ -43,6 +43,15 @@ Or jump directly to:
 - [FAQ](https://github.com/LumePart/Explo/wiki/8.-FAQ) – Common questions
 
 
+## Kubernetes
+
+```bash
+helm repo add explo https://lumepart.github.io/Explo && helm repo update
+helm install explo explo/explo --namespace explo --create-namespace
+```
+
+See [charts/explo/README.md](charts/explo/README.md).
+
 ## Acknowledgements
 
 Explo uses the following 3rd-party libraries:

charts/explo/.helmignore

@@ -0,0 +1,13 @@
+.DS_Store
+*.swp
+*.bak
+*.tmp
+*.orig
+*~
+.git/
+.gitignore
+.bzr/
+.bzrignore
+.hg/
+.hgignore
+.svn/

charts/explo/Chart.yaml

@@ -0,0 +1,17 @@
+apiVersion: v2
+name: explo
+description: Helm chart for Explo music discovery
+type: application
+version: 0.0.0
+appVersion: dev
+home: https://github.com/LumePart/Explo
+sources:
+  - https://github.com/LumePart/Explo
+maintainers:
+  - name: LumePart
+    url: https://github.com/LumePart
+keywords:
+  - explo
+  - music
+  - listenbrainz
+  - jellyfin

charts/explo/README.md

@@ -0,0 +1,47 @@
+# explo
+
+Helm chart for [Explo](https://github.com/LumePart/Explo).
+
+## Install
+
+```bash
+helm repo add explo https://lumepart.github.io/Explo
+helm repo update
+helm install explo explo/explo --namespace explo --create-namespace
+```
+
+## Example values
+
+```yaml
+ingress:
+  enabled: true
+  className: traefik
+  annotations:
+    cert-manager.io/cluster-issuer: letsencrypt
+  hosts:
+    - host: explo.example.com
+      paths:
+        - path: /
+          pathType: Prefix
+  tls:
+    - secretName: explo-tls
+      hosts: [explo.example.com]
+
+persistence:
+  config:
+    storageClass: longhorn
+  media:
+    existingClaim: music-library
+    subPath: explo
+
+extraEnv:
+  EXPLO_SYSTEM: jellyfin
+  SYSTEM_URL: http://jellyfin.jellyfin.svc.cluster.local:8096
+  API_KEY: your-api-key
+  LIBRARY_NAME: Music
+```
+
+
+Config is stored under `/opt/explo/config` (`WEB_ENV_PATH`). Downloads go to `/data`.
+
+See `values.yaml` for all knobs.

charts/explo/templates/NOTES.txt

@@ -0,0 +1,9 @@
+Explo is installed in namespace {{ .Release.Namespace }}.
+
+{{- if .Values.ingress.enabled }}
+{{- range .Values.ingress.hosts }}
+  http{{- if $.Values.ingress.tls }}s{{- end }}://{{ .host }}
+{{- end }}
+{{- else }}
+  kubectl port-forward -n {{ .Release.Namespace }} svc/{{ include "explo.fullname" . }} 7288:{{ .Values.service.port }}
+{{- end }}

charts/explo/templates/_helpers.tpl

@@ -0,0 +1,95 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "explo.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+*/}}
+{{- define "explo.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{/*
+Common labels
+*/}}
+{{- define "explo.labels" -}}
+helm.sh/chart: {{ include "explo.name" . }}-{{ .Chart.Version | replace "+" "_" }}
+{{ include "explo.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Selector labels
+*/}}
+{{- define "explo.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "explo.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}
+
+{{/*
+Image tag defaults to Chart appVersion.
+*/}}
+{{- define "explo.imageTag" -}}
+{{- .Values.image.tag | default .Chart.AppVersion }}
+{{- end }}
+
+{{/*
+Auth secret name when using inline credentials.
+*/}}
+{{- define "explo.authSecretName" -}}
+{{- if .Values.auth.existingSecret }}
+{{- .Values.auth.existingSecret }}
+{{- else }}
+{{- include "explo.fullname" . }}-auth
+{{- end }}
+{{- end }}
+
+{{/*
+True when UI credentials are injected at install time.
+*/}}
+{{- define "explo.authConfigured" -}}
+{{- if .Values.auth.existingSecret -}}
+true
+{{- else if and .Values.auth.username .Values.auth.password -}}
+true
+{{- else -}}
+false
+{{- end }}
+{{- end }}
+
+{{/*
+Config PVC claim name.
+*/}}
+{{- define "explo.configClaimName" -}}
+{{- if .Values.persistence.config.existingClaim }}
+{{- .Values.persistence.config.existingClaim }}
+{{- else }}
+{{- include "explo.fullname" . }}-config
+{{- end }}
+{{- end }}
+
+{{/*
+Media PVC claim name.
+*/}}
+{{- define "explo.mediaClaimName" -}}
+{{- if .Values.persistence.media.existingClaim }}
+{{- .Values.persistence.media.existingClaim }}
+{{- else }}
+{{- include "explo.fullname" . }}-media
+{{- end }}
+{{- end }}