claude-os/SHARING.md at bf1277182c51a855464d37bac297f467f2644de0

SheWhoReignsSupreme/claude-os

Fork 0

Bob Roberts 8e5a46aa59 first commit

2025-10-22 13:29:28 -05:00

7.1 KiB

Raw Blame History

This guide explains how to share Code-Forge with coworkers so they can run it on their own machines.

📦 What Your Coworker Needs

Prerequisites

Docker Desktop (includes Docker Compose)
Git (to clone the repository)
- Mac: Pre-installed or via Homebrew: brew install git
- Windows: https://git-scm.com/download/win
- Linux: sudo apt install git or sudo yum install git

That's it! No Python, Node.js, or other dependencies needed - Docker handles everything.

🎯 Quick Start for Your Coworker

If you have a private Git repo:

Push your code to the repo:

git add .
git commit -m "Add Code-Forge RAG system"
git push origin main

Share the repo URL with your coworker

Your coworker clones and runs:

# Clone the repository
git clone <your-repo-url>
cd code-forge

# Start the system
docker compose up -d

# Pull Ollama models (one-time setup)
docker compose exec ollama ollama pull nomic-embed-text
docker compose exec ollama ollama pull llama3.1

Access the UI:
- Open browser: http://localhost:8501
- Done! 🎉

If you don't have a Git repo:

Create a ZIP of your project:

cd /Users/iamanmp/Projects
zip -r code-forge.zip code-forge \
  -x "code-forge/data/*" \
  -x "code-forge/.git/*" \
  -x "code-forge/__pycache__/*" \
  -x "code-forge/**/__pycache__/*"

Share code-forge.zip via:
- Email (if < 25MB)
- Google Drive / Dropbox / OneDrive
- Slack / Teams file sharing

Your coworker extracts and runs:

# Extract the ZIP
unzip code-forge.zip
cd code-forge

# Start the system
docker compose up -d

# Pull Ollama models (one-time setup)
docker compose exec ollama ollama pull nomic-embed-text
docker compose exec ollama ollama pull llama3.1

🔧 What Gets Shared vs. What Doesn't

✅ Shared (in the repository/ZIP)

All source code (app/, mcp_server/, etc.)
Configuration files (docker-compose.yml, Dockerfile, etc.)
Requirements (requirements.txt)
Styling (.streamlit/config.toml)

❌ NOT Shared (stays local)

Ollama models (~5GB) - Each person downloads their own
ChromaDB data (knowledge bases) - Each person creates their own
Uploaded files - Each person uploads their own documents
Docker volumes - Created fresh on each machine

Option A: Export/Import Knowledge Bases

Currently, knowledge bases are stored in Docker volumes. To share them:

Export ChromaDB data:

# Create a backup directory
mkdir -p backups

# Copy ChromaDB data from Docker volume
docker compose cp chromadb:/chroma/chroma ./backups/chroma_data

Share the backup:

Add backups/ to your ZIP or Git repo

Your coworker copies it to their ChromaDB volume:

docker compose up -d chromadb
docker compose cp ./backups/chroma_data chromadb:/chroma/chroma
docker compose restart chromadb app

Option B: Share Original Documents

Simpler approach:

Create a shared_docs/ folder in the repo
Add your markdown/PDF files there
Your coworker uploads them via the UI or directory import

If you want your coworker to access your running instance instead of running their own:

1. Find Your Local IP Address

Mac/Linux:

ifconfig | grep "inet " | grep -v 127.0.0.1

Windows:

ipconfig

Look for something like 192.168.1.100

2. Update docker-compose.yml

Change the ports to bind to all interfaces:

services:
  app:
    ports:
      - "0.0.0.0:8501:8501"  # Streamlit UI
      - "0.0.0.0:8051:8051"  # MCP Server

3. Restart the containers

docker compose down
docker compose up -d

Your coworker can access:

UI: http://<your-ip>:8501
MCP: http://<your-ip>:8051/mcp

⚠️ Security Note: This exposes your instance to your local network. Only do this on trusted networks (office LAN, VPN). For internet sharing, use a reverse proxy with authentication.

🔐 Security Considerations

✅ Safe - Everything runs locally
✅ No authentication needed
✅ Data stays on the machine

⚠️ Use only on trusted networks
⚠️ No built-in authentication
⚠️ Anyone on the network can access

❌ NOT RECOMMENDED without additional security
If needed, use:
- Reverse proxy (nginx, Caddy)
- Authentication (OAuth, basic auth)
- HTTPS/SSL certificates
- Firewall rules

🐛 Troubleshooting for Your Coworker

"Docker command not found"

Install Docker Desktop: https://www.docker.com/products/docker-desktop/

"Port 8501 already in use"

Another app is using that port

Change ports in docker-compose.yml:

ports:
  - "8502:8501"  # Use 8502 instead

"Ollama models not found"

They forgot to pull the models:

docker compose exec ollama ollama pull nomic-embed-text
docker compose exec ollama ollama pull llama3.1

"ChromaDB connection error"

Wait 10 seconds for services to start
Check status: docker compose ps
Restart: docker compose restart

"Out of disk space"

Ollama models are ~5GB
Docker images are ~2GB
Free up space or use external drive

📝 Quick Reference Commands

# Start everything
docker compose up -d

# Stop everything
docker compose down

# View logs
docker compose logs -f app

# Restart a service
docker compose restart app

# Check status
docker compose ps

# Pull Ollama models
docker compose exec ollama ollama pull nomic-embed-text
docker compose exec ollama ollama pull llama3.1

# Access Ollama shell
docker compose exec ollama bash

🎓 What Your Coworker Should Know

First startup takes 5-10 minutes (downloading models)
Subsequent startups take ~10 seconds
Each person has their own knowledge bases (unless you share ChromaDB data)
Models run locally - no API keys or internet needed after setup
Everything is containerized - won't mess up their system

📞 Support

If your coworker has issues:

Check the troubleshooting section above
Run docker compose logs -f to see errors
Verify Docker Desktop is running
Try docker compose down && docker compose up -d (restart)

🚀 Next Steps

After your coworker gets it running:

Create a knowledge base
Upload some documents
Try the chat interface
Experiment with RAG strategies (Hybrid, Reranking, Agentic)
Connect Claude Desktop via MCP (optional)

Enjoy! 🎉

7.1 KiB Raw Blame History

🚀 Sharing Code-Forge with Your Team