Flavius Deployment Guide

• Introduction
• Prerequisites
• Cluster Setup
• GitOps Repository
• Service Installation
  • MinIO
  • etcd
  • Flavius Image Pull Credentials
  • Modify Cluster CoreDNS for K3D
  • Install Flavius Services
• Verify Deployment
• Interacting with Flavius
  • Via FE Pod Shell
  • Via Python SDK (No longer recommended)
    • Example Python Script
  • Via Neo4j SDK (Recommended)
• Troubleshooting
• License

Introduction

This guide walks you through deploying and interacting with the Flavius graph platform on a local k3d Kubernetes cluster. By the end, you'll have MinIO object storage, etcd, and Flavius services running, plus examples of how to query Flavius via its FE shell, Python SDK and Neo4j SDK.

Prerequisites

• k3d: Lightweight Kubernetes in Docker (v5.x)

  curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash

• kubectl: Kubernetes CLI (latest stable)

  curl -LO "https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl"
  chmod +x kubectl
  sudo mv kubectl /usr/local/bin/

• Helm: Kubernetes package manager (v3.x)

  curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

• Python: 3.10–3.12 for SDK usage

Cluster Setup

1. Create k3d cluster

   k3d cluster create flavius

2. (Optional) Delete cluster

   k3d cluster delete flavius

3. Verify cluster

   kubectl cluster-info

GitOps Repository

Clone the deployment manifests:

git clone https://github.com/Kasma-Inc/Flavius_Deployment.git
cd Flavius_Deployment

Service Installation

MinIO

Install MinIO via Helm:

helm install minio oci://registry-1.docker.io/bitnamicharts/minio \
  --create-namespace --namespace minio \
  --set auth.rootUser=fvadmin --set auth.rootPassword=fvadmin123 \
  --set defaultBuckets=flavius \
  --set service.type=NodePort --set service.nodePorts.api=30900 \
  --set persistence.enabled=true --wait

Etcd

Install single-node etcd:

helm install etcd ./etcd \
  --create-namespace --namespace etcd \
  --set auth.rbac.create=false --set persistence.enabled=true --wait

Flavius Image Pull Credentials

kubectl create namespace flavius
kubectl -n flavius create secret docker-registry image-pull-secret \
  --docker-server=registry-intl.cn-hongkong.aliyuncs.com \
  --docker-username="flavius_user@5170390357037810" \
  --docker-password="Kasma2025"

Modify Cluster CoreDNS for K3D

cd /Flavius_Deployment/tools
kubectl -n kube-system apply -f k3d-coredns-custom.yaml
kubectl rollout restart -n kube-system deployment/coredns

Install Flavius Services

helm install flavius ./flavius \
  --namespace flavius -f ./flavius/values.yaml --wait

Verify Deployment

Check all Pods:

kubectl get pods --all-namespaces

Interacting with Flavius

Prerequisites

• Forward port 30000 and 7687 of the Flavius FE pod in your k3d cluster to your local machine.
• Forward port 30900 of your MinIO service to your local machine.

 k3d cluster edit flavius --port-add 30000:30000@loadbalancer
 k3d cluster edit flavius --port-add 7687:7687@loadbalancer
 kubectl port-forward -n minio svc/minio 30900:9000

Via FE Pod Shell

kubectl exec -it fe-0 -n flavius -- /bin/bash
cd frontend/
./flavius-shell --host localhost --port 30000 --user <username> --password <password>

The default username is fvadmin, and password is fvadmin123.

Please check more details in the Flavius Official Doc/shell section.

Via Python SDK (No longer recommended)

Install SDK and dependencies

pip3 install flavius_py310  # flavius_py311 | flavius_py312
pip3 install minio

Example Python Script

See python_sdk/example.py for a complete demo illustrating:

• Uploading CSV data to MinIO
• Creating namespaces, graphs, vertex and edge tables
• Importing data with BLOCKING IMPORT
• Executing parameterized queries

Via Neo4j SDK (Recommended)

Please refer to Flavius Docs#sdk for installation and usage based on the Neo4j Bolt protocol.
For the Example Script, also check the “Example usage” section in the documentation.

Troubleshooting

• Installation errors: Verify network access to Docker registry and PyPI.
• Port conflicts: Ensure ports 30000 and 30900 are free on your host.
• DNS issues: Reapply CoreDNS config as shown above.

License

This project is licensed under the Apache 2.0 License. See LICENSE for details.