Take full control of your notes with Memos, a lightweight, open-source, self-hosted note-taking application. Memos is fast, flexible, and perfect for developers.

In this guide, you’ll learn how to deploy Memos on Kubernetes — whether in a browser-based playground like KillerKoda or a production cluster. You’ll get persistent storage, easy browser access, and a fully functional self-hosted environment.

Step-by-step instructions, ready-to-use manifests, and troubleshooting tips ensure a smooth deployment experience.

What Is Memos?

Memos is an open-source, self-hosted note-taking application designed for developers and knowledge workers who want full control over their data. Built with Go for the backend and React for the frontend, it’s lightweight, fast, and easy to deploy.

Why Deploy Memos on Kubernetes?

Running Memos locally or in a simple Docker container works fine for quick tests or personal use. However, as soon as you want reliability, persistence, and scalability, Kubernetes becomes a game-changer.

Here’s why deploying Memos on Kubernetes is a smart choice:

1. Persistent Storage for Your Notes
   • Without Kubernetes, a container restart can wipe all your data if volumes aren’t configured properly.
   • Kubernetes allows you to attach a PersistentVolumeClaim (PVC), ensuring all notes are saved even if pods are restarted or rescheduled.
2. Automatic Pod Management
   • Kubernetes ensures your Memos pod stays running. If it crashes, Kubernetes automatically restarts it — no manual intervention needed.
3. Easy Port Exposure and Networking
   • Using NodePort or Ingress, you can access Memos from your browser anywhere, without exposing your host machine directly.
4. Scalability and Team Usage
   • Even though Memos is lightweight, Kubernetes allows you to scale horizontally if needed — useful for teams or multi-user environments.
5. Perfect Playground for Experimentation
   • Platforms like KillerKoda let you spin up Kubernetes clusters directly in the browser, test deployments, and learn Kubernetes best practices — all without installing anything locally.

Prerequisites

Before we deploy Memos on Kubernetes, make sure you have the following ready. These steps will ensure your deployment runs smoothly and your notes remain safe.

1. A Running Kubernetes Cluster
   • You can use KillerKoda, Minikube, Kind, or any managed Kubernetes cluster.
   • For this guide, we’ll use KillerKoda’s browser-based playground, so no local installation is needed.
2. Kubectl CLI Access
   • Ensure the kubectl command-line tool is installed and configured to interact with your cluster.
   • Test your connection: kubectl get nodes
   • You should see the list of nodes in your cluster.
3. Internet Access for Pulling Docker Images
   • Memos is distributed as a Docker image (neosmemo/memos:latest), so your cluster must be able to pull images from Docker Hub.
4. Optional: Basic Kubernetes Knowledge
   • Familiarity with Deployments, Services, and PersistentVolumeClaims (PVCs) is helpful, but not strictly required — we’ll walk through each step in detail.

Install Memos on Kubernetes

In this section, we’ll deploy Memos on your Kubernetes cluster. Each step includes manifests, commands, and verification tips so you can follow along easily — especially in KillerKoda’s browser playground.

Create the Deployment Manifest

We start by defining a Deployment that runs the Memos container. It ensures the pod restarts automatically and listens on all interfaces (0.0.0.0) to avoid 502 errors.

// Create memos-deployment.yaml File

apiVersion: apps/v1
kind: Deployment
metadata:
  name: memos
spec:
  replicas: 1
  selector:
    matchLabels:
      app: memos
  template:
    metadata:
      labels:
        app: memos
    spec:
      containers:
        - name: memos
          image: neosmemo/memos:latest
          ports:
            - containerPort: 5230
          env:
            - name: MEMOS_LISTEN
              value: "0.0.0.0"
          volumeMounts:
            - name: memos-data
              mountPath: /var/opt/memos
      volumes:
        - name: memos-data
          emptyDir: {}

Tip: MEMOS_LISTEN=0.0.0.0 is crucial for external access in Kubernetes — without it, you’ll get a 502 error when connecting through NodePort.

Apply the Deployment

Apply the Deployment manifest to your cluster:

kubectl apply -f memos-deployment.yaml

Verify Deployement

Verify that the pod is running:

kubectl get pods -l app=memos
kubectl rollout status deployment/memos
kubectl logs -l app=memos --tail=20

Add Persistent Storage

To ensure your notes are saved even if the pod restarts, create a PersistentVolumeClaim (PVC):

// Create memos-pvc.yaml File

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: memos-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi

Make sure you have this configuration in memos-deployment.yaml for binding:

volumes:
  - name: memos-data
    persistentVolumeClaim:
      claimName: memos-pvc

Apply and Verify the PVC:

kubectl apply -f memos-pvc.yaml

kubectl get pvc memos-pvc

Tip: In KillerKoda, this stores data temporarily. For production, consider using NFS or cloud storage classes.

Expose Memos via NodePort

To access Memos in your browser, create a Service:

// Create memos-service.yaml File

apiVersion: v1
kind: Service
metadata:
  name: memos
spec:
  selector:
    app: memos
  ports:
    - port: 5230
      targetPort: 5230
      nodePort: 31230
  type: NodePort

Apply and Verify the service:

kubectl apply -f memos-service.yaml

kubectl get svc memos

Open the NodePort (e.g., 31230) in your browser to see Memos running.

Cleanup (Optional)

If you want to remove the deployment after testing:

kubectl delete all -l app=memos
kubectl delete pvc memos-pvc

This ensures no leftover pods or storage in your cluster playground.

Common Issues & Fixes

Even with a straightforward Kubernetes deployment, you might run into a few common issues when running Memos. Here’s a quick reference to troubleshoot and fix them efficiently.

1. 502 Bad Gateway
   • Accessing Memos in the browser returns a 502 error.
   • The container is listening only on localhost instead of all interfaces.
   • Set the environment variable in your Deployment manifest:
   • env:
     – name: MEMOS_LISTEN
     value: “0.0.0.0”
   • Then re-apply the Deployment.
2. Data Lost After Pod Restart
   • Notes disappear after restarting the pod.
   • No persistent storage was configured, so data is stored inside the ephemeral pod.
   • Create and attach a PersistentVolumeClaim (PVC)

Summary

Memos is a self-hosted, developer-friendly note app that combines simplicity, speed, and full data control. Deploying it on Kubernetes provides:

• Persistent Storage: Notes survive pod restarts via PersistentVolumeClaims.
• Automatic Pod Management: Kubernetes keeps your Memos pod running and self-healing.
• Accessible Networking: NodePort or Ingress allows browser access without exposing the host.
• Scalability: Scale horizontally for teams or multi-user environments.
• Easy Experimentation: Browser-based Kubernetes playgrounds like KillerKoda make testing seamless.

With this guide, you now have all the steps — Deployment manifests, PVC setup, NodePort service, verification commands, and cleanup instructions — to get Memos running reliably on Kubernetes. Plus, you’re equipped with a common issues cheat sheet to troubleshoot errors like 502 responses, pod restarts, or inaccessible services.