feat: Add helm chart for the app (#65)

Author: tarampampam

.github/workflows/release.yml

@@ -32,10 +32,55 @@ jobs:
           platforms: linux/amd64,linux/arm64
           tags: |
             ghcr.io/${{ github.actor }}/3proxy:latest
-            ghcr.io/${{ github.actor }}/3proxy:${{ steps.slug.outputs.version-semantic }}
+            ghcr.io/${{ github.actor }}/3proxy:${{ steps.slug.outputs.version }}
             ghcr.io/${{ github.actor }}/3proxy:${{ steps.slug.outputs.version-major }}.${{ steps.slug.outputs.version-minor }}
             ghcr.io/${{ github.actor }}/3proxy:${{ steps.slug.outputs.version-major }}
             docker.io/tarampampam/3proxy:latest
-            docker.io/tarampampam/3proxy:${{ steps.slug.outputs.version-semantic }}
+            docker.io/tarampampam/3proxy:${{ steps.slug.outputs.version }}
             docker.io/tarampampam/3proxy:${{ steps.slug.outputs.version-major }}.${{ steps.slug.outputs.version-minor }}
             docker.io/tarampampam/3proxy:${{ steps.slug.outputs.version-major }}
+
+  helm-pack:
+    name: Pack the Helm chart
+    runs-on: ubuntu-latest
+    defaults: {run: {working-directory: ./deployments/helm}}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: azure/setup-helm@v4
+      - {uses: gacts/github-slug@v1, id: slug}
+      - run: |
+          helm package \
+            --app-version "${{ steps.slug.outputs.version }}" \
+            --version "${{ steps.slug.outputs.version }}" .
+      - uses: actions/upload-artifact@v4
+        with:
+          name: helm-chart
+          path: ./deployments/helm/*.tgz
+          if-no-files-found: error
+          retention-days: 1
+
+  helm-publish:
+    name: Put the Helm chart to the GitHub pages branch
+    runs-on: ubuntu-latest
+    needs: [helm-pack]
+    steps:
+      - {uses: actions/checkout@v4, with: {ref: gh-pages}}
+      - uses: azure/setup-helm@v4
+      - uses: actions/download-artifact@v4
+        with: {name: helm-chart, path: ./helm-charts}
+      - name: Update the index.yaml
+        run: |
+          helm repo index \
+            --url https://${{ github.actor }}.github.io/${{ github.event.repository.name }}/helm-charts/ \
+            --merge \
+            ./helm-charts/index.yaml \
+            ./helm-charts
+      - uses: yKicchan/generate-directory-listing-action@v1
+        with: {target: ., ignore: "**/index.html", override: true}
+      - name: Commit and push the changes
+        run: |
+          git config user.name "${{ github.actor }}"
+          git config user.email "${{ github.actor }}@users.noreply.github.com"
+          git add .
+          git commit -m "Helm chart release"
+          git push origin gh-pages

.github/workflows/tests.yml

@@ -24,9 +24,39 @@ jobs:
       - {uses: actions/checkout@v4, with: {fetch-depth: 0}}
       - uses: gacts/gitleaks@v1
 
+  filter:
+    name: Filter files
+    runs-on: ubuntu-latest
+    permissions: {pull-requests: read}
+    outputs:
+      docker: ${{ steps.filter.outputs.docker }}
+      helm: ${{ steps.filter.outputs.helm }}
+    steps:
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            docker: [Dockerfile, '*docker*', '*3proxy*']
+            helm: ['deployments/helm/**', '*kube*']
+
+  lint-charts:
+    name: Lint the chart
+    runs-on: ubuntu-latest
+    needs: [filter]
+    if: needs.filter.outputs.helm == 'true'
+    defaults: {run: {working-directory: ./deployments/helm}}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: azure/setup-helm@v4
+      - run: helm dependency update .
+      - run: helm template . > /dev/null
+      - run: helm lint --strict .
+
   build-image:
     name: Build the docker image
     runs-on: ubuntu-latest
+    needs: [filter] # since this is the initial step, we can filter out the rest of the jobs right here to skip them
+    if: needs.filter.outputs.docker == 'true'
     steps:
       - uses: actions/checkout@v4
       - run: docker build -f ./Dockerfile --tag 3proxy:local .

Dockerfile

@@ -2,19 +2,19 @@
 
 FROM gcc:13.3.0 AS builder
 
-# renovate: source=github-tags name=z3APA3A/3proxy
+# renovate: source=github-tags name=3proxy/3proxy
 ARG Z3PROXY_VERSION=0.9.4
 
 # Fetch 3proxy sources
 RUN set -x \
-    && git -c advice.detachedHead=false clone --depth 1 --branch "${Z3PROXY_VERSION}" https://github.com/z3APA3A/3proxy.git /tmp/3proxy
+    && git -c advice.detachedHead=false clone --depth 1 --branch "${Z3PROXY_VERSION}" https://github.com/3proxy/3proxy.git /tmp/3proxy
 
 WORKDIR /tmp/3proxy
 
 # Patch sources
 RUN set -x \
     && echo '#define ANONYMOUS 1' >> ./src/3proxy.h \
-    # proxy.c source: <https://github.com/z3APA3A/3proxy/blob/0.9.3/src/proxy.c>
+    # proxy.c source: <https://github.com/3proxy/3proxy/blob/0.9.3/src/proxy.c>
     && sed -i 's~\(<\/head>\)~<style>:root{--color-bg-primary:#fff;--color-text-primary:#131313;--color-text-secondary:#232323}\
 @media (prefers-color-scheme: dark){:root{--color-bg-primary:#212121;--color-text-primary:#fafafa;--color-text-secondary:#bbb}}\
 html,body{height:100%;font-family:sans-serif;background-color:var(--color-bg-primary);color:var(--color-text-primary);margin:0;\

README.md

@@ -70,6 +70,12 @@ Image: ghcr.io/tarampampam/3proxy:1.8.2
 | `EXTRA_CONFIG`       | Additional 3proxy configuration (appended to the **end** of the config file, but before `proxy` and `flush`)          | `# line 1\n# line 2`              |
 | `LOG_OUTPUT`         | Path for log output (`/dev/stdout` by default; set to `/dev/null` to disable logging)                                 | `/tmp/3proxy.log`                 |
 
+## Helm Chart
+
+To install it on Kubernetes (K8s), please use the Helm chart from [ArtifactHUB][artifact-hub].
+
+[artifact-hub]:https://artifacthub.io/packages/helm/proxy-3proxy/proxy-3proxy
+
 ## How to Use This Image
 
 Example usage:
@@ -78,7 +84,7 @@ Example usage:
 docker run --rm -d \
   -p "3128:3128/tcp" \
   -p "1080:1080/tcp" \
-  ghcr.io/tarampampam/3proxy:latest
+  ghcr.io/tarampampam/3proxy:1
 ```
 
 With authentication and custom resolver settings:
@@ -90,15 +96,15 @@ docker run --rm -d \
   -e "PROXY_LOGIN=evil" \
   -e "PROXY_PASSWORD=live" \
   -e "PRIMARY_RESOLVER=2001:4860:4860::8888" \
-  ghcr.io/tarampampam/3proxy:latest
+  ghcr.io/tarampampam/3proxy:1
 ```
 
 Docker compose example:
 
 ```yaml
 services:
   3proxy:
-    image: ghcr.io/tarampampam/3proxy:latest
+    image: ghcr.io/tarampampam/3proxy:1
     environment:
       PROXY_LOGIN: evil
       PROXY_PASSWORD: live
@@ -142,4 +148,4 @@ This project is licensed under the WTFPL. Use it freely and enjoy!
 [link_docker_tags]:https://hub.docker.com/r/tarampampam/3proxy/tags
 [link_docker_hub]:https://hub.docker.com/r/tarampampam/3proxy/
 [link_ghcr]:https://github.com/tarampampam/3proxy-docker/pkgs/container/3proxy
-[link_3proxy]:https://github.com/z3APA3A/3proxy
+[link_3proxy]:https://github.com/3proxy/3proxy

deployments/helm/Chart.yaml

@@ -0,0 +1,13 @@
+# yaml-language-server: $schema=https://json.schemastore.org/chart.json
+
+apiVersion: v2
+name: proxy-3proxy
+description: Powerful and lightweight proxy server, written in pure C
+
+type: application
+version: 0.0.0 # will be replaced by the release workflow
+appVersion: 0.0.0 # will be replaced by the release workflow
+icon: https://github.com/user-attachments/assets/023186cf-b153-459c-8417-038fd87a2065
+home: https://github.com/3proxy/3proxy
+sources: [https://github.com/tarampampam/3proxy-docker]
+keywords: [proxy, 3proxy, http, socks]

deployments/helm/README.md

@@ -0,0 +1,35 @@
+# 3proxy
+
+Important note: Since the chart is released together with the app under the same version (i.e., the chart version
+matches the app version), its versioning is not compatible with semantic versioning (SemVer). I will do my best to
+avoid non-backward-compatible changes in the chart, but due to Murphy's Law, I cannot guarantee that they will
+never occur.
+
+Also, this chart does not include Ingress configuration. If you need it, please, create it manually.
+
+## Usage
+
+```shell
+helm repo add proxy-3proxy https://tarampampam.github.io/3proxy-docker/helm-charts
+helm repo update
+
+helm install my-3proxy proxy-3proxy/proxy-3proxy --version <version_here>
+```
+
+Alternatively, add the following lines to your `Chart.yaml`:
+
+```yaml
+dependencies:
+  - name: proxy-3proxy
+    version: <version_here>
+    repository: https://tarampampam.github.io/3proxy-docker/helm-charts
+```
+
+And override the default values in your `values.yaml`:
+
+```yaml
+proxy-3proxy:
+  # ...
+  service: {ports: {http: 3128}}
+  # ...
+```

deployments/helm/templates/_helpers.tpl

@@ -0,0 +1,52 @@
+{{/* Define namespace of chart, useful for multi-namespace deployments */}}
+{{- define "proxy-3proxy.namespace" -}}
+  {{- if .Values.namespaceOverride }}
+    {{- .Values.namespaceOverride }}
+  {{- else }}
+    {{- .Release.Namespace }}
+  {{- end }}
+{{- end }}
+
+{{/* Expand the name of the chart */}}
+{{- define "proxy-3proxy.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+We truncate at 63 chars because some Kubernetes name fields are limited to this (by the DNS naming spec).
+If release name contains chart name it will be used as a full name.
+*/}}
+{{- define "proxy-3proxy.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 }}
+
+{{/* Create chart name and version as used by the chart label */}}
+{{- define "proxy-3proxy.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/* Common labels */}}
+{{- define "proxy-3proxy.commonLabels" -}}
+helm.sh/chart: {{ include "proxy-3proxy.chart" . }}
+{{ include "proxy-3proxy.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/* Selector labels */}}
+{{- define "proxy-3proxy.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "proxy-3proxy.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}