DEV Community: Vultr

Installing R and RStudio Server on Ubuntu 24.04

Sanskriti Harmukh — Wed, 12 Aug 2026 16:26:33 +0000

R is an open-source language for statistical computing and data analysis; RStudio Server puts a full browser-based IDE for it on a remote machine. This guide installs R from the official CRAN repository, sets up RStudio Server, secures it behind Nginx with Let's Encrypt TLS, and runs a test script with a plot.

Prerequisites: an Ubuntu 24.04 server, non-root sudo user, a domain A record (e.g. rstudio.example.com).

Install R from CRAN

$ sudo apt update
$ sudo apt install --no-install-recommends software-properties-common dirmngr -y

Add and verify CRAN's key:

$ wget -qO- https://cloud.r-project.org/bin/linux/ubuntu/marutter_pubkey.asc | sudo tee /etc/apt/trusted.gpg.d/cran_ubuntu_key.asc
$ gpg --show-keys /etc/apt/trusted.gpg.d/cran_ubuntu_key.asc

Fingerprint should read E298A3A825C0D65DFD57CBB651716619E084DAB9.

$ sudo add-apt-repository "deb https://cloud.r-project.org/bin/linux/ubuntu $(lsb_release -cs)-cran40/"
$ sudo apt install --no-install-recommends r-base -y

Verify:

$ R --version
$ R

> "Hello, R!"
> mean(c(1, 2, 3, 4, 5))
> q()

Answer n when asked to save the workspace.

Install RStudio Server

$ sudo apt install gdebi-core -y
$ wget https://download2.rstudio.org/server/jammy/amd64/rstudio-server-2025.09.2-418-amd64.deb
$ sudo gdebi rstudio-server-2025.09.2-418-amd64.deb
$ sudo rstudio-server version

The Jammy (22.04) package works fine on Noble (24.04) — LTS releases are backward-compatible here.

Start RStudio Server

$ sudo systemctl enable rstudio-server
$ sudo systemctl start rstudio-server
$ sudo systemctl status rstudio-server

Secure with Nginx + Let's Encrypt

$ sudo apt install nginx -y
$ sudo apt install certbot python3-certbot-nginx -y
$ sudo nano /etc/nginx/sites-available/rstudio.conf

server {
    listen 80;
    server_name rstudio.example.com;

    location / {
        proxy_pass http://127.0.0.1:8787;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 20d;
    }
}

The long proxy_read_timeout keeps long-running RStudio sessions from getting cut off.

$ sudo ln -s /etc/nginx/sites-available/rstudio.conf /etc/nginx/sites-enabled/
$ sudo nginx -t
$ sudo systemctl restart nginx
$ sudo ufw allow 80,443/tcp
$ sudo certbot --nginx -d rstudio.example.com -m admin@example.com --agree-tos --no-eff-email

Access RStudio Server

Visit https://rstudio.example.com, sign in with your Linux user account. Each user gets an isolated R environment — personal package installs don't affect other users.

Run a Test Script

> x <- 1:10
> y <- x^2
> plot(x, y, type="b", col="red", main="Test Plot with RStudio Server")

File → New File → R Script, then:

# Calculate summary statistics
data <- c(12, 15, 18, 22, 25, 28, 30, 35)
summary(data)

# Create a histogram
hist(data, main="Sample Data Distribution", col="steelblue")

Run or Ctrl+Enter to execute.

Next Steps

RStudio Server is running with TLS and isolated per-user R environments. From here:

Add more Linux users to give teammates their own RStudio logins
Install commonly-needed CRAN packages system-wide so users don't duplicate installs
Connect to a database or object storage from within R scripts for real data-analysis workflows

For the full guide, visit the original article on Vultr Docs.

Installing and Setting Up Pritunl VPN Server on Ubuntu 24.04

Sanskriti Harmukh — Wed, 12 Aug 2026 16:25:50 +0000

Pritunl is an open-source VPN solution supporting OpenVPN and WireGuard, with a web console for managing organizations, users, servers, and client profiles — plus automatic NAT and Let's Encrypt certificates. This guide installs it on Ubuntu 24.04, creates a server/organization/user structure, connects a client, and covers revoking access.

Prerequisites: an Ubuntu 24.04 server, non-root sudo user, a domain A record (e.g. pritunlvpn.example.com).

Install Pritunl

Needs MongoDB (management data), OpenVPN, and WireGuard.

$ sudo apt update
$ sudo apt upgrade -y
$ sudo apt install gnupg -y

Add the repos:

$ sudo tee /etc/apt/sources.list.d/mongodb-org.list << EOF
deb [ signed-by=/usr/share/keyrings/mongodb-server-8.0.gpg ] https://repo.mongodb.org/apt/ubuntu noble/mongodb-org/8.0 multiverse
EOF
$ sudo tee /etc/apt/sources.list.d/openvpn.list << EOF
deb [ signed-by=/usr/share/keyrings/openvpn-repo.gpg ] https://build.openvpn.net/debian/openvpn/stable noble main
EOF
$ sudo tee /etc/apt/sources.list.d/pritunl.list << EOF
deb [ signed-by=/usr/share/keyrings/pritunl.gpg ] https://repo.pritunl.com/stable/apt noble main
EOF

Fetch GPG keys:

$ curl -fsSL https://www.mongodb.org/static/pgp/server-8.0.asc | sudo gpg -o /usr/share/keyrings/mongodb-server-8.0.gpg --dearmor --yes
$ curl -fsSL https://swupdate.openvpn.net/repos/repo-public.gpg | sudo gpg -o /usr/share/keyrings/openvpn-repo.gpg --dearmor --yes
$ curl -fsSL https://raw.githubusercontent.com/pritunl/pgp/master/pritunl_repo_pub.asc | sudo gpg -o /usr/share/keyrings/pritunl.gpg --dearmor --yes

Install:

$ sudo apt update
$ sudo apt install mongodb-org openvpn wireguard wireguard-tools -y
$ sudo apt install pritunl -y
$ pritunl version

Manage the Services

$ sudo systemctl enable pritunl
$ sudo systemctl start pritunl
$ sudo systemctl status pritunl
$ sudo systemctl enable mongod
$ sudo systemctl start mongod

Initial Setup

1. Generate a one-time setup key:

$ sudo pritunl setup-key

2. Open the firewall:

$ sudo ufw allow 80/tcp
$ sudo ufw allow 443/tcp
$ sudo ufw reload
$ sudo ufw status

3. Visit http://YOUR-SERVER-IP (accept the self-signed cert warning), paste the setup key, confirm the MongoDB URI points at localhost, Save.

4. Get the default web console credentials:

$ sudo pritunl default-password

5. Log in at http://YOUR-SERVER-IP/login with that username/password, set a new strong password in the Initial Setup dialog, confirm the server's public IP, enter your domain (e.g. pritunlvpn.example.com) as the Let's Encrypt Domain — your A record must already point here for cert issuance to work — Save.

Set Up Servers, Organizations, and Users

Server — the actual VPN endpoint (OpenVPN or WireGuard)
Organization — a standalone CA issuing user certs, for grouping/permissions
User — a client profile tied to an organization with its own certificate

1. Create a server: https://pritunlvpn.example.com → Servers → Add Server → name, DNS server, port, protocol, virtual network subnet → ADD.

2. Create an organization: Users → Add Organization → name → Add.

3. Attach and start: Servers → select your server → Attach Organization → pick the org → Attach → Start Server.

4. Create a user: Users → Add User → name, organization, email, PIN → Add.

5. Get the profile: from the user's options, Download Profile (archive) or Link for a shareable download link.

Firewall for VPN Traffic

Each server profile uses its own port/protocol — check Servers → Server for the exact port.

$ sudo ufw status
$ sudo ufw allow 12800/udp
$ sudo ufw reload
$ sudo ufw status

Replace 12800/udp with whatever your server profile actually uses.

Connect a Client

1. Download the Pritunl client for your OS.

2. Import: open Pritunl client → Import → Browse → select the downloaded .tar profile → Import.

3. Connect: verify user/server info, Connect, enter the PIN, Connect again to establish the tunnel.

4. Verify: check connection stats in the client, confirm your public IP via an IP checker matches the VPN server, and check Users in the web console shows the user as Online.

Revoke a User

Users → select the user → Delete Selected.

Next Steps

Pritunl is running with TLS via Let's Encrypt and at least one active VPN connection. From here:

Add more organizations to separate teams or environments
Configure split tunneling per server profile if you don't want all client traffic routed through the VPN
Set up additional servers on WireGuard for lower-overhead connections

For the full guide, visit the original article on Vultr Docs.

Deploying DeepSeek V3 (LLM) Using SGLang

Sanskriti Harmukh — Wed, 12 Aug 2026 16:25:11 +0000

DeepSeek V3 is a 671B-parameter Mixture-of-Experts language model: Multi-head Latent Attention and DeepseekMoE architecture, pre-trained on 14.8 trillion tokens, tuned with RL for strong reasoning at relatively efficient inference cost. This guide deploys it via SGLang in a ROCm-supported container on an AMD Instinct MI300X GPU server, then verifies inference over HTTP.

Prerequisites: access to an AMD Instinct MI300X GPU instance (large VRAM is required for this model's size).

Deploy DeepSeek V3

1. Install the Hugging Face CLI and start the model download in the background — it's large, so kick it off early and continue with the next steps while it completes:

$ pip install huggingface_hub[cli]
$ huggingface-cli download deepseek-ai/DeepSeek-V3

Downloads to $HOME/.cache/huggingface.

2. Clone SGLang and build the ROCm container (can take up to 30 minutes):

$ git clone https://github.com/sgl-project/sglang.git
$ cd sglang/docker
$ docker build --build-arg SGL_BRANCH=v0.4.2 -t sglang:v0.4.2-rocm620 -f Dockerfile.rocm .

If you hit error: RPC failed; curl 56 GnuTLS recv error during the build, add these lines to Dockerfile.rocm before the repo-cloning steps:

RUN git config --global http.postBuffer 1048576000
RUN git config --global https.postBuffer 1048576000

Connection timeouts during build are usually transient — just re-run; Docker caches completed layers.

3. Run the inference server:

$ docker run -d --device=/dev/kfd --device=/dev/dri --ipc=host \
    --group-add video --cap-add=SYS_PTRACE --security-opt seccomp=unconfined \
    -v $HOME/dockerx:/dockerx -v $HOME/.cache/huggingface:/root/.cache/huggingface \
    --shm-size 16G -p 30000:30000 sglang:v0.4.2-rocm620 \
    python3 -m sglang.launch_server --model-path deepseek-ai/DeepSeek-V3 --tp 8 --trust-remote-code --host 0.0.0.0 --port 30000

Runs detached with GPU device access, mounted caches, 16GB shared memory, and tensor parallelism across 8 GPUs (--tp 8), serving on port 30000.

4. Test inference:

$ curl http://localhost:30000/v1/chat/completions \
     -H "Content-Type: application/json" \
     -d "{\"model\": \"deepseek-ai/DeepSeek-V3\", \"messages\": [{\"role\": \"user\", \"content\": \"What are the key architectural ideas behind Mixture-of-Experts models?\"}], \"temperature\": 0.7}"

5. Optional — expose the port externally:

$ sudo ufw allow 30000

Next Steps

DeepSeek V3 is serving inference through SGLang's OpenAI-compatible API on port 30000. From here:

Front the server with a reverse proxy and TLS if exposing it beyond localhost
Tune --tp to match your available GPU count
Explore SGLang's batching and caching options for higher throughput under concurrent load

For the full guide, visit the original article on Vultr Docs.

Installing Couchbase Database on Ubuntu 22.04

Sanskriti Harmukh — Wed, 12 Aug 2026 16:24:37 +0000

Couchbase is a distributed NoSQL database combining key-value and document-store functionality with a memory-first architecture for fast reads. This guide deploys a multi-node Couchbase cluster on Ubuntu 22.04 over a private network, fronts it with an Nginx reverse proxy, loads a sample dataset, runs N1QL queries, and sets up monitoring.

Prerequisites: a main Couchbase server (4GB RAM min) plus at least 2 additional nodes (4GB RAM min each), all attached to the same private network, a domain A record pointing at the main server (e.g. couchbase.example.com).

Install Couchbase

Run on the main server first, then repeat on each node.

$ ssh linuxuser@SERVER-IP
$ curl -O https://packages.couchbase.com/releases/couchbase-release/couchbase-release-1.0-noarch.deb
$ sudo dpkg -i ./couchbase-release-1.0-noarch.deb
$ sudo apt-get update
$ sudo apt-get install couchbase-server-community
$ service couchbase-server status

Identify the private network interface and allow traffic on it:

$ ip a

Note the interface carrying your private-network IP (e.g. enp8s0), then:

$ sudo ufw allow in on enp8s0

Repeat the full install on every node before continuing.

Configure Nginx as a Reverse Proxy

Couchbase nodes talk to each other over private addresses; Nginx on the main server proxies external access without exposing backend ports directly.

$ sudo apt install nginx -y
$ sudo rm /etc/sites-enabled/default
$ sudo nano /etc/nginx/conf.d/couchbase.conf

server {
    listen 80;
    server_name couchbase.example.com;

    location / {
        proxy_pass http://127.0.0.1:8091;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

# Couchbase Node 1

    location /node1 {
        proxy_pass http://10.50.96.3:8091;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

# Couchbase Node 2

    location /node2 {
        proxy_pass http://10.50.96.5:8091;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Replace the node IPs with your actual private addresses. / proxies to the main server; /node1, /node2 proxy to each additional node.

$ sudo nginx -t
$ sudo systemctl restart nginx
$ sudo ufw allow 80/tcp
$ sudo ufw reload

Create the Cluster

Visit http://couchbase.example.com:

Setup New Cluster — cluster name, admin username, strong password.
Next: Accept Terms.
Check the terms checkbox, Finish with Defaults.

Add Nodes to the Cluster

For each node, via its Nginx proxy path (e.g. http://couchbase.example.com/node1):

Join Existing Cluster.
Enter the main server's private IP as Cluster Host Name/IP Address, plus the admin username/password.
Join Cluster.
Back on the main server: Servers → Rebalance, wait for Rebalance Completed Successfully.

Repeat for every node.

Load a Sample Dataset

Couchbase ships 3 sample datasets.

Buckets → sample bucket (in the ADD BUCKET notification).
Check travel-sample, Load Sample Data.

Inspect the Data

Buckets → Documents next to travel-sample to browse records.
Buckets → travel-sample → Scopes & Collections to see the inventory scope and its collections, with per-collection document counts and memory/disk usage.

Run a Query

Couchbase uses N1QL (SQL-like) for querying documents.

Query, paste:

SELECT name FROM `travel-sample`.inventory.hotel WHERE type = "hotel" AND city = "Paris" AND free_parking = true LIMIT 5;

Execute — results return as JSON, 5 matching hotel names.

Monitoring

Dashboard — Cluster Overview for active process stats, Node Resources for CPU/request-rate/memory per node.
Build a custom dashboard: Choose Dashboard → new dashboard, name it, Save.
Add a Chart → combine node data + multiple stats per chart → pick stats (e.g. Available RAM, Swap Used under one tab, Query Execution Time and Queries > 500ms under Query) → Save Chart.

Next Steps

Couchbase is running as a multi-node cluster over your private network, proxied through Nginx, with sample data loaded and query access confirmed. From here:

Set up XDCR (cross-datacenter replication) for multi-region durability
Configure bucket-level replica counts for higher availability
Explore the Couchbase SDKs to connect application code instead of the web console

For the full guide, visit the original article on Vultr Docs.

Installing Traefik Ingress Controller with cert-manager on Kubernetes

Sanskriti Harmukh — Wed, 12 Aug 2026 16:23:50 +0000

Traefik is an open-source Kubernetes Ingress controller that pairs with cert-manager to automatically provision and renew TLS certificates for services exposed from your cluster. This guide installs Traefik and cert-manager, then deploys a sample app behind an Ingress with a Let's Encrypt certificate.

Prerequisites: a Kubernetes cluster, kubectl and Helm configured against it, a domain (this guide uses example.com).

Install Traefik

$ kubectl create namespace traefik-namespace
$ helm repo add traefik https://helm.traefik.io/traefik
$ helm repo update
$ helm install --namespace=traefik-namespace traefik traefik/traefik
$ kubectl get services -n traefik-namespace

The traefik Service's EXTERNAL-IP may show <pending> briefly while your cloud provider provisions the LoadBalancer — wait and re-check.

Point a domain A record at that external IP with your DNS provider.

Install cert-manager

$ kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.17.2/cert-manager.yaml
$ kubectl get pods --namespace cert-manager

Check the cert-manager releases page for the current version.

Create a ClusterIssuer

$ nano cluster-issuer.yaml

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    email: hello@example.com
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: letsencrypt-prod-key
    solvers:
      - http01:
          ingress:
            class: traefik

Use a real email address — Let's Encrypt rejects example.com addresses.

$ kubectl apply -f cluster-issuer.yaml
$ kubectl get clusterissuer

READY: True confirms it's ready to issue certs.

Deploy a Sample App

$ kubectl create namespace example-app-namespace
$ nano example-app-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  namespace: example-app-namespace
  name: example-app-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: example-app
  template:
    metadata:
      labels:
        app: example-app
    spec:
      containers:
        - name: web-app
          image: nginx
          ports:
            - containerPort: 80

$ kubectl apply -f example-app-deployment.yaml
$ kubectl get pods -n example-app-namespace

Create an Ingress

1. Service:

$ nano example-app-service.yaml

apiVersion: v1
kind: Service
metadata:
  namespace: example-app-namespace
  name: example-app-service
spec:
  selector:
    app: example-app
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80

$ kubectl apply -f example-app-service.yaml
$ kubectl get services -n example-app-namespace

2. Ingress — replace example.com:

$ nano example-app-ingress.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web-app-ingress
  namespace: example-app-namespace
  annotations:
    traefik.ingress.kubernetes.io/router.entrypoints: websecure
    traefik.ingress.kubernetes.io/router.tls: "true"
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: example-app-service
                port:
                  number: 80
  tls:
    - secretName: web-app-cert
      hosts:
        - example.com

The Traefik-specific annotations route HTTPS traffic through the websecure entrypoint; the cert-manager.io/cluster-issuer annotation ties the Ingress to the ClusterIssuer. secretName doesn't need to exist beforehand — cert-manager creates it.

$ kubectl apply -f example-app-ingress.yaml
$ kubectl get ingress -n example-app-namespace

ADDRESS populates a few seconds later with Traefik's external IP.

3. Confirm the certificate:

$ kubectl get certificates -n example-app-namespace

READY: True means it's issued. Check auto-renewal is scheduled:

$ kubectl describe -n example-app-namespace certificate web-app-cert

Look for a Renewal Time a month or so out.

4. Visit https://example.com — you should see the default Nginx welcome page over a valid cert.

Troubleshooting

Certificate stuck False — confirm DNS points at Traefik's LoadBalancer IP, then check logs:

$ kubectl logs deployment/cert-manager -n cert-manager --tail=15 -f

Traefik routing issues — check its logs and resource status:

$ kubectl logs -n <namespace> <traefik-pod>
$ kubectl get pods -n traefik-namespace

Ingress not routing — verify the manifest has the right Traefik/cert-manager annotations:

$ kubectl get ingress

Next Steps

Traefik is routing traffic with automatic Let's Encrypt certificates via cert-manager. From here:

Add more Ingress resources for additional apps, reusing the same ClusterIssuer
Explore Traefik middlewares for rate limiting, auth, or redirects
Switch to DNS-01 challenges in the ClusterIssuer if you need wildcard certificates

For the full guide, visit the original article on Vultr Docs.

Deploying AFFiNE – Open-Source Knowledge Management Platform

Sanskriti Harmukh — Wed, 12 Aug 2026 16:22:45 +0000

AFFiNE is an open-source workspace platform combining docs, whiteboards, and databases in one interface including notes, tasks, and team projects together. This guide deploys it via Docker Compose with PostgreSQL, Redis, and Traefik-managed TLS, then builds a workspace, writes a doc, and tries the Edgeless canvas.

Prerequisites: a Linux server (4 vCPU / 2GB RAM minimum), Docker + Docker Compose, a domain A record (e.g. affine.example.com).

Set Up the Project

$ mkdir -p ~/affine-server/{letsencrypt,redis}
$ cd ~/affine-server
$ openssl rand -hex 64

Environment file — replace domain, email, DB password, and secret key:

$ nano .env

DOMAIN=affine.example.com
ACME_EMAIL=admin@example.com

AFFINE_SERVER_HTTPS=true
AFFINE_SERVER_HOST=affine.example.com
AFFINE_SERVER_EXTERNAL_URL=https://affine.example.com
AFFINE_SERVER_SECRET=GENERATED_SECRET_KEY

AFFINE_REVISION=stable
PORT=3010

DB_DATA_LOCATION=./postgres
UPLOAD_LOCATION=./storage
CONFIG_LOCATION=./config

DB_USERNAME=affine
DB_PASSWORD=STRONG_PASSWORD
DB_DATABASE=affine

Deploy with Docker Compose

$ nano docker-compose.yaml

name: affine
services:
  traefik:
    image: traefik:v3.7
    container_name: traefik
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.web.http.redirections.entryPoint.to=websecure"
      - "--entrypoints.web.http.redirections.entryPoint.scheme=https"
      - "--certificatesresolvers.myresolver.acme.tlschallenge=true"
      - "--certificatesresolvers.myresolver.acme.email=${ACME_EMAIL}"
      - "--certificatesresolvers.myresolver.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock:ro"
      - "./letsencrypt:/letsencrypt"
    restart: unless-stopped

  affine:
    image: ghcr.io/toeverything/affine:${AFFINE_REVISION:-stable}
    container_name: affine_server
    depends_on:
      redis:
        condition: service_healthy
      postgres:
        condition: service_healthy
      affine_migration:
        condition: service_completed_successfully
    volumes:
      - ${UPLOAD_LOCATION}:/root/.affine/storage
      - ${CONFIG_LOCATION}:/root/.affine/config
    env_file:
      - .env
    environment:
      - REDIS_SERVER_HOST=redis
      - DATABASE_URL=postgresql://${DB_USERNAME}:${DB_PASSWORD}@postgres:5432/${DB_DATABASE:-affine}
      - AFFINE_INDEXER_ENABLED=false
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.affine.rule=Host(`${DOMAIN}`)"
      - "traefik.http.routers.affine.entrypoints=websecure"
      - "traefik.http.routers.affine.tls.certresolver=myresolver"
      - "traefik.http.services.affine.loadbalancer.server.port=3010"
    restart: unless-stopped

  affine_migration:
    image: ghcr.io/toeverything/affine:${AFFINE_REVISION:-stable}
    container_name: affine_migration_job
    volumes:
      - ${UPLOAD_LOCATION}:/root/.affine/storage
      - ${CONFIG_LOCATION}:/root/.affine/config
    command: ['sh', '-c', 'node ./scripts/self-host-predeploy.js']
    env_file:
      - .env
    environment:
      - REDIS_SERVER_HOST=redis
      - DATABASE_URL=postgresql://${DB_USERNAME}:${DB_PASSWORD}@postgres:5432/${DB_DATABASE:-affine}
      - AFFINE_INDEXER_ENABLED=false
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

  redis:
    image: redis
    container_name: affine_redis
    volumes:
      - ./redis:/data
    healthcheck:
      test: ['CMD', 'redis-cli', '--raw', 'incr', 'ping']
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  postgres:
    image: pgvector/pgvector:pg16
    container_name: affine_postgres
    volumes:
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_DATABASE:-affine}
      POSTGRES_INITDB_ARGS: '--data-checksums'
    healthcheck:
      test: ['CMD', 'pg_isready', '-U', "${DB_USERNAME}", '-d', "${DB_DATABASE:-affine}"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

affine_migration runs the schema setup once before affine starts; affine waits on Postgres/Redis health plus migration completion.

$ docker compose up -d
$ docker compose ps
$ docker compose logs --tail=50

All containers should show running, with traefik listing ports 80/443.

First-Run Setup

Visit https://affine.example.com:

Enter Name, Email Address, Password to create the admin account.
Continue to the dashboard.

Build a Workspace

1. Create a workspace: open the default Demo Workspace → Create Workspace → name it (e.g. Team Knowledge Base) → type AFFiNE SelfHosted Cloud → Create.

2. Write a doc: inside the workspace, + in the sidebar → title it (e.g. Project Planning Notes) → add headings (Project Overview, Key Objectives) and a numbered list for tasks.

3. Switch to Edgeless view: open the doc, click the Edgeless View icon top-left — the canvas toolbar gives you shapes, connectors, drawing tools, and text annotations.

4. Link content: in Edgeless view, add a text block (e.g. Project Resources), then use the connector tool to visually link it back to the doc.

Next Steps

AFFiNE is running with persistent PostgreSQL/Redis storage and automatic HTTPS. From here:

Invite team members to the self-hosted cloud workspace for shared editing
Explore database blocks for structured, Notion-style data within docs
Combine doc and whiteboard views for project planning that needs both text and visual layout

For the full guide, visit the original article on Vultr Docs.

Deploying Langfuse – Open-Source LLM Observability Platform

Sanskriti Harmukh — Wed, 12 Aug 2026 16:22:06 +0000

Langfuse is an open-source observability platform for LLM applications including traces prompts/responses, tracks token usage and cost, and gives you debugging analytics for production AI workflows. This guide deploys it via Docker Compose with PostgreSQL, ClickHouse, Redis, and S3-compatible object storage, secured behind Traefik with Let's Encrypt, then sends a real trace through it.

Prerequisites: a Linux server (4 vCPU / 16GB RAM minimum), Docker + Docker Compose, an S3-compatible object storage bucket, a domain A record (e.g. langfuse.example.com).

Set Up the Project

$ mkdir -p ~/langfuse/{letsencrypt,postgres,clickhouse-data,clickhouse-logs,redis}
$ cd ~/langfuse

ClickHouse runs as UID 101 in the container. Match ownership on its host dirs:

$ sudo chown -R 101:101 clickhouse-data clickhouse-logs

Generate 6 secrets (run 6 times, save each):

$ openssl rand -hex 32

First 3 → SALT, ENCRYPTION_KEY, NEXTAUTH_SECRET. Last 3 → POSTGRES_PASSWORD, CLICKHOUSE_PASSWORD, REDIS_AUTH.

Environment file:

$ nano .env

DOMAIN=langfuse.example.com
LETSENCRYPT_EMAIL=admin@example.com
NEXTAUTH_URL=https://langfuse.example.com

SALT=GENERATED_SECRET_1
ENCRYPTION_KEY=GENERATED_SECRET_2
NEXTAUTH_SECRET=GENERATED_SECRET_3

POSTGRES_USER=langfuse
POSTGRES_PASSWORD=GENERATED_SECRET_4
POSTGRES_DB=langfuse
DATABASE_URL=postgresql://langfuse:GENERATED_SECRET_4@postgres:5432/langfuse

CLICKHOUSE_USER=langfuse
CLICKHOUSE_PASSWORD=GENERATED_SECRET_5
CLICKHOUSE_MIGRATION_URL=clickhouse://clickhouse:9000
CLICKHOUSE_URL=http://clickhouse:8123

REDIS_HOST=redis
REDIS_PORT=6379
REDIS_AUTH=GENERATED_SECRET_6

S3_BUCKET=YOUR_BUCKET_NAME
S3_REGION=YOUR_REGION
S3_ENDPOINT=https://YOUR_S3_ENDPOINT
S3_ACCESS_KEY=YOUR_ACCESS_KEY
S3_SECRET_KEY=YOUR_SECRET_KEY

TELEMETRY_ENABLED=true
LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES=false

TELEMETRY_ENABLED=true sends anonymous usage stats only (no prompts/traces) — set false if your compliance policy requires it. DATABASE_URL reuses POSTGRES_PASSWORD.

Deploy with Docker Compose

Six services: Traefik (TLS), PostgreSQL (metadata), ClickHouse (trace/metrics analytics), Redis (cache + queue), and two Langfuse components (web + worker).

$ nano docker-compose.yml

services:
  traefik:
    image: traefik:v3.7.0
    container_name: traefik
    restart: unless-stopped
    environment:
      DOCKER_API_VERSION: "1.44"
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--certificatesresolvers.le.acme.httpchallenge=true"
      - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.le.acme.email=${LETSENCRYPT_EMAIL}"
      - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./letsencrypt:/letsencrypt

  postgres:
    image: postgres:17
    container_name: langfuse-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
      TZ: UTC
      PGTZ: UTC
    ports:
      - "127.0.0.1:5432:5432"
    volumes:
      - ./postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
      interval: 3s
      timeout: 3s
      retries: 10

  clickhouse:
    image: clickhouse/clickhouse-server:26.5.1-alpine
    container_name: langfuse-clickhouse
    restart: unless-stopped
    user: "101:101"
    environment:
      CLICKHOUSE_DB: default
      CLICKHOUSE_USER: ${CLICKHOUSE_USER}
      CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD}
    ports:
      - "127.0.0.1:8123:8123"
      - "127.0.0.1:9000:9000"
    volumes:
      - ./clickhouse-data:/var/lib/clickhouse
      - ./clickhouse-logs:/var/log/clickhouse-server
    healthcheck:
      test: wget --no-verbose --tries=1 --spider http://127.0.0.1:8123/ping || exit 1
      interval: 5s
      timeout: 5s
      retries: 10
      start_period: 1s

  redis:
    image: redis:7-alpine
    container_name: langfuse-redis
    restart: unless-stopped
    command: >
      --requirepass ${REDIS_AUTH}
      --maxmemory-policy noeviction
    ports:
      - "127.0.0.1:6379:6379"
    volumes:
      - ./redis:/data
    healthcheck:
      test: ["CMD", "redis-cli", "--raw", "incr", "ping"]
      interval: 3s
      timeout: 10s
      retries: 10

  langfuse-worker:
    image: langfuse/langfuse-worker:3
    container_name: langfuse-worker
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
      clickhouse:
        condition: service_healthy
    ports:
      - "127.0.0.1:3030:3030"
    environment:
      DATABASE_URL: ${DATABASE_URL}
      NEXTAUTH_URL: ${NEXTAUTH_URL}
      SALT: ${SALT}
      ENCRYPTION_KEY: ${ENCRYPTION_KEY}
      TELEMETRY_ENABLED: ${TELEMETRY_ENABLED}
      LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES: ${LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES}
      CLICKHOUSE_MIGRATION_URL: ${CLICKHOUSE_MIGRATION_URL}
      CLICKHOUSE_URL: ${CLICKHOUSE_URL}
      CLICKHOUSE_USER: ${CLICKHOUSE_USER}
      CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD}
      CLICKHOUSE_CLUSTER_ENABLED: "false"
      REDIS_HOST: ${REDIS_HOST}
      REDIS_PORT: ${REDIS_PORT}
      REDIS_AUTH: ${REDIS_AUTH}
      REDIS_TLS_ENABLED: "false"
      LANGFUSE_S3_EVENT_UPLOAD_BUCKET: ${S3_BUCKET}
      LANGFUSE_S3_EVENT_UPLOAD_REGION: ${S3_REGION}
      LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID: ${S3_ACCESS_KEY}
      LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY: ${S3_SECRET_KEY}
      LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT: ${S3_ENDPOINT}
      LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE: "true"
      LANGFUSE_S3_EVENT_UPLOAD_PREFIX: "events/"
      LANGFUSE_S3_MEDIA_UPLOAD_BUCKET: ${S3_BUCKET}
      LANGFUSE_S3_MEDIA_UPLOAD_REGION: ${S3_REGION}
      LANGFUSE_S3_MEDIA_UPLOAD_ACCESS_KEY_ID: ${S3_ACCESS_KEY}
      LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY: ${S3_SECRET_KEY}
      LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT: ${S3_ENDPOINT}
      LANGFUSE_S3_MEDIA_UPLOAD_FORCE_PATH_STYLE: "true"
      LANGFUSE_S3_MEDIA_UPLOAD_PREFIX: "media/"
      LANGFUSE_S3_BATCH_EXPORT_ENABLED: "true"
      LANGFUSE_S3_BATCH_EXPORT_BUCKET: ${S3_BUCKET}
      LANGFUSE_S3_BATCH_EXPORT_REGION: ${S3_REGION}
      LANGFUSE_S3_BATCH_EXPORT_ACCESS_KEY_ID: ${S3_ACCESS_KEY}
      LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY: ${S3_SECRET_KEY}
      LANGFUSE_S3_BATCH_EXPORT_ENDPOINT: ${S3_ENDPOINT}
      LANGFUSE_S3_BATCH_EXPORT_EXTERNAL_ENDPOINT: ${S3_ENDPOINT}
      LANGFUSE_S3_BATCH_EXPORT_FORCE_PATH_STYLE: "true"
      LANGFUSE_S3_BATCH_EXPORT_PREFIX: "exports/"

  langfuse-web:
    image: langfuse/langfuse:3
    container_name: langfuse-web
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
      clickhouse:
        condition: service_healthy
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: ${DATABASE_URL}
      NEXTAUTH_URL: ${NEXTAUTH_URL}
      NEXTAUTH_SECRET: ${NEXTAUTH_SECRET}
      SALT: ${SALT}
      ENCRYPTION_KEY: ${ENCRYPTION_KEY}
      TELEMETRY_ENABLED: ${TELEMETRY_ENABLED}
      LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES: ${LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES}
      CLICKHOUSE_MIGRATION_URL: ${CLICKHOUSE_MIGRATION_URL}
      CLICKHOUSE_URL: ${CLICKHOUSE_URL}
      CLICKHOUSE_USER: ${CLICKHOUSE_USER}
      CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD}
      CLICKHOUSE_CLUSTER_ENABLED: "false"
      REDIS_HOST: ${REDIS_HOST}
      REDIS_PORT: ${REDIS_PORT}
      REDIS_AUTH: ${REDIS_AUTH}
      REDIS_TLS_ENABLED: "false"
      LANGFUSE_S3_EVENT_UPLOAD_BUCKET: ${S3_BUCKET}
      LANGFUSE_S3_EVENT_UPLOAD_REGION: ${S3_REGION}
      LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID: ${S3_ACCESS_KEY}
      LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY: ${S3_SECRET_KEY}
      LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT: ${S3_ENDPOINT}
      LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE: "true"
      LANGFUSE_S3_EVENT_UPLOAD_PREFIX: "events/"
      LANGFUSE_S3_MEDIA_UPLOAD_BUCKET: ${S3_BUCKET}
      LANGFUSE_S3_MEDIA_UPLOAD_REGION: ${S3_REGION}
      LANGFUSE_S3_MEDIA_UPLOAD_ACCESS_KEY_ID: ${S3_ACCESS_KEY}
      LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY: ${S3_SECRET_KEY}
      LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT: ${S3_ENDPOINT}
      LANGFUSE_S3_MEDIA_UPLOAD_FORCE_PATH_STYLE: "true"
      LANGFUSE_S3_MEDIA_UPLOAD_PREFIX: "media/"
      LANGFUSE_S3_BATCH_EXPORT_ENABLED: "true"
      LANGFUSE_S3_BATCH_EXPORT_BUCKET: ${S3_BUCKET}
      LANGFUSE_S3_BATCH_EXPORT_REGION: ${S3_REGION}
      LANGFUSE_S3_BATCH_EXPORT_ACCESS_KEY_ID: ${S3_ACCESS_KEY}
      LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY: ${S3_SECRET_KEY}
      LANGFUSE_S3_BATCH_EXPORT_ENDPOINT: ${S3_ENDPOINT}
      LANGFUSE_S3_BATCH_EXPORT_EXTERNAL_ENDPOINT: ${S3_ENDPOINT}
      LANGFUSE_S3_BATCH_EXPORT_FORCE_PATH_STYLE: "true"
      LANGFUSE_S3_BATCH_EXPORT_PREFIX: "exports/"
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.langfuse.rule=Host(`${DOMAIN}`)"
      - "traefik.http.routers.langfuse.entrypoints=websecure"
      - "traefik.http.routers.langfuse.tls=true"
      - "traefik.http.routers.langfuse.tls.certresolver=le"
      - "traefik.http.services.langfuse.loadbalancer.server.port=3000"

langfuse-worker handles async trace processing and batch exports to object storage; langfuse-web is the UI/API. Both wait on postgres/redis/clickhouse health.

$ docker compose up -d
$ docker compose ps -a
$ docker compose logs

postgres, clickhouse, redis should show healthy (the only ones with configured checks).

First-Run Setup

Visit https://langfuse.example.com:

Sign up — email + password.
Create an organization (e.g. My Company) → Create Organization.
Create a project (e.g. Production LLM) → Create Project.
Create API keys in the setup wizard — copy both Secret Key (sk-lf-...) and Public Key (pk-lf-...). The secret is shown once only.

Send a Test Trace

$ sudo apt install python3-venv -y
$ python3 -m venv langfuse-env
$ source langfuse-env/bin/activate
$ pip install langfuse openai

$ nano test_langfuse.py

from langfuse.openai import openai

client = openai.OpenAI(
    api_key="YOUR_LLM_API_KEY",
    base_url="https://api.groq.com/openai/v1"
)

response = client.chat.completions.create(
    model="openai/gpt-oss-120b",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain Langfuse in one sentence."}
    ],
    temperature=0.7,
    max_tokens=100
)

print(response.choices[0].message.content)

Swap base_url for your actual LLM provider if not using Groq.

$ export LANGFUSE_SECRET_KEY="YOUR_SECRET_KEY"
$ export LANGFUSE_PUBLIC_KEY="YOUR_PUBLIC_KEY"
$ export LANGFUSE_HOST="https://langfuse.example.com"
$ python test_langfuse.py

The Langfuse SDK auto-captures the request/response and forwards it as a trace.

In the UI, go to your project's Traces page — click the trace to see model name, token usage, latency, cost estimate, and the full conversation.

Next Steps

Langfuse is running with full trace persistence, analytics via ClickHouse, and object-storage-backed exports. From here:

Wire Langfuse into your actual production LLM app via its SDK
Set up cost/latency alerting on traces that exceed thresholds
Use batch exports for offline analysis of historical trace data

For the full guide, visit the original article on Vultr Docs.

Deploying Activepieces – Open-Source Business Automation Platform

Sanskriti Harmukh — Wed, 12 Aug 2026 16:19:02 +0000

Activepieces is an open-source, no-code business automation platform including a visual flow builder for connecting apps and automating repetitive tasks (lead management, marketing automation, internal ops). This guide deploys it via Docker Compose with PostgreSQL, Redis, and Traefik-managed TLS, then builds and tests a webhook-triggered flow.

Prerequisites: a Linux server (2 vCPU / 4GB RAM minimum), Docker + Docker Compose, a domain A record (e.g. active.example.com).

Set Up the Project

$ mkdir -p ~/activepieces/{cache,letsencrypt,postgres,redis}
$ cd ~/activepieces

cache — cached pieces + execution data
letsencrypt — TLS certs
postgres / redis — persistent DB/queue data

Generate keys:

$ openssl rand -hex 16
$ openssl rand -hex 32

Environment file:

$ nano .env

DOMAIN=active.example.com
LETSENCRYPT_EMAIL=admin@example.com

AP_ENVIRONMENT=prod
AP_FRONTEND_URL=https://active.example.com

AP_ENCRYPTION_KEY=PASTE_YOUR_32_CHARACTER_STRING_HERE
AP_JWT_SECRET=PASTE_YOUR_64_CHARACTER_STRING_HERE

AP_POSTGRES_DATABASE=activepieces
AP_POSTGRES_USERNAME=postgres
AP_POSTGRES_PASSWORD=CREATE_A_STRONG_PASSWORD_HERE
AP_POSTGRES_HOST=postgres
AP_POSTGRES_PORT=5432

AP_REDIS_HOST=redis
AP_REDIS_PORT=6379

Replace domain, email, the two generated keys (16-char → AP_ENCRYPTION_KEY, 32-char → AP_JWT_SECRET), and the DB password. AP_POSTGRES_HOST/AP_REDIS_HOST match the Compose service names below so containers can reach each other.

Deploy with Docker Compose

$ nano docker-compose.yml

services:
  traefik:
    image: "traefik:v3.7.0"
    container_name: "traefik"
    restart: unless-stopped
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.myresolver.acme.tlschallenge=true"
      - "--certificatesresolvers.myresolver.acme.email=${LETSENCRYPT_EMAIL}"
      - "--certificatesresolvers.myresolver.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - "./letsencrypt:/letsencrypt"
      - "/var/run/docker.sock:/var/run/docker.sock:ro"
    networks:
      activepieces:
        aliases:
          - "${DOMAIN}"

  app:
    image: ghcr.io/activepieces/activepieces:0.83.0
    container_name: activepieces-app
    restart: unless-stopped
    depends_on:
      - postgres
      - redis
    env_file: .env
    environment:
      - AP_CONTAINER_TYPE=WORKER_AND_APP
    volumes:
      - ./cache:/usr/src/app/cache
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.activepieces.rule=Host(`${DOMAIN}`)"
      - "traefik.http.routers.activepieces.entrypoints=websecure"
      - "traefik.http.routers.activepieces.tls.certresolver=myresolver"
      - "traefik.http.services.activepieces.loadbalancer.server.port=80"
    networks:
      - activepieces

  postgres:
    image: 'pgvector/pgvector:0.8.0-pg14'
    container_name: postgres
    restart: unless-stopped
    env_file: .env
    environment:
      - 'POSTGRES_DB=${AP_POSTGRES_DATABASE}'
      - 'POSTGRES_PASSWORD=${AP_POSTGRES_PASSWORD}'
      - 'POSTGRES_USER=${AP_POSTGRES_USERNAME}'
    volumes:
      - ./postgres:/var/lib/postgresql/data
    networks:
      - activepieces

  redis:
    image: 'redis:7.2'
    container_name: redis
    restart: unless-stopped
    volumes:
      - './redis:/data'
    networks:
      - activepieces

networks:
  activepieces:

postgres uses the pgvector extension for workflow/user/execution data; redis runs the job queue; app is the web UI + API. The aliases entry on traefik resolves DOMAIN to Traefik's internal address — without it, requests from app back to its own public URL fail, since most cloud networks don't route a server's public IP back to itself.

$ docker compose up -d
$ docker compose ps
$ docker compose logs app

Look for a line confirming the app bound to your configured domain.

First-Run Setup

Visit https://active.example.com (padlock confirms Traefik got a cert):

Sign up — first name, last name, email, password.
Set a Platform Name (e.g. My Automation Platform) to create your workspace.

Build a Test Flow

1. Start from scratch under Build a Flow.

2. Trigger: search Webhook, pick Catch Webhook → Test Trigger → Generate Sample Data → Send in the dialog. Confirm Tested Successfully with a captured request under Result #1.

3. Action: + below the trigger → Sub Flows → Return Response. Set Response Type to JSON, body:

{
  "message": "Workflow executed successfully"
}

4. Publish, then Test Flow. Hover the Catch Webhook block, click trigger to simulate an incoming request. Both steps should show Succeeded with execution times.

Next Steps

Activepieces is running with persistent PostgreSQL/Redis and automatic HTTPS. From here:

Connect real app integrations instead of the test webhook
Build custom pieces for internal tools not covered by the built-in connectors
Invite team members and set up shared workflow permissions

For the full guide, visit the original article on Vultr Docs.

Deploying Outline – Open-Source Knowledge Base Platform

Sanskriti Harmukh — Wed, 12 Aug 2026 16:17:30 +0000

Outline is an open-source knowledge base and team documentation platform including real-time collaborative editing, collections for structured content, and auth-provider integrations. This guide deploys it via Docker Compose with PostgreSQL, Redis, and Traefik-managed HTTPS, then builds a collection, writes a doc, and invites a team member.

Prerequisites: a Linux server (2 vCPU / 4GB RAM minimum), Docker + Docker Compose, a domain A record (e.g. outline.example.com), optional SMTP credentials (needed for invitations, password resets, notifications).

Set Up the Project

$ mkdir -p ~/outline/{data,pgdata,redis,letsencrypt}
$ cd ~/outline

data/ — attachments/uploads
pgdata/ — database files
redis/ — cache/session data
letsencrypt/ — Traefik ACME certs

Generate two secrets (run twice, save both):

$ openssl rand -hex 32

Environment file:

$ nano .env

NODE_ENV=production
DOMAIN=outline.example.com
LETSENCRYPT_EMAIL=admin@example.com

URL=https://outline.example.com
PORT=3000
SECRET_KEY=FIRST_GENERATED_SECRET
UTILS_SECRET=SECOND_GENERATED_SECRET

POSTGRES_DB=outline
POSTGRES_USER=outline
POSTGRES_PASSWORD=STRONG_DATABASE_PASSWORD
DATABASE_URL=postgres://outline:${POSTGRES_PASSWORD}@postgres:5432/outline
PGSSLMODE=disable

REDIS_URL=redis://redis:6379

FILE_STORAGE=local
FILE_STORAGE_LOCAL_ROOT_DIR=/var/lib/outline/data

LOG_LEVEL=info

# Optional: SMTP Configuration for outgoing emails
# SMTP_HOST=smtp.example.com
# SMTP_PORT=587
# SMTP_USERNAME=SMTP_USERNAME
# SMTP_PASSWORD=SMTP_PASSWORD
# SMTP_FROM_ADDRESS=noreply@outline.example.com
# SMTP_SECURE=false

Outline runs without SMTP, but invitations, password resets, and email notifications need it — uncomment for production.

Deploy with Docker Compose

$ nano docker-compose.yml

services:
  traefik:
    image: traefik:v3.6.15
    container_name: traefik
    restart: unless-stopped
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--certificatesresolvers.letsencrypt.acme.httpchallenge=true"
      - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.letsencrypt.acme.email=${LETSENCRYPT_EMAIL}"
      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - "./letsencrypt:/letsencrypt"
      - "/var/run/docker.sock:/var/run/docker.sock:ro"

  postgres:
    image: postgres:16-alpine
    container_name: outline-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - "./pgdata:/var/lib/postgresql/data"
    healthcheck:
      test: ["CMD", "pg_isready", "-d", "${POSTGRES_DB}", "-U", "${POSTGRES_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    container_name: outline-redis
    restart: unless-stopped
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - "./redis:/data"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 3

  outline:
    image: docker.getoutline.com/outlinewiki/outline:1.7.0
    container_name: outline
    restart: unless-stopped
    env_file:
      - .env
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    expose:
      - "3000"
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.outline.rule=Host(`${DOMAIN}`)"
      - "traefik.http.routers.outline.entrypoints=websecure"
      - "traefik.http.routers.outline.tls.certresolver=letsencrypt"
      - "traefik.http.services.outline.loadbalancer.server.port=3000"
    volumes:
      - "./data:/var/lib/outline/data"

$ docker compose up -d
$ docker compose ps -a
$ docker compose logs

Four containers: Outline, PostgreSQL, and Redis should show healthy; Traefik shows Up (no health check configured on it).

First-Run Setup

Visit https://outline.example.com:

Create Workspace — workspace name, admin name, admin email.
Continue to reach the super admin account.

Build a Knowledge Base

1. Create a collection: sidebar → New Collection, name it (e.g. March Articles), pick default access (Can edit / View only / No access), optionally configure Advanced options (templates, public sharing, comments), Create.

2. Write a document: + New doc, title it, use the rich text editor — type / for headings, lists, tables, code blocks.

3. Invite team members: sidebar → + Invite people, pick a role per invite (Admin / Editor / Viewer), enter email + name, + Add another for more, Send Invites.

Email invites need working SMTP — without it, share via public links or create accounts manually instead.

Next Steps

Outline is running with persistent storage, caching, and automatic HTTPS. From here:

Configure SMTP so invitations and notifications actually send
Set up an OIDC/SAML provider for team SSO
Explore the API for programmatic doc creation and integrations

For the full guide, visit the original article on Vultr Docs.

Deploying Planka – Open-Source Project Management Tool

Sanskriti Harmukh — Wed, 12 Aug 2026 16:16:11 +0000

Planka is an open-source, Kanban-style project management tool including boards, lists, and cards for organizing tasks and tracking team progress. This guide deploys it via Docker Compose with a PostgreSQL backend and Traefik-managed HTTPS, then builds a board and tests collaboration.

Prerequisites: a Linux server (2 vCPU / 4GB RAM minimum), Docker + Docker Compose, a domain A record (e.g. planka.example.com).

Set Up the Project

$ mkdir ~/planka
$ cd ~/planka
$ openssl rand -hex 64

Environment file — replace domain, email, secret key, and DB password:

$ nano .env

DOMAIN=planka.example.com
LETSENCRYPT_EMAIL=admin@example.com

BASE_URL=https://planka.example.com
SECRET_KEY=YOUR_GENERATED_SECRET_KEY

POSTGRES_DB=planka
POSTGRES_USER=planka_admin
POSTGRES_PASSWORD=STRONG_DATABASE_PASSWORD

Deploy with Docker Compose

$ nano docker-compose.yml

services:
  traefik:
    image: traefik:v3.7.0
    restart: unless-stopped
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--certificatesresolvers.letsencrypt.acme.tlschallenge=true"
      - "--certificatesresolvers.letsencrypt.acme.email=${LETSENCRYPT_EMAIL}"
      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./letsencrypt:/letsencrypt

  postgres:
    image: postgres:16-alpine
    container_name: planka-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5

  planka:
    image: ghcr.io/plankanban/planka:2.1.1
    container_name: planka-app
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      BASE_URL: ${BASE_URL}
      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres/${POSTGRES_DB}
      SECRET_KEY: ${SECRET_KEY}
    volumes:
      - ./data:/app/data
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.planka.rule=Host(`${DOMAIN}`)"
      - "traefik.http.routers.planka.entrypoints=websecure"
      - "traefik.http.routers.planka.tls.certresolver=letsencrypt"
    restart: unless-stopped

$ docker compose up -d
$ docker compose ps -a

Create the admin account:

$ docker compose run --rm planka npm run db:create-admin-user

Enter email, password, name (username optional).

$ docker compose logs

Confirm PostgreSQL accepts connections and Planka starts cleanly.

First-Run Setup

Visit https://planka.example.com, log in with your admin credentials, accept the End User Terms of Service to reach the dashboard.

Build a Kanban Board

1. Create a project: Create project → name (e.g. Team Collaboration Project) → optional description → Create project.

2. Create a board: open the project → Create board → name (e.g. Development Tasks) → Create board.

3. Add lists and cards: Add list for To Do, In Progress, Completed. Under each, Add card, name it, Enter. Drag cards between lists to confirm movement works.

4. Invite a team member: profile avatar → Administration → Add user (name, email, password) → Add User. Back on the board, open the members panel, search for the new user, add them.

Next Steps

Planka is running with persistent PostgreSQL storage and automatic HTTPS. From here:

Set up OIDC for SSO instead of local accounts
Configure SMTP for email notifications on card activity
Explore custom labels, due dates, and card attachments for richer workflows

For the full guide, visit the original article on Vultr Docs.

Installing Elasticsearch, Logstash, and Kibana (ELK Stack) on Kubernetes

Sanskriti Harmukh — Thu, 06 Aug 2026 17:51:37 +0000

The Elastic (ELK) Stack — Elasticsearch, Logstash, Kibana, and Beats — collects, processes, stores, and visualizes logs in real time. This guide deploys it on Kubernetes via the Elastic Cloud on Kubernetes (ECK) operator: Elasticsearch for storage/search, Logstash for pipeline processing, Filebeat as a per-node log shipper, and Kibana for visualization, all behind Traefik with Let's Encrypt TLS.

Prerequisites: a Kubernetes cluster (3+ nodes, 4GB RAM each minimum), kubectl/helm configured, a domain for Kibana (e.g. kibana.example.com).

Install Elasticsearch

ECK handles Elasticsearch cluster config, scaling, and upgrades automatically.

1. Install the operator — check the ECK releases page for the current version:

$ kubectl create -f https://download.elastic.co/downloads/eck/3.4.0/crds.yaml
$ kubectl apply -f https://download.elastic.co/downloads/eck/3.4.0/operator.yaml
$ kubectl get -n elastic-system pods

Confirm elastic-operator-0 is Running.

2. Define the Elasticsearch cluster:

$ nano elasticsearch.yaml

apiVersion: elasticsearch.k8s.elastic.co/v1
kind: Elasticsearch
metadata:
  name: quickstart
spec:
  version: 9.4.0
  nodeSets:
  - name: default
    count: 1
    config:
      node.store.allow_mmap: false
    volumeClaimTemplates:
    - metadata:
        name: elasticsearch-data
      spec:
        accessModes:
        - ReadWriteOnce
        resources:
          requests:
            storage: 40Gi
        storageClassName: standard

Replace standard with an actual StorageClass from your cluster — run kubectl get storageclass to see what's available. node.store.allow_mmap: false avoids memory-map permission issues in containers.

$ kubectl apply -f elasticsearch.yaml

Wait ~2 minutes, then verify:

$ kubectl get pods -l elasticsearch.k8s.elastic.co/cluster-name=quickstart
$ kubectl get service quickstart-es-http
$ kubectl get pvc
$ kubectl get elasticsearch

Single-node setups show yellow health (replicas can't be placed) — that's expected. red means check pods/service/PVC.

3. Grab the generated elastic user password — you'll need it for Elasticsearch and Kibana:

$ PASSWORD=$(kubectl get secret quickstart-es-elastic-user -o go-template='{{.data.elastic | base64decode}}')
$ echo $PASSWORD

Install Logstash

Logstash ingests from Filebeat, filters/enriches, and forwards to Elasticsearch.

$ nano logstash.yaml

apiVersion: logstash.k8s.elastic.co/v1alpha1
kind: Logstash
metadata:
  name: quickstart
spec:
  version: 9.4.0
  count: 1
  elasticsearchRefs:
  - name: quickstart
    clusterName: quickstart
  pipelines:
  - pipeline.id: main
    config.string: |
      input {
        beats {
          port => 5044
        }
      }
      filter {
        if [kubernetes][namespace] {
          mutate {
            add_field => { "environment" => "%{[kubernetes][namespace]}" }
          }
        }
      }
      output {
        elasticsearch {
          hosts => [ "${QUICKSTART_ES_HOSTS}" ]
          user => "${QUICKSTART_ES_USER}"
          password => "${QUICKSTART_ES_PASSWORD}"
          ssl_certificate_authorities => "${QUICKSTART_ES_SSL_CERTIFICATE_AUTHORITY}"
          index => "logstash-%{+YYYY.MM.dd}"
        }
      }
  services:
  - name: beats
    service:
      spec:
        type: ClusterIP
        ports:
        - port: 5044
          name: beats
          protocol: TCP
          targetPort: 5044
  volumeClaimTemplates:
  - metadata:
      name: logstash-data
    spec:
      accessModes:
      - ReadWriteOnce
      resources:
        requests:
          storage: 40Gi
      storageClassName: standard

elasticsearchRefs auto-injects connection credentials as env vars. The pipeline listens for Filebeat on port 5044, tags each log with its Kubernetes namespace, and writes to a daily logstash-YYYY.MM.dd index.

$ kubectl apply -f logstash.yaml
$ kubectl get pods -l logstash.k8s.elastic.co/name=quickstart
$ kubectl get logstash

Expect green health, 1/1 available.

Install Filebeat

Runs as a DaemonSet, tailing /var/log/containers/ on every node and enriching with Kubernetes metadata.

$ nano filebeat.yaml

apiVersion: beat.k8s.elastic.co/v1beta1
kind: Beat
metadata:
  name: quickstart
spec:
  type: filebeat
  version: 9.4.0
  config:
    filebeat.inputs:
    - type: filestream
      id: kubernetes-container-logs
      paths:
      - /var/log/containers/*.log
      parsers:
      - container: {}
      prospector.scanner.symlinks: true
      processors:
      - add_kubernetes_metadata:
          host: ${NODE_NAME}
          matchers:
          - logs_path:
              logs_path: /var/log/containers/
      - drop_event.when:
          or:
          - equals:
              kubernetes.namespace: "kube-system"
          - equals:
              kubernetes.namespace: "kube-public"
          - equals:
              kubernetes.namespace: "elastic-system"
          - equals:
              kubernetes.namespace: "kube-node-lease"
    output.logstash:
      hosts: ["quickstart-ls-beats:5044"]
  daemonSet:
    podTemplate:
      spec:
        serviceAccountName: filebeat
        automountServiceAccountToken: true
        terminationGracePeriodSeconds: 30
        dnsPolicy: ClusterFirstWithHostNet
        hostNetwork: true
        containers:
        - name: filebeat
          env:
          - name: NODE_NAME
            valueFrom:
              fieldRef:
                fieldPath: spec.nodeName
          securityContext:
            runAsUser: 0
          volumeMounts:
          - name: varlogcontainers
            mountPath: /var/log/containers
          - name: varlogpods
            mountPath: /var/log/pods
          - name: varlibdockercontainers
            mountPath: /var/lib/docker/containers
        volumes:
        - name: varlogcontainers
          hostPath:
            path: /var/log/containers
        - name: varlogpods
          hostPath:
            path: /var/log/pods
        - name: varlibdockercontainers
          hostPath:
            path: /var/lib/docker/containers

drop_event.when filters out system namespace noise. hostNetwork: true + runAsUser: 0 are needed for node-level log access.

RBAC:

$ nano filebeat-rbac.yaml

apiVersion: v1
kind: ServiceAccount
metadata:
  name: filebeat
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: filebeat
rules:
- apiGroups: [""]
  resources: [namespaces, pods, nodes]
  verbs: [get, list, watch]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: filebeat
subjects:
- kind: ServiceAccount
  name: filebeat
  namespace: default
roleRef:
  kind: ClusterRole
  name: filebeat
  apiGroup: rbac.authorization.k8s.io

$ kubectl apply -f filebeat-rbac.yaml
$ kubectl apply -f filebeat.yaml
$ kubectl get pods -A -l common.k8s.elastic.co/type=beat
$ kubectl get beat

One Filebeat pod per node, green health.

Install Kibana

$ nano kibana.yaml

apiVersion: kibana.k8s.elastic.co/v1
kind: Kibana
metadata:
  name: quickstart
  namespace: default
spec:
  version: 9.4.0
  count: 1
  elasticsearchRef:
    name: quickstart
  http:
    tls:
      selfSignedCertificate:
        disabled: true

TLS is disabled here because Traefik handles termination downstream.

$ kubectl apply -f kibana.yaml
$ kubectl get pods --selector='kibana.k8s.elastic.co/name=quickstart'
$ kubectl get service quickstart-kb-http
$ kubectl get kibana

Secure with Traefik + cert-manager

1. Install Traefik as Ingress:

$ helm repo add traefik https://traefik.github.io/charts
$ helm repo update
$ helm install traefik traefik/traefik \
  --namespace traefik \
  --create-namespace \
  --set "ports.web.exposedPort=80" \
  --set "ports.websecure.exposedPort=443" \
  --set "ports.web.http.redirections.entryPoint.to=websecure" \
  --set "ports.web.http.redirections.entryPoint.scheme=https" \
  --set persistence.enabled=false
$ kubectl get all -n traefik

Wait ~3 minutes for the LoadBalancer, then get its IP and point your DNS provider's A record at it:

$ kubectl get service traefik --namespace traefik

2. Install cert-manager — check the releases page for the current version:

$ kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.20.2/cert-manager.yaml
$ kubectl get pods -n cert-manager

3. Create a ClusterIssuer:

$ nano issuer.yaml

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt
spec:
  acme:
    email: admin@example.com
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: letsencrypt-account-key
    solvers:
      - http01:
          ingress:
            ingressClassName: traefik

$ kubectl apply -f issuer.yaml

4. Create the Ingress. Replace kibana.example.com:

$ nano kibana-ingress.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: kibana
  namespace: default
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt
spec:
  ingressClassName: traefik
  tls:
    - hosts:
        - kibana.example.com
      secretName: kibana-tls
  rules:
    - host: kibana.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: quickstart-kb-http
                port:
                  number: 5601

$ kubectl apply -f kibana-ingress.yaml
$ kubectl get ingress -n default
$ kubectl get certificate -n default

kibana-tls should show READY: True — give cert-manager a few minutes if not.

5. Confirm TLS works:

$ curl -I https://kibana.example.com

Access Kibana

$ kubectl get secret quickstart-es-elastic-user -o go-template='{{.data.elastic | base64decode}}' && echo

Visit https://kibana.example.com, log in as elastic with that password, Explore on my own.

Explore logs:

Main menu → Analytics → Discover.
Select (or create) the logstash-* data view — index pattern logstash-*, time field @timestamp.
Filter with queries like kubernetes.namespace: default, kubernetes.pod.name: demo-app*, or message: error.
Adjust the time range picker, click any log entry to expand full metadata.

Troubleshooting

Elasticsearch pod stuck Pending — kubectl describe pod quickstart-es-default-0. Usually insufficient node resources, or the PVC's StorageClass doesn't exist (kubectl get storageclass to check).

Elasticsearch yellow/red — kubectl get elasticsearch. Yellow is normal for single-node (no room for replicas); scale nodeSets.count to 3+ for green in production. Red means check kubectl logs quickstart-es-default-0 for OOM or storage failures.

Filebeat not collecting — verify RBAC:

$ kubectl get serviceaccount filebeat
$ kubectl get clusterrole filebeat
$ kubectl get clusterrolebinding filebeat

Reapply filebeat-rbac.yaml if anything's missing; check kubectl logs -l common.k8s.elastic.co/type=beat.

Certificate not issued — kubectl describe certificate kibana-tls -n default, kubectl describe certificaterequest -n default, kubectl logs -n cert-manager -l app=cert-manager. Usually DNS not propagated yet (dig kibana.example.com) or port 80 not reachable for the HTTP-01 challenge.

"Kibana server is not ready yet" — confirm kubectl get elasticsearch shows green; if it does but Kibana still fails, check kubectl logs -l kibana.k8s.elastic.co/name=quickstart.

LoadBalancer stuck <pending> — needs cloud-provider LoadBalancer integration; check kubectl describe service traefik -n traefik if it doesn't resolve within 5 minutes.

Next Steps

Logs flow from every node through Filebeat → Logstash → Elasticsearch, visualized in Kibana over TLS. From here:

Scale nodeSets.count to 3+ for a green, replicated Elasticsearch cluster
Add more Logstash filters (grok, geoip) for richer log parsing
Set up Kibana alerting rules on error-rate thresholds

For the full guide, visit the original article on Vultr Docs.

Deploying ZITADEL – Open-Source Identity and Access Management Platform

Sanskriti Harmukh — Thu, 06 Aug 2026 17:44:24 +0000

ZITADEL is an open-source IAM platform supporting OIDC, OAuth 2.0, and SAML, with MFA, passkeys, and SSO built in. This guide deploys it via Docker Compose with PostgreSQL and Traefik-managed TLS, then walks through creating a test user and an OIDC application.

Prerequisites: a Linux server (4 vCPU / 8GB RAM minimum), Docker + Docker Compose, a domain A record (e.g. zitadel.example.com).

Set Up the Project

$ sudo usermod -aG docker $USER
$ newgrp docker
$ mkdir -p ~/zitadel/{letsencrypt,postgres,zitadel-bootstrap}
$ cd ~/zitadel

letsencrypt — TLS certs
postgres — database files
zitadel-bootstrap — shares the machine user's personal access token between the API and login containers

Generate a 32-char masterkey:

$ tr -dc A-Za-z0-9 </dev/urandom | head -c 32

Create the environment file:

$ nano .env

ZITADEL_DOMAIN=zitadel.example.com
LETSENCRYPT_EMAIL=admin@example.com

ZITADEL_MASTERKEY=YOUR_32_CHARACTER_MASTERKEY

POSTGRES_DB=zitadel
POSTGRES_USER=postgres
POSTGRES_PASSWORD=STRONG_DATABASE_PASSWORD

ADMIN_USERNAME=admin
ADMIN_PASSWORD=ADMIN_PASSWORD_VALUE

ZITADEL_VERSION=v4.15.1
TRAEFIK_VERSION=v3.7.0
POSTGRES_VERSION=17.2-alpine

Replace the placeholders with real values. Two gotchas:

The admin password needs 8+ chars with upper/lower/number/symbol, or ZITADEL fails to initialize.
Avoid $ in .env passwords — Docker Compose treats it as a variable reference and silently strips what follows.

Check the ZITADEL releases page if you want a version other than the pinned v4.15.1.

Deploy with Docker Compose

Four services: Traefik (TLS), PostgreSQL, the ZITADEL API, and the Login UI.

$ nano docker-compose.yml

services:
  traefik:
    image: traefik:${TRAEFIK_VERSION}
    container_name: zitadel-traefik
    restart: unless-stopped
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--providers.docker.network=zitadel"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--certificatesresolvers.le.acme.httpchallenge=true"
      - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.le.acme.email=${LETSENCRYPT_EMAIL}"
      - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    networks:
      - zitadel
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./letsencrypt:/letsencrypt

  postgres:
    image: postgres:${POSTGRES_VERSION}
    container_name: zitadel-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - ./postgres:/var/lib/postgresql/data
    networks:
      - zitadel
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -d ${POSTGRES_DB} -U ${POSTGRES_USER}"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 20s

  zitadel-api:
    image: ghcr.io/zitadel/zitadel:${ZITADEL_VERSION}
    container_name: zitadel-api
    restart: unless-stopped
    user: "0"
    command: start-from-init --masterkey "${ZITADEL_MASTERKEY}"
    environment:
      ZITADEL_PORT: 8080
      ZITADEL_EXTERNALDOMAIN: ${ZITADEL_DOMAIN}
      ZITADEL_EXTERNALPORT: 443
      ZITADEL_EXTERNALSECURE: true
      ZITADEL_TLS_ENABLED: false
      ZITADEL_DATABASE_POSTGRES_DSN: "postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}?sslmode=disable"
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME: ${ADMIN_USERNAME}
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD: ${ADMIN_PASSWORD}
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: true
      ZITADEL_FIRSTINSTANCE_LOGINCLIENTPATPATH: /zitadel/bootstrap/login-client.pat
      ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_MACHINE_USERNAME: login-client
      ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_MACHINE_NAME: Automatically Initialized IAM_LOGIN_CLIENT
      ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_PAT_EXPIRATIONDATE: "2099-01-01T00:00:00Z"
      ZITADEL_DEFAULTINSTANCE_FEATURES_LOGINV2_REQUIRED: true
      ZITADEL_DEFAULTINSTANCE_FEATURES_LOGINV2_BASEURI: https://${ZITADEL_DOMAIN}/ui/v2/login/
      ZITADEL_OIDC_DEFAULTLOGINURLV2: https://${ZITADEL_DOMAIN}/ui/v2/login/login?authRequest=
      ZITADEL_OIDC_DEFAULTLOGOUTURLV2: https://${ZITADEL_DOMAIN}/ui/v2/login/logout?post_logout_redirect=
      ZITADEL_SAML_DEFAULTLOGINURLV2: https://${ZITADEL_DOMAIN}/ui/v2/login/login?samlRequest=
    volumes:
      - ./zitadel-bootstrap:/zitadel/bootstrap:rw
    networks:
      - zitadel
    depends_on:
      postgres:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "/app/zitadel", "ready"]
      interval: 10s
      timeout: 30s
      retries: 12
      start_period: 20s
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=zitadel"
      - "traefik.http.services.zitadel-api.loadbalancer.server.port=8080"
      - "traefik.http.services.zitadel-api.loadbalancer.server.scheme=h2c"
      - "traefik.http.middlewares.zitadel-strip-api.stripprefix.prefixes=/api"
      - "traefik.http.middlewares.zitadel-strip-api.stripprefix.forceSlash=false"
      - "traefik.http.routers.zitadel-api-alias.rule=Host(`${ZITADEL_DOMAIN}`) && PathPrefix(`/api`)"
      - "traefik.http.routers.zitadel-api-alias.entrypoints=websecure"
      - "traefik.http.routers.zitadel-api-alias.tls.certresolver=le"
      - "traefik.http.routers.zitadel-api-alias.middlewares=zitadel-strip-api"
      - "traefik.http.routers.zitadel-api-alias.service=zitadel-api"
      - "traefik.http.routers.zitadel-api-alias.priority=200"
      - "traefik.http.routers.zitadel-api.rule=Host(`${ZITADEL_DOMAIN}`) && !PathPrefix(`/ui/v2/login`) && !PathPrefix(`/api`) && !Path(`/`)"
      - "traefik.http.routers.zitadel-api.entrypoints=websecure"
      - "traefik.http.routers.zitadel-api.tls.certresolver=le"
      - "traefik.http.routers.zitadel-api.service=zitadel-api"
      - "traefik.http.routers.zitadel-api.priority=100"

  zitadel-login:
    image: ghcr.io/zitadel/zitadel-login:${ZITADEL_VERSION}
    container_name: zitadel-login
    restart: unless-stopped
    user: "0"
    environment:
      ZITADEL_API_URL: http://zitadel-api:8080
      NEXT_PUBLIC_BASE_PATH: /ui/v2/login
      ZITADEL_SERVICE_USER_TOKEN_FILE: /zitadel/bootstrap/login-client.pat
      CUSTOM_REQUEST_HEADERS: Host:${ZITADEL_DOMAIN},X-Forwarded-Proto:https
    volumes:
      - ./zitadel-bootstrap:/zitadel/bootstrap:ro
    networks:
      - zitadel
    depends_on:
      zitadel-api:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "/bin/sh", "-c", "node /app/healthcheck.mjs http://localhost:3000/ui/v2/login/healthy"]
      interval: 10s
      timeout: 30s
      retries: 12
      start_period: 20s
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=zitadel"
      - "traefik.http.services.zitadel-login.loadbalancer.server.port=3000"
      - "traefik.http.middlewares.zitadel-root-rewrite.replacepath.path=/ui/v2/login/"
      - "traefik.http.routers.zitadel-root.rule=Host(`${ZITADEL_DOMAIN}`) && Path(`/`)"
      - "traefik.http.routers.zitadel-root.entrypoints=websecure"
      - "traefik.http.routers.zitadel-root.tls.certresolver=le"
      - "traefik.http.routers.zitadel-root.middlewares=zitadel-root-rewrite"
      - "traefik.http.routers.zitadel-root.service=zitadel-login"
      - "traefik.http.routers.zitadel-root.priority=400"
      - "traefik.http.routers.zitadel-login.rule=Host(`${ZITADEL_DOMAIN}`) && PathPrefix(`/ui/v2/login`)"
      - "traefik.http.routers.zitadel-login.entrypoints=websecure"
      - "traefik.http.routers.zitadel-login.tls.certresolver=le"
      - "traefik.http.routers.zitadel-login.service=zitadel-login"
      - "traefik.http.routers.zitadel-login.priority=250"

networks:
  zitadel:
    name: zitadel

traefik — TLS termination, HTTP→HTTPS redirect, ACME certs
postgres — identity data, users, orgs, apps
zitadel-api — auth, user management, admin operations
zitadel-login — the Next.js login/registration/recovery UI

$ docker compose up -d
$ docker compose ps -a
$ docker compose logs

postgres, zitadel-api, and zitadel-login should report healthy; traefik shows Up (no health check configured on it).

If zitadel-api won't start, check docker compose logs zitadel-api — a PasswordComplexityPolicy error means your admin password doesn't meet requirements. ZITADEL writes a partial migration that can't be fixed by just restarting: docker compose down -v, fix .env, then docker compose up -d for a clean start. Also note docker compose restart doesn't re-read .env — always use up -d after config changes.

First-Run Setup

Open https://zitadel.example.com/ui/console:

Login name format: USERNAME@zitadel.DOMAIN (e.g. admin@zitadel.zitadel.example.com) — the default org is named zitadel.
Enter your ADMIN_PASSWORD from .env.
Set a new password when prompted (first-login change is mandatory).

Create a Test User and OIDC App

1. Create a user: Users → + New → email, username, first/last name, set an initial password, Create.

2. Create a project and application:

Projects → Create New Project, name it (e.g. Test Application), Continue.
Under Applications, + New → name it, type Web, Continue.
Pick an auth method, Continue.
Add a redirect URI (e.g. https://example.com/callback), Continue.
Review on Overview, Create.
Copy the Client ID — use your ZITADEL domain as the issuer URL in your app's OIDC config.

Next Steps

ZITADEL is running with TLS, a bootstrapped admin org, and a working OIDC app. From here:

Add identity providers (Google, GitHub, generic OIDC/SAML) for federated login
Enable MFA and passkeys for the org
Customize branding on the login UI before rolling out to end users

For the full guide, visit the original article on Vultr Docs.