Deploying an AI-ready AFFiNE workspace with pgvector on Civo Kubernetes

AFFiNE is an open-source workspace tool that combines documents, whiteboards, and knowledge management into a single platform. It provides a self-hosted alternative to proprietary collaboration tools, giving individuals and teams full control over their data while helping reduce software subscription costs.

While AFFiNE can be deployed using Docker Compose on a single server, production environments often require higher availability, easier scaling, and improved reliability. Running AFFiNE on Kubernetes allows workloads to be distributed across multiple nodes while providing automated recovery and simplified infrastructure management.

In this tutorial, we will deploy AFFiNE on a Civo K3s Kubernetes cluster using Kubernetes YAML manifests. The deployment includes the AFFiNE application, Redis for caching, and a Civo Managed PostgreSQL database with pgvector support for persistent storage, resulting in a scalable and production-ready deployment.

Why Affine self-host on Kubernetes

A few reasons teams choose this approach:

• You control your data. Documents, whiteboards, and workspace data stay within your own infrastructure rather than being stored on a third-party platform.
• Lower long-term costs. Self-hosting AFFiNE can be more cost-effective than paying recurring subscription fees, especially for growing teams with multiple users.
• Built for growth. Kubernetes makes it easier to support a larger number of users by distributing workloads across multiple nodes and scaling resources as demand increases.

Prerequisites

Before getting started, make sure you have the following:

• A Civo account
• A running Civo K3s Kubernetes cluster
• The Civo CLI installed and authenticated
• kubectl installed and configured
• A Civo Managed PostgreSQL database
• An LLM API key (required to run the AI Copilot and search features) 
• A domain name you control, with the ability to add an A record pointing at your VM. If you don't have a domain, we will use nip.io, a free wildcard DNS service, so any IP gets a working hostname that Caddy can fetch a certificate for

Connect kubectl to the Civo Kubernetes cluster

Before managing any AFFiNE resources on the Civo Kubernetes cluster, ensure that your local kubectl client is connected. This allows you to manage cluster resources and apply Kubernetes manifests from your workstation.

List the available Kubernetes clusters in your Civo account:

1civo kubernetes ls

Example output:

1+--------------------------------------+-------------------+
2| ID                                   | Name              |
3+--------------------------------------+-------------------+
4| ca878c7d-2c2a-43e6-82c0-454005709d3e | cool-sky-65132581 |
5+--------------------------------------+-------------------+

Download and save the kubeconfig for your cluster:

1civo kubernetes config <cluster_name> --save

Replace <cluster_name> with the actual cluster name

Verify that the Kubernetes context has been added successfully:

1kubectl config get-contexts

Expected output:

1CURRENT   NAME
2*         <cluster_name>

If multiple contexts exist on your machine, switch to the AFFiNE cluster context:

1kubectl config use-context <cluster_name>

Next, verify that kubectl can communicate with the cluster:

1kubectl cluster-info

Expected output:

1Kubernetes control plane is running at https://<CLUSTER-ENDPOINT>:6443
2CoreDNS is running at https://<CLUSTER-ENDPOINT>:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

Finally, confirm that the cluster node is available:

1kubectl get nodes

Expected output:

1NAME                                      STATUS   ROLES    AGE   VERSION
2
3k3s-cool-sky-65132581-default-pool-xxxx   Ready    <none>   5m    v1.xx.x+k3s1

Once the node reports a Ready status, you're ready to begin deploying AFFiNE resources to the cluster.

Create a namespace for AFFiNE

To keep the deployment organized, we'll create a dedicated working directory for all Kubernetes manifests and then create a separate namespace for the AFFiNE resources.

First, create a project directory and navigate into it:

1mkdir -p ~/affine-k8s

1cd ~/affine-k8s

Next, create a file named namespace.yaml:

1nano namespace.yaml

Add the following content:

1apiVersion: v1
2kind: Namespace
3metadata:
4  name: affine

Apply the manifest:

1kubectl apply -f namespace.yaml

Expected output:

1namespace/affine created

Verify that the namespace was created successfully:

1kubectl get namespaces

You should see the affine namespace listed in the output:

1NAME              STATUS
2affine            Active

With the namespace in place, we'll deploy all remaining AFFiNE resources into this dedicated namespace.

Deploy PostgreSQL with pgvector inside the Cluster 

AFFiNE requires a PostgreSQL database to store user accounts, workspaces, and application data. We will deploy PostgreSQL directly into our Kubernetes cluster using the official pgvectorimage. This ensures our database is fully AI-ready right out of the box.

Create a file named postgres.yaml: 

1nano postgres.yaml

Add the following manifests. This file creates persistent storage, the PostgreSQL deployment, and an internal service to route traffic:

1apiVersion: v1
2kind: PersistentVolumeClaim
3metadata:
4  name: postgres-storage
5  namespace: affine
6spec:
7  accessModes:
8    - ReadWriteOnce
9  storageClassName: civo-volume
10  resources:
11    requests:
12      storage: 10Gi
13---
14apiVersion: apps/v1
15kind: Deployment
16metadata:
17  name: postgres
18  namespace: affine
19spec:
20  replicas: 1
21  selector:
22    matchLabels:
23      app: postgres
24  template:
25    metadata:
26      labels:
27        app: postgres
28    spec:
29      containers:
30      - name: postgres
31        image: pgvector/pgvector:pg16
32        env:
33        - name: POSTGRES_USER
34          value: "civo"
35        - name: POSTGRES_PASSWORD
36          value: "<YOUR_POSTGRES_PASSWORD>"
37        - name: POSTGRES_DB
38          value: "affine"
39        - name: PGDATA
40          value: "/var/lib/postgresql/data/pgdata"
41        ports:
42        - containerPort: 5432
43        volumeMounts:
44        - name: postgres-data
45          mountPath: /var/lib/postgresql/data
46      volumes:
47      - name: postgres-data
48        persistentVolumeClaim:
49          claimName: postgres-storage
50---
51apiVersion: v1
52kind: Service
53metadata:
54  name: postgres
55  namespace: affine
56spec:
57  selector:
58    app: postgres
59  ports:
60  - port: 5432
61    targetPort: 5432

Replace:

• <YOUR_POSTGRES_PASSWORD> with your actual password.

Apply the manifest:

1kubectl apply -f postgres.yaml

Wait a minute for the pod to start running, then verify it:

1kubectl get pods -n affine

Finally, we must turn on the pgvectorextension so the AI Copilot can save vector data. Since the database is running inside our cluster, run this command to execute the SQL query directly inside the pod:

1kubectl exec -it deployment/postgres -n affine -- psql -U civo -d affine -c "CREATE EXTENSION IF NOT EXISTS vector;"

Expected output:

1CREATE EXTENSION

Configure persistent storage

AFFiNE stores uploaded files, workspace assets, and application data that should persist even if a pod is restarted or rescheduled. To ensure this data is not lost, we'll create a PersistentVolumeClaim (PVC) that uses Civo's default StorageClass.

Before creating the PVC, verify the available StorageClass in the cluster:

1kubectl get storageclass

Expected output:

1NAME                    PROVISIONER    RECLAIMPOLICY
2civo-volume (default)   csi.civo.com   Delete

Next, create a file named pvc.yaml:

1nano pvc.yaml

Add the following configuration:

1apiVersion: v1
2kind: PersistentVolumeClaim
3metadata:
4  name: affine-storage
5  namespace: affine
6spec:
7  accessModes:
8    - ReadWriteOnce
9  storageClassName: civo-volume
10  resources:
11    requests:
12      storage: 10Gi

Apply the manifest:

1kubectl apply -f pvc.yaml

Expected output:

1persistentvolumeclaim/affine-storage created

Verify that the PVC has been created:

1kubectl get pvc -n affine

Initially, the PVC may show a Pending status. This is expected because the default civo-volume StorageClass uses the WaitForFirstConsumer binding mode, meaning a volume is only provisioned when a pod starts using the claim.

1NAME             STATUS
2affine-storage   Pending

Once the AFFiNE pod is deployed and mounts this PVC, Kubernetes will automatically provision the volume and bind it to the claim.

With persistent storage configured, we can now deploy Redis, which AFFiNE uses for caching and background job processing.

Deploy Redis

AFFiNE uses Redis for caching and background task processing. We'll deploy Redis inside the Kubernetes cluster and expose it internally using a ClusterIP service.

Create a file named redis.yaml:

1nano redis.yaml

Add the Redis Deployment and Service manifests:

1apiVersion: v1
2kind: PersistentVolumeClaim
3metadata:
4  name: redis-storage
5  namespace: affine
6spec:
7  accessModes:
8    - ReadWriteOnce
9  storageClassName: civo-volume
10  resources:
11    requests:
12      storage: 2Gi
13---
14apiVersion: apps/v1
15kind: Deployment
16metadata:
17  name: redis
18  namespace: affine
19spec:
20  replicas: 1
21  selector:
22    matchLabels:
23      app: redis
24  template:
25    metadata:
26      labels:
27        app: redis
28    spec:
29      containers:
30      - name: redis
31        image: redis:7-alpine
32        command: ["redis-server", "--appendonly", "yes"]
33        ports:
34        - containerPort: 6379
35        volumeMounts:
36        - name: redis-data
37          mountPath: /data
38      volumes:
39      - name: redis-data
40        persistentVolumeClaim:
41          claimName: redis-storage
42---
43apiVersion: v1
44kind: Service
45metadata:
46  name: redis
47  namespace: affine
48spec:
49  selector:
50    app: redis
51  ports:
52  - port: 6379
53    targetPort: 6379

Apply the manifest:

1kubectl apply -f redis.yaml

Expected output:

1deployment.apps/redis created
2service/redis created

Verify that the Redis pod is running:

1kubectl get pods -n affine

Expected output:

1NAME                     READY   STATUS
2redis-596d56fb4f-456hr   1/1     Running

Next, verify that the Redis service has been created:

1kubectl get svc -n affine

Expected output:

1NAME    TYPE        CLUSTER-IP      PORT(S)
2redis   ClusterIP   10.43.xxx.xxx   6379/TCP

We'll use this hostname when configuring AFFiNE to connect to Redis in the next section.

Create Kubernetes secrets

AFFiNE requires access to both PostgreSQL and Redis. Rather than hardcoding connection details in the deployment manifest, we'll store them securely using Kubernetes Secrets.

Create a file named secret.yaml:

1nano secret.yaml

Add the following configuration, replacing the database credentials with your own values:

1apiVersion: v1
2kind: Secret
3metadata:
4  name: affine-secret
5  namespace: affine
6type: Opaque
7stringData:
8  DATABASE_URL: postgresql://civo:<PASSWORD>@<HOST>:5432/affine
9  REDIS_SERVER_HOST: redis
10  AFFINE_SERVER_EXTERNAL_URL: "https://affine.yourdomain.com"
11  AFFINE_ADMIN_EMAIL: "admin@yourdomain.com"
12  AFFINE_ADMIN_PASSWORD: "SuperSecurePassword123!"
13  TELEMETRY_ENABLE: "false"

Replace:

• <PASSWORD> with actual password
• <HOST> with the actual host
• <affine.yourdomain.com> replace with actual configured domain.
• <admin@yourdomain.com> replace with actual configured domain email.

AFFiNE configuration variables explained

It is useful to understand the role of each variable before you apply the secret:

• AFFINE_ADMIN_EMAIL and AFFINE_ADMIN_PASSWORD: These credentials define your primary administrative user. You will need these specific login details to access the dashboard when you first launch the instance.
• TELEMETRY_ENABLE: By setting this value to "false", you disable tracking and ensure all activity remains localized to your environment.
• AFFINE_SERVER_EXTERNAL_URL: This defines the public-facing endpoint for the application, which is critical for the proper rendering of links and shared workspace resources.

Apply the manifest:

1kubectl apply -f secret.yaml

Expected output:

1secret/affine-secret created

Verify that the secret has been created successfully:

1kubectl get secrets -n affine

Expected output:

1NAME            TYPE     DATA
2affine-secret   Opaque   2

You can inspect the secret metadata using:

1kubectl describe secret affine-secret -n affine

Expected output:

1Name:         affine-secret
2Namespace:    affine
3Data
4====
5DATABASE_URL:       <value hidden>
6REDIS_SERVER_HOST:  <value hidden>

At this point, Kubernetes can securely provide the PostgreSQL and Redis connection details to the AFFiNE containers without exposing sensitive credentials directly in the deployment manifests.

Configure AI features (Semantic search & copilot) 

To make this workspace truly "AI-ready," we must pass a configuration file to AFFiNE containing our AI provider's API key. We will store this securely as a Kubernetes Secret. 

Create a file named ai-config.yaml:

1nano ai-config.yaml

1apiVersion: v1
2kind: Secret
3metadata:
4  name: affine-config
5  namespace: affine
6type: Opaque
7stringData:
8  config.json: |
9    {
10      "copilot": {
11        "enabled": true,
12        "providers.openai": {
13          "apiKey": "<YOUR_OPENAI_API_KEY>"
14        }
15      }
16    }

Replace:

• <YOUR_OPENAI_API_KEY>  with your actual API key 

Apply the secret to the cluster:

1kubectl apply -f ai-config.yaml

Run the database migrations

Before starting the AFFiNE application, we need to initialize the PostgreSQL database schema. AFFiNE provides a migration container that creates the required tables and prepares the database for the application.

Create a file named migration.yaml:

1nano migration.yaml

Add the migration Job manifest:

1apiVersion: batch/v1
2kind: Job
3metadata:
4  name: affine-migration
5  namespace: affine
6spec:
7  template:
8    spec:
9      restartPolicy: Never
10      containers:
11      - name: migration
12        image: ghcr.io/toeverything/affine:stable
13        command: ["sh","-c","node ./scripts/self-host-predeploy.js"]
14        envFrom:
15        - secretRef:
16            name: affine-secret

Apply the manifest:

1kubectl apply -f migration.yaml

Expected output:

1job.batch/affine-migration created

You can monitor the migration job using:

1kubectl get jobs -n affine

Once the migration completes successfully, you should see output similar to:

1NAME               STATUS     COMPLETIONS
2affine-migration   Complete   1/1

To view the migration logs, run:

1kubectl logs job/affine-migration -n affine

Finally, verify that the job completed successfully:

1kubectl get jobs -n affine

Expected output:

1NAME               STATUS     COMPLETIONS   DURATION
2affine-migration   Complete   1/1           37s

With the database schema initialized, we're ready to deploy the AFFiNE application and connect it to Redis, PostgreSQL, and persistent storage.

Troubleshooting a failed migration job

Because this job is configured with restartPolicy: Never, it will not automatically retry if something is wrong. If the status shows 0/1 completions or enters a Failed state, use these steps to fix it: 

1. Check the logs for errors: Run this command to see why the migration failed: 

1kubectl logs job/affine-migration -n affine

2. Delete the failed job: Kubernetes jobs are immutable, meaning you cannot update or re-run a failed job. You must delete the old one first:

1kubectl delete job affine-migration -n affine 

3. Fix and retry: Correct any mistakes in your secret.yaml file, re-apply it using kubectl apply -f secret.yaml, and then re-run your migration manifest: 

1kubectl apply -f migration.yaml

4. Once you add this block to your document, you can tick off this comment as Resolved. Paste the next piece of feedback whenever you are ready!

Deploy AFFiNE

With PostgreSQL, Redis, and the database schema in place, we can now deploy the AFFiNE application. The deployment will connect to the managed PostgreSQL database, use Redis for caching, and mount persistent storage for application data.

Create a file named affine-deployment.yaml:

1nano affine-deployment.yaml

Add the deployment manifest:

1apiVersion: apps/v1
2kind: Deployment
3metadata:
4  name: affine
5  namespace: affine
6spec:
7  replicas: 1
8  selector:
9    matchLabels:
10      app: affine
11  template:
12    metadata:
13      labels:
14        app: affine
15    spec:
16      containers:
17      - name: affine
18        image: ghcr.io/toeverything/affine:stable
19        ports:
20        - containerPort: 3010
21        envFrom:
22        - secretRef:
23            name: affine-secret
24        volumeMounts:
25        - name: affine-storage
26          mountPath: /root/.affine/storage
27        # NEW: Put the AI config file into the app
28        - name: ai-config-volume
29          mountPath: /root/.affine/config
30      volumes:
31      - name: affine-storage
32        persistentVolumeClaim:
33          claimName: affine-storage
34      # NEW: Get the AI config from your secret
35      - name: ai-config-volume
36        secret:
37          secretName: affine-config

Apply the manifest:

1kubectl apply -f affine-deployment.yaml

Expected output:

1deployment.apps/affine created

Verify that the AFFiNE pod is running:

1kubectl get pods -n affine

Expected output:

1NAME                       READY   STATUS
2affine-xxxxxxxxxx-xxxxx    1/1     Running

You can also inspect the deployment:

1kubectl get deployments -n affine

Expected output:

1NAME     READY   UP-TO-DATE   AVAILABLE
2affine   1/1     1            1

At this stage, the AFFiNE application is running inside the cluster and connected to both Redis and PostgreSQL. The persistent volume claim should also become bound automatically once the pod starts using it.

Verify the storage status:

1kubectl get pvc -n affine

Expected output:

1NAME             STATUS
2affine-storage   Bound

With the application successfully deployed, the final step is to expose it outside the cluster so it can be accessed from a web browser.

Open firewall ports for web traffic

Before we expose the application to the internet, we must ensure the Civo cluster firewall allows incoming web traffic. This allows users to reach your site and allows Let's Encrypt to verify your domain for a security certificate.

1. Log into your Civo Dashboard and navigate to Networking > Firewalls.
2. Select the firewall attached to your K3s cluster.
3. Under Inbound Rules, add two new rules:
4. • Port: 80 (Source: 0.0.0.0/0)
   • Port: 443 (Source: 0.0.0.0/0)
4. Save the firewall rules.

Point your domain to the cluster

We want users to access AFFiNE using a custom domain. We need to point your domain name to the public IP address of a node in your cluster.

Run this command to find the external IP of your nodes:

1kubectl get nodes -o wide

Copy the IP address listed under the EXTERNAL-IP column.

Log into your domain registrar (such as Namecheap or GoDaddy) and create an A Record. Point your custom domain (e.g., affine.yourdomain.com) to this IP address. Save the record and wait a few minutes for the internet to update.

Expose the application using Traefik 

The AFFiNE application is currently running inside the Kubernetes cluster,Civo K3s comes with Traefik pre-installed to route traffic. First, we will create an internal ClusterIP service for AFFiNE. 

Create a file named affine-service.yaml:

1nano affine-service.yaml

Add the following Service manifest:

1apiVersion: v1
2kind: Service
3metadata:
4  name: affine
5  namespace: affine
6spec:
7  type: LoadBalancer
8  selector:
9    app: affine
10  ports:
11    - port: 80
12      targetPort: 3010

Apply the manifest:

1kubectl apply -f affine-service.yaml

Expected output:

1service/affine created

Verify that the service has been created:

1kubectl get svc -n affine

Secure the application with HTTPS

To make sure data is safe, we will use cert-manager to automatically fetch free SSL certificates from Let's Encrypt.

Install cert-manager using the official release manifest:

1kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.4/cert-manager.yaml

Wait a minute for the pods to start, and verify they are running:

1kubectl get pods -n cert-manager 

Create a file named cluster-issuer.yaml:

1nano cluster-issuer.yaml

Add the following code:

1apiVersion: cert-manager.io/v1
2kind: ClusterIssuer
3metadata:
4  name: letsencrypt-prod
5spec:
6  acme:
7    server: https://acme-v02.api.letsencrypt.org/directory
8    email: your-email@example.com
9    privateKeySecretRef:
10      name: letsencrypt-prod
11    solvers:
12    - http01:
13        ingress:
14          class: traefik

Replace:

• your-email@example.com with actual configured domain email.

Apply the ClusterIssuer: 

1kubectl apply -f cluster-issuer.yaml

Create an Ingress resource. This tells Traefik to route traffic from your custom domain to AFFiNE and secure it with the certificate.

Create a file named affine-ingress.yaml: 

1nano affine-ingress.yaml

Add the following code:

1apiVersion: networking.k8s.io/v1
2kind: Ingress
3metadata:
4  name: affine-ingress
5  namespace: affine
6  annotations:
7    cert-manager.io/cluster-issuer: "letsencrypt-prod"
8    ingress.kubernetes.io/ssl-redirect: "true"
9spec:
10  tls:
11  - hosts:
12    - affine.yourdomain.com
13    secretName: affine-tls-secret
14  rules:
15  - host: affine.yourdomain.com
16    http:
17      paths:
18      - path: /
19        pathType: Prefix
20        backend:
21          service:
22            name: affine
23            port:
24              number: 80

Replace <affine.yourdomain.com> with your actual domain

Apply the manifest:

1kubectl apply -f affine-ingress.yaml

Wait about one minute. You can check the status of your SSL certificate by running:

1kubectl get certificate -n affine

When the READY column says True, your SSL certificate is installed.

Verify the deployment

Now that AFFiNE is accessible through the LoadBalancer service, let's verify that all components are working correctly.

First, check that all pods are running successfully:

1kubectl get pods -n affine

Expected output:

1NAME                        READY   STATUS
2affine-xxxxxxxxxx-xxxxx     1/1     Running
3redis-xxxxxxxxxx-xxxxx      1/1     Running

Next, verify that the persistent volume claim has been bound successfully:

1kubectl get pvc -n affine

Expected output:

1NAME             STATUS
2affine-storage   Bound

You can also confirm that the migration job completed successfully:

1kubectl get jobs -n affine

Expected output:

1NAME               STATUS     COMPLETIONS
2affine-migration   Complete   1/1

Next, open your web browser and navigate to your secure custom domain: https://affine.yourdomain.com

Replace <affine.yourdomain.com> with your actual domain

You should be presented with the AFFiNE setup screen. Complete the initial setup process and create your first workspace.

Once the workspace is created, try creating a document or whiteboard to confirm that the application is functioning correctly and that data is being stored successfully.

At this point, you have successfully deployed AFFiNE on a Civo K3s Kubernetes cluster using a managed PostgreSQL database, Redis, persistent storage, and Kubernetes YAML manifests.

Cleaning up resources

If you were following along for testing purposes and do not want to keep AFFiNE running, it is important to clean up your resources to avoid unexpected charges.

First, delete all Kubernetes resources (including the AFFiNE deployment, Redis, persistent volumes, and secrets) by deleting the entire namespace:

1kubectl delete namespace affine 

Next, delete the cluster and database from your Civo account:

1. Log into the Civo Dashboard.
2. Navigate to Kubernetes and delete your K3s cluster.
3. Navigate to Databases and delete your Managed PostgreSQL instance.

Log into your domain registrar (e.g., Namecheap or GoDaddy) and remove the A Record you created so your custom domain no longer points to the deleted cluster.

Summary

In this tutorial, we deployed AFFiNE on a Civo K3s Kubernetes cluster using Kubernetes YAML manifests. We provisioned a Civo Managed PostgreSQL database, deployed Redis for caching, configured persistent storage, initialised the database schema, and exposed the application through a LoadBalancer service.

By running AFFiNE on Kubernetes, we gain improved reliability, easier scalability, and better operational flexibility compared to a single-server deployment. This architecture provides a solid foundation for teams looking to self-host an open-source workspace platform while maintaining control over their data and infrastructure.