HemSarin
Wiki.js Kubernetes Deployment with ArgoCD
Jun 07, 2025, 12:00 AM

🚀 Deploying Production-Ready Wiki.js on Kubernetes with GitOps & ArgoCD

Managing documentation in a fast-paced engineering team shouldn't be a pain. Wiki.js is one of the most powerful, modern, and open-source wiki applications available today. But how do you deploy and manage it reliably at scale?

In this guide, we'll walk through deploying Wiki.js on Kubernetes using a true GitOps workflow with ArgoCD.

🔗 Quick Links

📋 Overview

This project provides a complete, production-ready Kubernetes deployment configuration for Wiki.js. By pairing Kubernetes with ArgoCD, any changes made to your infrastructure manifests in Git are automatically synced to your cluster—giving you automated drift correction, version control, and painless rollbacks.

✨ Key Features

  • Production-Ready & Hardened: Non-root execution, dropped capabilities, and strict security contexts.
  • GitOps Automation: Fully compatible with ArgoCD automated sync, pruning, and self-healing.
  • Persistent Storage: Configured with persistent volumes for SQLite database retention.
  • Reliability & Health Checks: Integrated liveness and readiness probes for zero-downtime operations.
  • Network & RBAC Security: Strict ingress control and minimal service account permissions.

🏗️ Architecture Breakdown

The deployment includes the following core Kubernetes resources:

  • Namespace: Isolated wikijs environment.
  • ConfigMap: Holds non-sensitive application settings.
  • Secret: Secure container for sensitive data and credentials.
  • PersistentVolume / PVC: Ensures data persistence across pod restarts.
  • Deployment: Runs the Wiki.js container instance.
  • Service: Exposes internal networking endpoints.
  • Ingress: Provides secure external access via host routing.
  • ServiceAccount & RBAC: Enforces minimal security permissions.
  • NetworkPolicy: Controls inbound and outbound traffic flow.

🚀 Step-by-Step Deployment Guide

Prerequisites

Before getting started, make sure you have:

  • A running Kubernetes cluster (v1.19+)
  • kubectl configured
  • ArgoCD installed in your cluster
  • An Ingress controller and available Storage Class (e.g. local-storage)

1. Clone the Repository

git clone https://github.com/SarinHem/wikijs-deployment-argocd.git
cd wikijs-deployment-argocd/wikijs

2. Review & Adjust Configuration

Edit the configuration files to match your cluster environment:

  • Update the wikijs-ingress host domain in wikijs.yaml.
  • Adjust storage paths and volume sizes based on your requirements.
  • Tweak CPU and Memory requests/limits for your workload.

3. Option A: Deploy Manually with kubectl

# Apply all Kubernetes manifests
kubectl apply -f wikijs.yaml

# Verify deployment status
kubectl get pods -n wikijs
kubectl get pvc -n wikijs

4. Option B: GitOps Deployment with ArgoCD (Recommended)

Create an ArgoCD Application manifest (argocd-app.yaml):

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: wikijs
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/SarinHem/wikijs-deployment-argocd.git
    path: .
    targetRevision: HEAD
  destination:
    server: https://kubernetes.default.svc
    namespace: wikijs
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Apply it to your ArgoCD setup:

kubectl apply -f argocd-app.yaml

🌐 Accessing Your Wiki.js Instance

Local Testing (Port Forward)

kubectl port-forward svc/wikijs-service 8080:80 -n wikijs

Open http://localhost:8080 in your browser.

External Production Access

  1. Update your ingress host in the deployment manifest:

    host: wiki.yourdomain.com

  2. Point your DNS records to your ingress controller IP.

  3. Access your wiki at https://wiki.yourdomain.com.

🔒 Security & Performance Highlights

  • Pod Security: Runs under non-root UID 1000 with dropped Linux capabilities and read-only root filesystems where applicable.
  • Network Isolation: Restricted ingress traffic via Kubernetes NetworkPolicies.
  • Database Scaling Note: While configured with SQLite for simplicity, consider switching to PostgreSQL for multi-replica horizontal scaling.

💡 Conclusion

With this GitOps setup, managing your internal wiki is completely automated, secure, and resilient. Any updates to your configuration can be committed directly to Git, letting ArgoCD handle the rest.

Happy documenting! 📝

← Back to Blog