Skip to main content

Installation

This guide covers deploying Dploy to a production Kubernetes cluster.

Prerequisites​

Before installing Dploy, ensure you have:

  • Kubernetes cluster (1.25+)
  • ArgoCD installed and configured
  • OIDC Provider (Authentik, Keycloak, Okta, etc.) for JWT authentication
  • Ingress Controller (NGINX recommended)
  • kubectl and Helm configured to access your cluster

Quick Start with Kind​

For local development and testing, use the automated setup script:

git clone https://github.com/AYDEV-FR/dploy.git
cd dploy
./dev/setup.sh

This creates a complete local environment with Kind, ArgoCD, Authentik, and Dploy.

Helm is the recommended way to install Dploy in production.

Option 1: Helm CLI​

Add the Helm repository​

helm repo add dploy https://aydev-fr.github.io/dploy
helm repo update

Install with minimal configuration​

helm install dploy dploy/dploy \
  --namespace dploy-system \
  --create-namespace \
  --set auth.jwksURL="https://your-oidc-provider.com/keys" \
  --set auth.jwtIssuer="https://your-oidc-provider.com" \
  --set auth.oidcClientID="dploy" \
  --set auth.oidcClientSecret="your-client-secret"

Install with custom values file​

Create a values.yaml file:

# values.yaml
auth:
  jwksURL: "https://your-oidc-provider.com/keys"
  jwtIssuer: "https://your-oidc-provider.com"
  oidcClientID: "dploy"
  oidcClientSecret: "your-client-secret"
  oidcRedirectURL: "https://dploy.your-domain.com/auth/callback"

config:
  baseDomain: "env.your-domain.com"
  defaultTTL: 86400        # 24 hours
  maxEnvironmentsPerUser: 5

argocd:
  namespace: argocd
  project: dploy

ingress:
  enabled: true
  className: nginx
  host: dploy.your-domain.com
  tls:
    - secretName: dploy-tls
      hosts:
        - dploy.your-domain.com

environments:
  - name: webterm
    description: "Web Terminal for students"
    chart: "github.com/AYDEV-FR/dploy-charts/webshell@main"
    enabled: true
    icon: "terminal"
    ttl: 86400

  - name: vscode
    description: "VSCode in the browser"
    chart: "github.com/AYDEV-FR/dploy-charts/vscode@main"
    enabled: true
    icon: "code"
    ttl: 43200

  - name: jupyter
    description: "Jupyter Notebook"
    chart: "github.com/AYDEV-FR/dploy-charts/jupyter@main"
    enabled: true
    icon: "book"
    ttl: 86400

Then install:

helm install dploy dploy/dploy \
  --namespace dploy-system \
  --create-namespace \
  -f values.yaml

Upgrade an existing installation​

helm upgrade dploy dploy/dploy \
  --namespace dploy-system \
  -f values.yaml

Option 2: ArgoCD Application​

Deploy Dploy using GitOps with an ArgoCD Application manifest.

Create the Application manifest​

# dploy-application.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: dploy
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://aydev-fr.github.io/dploy
    chart: dploy
    targetRevision: 0.1.0
    helm:
      valuesObject:
        auth:
          jwksURL: "https://your-oidc-provider.com/keys"
          jwtIssuer: "https://your-oidc-provider.com"
          oidcClientID: "dploy"
          oidcClientSecret: "your-client-secret"
          oidcRedirectURL: "https://dploy.your-domain.com/auth/callback"

        config:
          baseDomain: "env.your-domain.com"
          defaultTTL: 86400
          maxEnvironmentsPerUser: 5

        argocd:
          namespace: argocd
          project: dploy

        ingress:
          enabled: true
          className: nginx
          host: dploy.your-domain.com
          tls:
            - secretName: dploy-tls
              hosts:
                - dploy.your-domain.com

        environments:
          - name: webterm
            description: "Web Terminal"
            chart: "github.com/AYDEV-FR/dploy-charts/webshell@main"
            enabled: true
            icon: "terminal"
            ttl: 86400

          - name: vscode
            description: "VSCode in browser"
            chart: "github.com/AYDEV-FR/dploy-charts/vscode@main"
            enabled: true
            icon: "code"
            ttl: 43200

  destination:
    server: https://kubernetes.default.svc
    namespace: dploy-system

  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Apply the Application​

kubectl apply -f dploy-application.yaml

ArgoCD will automatically sync and deploy Dploy with the configured values.

Using a Git repository for values​

For better GitOps practices, store your values in a Git repository:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: dploy
  namespace: argocd
spec:
  project: default
  sources:
    - repoURL: https://aydev-fr.github.io/dploy
      chart: dploy
      targetRevision: 0.1.0
      helm:
        valueFiles:
          - $values/dploy/values.yaml
    - repoURL: https://github.com/your-org/gitops-config
      targetRevision: main
      ref: values
  destination:
    server: https://kubernetes.default.svc
    namespace: dploy-system
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Helm Values Reference​

Authentication (auth)​

ParameterDescriptionDefault
auth.jwksURLJWKS endpoint for JWT validation-
auth.jwtIssuerJWT issuer claim-
auth.jwtAudienceJWT audience claimdploy
auth.jwtUsernameClaimJWT claim for usernamepreferred_username
auth.oidcClientIDOIDC client IDdploy
auth.oidcClientSecretOIDC client secret-
auth.oidcIssuerOIDC issuer URL-
auth.oidcRedirectURLOIDC redirect URL-

Configuration (config)​

ParameterDescriptionDefault
config.baseDomainBase domain for environment ingressesenv.dploy.dev
config.defaultTTLDefault TTL in seconds86400 (24h)
config.extendTTLTTL extension in seconds7200 (2h)
config.maxEnvironmentsPerUserMax environments per user5
config.serverHostServer bind address0.0.0.0
config.serverPortServer port8080

ArgoCD (argocd)​

ParameterDescriptionDefault
argocd.namespaceArgoCD namespaceargocd
argocd.projectArgoCD project namedploy

Ingress (ingress)​

ParameterDescriptionDefault
ingress.enabledEnable ingressfalse
ingress.classNameIngress classnginx
ingress.hostIngress hostnamedploy.example.com
ingress.annotationsIngress annotations{}
ingress.tlsTLS configuration[]

Environments (environments)​

ParameterDescriptionRequired
environments[].nameEnvironment nameYes
environments[].descriptionHuman-readable descriptionYes
environments[].chartHelm chart referenceYes
environments[].enabledEnable/disable environmentYes
environments[].iconIcon name for UINo
environments[].ttlTTL in secondsNo
environments[].extraValuesAdditional Helm valuesNo

See Environments Configuration for detailed chart format.

Manual Installation (Alternative)​

If you prefer not to use Helm, you can deploy Dploy manually.

1. Create Namespace​

kubectl create namespace dploy-system

2. Deploy ArgoCD AppProject​

kubectl apply -f k8s/appproject.yaml

3. Deploy RBAC​

kubectl apply -f k8s/rbac.yaml

4. Configure and Deploy​

Edit k8s/deployment.yaml with your configuration, then:

kubectl apply -f k8s/deployment.yaml

5. Configure Ingress​

kubectl apply -f k8s/ingress.yaml

Verify Installation​

Check that all components are running:

# Check Dploy API pods
kubectl get pods -n dploy-system

# Check health endpoint
kubectl port-forward -n dploy-system svc/dploy-api 8080:80
curl http://localhost:8080/health

# Check ArgoCD
kubectl get pods -n argocd
kubectl get applications -n argocd

Docker Image​

The official Docker image is available at:

docker pull ghcr.io/aydev-fr/dploy:latest

Or build from source:

docker build -t dploy:latest .

Next Steps​