Dockerize

DOCKER.md

@@ -0,0 +1,197 @@
+# 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:
+
+```bash
+docker compose -f docker-compose.prod.yml up -d
+```
+
+### Option 2: Build Locally
+
+Build and run all services locally:
+
+```bash
+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:
+
+```bash
+# 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:
+
+```bash
+# All services
+docker compose logs -f
+
+# Specific service
+docker compose logs -f backend
+docker compose logs -f frontend
+```
+
+### Stop services:
+
+```bash
+docker compose down
+```
+
+### Stop and remove volumes (clean slate):
+
+```bash
+docker compose down -v
+```
+
+### Restart services:
+
+```bash
+docker compose restart
+```
+
+### Check service status:
+
+```bash
+docker compose ps
+```
+
+## Development
+
+For local development outside Docker, use the existing npm scripts:
+
+**Backend:**
+
+```bash
+cd backend
+npm install
+npm run dev
+```
+
+**Frontend:**
+
+```bash
+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:
+
+```bash
+docker-compose ps
+```
+
+Both services should show "healthy" status.
+
+### Reset database:
+
+```bash
+docker-compose down -v
+docker-compose up -d
+```
+
+### View detailed backend logs:
+
+```bash
+docker-compose logs backend
+```
+
+### Rebuild specific service:
+
+```bash
+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.