Docker Support for iHub Apps

This document provides comprehensive guidance for running iHub Apps in Docker containers for both development and production environments.

Quickstart (Zero-config)

The fastest way to try iHub Apps — no .env file, no pre-configuration required:

docker compose -f docker-compose.quickstart.yml up

Then open http://localhost:3000 and navigate to Admin → Configuration to add your LLM API keys via the browser UI.

This uses the pre-built image from the registry and mounts a local ./contents/ folder so your configuration persists between restarts. Nothing else is needed to get started.

Available Images

Images are published to two registries:

Registry	Image
GitHub Container Registry	`ghcr.io/intrafind/ihub-apps:latest`
Docker Hub	`intrafind/ihub-apps:latest`

# Pull from GHCR
docker pull ghcr.io/intrafind/ihub-apps:latest

# Pull from Docker Hub
docker pull intrafind/ihub-apps:latest

Quick Start

Development Environment (Automatic Local Contents)

The Docker development setup automatically uses your local contents/ folder - no additional configuration needed!

Copy environment file:

cp .env.example .env
# Edit .env with your API keys and configuration

Start development with automatic local contents:
```
npm run docker:up
```
This automatically:
- ✅ Mounts your entire local contents/ folder into the container
- ✅ Any changes to files in contents/ appear immediately in the container
- ✅ No rebuilding or restarting required for content changes
- ✅ Edit configs, apps, models, pages directly on your machine
Access the application:
- Main app: http://localhost:3000 (Node.js server + static files)
- Vite dev server: http://localhost:5173 (Hot reload development server)
In development, both the Node.js server and Vite dev server run simultaneously for the best development experience.

Volume Strategy:

Local contents: Your entire contents/ folder is mounted read-write
Persistent data: contents/data/, contents/uploads/, and logs use Docker volumes for persistence
Best of both: Edit configs locally, keep runtime data persistent

Production Environment

Prepare production environment:

cp .env.production .env.production
# Configure with production secrets (use secrets management in real deployment)

Build and start production:

npm run docker:build:prod
npm run docker:prod:up

Access the production application:
- Main app: http://localhost:3000 (Node.js server with built client)
In production, the Node.js server serves the pre-built client files directly.

Building Docker Images Locally

Quick Build Commands

# Build development image locally
npm run docker:build:dev

# Build production image locally
npm run docker:build:prod

# Build and start development environment
npm run docker:up:build

Manual Docker Build Commands

# Development build
docker build -f docker/Dockerfile -t ihub-apps:dev --target development .

# Production build
docker build -f docker/Dockerfile -t ihub-apps:prod --target production .

# Multi-platform build (requires Docker Buildx)
docker buildx build -f docker/Dockerfile --platform linux/amd64,linux/arm64 -t ihub-apps:multi .

Build Process Explained

The Docker build process uses multi-stage builds:

Base Stage: Sets up Node.js environment and creates non-root user
Dependencies Stage: Installs npm dependencies with caching
Development Stage: Includes dev dependencies and source code mounting
Production Stage: Optimized build with only production dependencies

Build Arguments

# Build with custom arguments
docker build -f docker/Dockerfile \
  --build-arg BUILDTIME="$(date -u +'%Y-%m-%dT%H:%M:%SZ')" \
  --build-arg VERSION="1.0.0" \
  --build-arg REVISION="$(git rev-parse HEAD)" \
  -t ihub-apps:custom .

Build Verification

# Test development build
docker run --rm -p 3000:3000 -p 5173:5173 \
  -v $(pwd)/contents:/app/contents \
  -e JWT_SECRET=test-secret \
  ihub-apps:dev

# Test production build (serves built client + API on port 3000)
docker run --rm -p 3000:3000 \
  -v $(pwd)/contents:/app/contents \
  -e JWT_SECRET=test-secret \
  -e NODE_ENV=production \
  ihub-apps:prod

# Check image details
docker image inspect ihub-apps:prod

Expected behavior:

Development: Both Node.js server (3000) and Vite dev server (5173) should start
Production: Only Node.js server (3000) should start, serving the built client files

Docker Commands Reference

Running Containers


### Development Workflow

```bash
# Start development environment
npm run docker:up

# Start with rebuilding images
npm run docker:up:build

# View logs
npm run docker:logs

# Access container shell
npm run docker:shell

# Stop development environment
npm run docker:down

# Stop and remove volumes
npm run docker:down:volumes

Production Deployment

# Start production environment
npm run docker:prod:up

# View production logs
npm run docker:prod:logs

# Access production container shell
npm run docker:prod:shell

# Stop production environment
npm run docker:prod:down

CI/CD and Image Publishing

Automated Docker Builds

Docker images are automatically built and published to both GitHub Container Registry (ghcr.io) and Docker Hub in the following scenarios:

On Release Creation: When you create a GitHub release
On Version Tags: When you push a tag starting with v (e.g., v1.0.0)
Manual Trigger: Comment @build docker images on any issue or PR
Manual Workflow: Use GitHub Actions "Run workflow" button

Manual Build Trigger

To manually trigger a Docker build, comment on any GitHub issue or pull request:

@build docker images

This will automatically start the CI/CD pipeline and publish new images to the registry.

Published Images

Images are published to both GitHub Container Registry (GHCR) and Docker Hub:

GitHub Container Registry:

ghcr.io/intrafind/ihub-apps:latest
ghcr.io/intrafind/ihub-apps:v1.0.0
ghcr.io/intrafind/ihub-apps:main

Docker Hub:

intrafind/ihub-apps:latest
intrafind/ihub-apps:v1.0.0

Using Published Images

# Quickstart — zero-config, configure via admin UI after startup
docker compose -f docker-compose.quickstart.yml up

# Run directly with Docker (GHCR)
# Note: JWT_SECRET is optional - auto-generated if not provided
docker run -p 3000:3000 \
  -v $(pwd)/contents:/app/contents \
  ghcr.io/intrafind/ihub-apps:latest

# Run directly with Docker (Docker Hub)
docker run -p 3000:3000 \
  -v $(pwd)/contents:/app/contents \
  intrafind/ihub-apps:latest

# Use specific version with custom JWT secret
docker run -p 3000:3000 \
  -v $(pwd)/contents:/app/contents \
  -e JWT_SECRET=your-secret \
  ghcr.io/intrafind/ihub-apps:v1.0.0

Maintenance Commands

# Clean up unused Docker resources
npm run docker:clean

# Clean up everything (be careful!)
npm run docker:clean:all

# Run tests in container
npm run docker:test

Volume Structure

Development Volumes

Source Code: Bind mounted for hot reloading
Configuration: Bind mounted for easy editing
Data: Docker volumes for persistence
Node Modules: Cached volumes for performance

Production Volumes

Contents: Single named volume (ihub-contents) mounted read-write at /app/contents — config, apps, models, prompts, locales, pages, sources, data, and uploads all live here. Seeded from the image's bundled defaults on first boot when empty (same performInitialSetup logic as the quickstart/dev setups), and written to at runtime by config migrations and admin-UI saves.
Logs: Separate persistent volume (ihub-logs) for application logs

Environment Configuration

Required Environment Variables

# LLM API Keys (at least one required for AI functionality)
OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key
GOOGLE_API_KEY=your-google-key
MISTRAL_API_KEY=your-mistral-key

Optional Environment Variables

# Security Configuration
# JWT_SECRET: Auto-generated and persisted if not set
# Only required for multi-node deployments to share the same secret
JWT_SECRET=your-secure-jwt-secret

# Admin Configuration
ADMIN_SECRET=your-admin-secret

Optional Services

PostgreSQL Database

# Enable PostgreSQL service
docker-compose --profile database up -d

# Environment variables
DB_HOST=ihub-db
DB_NAME=ihub
DB_USER=ihub
DB_PASSWORD=your-db-password

Redis Cache

# Enable Redis service
docker-compose --profile cache up -d

# Environment variables
REDIS_HOST=ihub-redis
REDIS_PASSWORD=your-redis-password

Nginx Reverse Proxy

# Enable Nginx for development
docker-compose --profile nginx up -d

# Access via proxy
http://localhost:8080

Security Considerations

Container Security

Non-root user: Containers run as UID 1000
Read-only filesystem: Root filesystem is read-only
No privileged access: Containers drop all capabilities
Resource limits: CPU and memory limits enforced

Data Security

Volume encryption: Use encrypted volumes in production
Secret management: Never store secrets in images
Network isolation: Use Docker networks for service isolation
Regular updates: Keep base images updated

Production Security Checklist

Use secrets management system (not .env files)
Enable HTTPS with valid certificates
Configure proper CORS settings
Enable rate limiting and security headers
Use read-only volumes where possible
Implement proper backup strategy
Monitor and log security events

Networking

Development Network

Bridge network: ihub-network
Port mappings: 3000 (app), 5173 (vite), 5432 (postgres), 6379 (redis)
Service discovery: Containers communicate by service name

Production Network

Isolated network: ihub-prod-network
External access: Only through reverse proxy
Internal communication: Services communicate privately
Load balancing: Multiple app replicas supported

Monitoring and Logging

Health Checks

Application: http://localhost:3000/api/health
Container: Built-in Docker health checks
Dependencies: PostgreSQL and Redis health checks

Logging

# View all logs
docker-compose logs -f

# View specific service logs
docker-compose logs -f ihub-dev

# Production logs with rotation
docker-compose -f docker-compose.prod.yml logs -f

Metrics

Prometheus metrics: Available at /api/metrics
Container metrics: Docker stats and cAdvisor
Custom dashboards: Grafana configurations available

Data Management

Backup Procedures

# Backup the whole contents/ volume (config, apps, models, prompts, data, uploads, ...)
docker run --rm -v ihub-contents:/data -v $(pwd)/backups:/backup alpine tar czf /backup/contents-$(date +%Y%m%d).tar.gz -C /data .

# Backup database (if using PostgreSQL)
docker-compose exec ihub-db pg_dump -U ihub ihub > backup-$(date +%Y%m%d).sql

Migration from Non-Docker

# 1. Stop current application
npm run server:stop

# 2. Backup current contents (optional, belt-and-suspenders)
cp -r contents contents.backup

# 3. Create the Docker volume
docker volume create ihub-contents

# 4. Copy contents/ into the volume
docker run --rm -v $(pwd)/contents:/source -v ihub-contents:/dest alpine cp -r /source/* /dest/

# 5. Start Docker environment
npm run docker:up

Troubleshooting

Common Issues

Container fails to start

# Check logs
docker-compose logs ihub-dev

# Check if required environment variables are set
docker-compose config

# Verify image exists
docker images | grep ihub-apps

Permission issues

# Fix volume permissions
docker-compose exec ihub-dev chown -R ihub:nodejs /app/contents /app/logs

# Check user inside container
docker-compose exec ihub-dev id

Port conflicts

# Check what's using the port
lsof -i :3000

# Use different ports
AI_HUB_PORT=3001 docker-compose up -d

Volume data not persisting

# List volumes
docker volume ls

# Inspect volume
docker volume inspect ihub-data

# Check mount points
docker-compose exec ihub-dev df -h

Performance Optimization

Build Optimization

# Use BuildKit for faster builds
DOCKER_BUILDKIT=1 docker build -t ihub-apps:latest .

# Use multi-stage caching
docker build --target production --cache-from ihub-apps:latest -t ihub-apps:latest .

Runtime Optimization

# Adjust resource limits in docker-compose.yml
deploy:
  resources:
    limits:
      cpus: '2.0'
      memory: 2G

CI/CD Integration

GitHub Actions

The repository includes a comprehensive GitHub Actions workflow that:

Builds multi-platform Docker images
Runs security scans with Trivy
Publishes to GitHub Container Registry
Supports automated deployments

Manual Registry Push

# Tag and push to GHCR
docker tag ihub-apps:latest ghcr.io/intrafind/ihub-apps:latest
docker push ghcr.io/intrafind/ihub-apps:latest

# Tag and push to Docker Hub
docker tag ihub-apps:latest intrafind/ihub-apps:latest
docker push intrafind/ihub-apps:latest

# Pull from either registry
docker pull ghcr.io/intrafind/ihub-apps:latest
docker pull intrafind/ihub-apps:latest

Advanced Configuration

Custom Dockerfile

For customized deployments, you can extend the base Dockerfile:

FROM ghcr.io/intrafind/ihub-apps:latest

# Add custom certificates
COPY custom-ca.crt /usr/local/share/ca-certificates/
RUN update-ca-certificates

# Add custom configuration
COPY custom-config/ /app/contents/config/

USER ihub

Kubernetes Deployment

For Kubernetes deployments, see the concepts/docker-support/ directory for comprehensive Kubernetes manifests and Helm charts.

Docker Swarm

# Initialize swarm
docker swarm init

# Deploy stack
docker stack deploy -c docker-compose.prod.yml ihub-apps

# Scale services
docker service scale ihub-apps_ihub-app=3

Support and Resources

Documentation: See docs/ directory for comprehensive guides
Examples: Check examples/ for sample configurations
Issues: Report Docker-related issues on GitHub
Security: Follow security best practices in production

For more detailed information, refer to the specifications in concepts/docker-support/.

Uh oh!

FilesExpand file tree

DOCKER.md

Latest commit

History