ExcaliDash/DOCKER.md

ExcaliDash Docker Setup

This Docker setup containerizes the ExcaliDash application with a multi-container architecture.

Architecture

• Frontend: React/Vite app served by Nginx
• Backend: Express.js API with Socket.IO
• Database: SQLite (persisted in Docker volume)

Single Port Exposure

The application exposes only port 6767 externally, which serves the frontend. The frontend's Nginx acts as a reverse proxy to route:

• /api/* requests to the backend container
• /socket.io/* WebSocket connections to the backend container

All inter-container communication happens on an internal Docker network.

Quick Start

Option 1: Use Pre-built Images from Docker Hub (Recommended)

Pull and run the latest multi-platform images:

docker compose -f docker-compose.prod.yml up -d

Option 2: Build Locally

Build and run all services locally:

docker compose up -d --build

Access the application:

Open your browser to http://localhost:6767

Publishing to Docker Hub

Build and Push Multi-Platform Images

The publish-docker.sh script builds images for multiple platforms (amd64, arm64) and pushes them to Docker Hub:

# Build and push with 'latest' tag
./publish-docker.sh

# Build and push with a specific version
./publish-docker.sh v1.0.0

Prerequisites:

• Docker Buildx enabled
• Logged in to Docker Hub: docker login

Platforms supported:

• linux/amd64 (Intel/AMD x86_64)
• linux/arm64 (Apple Silicon, ARM servers)

The script will:

1. Create a buildx builder if needed
2. Build both frontend and backend images for all platforms
3. Push to zimengxiong/excalidash-backend and zimengxiong/excalidash-frontend
4. Tag with both the specified version and latest

Management Commands

View logs:

# All services
docker compose logs -f

# Specific service
docker compose logs -f backend
docker compose logs -f frontend

Stop services:

docker compose down

Stop and remove volumes (clean slate):

docker compose down -v

Restart services:

docker compose restart

Check service status:

docker compose ps

Development

For local development outside Docker, use the existing npm scripts:

Backend:

cd backend
npm install
npm run dev

Frontend:

cd frontend
npm install
npm run dev

Database

The SQLite database is stored in a Docker volume named backend-data which persists data across container restarts. Database migrations run automatically when the backend container starts.

Environment Variables

Default configuration works out of the box. To customize:

Create .env files in backend/ or frontend/ directories:

Backend .env:

PORT=8000
NODE_ENV=production

Frontend .env:

VITE_API_URL=/api

Troubleshooting

Check health status:

docker-compose ps

Both services should show "healthy" status.

Reset database:

docker-compose down -v
docker-compose up -d

View detailed backend logs:

docker-compose logs backend

Rebuild specific service:

docker-compose up -d --build backend

Production Deployment

For production deployment:

1. Use proper environment variables
2. Configure proper CORS settings in the backend
3. Add HTTPS/TLS termination (e.g., via reverse proxy like Traefik or nginx)
4. Consider using PostgreSQL instead of SQLite for better concurrency
5. Set up proper backup strategy for the backend-data volume

Port Mapping

• 6767 (external) → 80 (frontend nginx) → Routes to backend on internal network
• 8000 (internal only) - Backend API server

Only port 6767 is accessible from outside the Docker network.