ProjectsAboutSkillsArticlesToolsContact
Back to Insights
Next.js & React•Building Self-Hosted Developer Tools with TrueCharts: Deploying Private Services Like AdGuard and V2Ray on Kubernetes•tutorial•September 13, 2026•4 min read

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

Deploy AdGuard Home and V2Ray as self-hosted services on Kubernetes using TrueCharts. Step-by-step guide for developers managing private infrastructure.

T
Tamiz UddinFull-Stack Engineer

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.

bash
kubectl create ns truecharts-system

Step 1: Add the TrueCharts Helm Repository

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

bash
helm repo add truecharts https://charts.truecharts.org/stable
helm repo update

Verify the repository is available:

bash
helm search repo truecharts/adguard
helm search repo truecharts/v2ray

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:

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

Install the chart:

bash
helm install adguard truecharts/adguard \
  -n truecharts-system \
  -f adguard-values.yaml

Wait for pods to start:

bash
kubectl -n truecharts-system get pods

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

bash
kubectl -n truecharts-system port-forward svc/adguard 3000:3000

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:

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

Apply updated config:

bash
helm upgrade adguard truecharts/adguard \
  -n truecharts-system \
  -f adguard-values.yaml

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

lua
adguard.truecharts-system.svc.cluster.local

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:

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

Replace <UUID> with a generated UUID using:

bash
uuidgen

Deploy V2Ray:

bash
helm install v2ray truecharts/v2ray \
  -n truecharts-system \
  -f v2ray-values.yaml

Check status:

bash
kubectl -n truecharts-system get pods

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:

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

Then redeploy:

bash
helm upgrade adguard truecharts/adguard \
  -n truecharts-system \
  -f adguard-values.yaml

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:

bash
# 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

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

Cleanup

Delete installed applications when no longer required:

bash
helm uninstall adguard -n truecharts-system
helm uninstall v2ray -n truecharts-system
kubectl delete ns truecharts-system

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.