Lars Varming aab233496c Use official Dockerfile.standalone for custom MCP server build

2025-11-08 21:07:28 +01:00

8.7 KiB

Raw Blame History

GitHub Actions → Docker Hub Automated Build Setup

This guide explains how to automatically build your custom Graphiti MCP Docker image with your local changes and push it to Docker Hub using GitHub Actions.

Why This Approach?

✅ Automatic builds - Every push to main triggers a new build ✅ Reproducible - Anyone can see exactly what was built ✅ Multi-platform - Builds for both AMD64 and ARM64 ✅ No local building - GitHub does all the work ✅ Version tracking - Tied to git commits ✅ Clean workflow - Professional CI/CD pipeline

Prerequisites

GitHub account with a fork of the graphiti repository
Docker Hub account (username: lvarming)
Docker Hub Access Token (for GitHub Actions to push images)

Step 1: Create Docker Hub Access Token

Go to Docker Hub
Click your username → Account Settings
Click Security → New Access Token
Give it a description: "GitHub Actions - Graphiti MCP"
Copy the token (you'll only see it once!)

Step 2: Add Token to GitHub Repository Secrets

Go to your forked repository on GitHub
Click Settings → Secrets and variables → Actions
Click New repository secret
Name: DOCKERHUB_TOKEN
Value: Paste the access token from Step 1
Click Add secret

Step 3: Verify Workflow Files

The repository already includes the necessary workflow file at:

.github/workflows/build-custom-mcp.yml

And the custom Dockerfile at:

mcp_server/docker/Dockerfile.custom

These files are configured to:

Build using YOUR local graphiti-core changes (not PyPI)
Push to lvarming/graphiti-mcp on Docker Hub
Tag with version numbers and latest

Step 4: Trigger a Build

Option A: Automatic Build (On Push)

The workflow automatically triggers when you:

Push to the main branch
Modify files in graphiti_core/ or mcp_server/

Simply commit and push your changes:

git add .
git commit -m "Update graphiti-core with custom changes"
git push origin main

Option B: Manual Build

Go to your repository on GitHub
Click Actions tab
Select Build Custom MCP Server workflow
Click Run workflow dropdown
(Optional) Specify a custom tag, or leave as latest
Click Run workflow

Step 5: Monitor the Build

Click on the running workflow to see progress
The build takes about 5-10 minutes
You'll see:
- Version extraction
- Docker image build (for AMD64 and ARM64)
- Push to Docker Hub
- Build summary with tags

Step 6: Verify Image on Docker Hub

Go to Docker Hub
Navigate to your repository: lvarming/graphiti-mcp
Check the Tags tab
You should see tags like:
- latest
- mcp-1.0.0
- mcp-1.0.0-core-0.23.0
- sha-abc1234

Step 7: Use Your Custom Image

In Unraid

Update your Docker container to use:

Repository: lvarming/graphiti-mcp:latest

In Docker Compose

services:
  graphiti-mcp:
    image: lvarming/graphiti-mcp:latest
    container_name: graphiti-mcp
    restart: unless-stopped
    # ... rest of your config

Pull Manually

docker pull lvarming/graphiti-mcp:latest

Understanding the Build Process

What Gets Built

The custom Dockerfile (Dockerfile.custom) does the following:

Copies entire project - Both graphiti_core/ and mcp_server/
Builds graphiti-core from local source - Not from PyPI
Installs MCP server - Using the local graphiti-core
Creates multi-platform image - AMD64 and ARM64

Version Tagging

Each build creates multiple tags:

Tag	Description	Example
`latest`	Always points to most recent build	`lvarming/graphiti-mcp:latest`
`mcp-X.Y.Z`	MCP server version	`lvarming/graphiti-mcp:mcp-1.0.0`
`mcp-X.Y.Z-core-A.B.C`	Full version info	`lvarming/graphiti-mcp:mcp-1.0.0-core-0.23.0`
`sha-xxxxxxx`	Git commit SHA	`lvarming/graphiti-mcp:sha-abc1234`

Build Arguments

The workflow passes these build arguments:

GRAPHITI_CORE_VERSION=0.23.0       # From pyproject.toml
MCP_SERVER_VERSION=1.0.0            # From mcp_server/pyproject.toml
BUILD_DATE=2025-11-08T12:00:00Z    # UTC timestamp
VCS_REF=abc1234                     # Git commit hash

Workflow Customization

Change Docker Hub Username

If you want to use a different Docker Hub account, edit .github/workflows/build-custom-mcp.yml:

env:
  DOCKERHUB_USERNAME: your-username  # Change this
  IMAGE_NAME: graphiti-mcp

Change Trigger Conditions

To only build on tags instead of every push:

on:
  push:
    tags:
      - 'v*.*.*'

Add Slack/Discord Notifications

Add a notification step at the end of the workflow:

- name: Notify on Success
  uses: slackapi/slack-github-action@v1
  with:
    webhook-url: ${{ secrets.SLACK_WEBHOOK }}
    payload: |
      {
        "text": "✅ New Graphiti MCP image built: lvarming/graphiti-mcp:latest"
      }

Troubleshooting

Build Fails - "Error: buildx failed"

Cause: Docker Buildx issue Solution: Re-run the workflow (transient issue)

Build Fails - "unauthorized: incorrect username or password"

Cause: Invalid Docker Hub credentials Solution:

Verify DOCKERHUB_TOKEN secret is correct
Regenerate access token on Docker Hub
Update the secret in GitHub

Build Fails - "No space left on device"

Cause: GitHub runner out of disk space Solution: Add cleanup step before build:

- name: Free up disk space
  run: |
    docker system prune -af
    df -h

Image Not Found on Docker Hub

Cause: Image is private Solution:

Go to Docker Hub → lvarming/graphiti-mcp
Click Settings
Make repository Public

Workflow Doesn't Trigger

Cause: Branch protection or incorrect path filters Solution:

Check you're pushing to main branch
Verify changes are in graphiti_core/ or mcp_server/
Manually trigger from Actions tab

Advanced: Multi-Repository Setup

If you want separate images for development and production:

Development Image

Create .github/workflows/build-dev-mcp.yml:

name: Build Dev MCP Server

on:
  push:
    branches:
      - dev
      - feature/*

env:
  DOCKERHUB_USERNAME: lvarming
  IMAGE_NAME: graphiti-mcp-dev  # Different image name

Production Image

Keep the main workflow for production builds on main branch.

Comparing with Official Builds

Feature	Official (zepai)	Your Custom Build
Source	PyPI graphiti-core	Local graphiti-core
Trigger	Manual tags only	Auto on push + manual
Docker Hub	zepai/knowledge-graph-mcp	lvarming/graphiti-mcp
Build Platform	Depot (paid)	GitHub Actions (free)
Customization	Limited	Full control

Best Practices

1. Pin Versions for Production

Instead of latest, use specific versions:

image: lvarming/graphiti-mcp:mcp-1.0.0-core-0.23.0

2. Test Before Deploying

Add a test step in the workflow:

- name: Test image
  run: |
    docker run --rm lvarming/graphiti-mcp:latest --version

3. Keep Workflows Updated

GitHub Actions updates frequently. Use Dependabot:

Create .github/dependabot.yml:

version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"

4. Monitor Build Times

If builds are slow, enable caching:

cache-from: type=gha
cache-to: type=gha,mode=max

(Already enabled in the workflow!)

5. Security Scanning

Add Trivy security scanner:

- name: Run Trivy vulnerability scanner
  uses: aquasecurity/trivy-action@master
  with:
    image-ref: lvarming/graphiti-mcp:latest
    format: 'table'
    exit-code: '1'
    severity: 'CRITICAL,HIGH'

Next Steps

✅ Set up Docker Hub access token
✅ Add secret to GitHub repository
✅ Push changes to trigger first build
✅ Verify image appears on Docker Hub
✅ Update your Unraid/LibreChat config to use new image
📝 Document any custom changes in DOCS/

Questions?

GitHub Actions Issues: Check the Actions tab for detailed logs
Docker Hub Issues: Verify your account and access token
Build Failures: Review the workflow logs for specific errors

8.7 KiB Raw Blame History