Keep/keep-notes/DOCKER_DEPLOYMENT.md

🐳 Docker Deployment Guide for Proxmox

Complete guide to deploy Keep Notes on Proxmox using Docker Compose.

📋 Prerequisites

On Your Proxmox Host:

• Proxmox VE 7.x or 8.x
• Docker and Docker Compose installed
• At least 2GB RAM available (4GB+ recommended for AI features)
• 10GB disk space available

Optional for AI Features:

• For OpenAI: Valid API key
• For Ollama (Local AI): 8GB+ RAM, 4+ CPU cores recommended

🚀 Quick Start

1. Prepare Environment Files

Create a .env file in the keep-notes directory:

cd /path/to/keep-notes
cat > .env << 'EOF'
# Required: Generate a random secret
NEXTAUTH_SECRET=$(openssl rand -base64 32)
NEXTAUTH_URL=http://your-domain.com:3000

# Optional: OpenAI API Key
# OPENAI_API_KEY=sk-your-key-here

# Optional: Ollama Configuration (if using local AI)
# OLLAMA_BASE_URL=http://ollama:11434
# OLLAMA_MODEL=granite4:latest

# Optional: Custom Session Max Age (in seconds)
NEXTAUTH_SESSION_MAX_AGE=604800
EOF

2. Build and Start Containers

# Build the Docker image
docker-compose build

# Start the application
docker-compose up -d

# View logs
docker-compose logs -f keep-notes

3. Access the Application

Open your browser and navigate to:

• http://YOUR_PROXMOX_IP:3000

🔧 Configuration Options

Without Reverse Proxy (Basic)

Edit docker-compose.yml:

environment:
  - NEXTAUTH_URL=http://your-ip:3000
  - NEXTAUTH_SECRET=your-random-secret
ports:
  - "3000:3000"

With Nginx Reverse Proxy (Recommended)

1. Create Nginx Configuration

# /etc/nginx/conf.d/keep-notes.conf
server {
    listen 80;
    server_name notes.yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Max upload size for images
    client_max_body_size 10M;
}

2. Update docker-compose.yml

environment:
  - NEXTAUTH_URL=https://notes.yourdomain.com

3. Restart Container

docker-compose down
docker-compose up -d

With SSL/HTTPS (Let's Encrypt)

# Install certbot
apt install certbot python3-certbot-nginx

# Get certificate
certbot --nginx -d notes.yourdomain.com

# Auto-renewal (cron)
echo "0 0,12 * * * root certbot renew --quiet" | tee /etc/cron.d/certbot-renew

🤖 AI Features Setup

Option 1: OpenAI (Cloud)

1. Get API key from https://platform.openai.com/api-keys
2. Add to .env:

   OPENAI_API_KEY=sk-your-key-here
   

3. Restart: docker-compose restart

Option 2: Ollama (Local AI)

1. Enable Ollama in docker-compose.yml

Uncomment the ollama service section in docker-compose.yml:

ollama:
  image: ollama/ollama:latest
  container_name: keep-ollama
  restart: unless-stopped
  ports:
    - "11434:11434"
  volumes:
    - ollama-data:/root/.ollama
  networks:
    - keep-network

Uncomment volume:

volumes:
  ollama-data:
    driver: local

2. Add Environment Variables

keep-notes:
  environment:
    - OLLAMA_BASE_URL=http://ollama:11434
    - OLLAMA_MODEL=granite4:latest

3. Start and Pull Model

docker-compose up -d
docker-compose exec -it ollama ollama pull granite4

Option 3: Custom OpenAI-compatible API

If you have a custom API (like LocalAI, LM Studio, etc.):

# Add to .env or docker-compose.yml
OPENAI_API_BASE_URL=http://your-api-host:port/v1
OPENAI_API_KEY=any-key-here

📊 Resource Recommendations

Minimal Setup (Without AI)

• CPU: 1 core
• RAM: 512MB
• Disk: 5GB

Recommended Setup (With OpenAI)

• CPU: 1-2 cores
• RAM: 1-2GB
• Disk: 10GB

AI Setup (With Ollama)

• CPU: 4+ cores
• RAM: 8GB+
• Disk: 20GB+

🗄️ Database Backup

Backup SQLite Database

# Create backup script
cat > /path/to/backup-keep.sh << 'EOF'
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/path/to/backups"
CONTAINER_NAME="keep-notes"

# Create backup directory
mkdir -p $BACKUP_DIR

# Backup database
docker exec $CONTAINER_NAME \
  cp /app/prisma/dev.db /app/prisma/backup_$DATE.db

# Copy from container to host
docker cp $CONTAINER_NAME:/app/prisma/backup_$DATE.db \
  $BACKUP_DIR/keep-notes_$DATE.db

# Keep last 7 days
find $BACKUP_DIR -name "keep-notes_*.db" -mtime +7 -delete

echo "Backup completed: keep-notes_$DATE.db"
EOF

chmod +x /path/to/backup-keep.sh

# Add to crontab (daily backup at 2 AM)
crontab -e
# Add: 0 2 * * * /path/to/backup-keep.sh

Restore Database

# Stop container
docker-compose down

# Restore database
cp /path/to/backups/keep-notes_YYYYMMDD_HHMMSS.db \
  keep-notes/prisma/dev.db

# Start container
docker-compose up -d

🔄 Updating the Application

# Pull latest changes
git pull

# Rebuild image
docker-compose build

# Restart with new image
docker-compose down
docker-compose up -d

# Clean up old images
docker image prune -a -f

🐛 Troubleshooting

Container Won't Start

# Check logs
docker-compose logs keep-notes

# Check container status
docker-compose ps

# Enter container for debugging
docker-compose exec keep-notes sh

Database Errors

# Fix database permissions
docker-compose exec keep-notes \
  chown -R nextjs:nodejs /app/prisma

# Regenerate Prisma client
docker-compose exec keep-notes \
  npx prisma generate

# Run migrations
docker-compose exec keep-notes \
  npx prisma migrate deploy

AI Features Not Working

# Check Ollama status
docker-compose logs ollama

# Test Ollama connection
docker-compose exec keep-notes \
  curl http://ollama:11434/api/tags

# Check environment variables
docker-compose exec keep-notes env | grep -E "OLLAMA|OPENAI"

Performance Issues

# Check resource usage
docker stats keep-notes

# Increase resources in docker-compose.yml
deploy:
  resources:
    limits:
      cpus: '4'
      memory: 4G

🔒 Security Best Practices

1. Change NEXTAUTH_SECRET: Never use the default value
2. Use HTTPS: Always use SSL in production
3. Limit Resources: Prevent container from using all system resources
4. Regular Updates: Keep Docker image and dependencies updated
5. Backups: Set up automated database backups
6. Firewall: Only expose necessary ports (3000 or reverse proxy port)

📱 Proxmox LXC Container Setup

Create LXC Container (Recommended)

# In Proxmox shell
pveam available
pveam update

# Create Ubuntu 22.04 container
pct create 999 local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst \
  --hostname keep-notes \
  --storage local-lvm \
  --cores 2 \
  --memory 2048 \
  --swap 512 \
  --net0 name=eth0,bridge=vmbr0,ip=dhcp

# Start container
pct start 999

# Enter container
pct enter 999

# Install Docker inside LXC
apt update && apt upgrade -y
apt install -y curl git
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh
usermod -aG docker ubuntu

# Enable nested containerization for LXC
# Edit /etc/pve/lxc/999.conf on Proxmox host
# Add: features: nesting=1,keyctl=1

Then deploy Keep Notes as described above.

📚 Additional Resources

• Next.js Deployment
• Docker Compose Reference
• Prisma Docker Guide
• Proxmox LXC Documentation

💡 Tips

1. Use Volumes: Always use Docker volumes for persistent data
2. Health Checks: Enable health checks for auto-restart
3. Log Rotation: Prevent disk filling with logs
4. Monitoring: Use Portainer or similar for easy management
5. Testing: Test in staging environment before production

---

Need Help? Check the main README or open an issue on GitHub.