Zimeng Xiong
198 lines
3.7 KiB
Markdown
198 lines
3.7 KiB
Markdown
# 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.
|