Skip to content

Run Membrick with Docker

Docker Compose builds and runs the Membrick HTTP server, keeps its memory index in a persistent volume, and publishes the API on localhost.

Requirements

  • Docker Engine with the Compose plugin
  • A terminal in the Membrick repository

Start the server

Create a private token file, then build and start the container:

mkdir -p secrets
openssl rand -hex 32 > secrets/server-token
chmod 700 secrets
chmod 644 secrets/server-token
docker compose up --build -d

Compose mounts this file as a container secret. Server options live in deploy/docker/server.toml.

The first start builds the release server image. Compose stores the index in the membrick-data volume, so memories remain available when the container is restarted or upgraded.

The server is available at http://127.0.0.1:8080. The Compose port mapping binds the host side to localhost. The container listens on its own network interface with --allow-non-loopback; that option requires authentication through the mounted token file or a configured JWT secret and cannot be combined with --allow-unauthenticated.

The dashboard is included and served by default. Open http://127.0.0.1:8080/dashboard to view memory index health, search activity, and agent activity. No separate container, port, or dashboard flag is needed. See the Observability guide for what it displays.

Check that it started:

curl http://127.0.0.1:8080/health

Add and search a memory:

curl -X POST http://127.0.0.1:8080/add \
  -H "X-Api-Key: $(cat secrets/server-token)" \
  -H 'Content-Type: application/json' \
  --data '{
    "request_id": "docker-demo:session-1:chunk-1",
    "messages": [{"role": "user", "content": "I prefer concise answers."}],
    "user_id": "docker-demo-user",
    "session_id": "docker-demo-session"
  }'

curl -X POST http://127.0.0.1:8080/search \
  -H "X-Api-Key: $(cat secrets/server-token)" \
  -H 'Content-Type: application/json' \
  --data '{
    "query": "How should I format answers?",
    "user_id": "docker-demo-user",
    "top_k": 5
  }'

The Compose setup uses the same routes as the HTTP server API, including POST /add/batch for adding up to 128 memories in one request.

Stop and manage data

Stop the server and keep its saved memories:

docker compose down

Start it again with docker compose up -d. To permanently delete the stored index as well as stop the server, remove the named volume:

docker compose down --volumes

The Helm chart also retains its persistent volume when the release is uninstalled. To permanently delete the Helm-managed index, remove the claim after uninstalling:

helm uninstall membrick --namespace membrick
kubectl delete pvc membrick --namespace membrick

Keep the token file private. The supplied Compose file publishes the port only on the local machine. If you change that port binding to expose the service on another interface, put it behind an authenticated, encrypted access layer.

Install on Kubernetes with Helm

The chart runs one server replica with a persistent volume and an internal ClusterIP Service. The single replica is required because one Membrick server process owns writes to its index. The dashboard is included at /dashboard.

Create a namespace and token Secret:

kubectl create namespace membrick
mkdir -p secrets
openssl rand -hex 32 > secrets/server-token
chmod 700 secrets
chmod 644 secrets/server-token
kubectl create secret generic membrick-auth \
  --namespace membrick \
  --from-file=SERVER_TOKEN=secrets/server-token

The chart defaults to ghcr.io/rooagi/membrick-server:0.6.0; the repository does not currently publish this image automatically. Build and push the image to a registry you control, then set image.repository and image.tag during installation. For example:

docker build -t registry.example.com/membrick-server:0.6.0 .
docker push registry.example.com/membrick-server:0.6.0
helm upgrade --install membrick ./charts/membrick \
  --namespace membrick \
  --set image.repository=registry.example.com/membrick-server \
  --set image.tag=0.6.0

The default chart provisions a 10 GiB persistent volume claim using the cluster's default StorageClass; set persistence.size or persistence.storageClassName to change it. For clusters without a default StorageClass, set the storage class explicitly.

Forward the internal Service to your local machine to try the API and dashboard:

kubectl port-forward --namespace membrick service/membrick 8080:8080

Open http://127.0.0.1:8080/dashboard. In-cluster agents can call http://membrick.membrick.svc.cluster.local:8080 and send the token in the X-Api-Key header. The chart does not create a public Ingress. Add TLS and authenticated access at your cluster's gateway if outside-cluster clients need to connect.

The chart source is versioned in charts/membrick; it can be installed on any Kubernetes cluster, including AWS EKS. Amazon ECR supports hosting images and Helm charts as OCI artifacts; see the AWS ECR chart instructions to publish your image and chart in your AWS account. For a private image registry, configure imagePullSecrets in the chart values.