admin/basicmachines-co-basic-memory
1
0
Fork 0
mirror of https://github.com/basicmachines-co/basic-memory synced 2026-06-21 13:47:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: implement Docker CI workflow for automated image publishing (#159)

Browse Source 
Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Paul Hernandez
2025-06-20 15:42:55 -05:00
committed by GitHub
parent d3b6c85184
commit 74847cc380
5 changed files with 263 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.dockerignore
+60
View File
@@ -0,0 +1,60 @@
# Git files
.git/
.gitignore
.gitattributes
# Development files
.vscode/
.idea/
*.swp
*.swo
*~
# Testing files
tests/
test-int/
.pytest_cache/
.coverage
htmlcov/
# Build artifacts
build/
dist/
*.egg-info/
__pycache__/
*.pyc
*.pyo
*.pyd
.Python
# Virtual environments (uv creates these during build)
.venv/
venv/
.env
# CI/CD files
.github/
# Documentation (keep README.md and pyproject.toml)
docs/
CHANGELOG.md
CLAUDE.md
CONTRIBUTING.md
# Example files not needed for runtime
examples/
# Local development files
.basic-memory/
*.db
*.sqlite3
# OS files
.DS_Store
Thumbs.db
# Temporary files
tmp/
temp/
*.tmp
*.log
.github/workflows/docker.yml
+68
View File
@@ -0,0 +1,68 @@
name: Docker Image CI
on:
push:
tags:
- 'v*' # Trigger on version tags like v1.0.0, v0.13.0, etc.
workflow_dispatch: # Allow manual triggering for testing
env:
REGISTRY: docker.io
IMAGE_NAME: basicmachines/basic-memory
jobs:
docker:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
with:
platforms: linux/amd64,linux/arm64
- name: Log in to Docker Hub
uses: docker/login-action@v3
with:
registry: ${{ env.REGISTRY }}
username: ${{ secrets.DOCKER_USERNAME }}
password: ${{ secrets.DOCKER_PASSWORD }}
- name: Extract metadata
id: meta
uses: docker/metadata-action@v5
with:
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
tags: |
type=ref,event=branch
type=ref,event=pr
type=semver,pattern={{version}}
type=semver,pattern={{major}}.{{minor}}
type=raw,value=latest,enable={{is_default_branch}}
- name: Build and push Docker image
uses: docker/build-push-action@v5
with:
context: .
file: ./Dockerfile
platforms: linux/amd64,linux/arm64
push: true
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
cache-from: type=gha
cache-to: type=gha,mode=max
- name: Update Docker Hub description
uses: peter-evans/dockerhub-description@v4
with:
username: ${{ secrets.DOCKER_USERNAME }}
password: ${{ secrets.DOCKER_PASSWORD }}
repository: ${{ env.IMAGE_NAME }}
readme-filepath: ./docs/Docker.md
Dockerfile
+25 -6
View File
@@ -1,13 +1,32 @@
FROM python:3.12-slim
FROM python:3.12-slim-bookworm
# Copy uv from official image
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
# Set environment variables
ENV PYTHONUNBUFFERED=1 \
PYTHONDONTWRITEBYTECODE=1
# Copy the project into the image
ADD . /app
# Sync the project into a new environment, asserting the lockfile is up to date
WORKDIR /app
RUN uv sync --locked
# Copy the project files
COPY . .
# Create data directory
RUN mkdir -p /app/data
# Install pip and build dependencies
RUN pip install --upgrade pip \
&& pip install . --no-cache-dir --ignore-installed
# Set default data directory and add venv to PATH
ENV BASIC_MEMORY_HOME=/app/data \
PATH="/app/.venv/bin:$PATH"
# Expose port
EXPOSE 8000
# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
CMD basic-memory --version || exit 1
# Use the basic-memory entrypoint to run the MCP server with default SSE transport
CMD ["basic-memory", "mcp", "--transport", "sse", "--host", "0.0.0.0", "--port", "8000"]
docker-compose.yml
+13 -6
View File
@@ -5,7 +5,12 @@ version: '3.8'
services:
basic-memory:
build: .
# Use pre-built image (recommended for most users)
image: basicmachines/basic-memory:latest
# Uncomment to build locally instead:
# build: .
container_name: basic-memory-server
# Volume mounts for knowledge directories and persistent data
@@ -14,14 +19,16 @@ services:
# Persistent storage for configuration and database
- basic-memory-config:/root/.basic-memory:rw
# The default project will be at /root/basic-memory
# Mount your knowledge directory (required)
# Change './knowledge' to your actual Obsidian vault or knowledge directory
- ./knowledge:/app/data:rw
# OPTIONAL: Mount additional knowledge directories for multiple projects
# - ./work-notes:/data/projects/work:rw
# - ./personal-notes:/data/projects/personal:rw
# - ./work-notes:/app/data/work:rw
# - ./personal-notes:/app/data/personal:rw
# You can edit the project config manually in
# /root/.basic-memory/config.json
# You can edit the project config manually in the mounted config volume
# The default project will be configured to use /app/data
environment:
# Project configuration
- BASIC_MEMORY_DEFAULT_PROJECT=main
docs/Docker.md
+97 -15
View File
@@ -5,7 +5,38 @@ system. This is particularly useful for integrating with existing Dockerized MCP
## Quick Start
### Option 1: Using Docker Compose (Recommended)
### Option 1: Using Pre-built Images (Recommended)
Basic Memory provides pre-built Docker images on Docker Hub that are automatically updated with each release.
1. **Use the official image directly:**
```bash
docker run -d \
--name basic-memory-server \
-p 8000:8000 \
-v /path/to/your/obsidian-vault:/app/data:rw \
-v basic-memory-config:/root/.basic-memory:rw \
basicmachines/basic-memory:latest
```
2. **Or use Docker Compose with the pre-built image:**
```yaml
version: '3.8'
services:
basic-memory:
image: basicmachines/basic-memory:latest
container_name: basic-memory-server
ports:
- "8000:8000"
volumes:
- /path/to/your/obsidian-vault:/app/data:rw
- basic-memory-config:/root/.basic-memory:rw
environment:
- BASIC_MEMORY_DEFAULT_PROJECT=main
restart: unless-stopped
```
### Option 2: Using Docker Compose (Building Locally)
1. **Clone the repository:**
```bash
@@ -18,7 +49,7 @@ system. This is particularly useful for integrating with existing Dockerized MCP
```yaml
volumes:
# Change './obsidian-vault' to your actual directory path
- /path/to/your/obsidian-vault:/data/knowledge:rw
- /path/to/your/obsidian-vault:/app/data:rw
```
3. **Start the container:**
@@ -26,7 +57,7 @@ system. This is particularly useful for integrating with existing Dockerized MCP
docker-compose up -d
```
### Option 2: Using Docker CLI
### Option 3: Using Docker CLI
```bash
# Build the image
@@ -35,7 +66,7 @@ docker build -t basic-memory .
# Run with volume mounting
docker run -d \
--name basic-memory-server \
-v /path/to/your/obsidian-vault:/data/knowledge:rw \
-v /path/to/your/obsidian-vault:/app/data:rw \
-v basic-memory-config:/root/.basic-memory:rw \
-e BASIC_MEMORY_DEFAULT_PROJECT=main \
basic-memory
@@ -49,7 +80,7 @@ Basic Memory requires several volume mounts for proper operation:
1. **Knowledge Directory** (Required):
```yaml
- /path/to/your/obsidian-vault:/data/knowledge:rw
- /path/to/your/obsidian-vault:/app/data:rw
```
Mount your Obsidian vault or knowledge base directory.
@@ -63,8 +94,8 @@ You can edit the basic-memory config.json file located in the /root/.basic-memor
3. **Multiple Projects** (Optional):
```yaml
- /path/to/project1:/data/projects/project1:rw
- /path/to/project2:/data/projects/project2:rw
- /path/to/project1:/app/data/project1:rw
- /path/to/project2:/app/data/project2:rw
```
You can edit the basic-memory config.json file located in the /root/.basic-memory/config.json
@@ -97,8 +128,8 @@ When using Docker volumes, you'll need to configure projects to point to your mo
2. **Add a project for your mounted volume:**
```bash
# If you mounted /path/to/your/vault to /data/knowledge
docker exec basic-memory-server basic-memory project create my-vault /data/knowledge
# If you mounted /path/to/your/vault to /app/data
docker exec basic-memory-server basic-memory project create my-vault /app/data
# Set it as default
docker exec basic-memory-server basic-memory project set-default my-vault
@@ -114,13 +145,13 @@ When using Docker volumes, you'll need to configure projects to point to your mo
If you mounted your Obsidian vault like this in docker-compose.yml:
```yaml
volumes:
- /Users/yourname/Documents/ObsidianVault:/data/obsidian:rw
- /Users/yourname/Documents/ObsidianVault:/app/data:rw
```
Then configure it:
```bash
# Create project pointing to mounted vault
docker exec basic-memory-server basic-memory project create obsidian /data/obsidian
docker exec basic-memory-server basic-memory project create obsidian /app/data
# Set as default
docker exec basic-memory-server basic-memory project set-default obsidian
@@ -211,8 +242,8 @@ docker-compose logs -f basic-memory
## Security Considerations
1. **Use Non-Root User:**
The default Dockerfile runs as root. Consider creating a custom Dockerfile with a non-root user for production.
1. **Docker Security:**
The container runs as root for simplicity. For production, consider additional security measures.
2. **Volume Permissions:**
Ensure mounted directories have appropriate permissions and don't expose sensitive data.
@@ -221,7 +252,7 @@ docker-compose logs -f basic-memory
If using HTTP transport, consider using reverse proxy with SSL/TLS and authentication if the endpoint is available on
a network.
4. **IMPORTANT:** the https have no auhorization. They should not be exposed on a public network.
4. **IMPORTANT:** The HTTP endpoints have no authorization. They should not be exposed on a public network.
## Integration Examples
@@ -260,4 +291,55 @@ For Docker-specific issues:
4. Test file permissions: `docker exec basic-memory-server ls -la /root`
For general Basic Memory support, see the main [README](../README.md)
and [documentation](https://memory.basicmachines.co/).
and [documentation](https://memory.basicmachines.co/).
## Docker Hub Images
### Available Images
Pre-built Docker images are available on Docker Hub at [`basicmachines/basic-memory`](https://hub.docker.com/r/basicmachines/basic-memory).
**Supported architectures:**
- `linux/amd64` (Intel/AMD x64)
- `linux/arm64` (ARM64, including Apple Silicon)
**Available tags:**
- `latest` - Latest stable release
- `v0.13.8`, `v0.13.7`, etc. - Specific version tags
- `v0.13`, `v0.12`, etc. - Major.minor tags
### Automated Builds
Docker images are automatically built and published when new releases are tagged:
1. **Release Process:** When a git tag matching `v*` (e.g., `v0.13.8`) is pushed, the CI workflow automatically:
- Builds multi-platform Docker images
- Pushes to Docker Hub with appropriate tags
- Updates the Docker Hub repository description
2. **CI/CD Pipeline:** The Docker workflow includes:
- Multi-platform builds (AMD64 and ARM64)
- Layer caching for faster builds
- Automatic tagging with semantic versioning
- Security scanning and optimization
### Setup Requirements (For Maintainers)
To set up Docker Hub integration for this repository:
1. **Create Docker Hub Repository:**
- Repository name: `basicmachines/basic-memory`
- Set as public repository
2. **Configure GitHub Secrets:**
```
DOCKER_USERNAME - Docker Hub username
DOCKER_PASSWORD - Docker Hub access token (not password)
```
3. **Generate Docker Hub Access Token:**
- Go to Docker Hub → Account Settings → Security
- Create new access token with Read/Write permissions
- Use this token as `DOCKER_PASSWORD` secret
The Docker CI workflow (`.github/workflows/docker.yml`) will automatically handle the rest.