Skip to content
Tutorials Center
My learning

Topics

Lesson 72 of 78 ยท Projects

Project: A Self-Hosted Git Server (Gitea) with Helm

Install a self-hosted Git server on Kubernetes with the Gitea Helm chart: values file, persistent volume, ingress, first admin and repository push, upgrade and cleanup.

Helm is how most people install other people's software on Kubernetes. In this project you will use it for a realistic job: running Gitea, a lightweight Git hosting service with repositories, pull requests, issues and a package registry, inside your own cluster. You will write a small values.yaml, install the chart, expose it through an Ingress, create an administrator, push a first repository, upgrade the release and remove everything cleanly.

Previously you built a chart yourself in the Helm chart project. Here you are the consumer: you read a chart's values, decide what to override and operate the release. There is no cluster or Helm on this site, so the commands and manifests are read-only. What was run for this lesson: Gitea itself, in Docker, with the same SQLite configuration, a persistent volume at /data, the /api/healthz endpoint, creating an admin and pushing a repository over HTTP. Chart value names change between chart versions, so always compare with helm show values for the version you install. The runnable examples are Python models.

The plan

flowchart LR
  user["git / browser"] -->|"HTTPS"| ing["Ingress<br/>git.example.test"]
  ing --> svc["Service gitea-http :3000"]
  svc --> pod["Gitea Pod"]
  pod --> pvc[("PVC 5Gi<br/>/data")]
  user -.->|"SSH (optional)"| ssh["Service gitea-ssh :22"]
  ssh --> pod

Everything Gitea stores (database file, repositories, attachments, configuration) lives under /data, so one PersistentVolumeClaim is enough for a small install.

Pieces you will touch: a Helm release, a PVC, two Services (web and SSH), an Ingress, and a Secret for the admin password. Related background: Helm Basics, Persistent Volumes, Ingress, and the container-level view of the same tool in Running Dev Tools in Containers.

Step 1: Find the chart and read its values

Terminal
helm repo add gitea-charts https://dl.gitea.com/charts/
helm repo update
helm search repo gitea-charts/gitea
helm show values gitea-charts/gitea > default-values.yaml

Open default-values.yaml. It is long, and that is normal. Find the sections you care about:

  • service and ingress: how the chart exposes HTTP and SSH.
  • persistence: whether and how big the data volume is.
  • gitea.admin: the first administrator.
  • gitea.config: settings that end up in Gitea's app.ini.
  • Sub-charts for a database and a cache (PostgreSQL and Valkey/Redis in current charts). By default the chart installs a highly available database and cache, which is far more than a small team needs.

Always pin the chart version when you install, so that an upgrade is a conscious decision: --version <x.y.z> (shown in the search output).

Step 2: Write your values file

Your values file contains only what you change. Helm deep-merges it over the chart defaults. For a small single-replica install with SQLite:

YAML
# values.yaml
replicaCount: 1

service:
  http:
    type: ClusterIP
    port: 3000
  ssh:
    type: ClusterIP
    port: 22

ingress:
  enabled: true
  className: nginx
  hosts:
    - host: git.example.test
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: gitea-tls
      hosts:
        - git.example.test
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: 512m   # allow big pushes over HTTP

persistence:
  enabled: true
  size: 5Gi
  # storageClass: fast-ssd          # uncomment to choose one; empty means the cluster default

gitea:
  admin:
    existingSecret: gitea-admin     # created in step 3, so no password in this file
  config:
    database:
      DB_TYPE: sqlite3
    session:
      PROVIDER: memory
    cache:
      ADAPTER: memory
    queue:
      TYPE: level
    server:
      DOMAIN: git.example.test
      ROOT_URL: https://git.example.test/
    service:
      DISABLE_REGISTRATION: true

# turn the bundled HA database and cache off, because SQLite and in-memory cache are enough here
postgresql-ha:
  enabled: false
postgresql:
  enabled: false
valkey-cluster:
  enabled: false
valkey:
  enabled: false

Things to understand in this file:

  • gitea.config is the chart's way to set app.ini. Each key under a section becomes a setting. Gitea also reads the same settings as environment variables named GITEA__SECTION__KEY, which is how the container image is configured. The model below converts one to the other, so the mapping is visible.
  • SQLite and in-memory cache keep the footprint tiny, but they limit you to one replica. For a team that depends on the server, switch to PostgreSQL and keep the sub-chart or an external database (Stateful Apps and Backups).
  • Sub-chart value names differ between chart versions (postgresql-ha, postgresql, valkey-cluster, redis-cluster, ...). Check which ones exist in your default-values.yaml and disable the ones you do not want; the key point is to avoid an unplanned multi-node database.
  • ROOT_URL must match the external address exactly. Gitea builds clone URLs, redirects and webhook links from it.
Python From chart values to app.ini and environment variables

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Step 3: Create the namespace and the admin Secret

Keep the first administrator's password out of values files and Git history:

Terminal
kubectl create namespace git
kubectl create secret generic gitea-admin -n git \
  --from-literal=username=gitadmin \
  --from-literal=password='choose-a-long-password' \
  --from-literal=email=admin@example.test

The gitea.admin.existingSecret setting tells the chart to read the three keys from this Secret (Secrets). If the chart version you use has a different admin option, helm show values will say so.

Step 4: Preview, then install

Render the manifests first, without touching the cluster:

Terminal
helm template gitea gitea-charts/gitea -n git -f values.yaml > rendered.yaml
grep '^kind:' rendered.yaml | sort | uniq -c

Read what will be created: expect a StatefulSet or Deployment, two Services (gitea-http and gitea-ssh), a PersistentVolumeClaim, an Ingress, Secrets and ConfigMaps. Surprises here (for example, a database StatefulSet you did not want) are much cheaper to fix now.

Install, using upgrade --install so the same command works for the first install and every update:

Terminal
helm upgrade --install gitea gitea-charts/gitea \
  --namespace git \
  --version <x.y.z> \
  -f values.yaml \
  --wait --timeout 10m

--wait makes Helm wait until the workload is ready, which catches a Pod that cannot start (a Pending PVC with no StorageClass is the classic cause; see Storage Classes). Then check:

Terminal
helm list -n git
kubectl get pods,svc,pvc,ingress -n git
TEXT
NAME                READY   STATUS    RESTARTS   AGE
pod/gitea-0         1/1     Running   0          2m

NAME                TYPE        CLUSTER-IP     PORT(S)
service/gitea-http  ClusterIP   10.96.12.40    3000/TCP
service/gitea-ssh   ClusterIP   10.96.12.41    22/TCP

NAME                              STATUS   CAPACITY   STORAGECLASS
persistentvolumeclaim/gitea-...   Bound    5Gi        standard

(Example shape only; names and addresses depend on the chart version and cluster.)

Step 5: Reach it

Before DNS and ingress work, use a tunnel:

Terminal
kubectl port-forward -n git svc/gitea-http 3000:3000
curl -s http://127.0.0.1:3000/api/healthz

The health endpoint answers like this (checked against the same Gitea in Docker):

TEXT
{ "status": "pass", "description": "Gitea: Git with a cup of tea",
  "checks": { "database:ping": [ { "status": "pass", ... } ], "cache:ping": [ { "status": "pass", ... } ] } }

Through the Ingress: point git.example.test at your ingress controller (an /etc/hosts entry on a laptop cluster, a DNS record or a load balancer address elsewhere), and open https://git.example.test/. Log in as the admin you stored in the Secret. If you installed an ingress controller and cert-manager, the tls block and an issuer annotation give you a real certificate (Ingress).

A frequent mistake is a mismatch between ROOT_URL, the Ingress host and TLS. The checker below shows the symptoms:

Python ROOT_URL, Ingress and clone URLs must agree

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Step 6: Push your first repository

Create an empty repository in the web UI (or with the API), then push an existing project:

Terminal
git init -b main hello && cd hello
echo "# hello" > README.md
git add . && git commit -m "first commit"
git remote add origin https://git.example.test/gitadmin/hello.git
git push -u origin main

Use a personal access token instead of your password where you can (User settings, Applications). The same flow was run against Gitea in Docker with HTTP: the repository was created through the API, git push -u origin main printed [new branch] main -> main, and the repository directory appeared under /data/git/repositories/<user>/hello.git.

For git clone over SSH you need the SSH Service reachable from outside the cluster: a LoadBalancer or NodePort for gitea-ssh, or a TCP passthrough on your ingress controller. HTTPS is simpler to start with. Many teams also enable Gitea Actions and register a runner later.

Step 7: Prove the data survives

The PVC is what makes this a real service. Delete the Pod and let the controller recreate it:

Terminal
kubectl delete pod gitea-0 -n git
kubectl get pods -n git -w

When it is back, your repository, users and settings are still there, because /data lives on the PVC (Persistent Volumes). A volume is not a backup, though. Take regular backups of the PVC (a VolumeSnapshot, Velero, or gitea dump run inside the Pod and copied out), and test a restore (Stateful Apps and Backups).

Step 8: Upgrade and roll back

Change values.yaml or the chart version, and run the same helm upgrade --install command. Helm keeps a history of releases:

Terminal
helm history gitea -n git
helm get values gitea -n git          # what you set
helm diff upgrade gitea ...           # needs the helm-diff plugin, useful in review
helm rollback gitea 1 -n git          # back to revision 1

Before upgrading Gitea to a new major version, read the release notes, back up the data, and test on a copy. With SQLite on one replica, the upgrade restarts the only Pod, so expect a short outage.

Step 9: Clean up

Terminal
helm uninstall gitea -n git
kubectl get pvc -n git            # check whether the data volume remains
kubectl delete pvc --all -n git   # destroys the repositories!
kubectl delete namespace git

helm uninstall removes what the chart created. Whether the PVC remains depends on how the chart creates it and on the StorageClass reclaim policy: with Delete the volume is wiped, with Retain the data stays on the storage backend. Check before you assume the data is gone or kept (Storage Classes).

What is real and what is a stand-in

  • Real (run in Docker for this lesson): Gitea with SQLite and a data volume, the GITEA__section__KEY environment mapping, the health endpoint, admin creation, a repository push over HTTP and the data surviving a container replacement.
  • Read-only (not run here): Helm, the chart's values and sub-chart names, the Ingress, TLS and SSH exposure, and the cluster commands. Verify them against your chart version.
  • Stand-ins: the two Python models of config mapping and URL consistency.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What should a values.yaml file for a chart release contain?

    Helm deep-merges your values over the chart defaults. A small file is easier to review and upgrade.
  2. 2. Why use helm upgrade --install in scripts and pipelines?

    The same idempotent command works for first install and later changes.
  3. 3. Why does the project set SQLite and in-memory cache and disable the bundled database sub-charts?

    SQLite is enough for one replica and a small team. It limits you to one Pod, so growth means switching to PostgreSQL.
  4. 4. Which setting must match the external address of the service?

    Gitea builds clone URLs and redirects from ROOT_URL, so a mismatch with the Ingress host or scheme breaks links.
  5. 5. You delete the Gitea Pod. What happens to the repositories?

    State lives on the PVC. The new Pod mounts it, but you should still keep separate backups.

Summary

  • Helm installs third-party software from a chart; you supply a small values.yaml, pin the chart version and render with helm template before installing.
  • For a small Gitea: SQLite, in-memory cache, one replica, a 5 Gi PVC at /data, a ClusterIP Service behind an Ingress, and the admin credentials in a Secret.
  • ROOT_URL, the Ingress host and TLS must agree. Test with port-forward and /api/healthz first.
  • The PVC keeps your data across Pod restarts, but it is not a backup.
  • helm upgrade --install for changes, helm rollback for mistakes, and check what remains (PVC) after helm uninstall.

Next, automate deployments like this one with Project: CI/CD with GitOps.