DEV Community

Tamiz Uddin
Tamiz Uddin

Posted on Originally published at tamiz.pro

Building Self-Hosted Developer Tools with TrueCharts: Deploying Private Services Like AdGuard and V2Ray on Kubernetes

#nextjs #javascript #react #self

Originally published on tamiz.pro.

Self-hosting developer tools gives teams control over privacy, performance, and cost—especially when those tools run on Kubernetes. TrueCharts provides a curated catalog of Helm charts that simplify deploying complex applications like AdGuard Home (DNS-based ad blocking) and V2Ray (secure proxy/tunneling) into a Kubernetes cluster. This guide walks through installing both services using TrueCharts, configuring them for production use, and exposing them securely.

Prerequisites

Before starting:

  • A running Kubernetes cluster (e.g., k3s, MicroK8s, or cloud-managed like EKS/GKE)
  • kubectl configured to access the cluster
  • Helm v3+ installed locally
  • Basic familiarity with Kubernetes concepts (namespaces, services, ingress)

We’ll install everything into a dedicated namespace called truecharts-system.

kubectl create ns truecharts-system
Enter fullscreen mode Exit fullscreen mode

Step 1: Add the TrueCharts Helm Repository

TrueCharts maintains its own Helm repository with stable releases. Add it to your local configuration:

helm repo add truecharts https://charts.truecharts.org/stable
helm repo update
Enter fullscreen mode Exit fullscreen mode

Verify the repository is available:

helm search repo truecharts/adguard
helm search repo truecharts/v2ray
Enter fullscreen mode Exit fullscreen mode

Both should return version information if the charts exist.

Step 2: Deploy AdGuard Home Using TrueCharts

AdGuard Home provides network-wide DNS filtering. We’ll define a custom values file to configure persistence and expose it via ClusterIP initially.

Create adguard-values.yaml:

image:
  repository: ghcr.io/truecharts/adguard
  tag: latest

persistence:
  enabled: true
  storageClass: ""
  accessModes:
    - ReadWriteOnce
  size: 1Gi

service:
  main:
    enabled: true
    ports:
      http:
        port: 3000
        targetPort: 3000
      dns-tcp:
        port: 53
        protocol: TCP
      dns-udp:
        port: 53
        protocol: UDP
    type: ClusterIP

ingress:
  main:
    enabled: false
Enter fullscreen mode Exit fullscreen mode

Install the chart:

helm install adguard truecharts/adguard \
  -n truecharts-system \
  -f adguard-values.yaml
Enter fullscreen mode Exit fullscreen mode

Wait for pods to start:

kubectl -n truecharts-system get pods
Enter fullscreen mode Exit fullscreen mode

Once ready, forward port 3000 temporarily to complete initial setup:

kubectl -n truecharts-system port-forward svc/adguard 3000:3000
Enter fullscreen mode Exit fullscreen mode

Visit http://localhost:3000 and follow the web UI to complete configuration (set admin password, choose upstream DNS servers, etc.).

Tip: You can re-export the final config from the UI after setup and bake it into future deployments using a ConfigMap.

Step 3: Expose AdGuard Internally via DNS Service

To route traffic inside the cluster to AdGuard’s DNS resolver, create a separate service definition in your values file or override defaults.

Update adguard-values.yaml under service:

service:
  main:
    enabled: true
    ports:
      http:
        port: 3000
        targetPort: 3000
      dns-tcp:
        port: 53
        protocol: TCP
      dns-udp:
        port: 53
        protocol: UDP
    type: ClusterIP
Enter fullscreen mode Exit fullscreen mode

Apply updated config:

helm upgrade adguard truecharts/adguard \
  -n truecharts-system \
  -f adguard-values.yaml
Enter fullscreen mode Exit fullscreen mode

Now other workloads can resolve domains through AdGuard by pointing their DNS settings to:

adguard.truecharts-system.svc.cluster.local
Enter fullscreen mode Exit fullscreen mode

Step 4: Deploy V2Ray for Secure Tunneling

V2Ray creates encrypted proxy tunnels. It's useful for developers needing secure access to internal resources without exposing them publicly.

Create v2ray-values.yaml:

image:
  repository: ghcr.io/truecharts/v2ray
  tag: latest

v2ray:
  dns:
    servers:
      - 8.8.8.8
      - 1.1.1.1
  inbounds:
    - port: 10082
      protocol: vless
      settings:
        clients:
          - id: <UUID>
            level: 1
            email: dev@example.com
        decryption: none
      streamSettings:
        network: ws
        security: auto
        wsSettings:
          path: /vless
  outbounds:
    - protocol: freedom
      settings:
        - vnext: []
  routing:
    rules:
      - ip:
          - 0.0.0.0/0
        outboundTag: direct

service:
  main:
    enabled: true
    ports:
      vless:
        port: 10082
        targetPort: 10082
    type: ClusterIP

ingress:
  vless:
    enabled: false
Enter fullscreen mode Exit fullscreen mode

Replace <UUID> with a generated UUID using:

uuidgen
Enter fullscreen mode Exit fullscreen mode

Deploy V2Ray:

helm install v2ray truecharts/v2ray \
  -n truecharts-system \
  -f v2ray-values.yaml
Enter fullscreen mode Exit fullscreen mode

Check status:

kubectl -n truecharts-system get pods
Enter fullscreen mode Exit fullscreen mode

Step 5: Secure Traffic with Ingress (Optional)

If you want external access to either AdGuard or V2Ray, enable ingress in their respective values files.

For example, update adguard-values.yaml:

ingress:
  main:
    enabled: true
    annotations:
      kubernetes.io/ingress.class: nginx
      cert-manager.io/cluster-issuer: letsencrypt-prod
    hosts:
      - host: adguard.dev.internal
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: adguard-tls
        hosts:
          - adguard.dev.internal
Enter fullscreen mode Exit fullscreen mode

Then redeploy:

helm upgrade adguard truecharts/adguard \
  -n truecharts-system \
  -f adguard-values.yaml
Enter fullscreen mode Exit fullscreen mode

Ensure your cluster has the NGINX Ingress Controller and cert-manager installed beforehand.

Step 6: Monitor Health and Logs

Use standard tools to monitor deployed services:

# View logs
kubectl -n truecharts-system logs -l app.kubernetes.io/name=adguard

kubectl -n truecharts-system logs -l app.kubernetes.io/name=v2ray

# Check resource usage
kubectl -n truecharts-system top pods
Enter fullscreen mode Exit fullscreen mode

Enable metrics collection by integrating with Prometheus/Grafana stacks if needed.

Cleanup

Delete installed applications when no longer required:

helm uninstall adguard -n truecharts-system
helm uninstall v2ray -n truecharts-system
kubectl delete ns truecharts-system
Enter fullscreen mode Exit fullscreen mode

Frequently Asked Questions

Can I run these tools outside Kubernetes?

Yes. Both AdGuard and V2Ray have Docker Compose setups. However, TrueCharts abstracts away much of the boilerplate logic involved in scaling and managing stateful apps within Kubernetes environments.

Is TLS necessary for internal-only services?

Not strictly required unless handling sensitive data. But for cross-node communication or multi-tenant clusters, enabling TLS ensures confidentiality even within trusted networks.

How do I back up AdGuard configurations regularly?

Enable snapshot-based backups using Velero or Stash, which support volume-level snapshots compatible with most storage providers.

Deploying private developer tools doesn’t require reinventing infrastructure—leveraging mature platforms like TrueCharts allows rapid provisioning while maintaining flexibility and scalability. Whether securing internet-bound traffic with V2Ray or filtering unwanted content via AdGuard, these patterns empower engineering teams to own their tooling stack effectively.

Explore more charts at tamiz.pro or check out Tamiz's Insights for deeper dives into DevOps practices.

Top comments (0)