brainy/docs/quick-start-docker.md

Docker Quick Start Guide

Get Brainy running in Docker in under 5 minutes with embedded models for maximum performance.

🚀 Fastest Start (3 Steps)

Step 1: Install Models

npm install @soulcraft/brainy-models

Step 2: Create Dockerfile

FROM node:24-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run extract-models  # ← Magic happens here
RUN npm run build

FROM node:24-alpine AS production
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production --omit=optional
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/models ./models  # ← Models embedded
ENV PORT=3000
EXPOSE 3000
CMD ["node", "dist/server.js"]

Step 3: Build & Run

docker build -t brainy-app .
docker run -p 3000:3000 brainy-app

Done! Your app starts in ~2 seconds with embedded models.

📱 Sample Application

Create server.js:

import express from 'express'
import { BrainyData } from '@soulcraft/brainy'

const app = express()
const port = process.env.PORT || 3000

// Initialize Brainy (models auto-detected from ./models)
const brainy = new BrainyData()
await brainy.init()

app.use(express.json())

// Health check
app.get('/health', (req, res) => {
  res.json({ status: 'healthy', timestamp: new Date().toISOString() })
})

// Add data
app.post('/add', async (req, res) => {
  try {
    const { content, metadata } = req.body
    const id = await brainy.add({ content, ...metadata })
    res.json({ id, message: 'Added successfully' })
  } catch (error) {
    res.status(400).json({ error: error.message })
  }
})

// Search
app.post('/search', async (req, res) => {
  try {
    const { query, limit = 10 } = req.body
    const results = await brainy.search(query, limit)
    res.json({ results, count: results.length })
  } catch (error) {
    res.status(400).json({ error: error.message })
  }
})

app.listen(port, () => {
  console.log(`🧠 Brainy server running on port ${port}`)
  console.log(`📊 Database: ${brainy.getStatistics().totalVectors} vectors loaded`)
})

Package.json dependencies:

{
  "dependencies": {
    "@soulcraft/brainy": "latest",
    "@soulcraft/brainy-models": "latest",
    "express": "^4.18.0"
  },
  "type": "module"
}

☁️ Deploy to Cloud

Google Cloud Run

gcloud run deploy brainy-app \
  --source . \
  --platform managed \
  --region us-central1 \
  --memory 2Gi \
  --allow-unauthenticated

AWS ECS (via ECR)

# Build and push
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin $ECR_URI
docker build -t brainy-app .
docker tag brainy-app:latest $ECR_URI:latest
docker push $ECR_URI:latest

# Deploy
aws ecs create-service \
  --cluster brainy-cluster \
  --service-name brainy-service \
  --task-definition brainy-task \
  --desired-count 1

Azure Container Instances

# Build and push to ACR
az acr build --registry myregistry --image brainy-app .

# Deploy
az container create \
  --resource-group myResourceGroup \
  --name brainy-container \
  --image myregistry.azurecr.io/brainy-app:latest \
  --cpu 1 \
  --memory 2 \
  --ports 3000

🧪 Test Your Deployment

# Health check
curl http://localhost:3000/health

# Add some data
curl -X POST http://localhost:3000/add \
  -H "Content-Type: application/json" \
  -d '{"content": "Cats are amazing pets", "category": "animals"}'

curl -X POST http://localhost:3000/add \
  -H "Content-Type: application/json" \
  -d '{"content": "Dogs are loyal companions", "category": "animals"}'

# Search by meaning
curl -X POST http://localhost:3000/search \
  -H "Content-Type: application/json" \
  -d '{"query": "pet animals", "limit": 5}'

Expected response:

{
  "results": [
    {
      "id": "uuid-1",
      "content": "Cats are amazing pets",
      "similarity": 0.89,
      "metadata": {"category": "animals"}
    },
    {
      "id": "uuid-2", 
      "content": "Dogs are loyal companions",
      "similarity": 0.86,
      "metadata": {"category": "animals"}
    }
  ],
  "count": 2
}

🔍 Verify Model Embedding

Check your Docker logs for these success messages:

✅ Build time (what you want to see):

[Brainy Model Extractor] ✅ Found @soulcraft/brainy-models package
[Brainy Model Extractor] 📦 Creating models directory...
[Brainy Model Extractor] ✅ Models extracted successfully!

✅ Runtime (what you want to see):

🎯 Auto-detected extracted models at: /app/models
✅ Successfully loaded model from custom directory
   Using custom model path for Docker/production deployment
🧠 Brainy server running on port 3000

❌ If models not found:

⚠️ Local model not found. Falling back to remote model loading.

If you see the warning, check:

1. @soulcraft/brainy-models is in package.json dependencies
2. RUN npm run extract-models is in your Dockerfile
3. COPY --from=builder /app/models ./models is present

🚨 Troubleshooting

Container Won't Start

• Increase memory: Add --memory 2g to docker run
• Check port: Ensure PORT environment variable is set
• Verify models: docker run -it your-image ls -la /app/models

Slow Startup (15+ seconds)

• Models not embedded properly
• Check build logs for extraction success
• Verify /app/models directory exists in container

Memory Issues

• Brainy + models need ~2GB RAM
• Use multi-stage build to minimize final image size
• Consider using compressed models for memory-constrained environments

🎯 Next Steps

• Production Setup: See docs/docker-deployment.md for advanced configurations
• Scaling: Learn about distributed mode with multiple instances
• Monitoring: Add metrics and logging for production monitoring
• Security: Implement authentication and rate limiting

💡 Pro Tips

1. Layer Caching: Put npm run extract-models after dependency installation for better Docker layer caching
2. Security: Always run as non-root user in production
3. Health Checks: Include health check endpoint for load balancers
4. Graceful Shutdown: Handle SIGTERM for clean container stops
5. Resource Limits: Set memory limits to prevent OOM kills

That's it! You now have a production-ready Brainy application running in Docker with embedded models for maximum performance and reliability. 🎉