354 lines
7.1 KiB
Markdown
354 lines
7.1 KiB
Markdown
# Docker Deployment Guide
|
|
|
|
This guide explains how to deploy the Pradit application using Docker and Docker Compose.
|
|
|
|
## Prerequisites
|
|
|
|
- Docker Engine 20.10+
|
|
- Docker Compose 2.0+
|
|
- Gemini API Key (get from https://aistudio.google.com/app/apikey)
|
|
|
|
## Quick Start
|
|
|
|
### 1. Setup Environment Variables
|
|
|
|
Copy the example environment file and add your Gemini API key:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit `.env` and set your `GEMINI_API_KEY`:
|
|
|
|
```
|
|
GEMINI_API_KEY=your_actual_api_key_here
|
|
```
|
|
|
|
### 2. Run Development Mode
|
|
|
|
Development mode includes hot reload for rapid iteration:
|
|
|
|
```bash
|
|
docker-compose --profile dev up
|
|
```
|
|
|
|
Access the app at: http://localhost:3000
|
|
|
|
### 3. Run Production Mode
|
|
|
|
Production mode uses optimized build with nginx:
|
|
|
|
```bash
|
|
docker-compose --profile prod up -d
|
|
```
|
|
|
|
Access the app at: http://localhost:80
|
|
|
|
## Docker Compose Profiles
|
|
|
|
This project uses Docker Compose profiles to separate dev and prod environments.
|
|
|
|
### Development Profile (`dev`)
|
|
|
|
- **Port**: 3000
|
|
- **Hot Reload**: Enabled
|
|
- **Volume Mounts**: Source code mounted for live changes
|
|
- **Server**: Vite dev server
|
|
- **Optimizations**: None (fast rebuild)
|
|
|
|
**Commands**:
|
|
```bash
|
|
# Start dev server
|
|
docker-compose --profile dev up
|
|
|
|
# Start in background
|
|
docker-compose --profile dev up -d
|
|
|
|
# View logs
|
|
docker-compose --profile dev logs -f
|
|
|
|
# Stop
|
|
docker-compose --profile dev down
|
|
```
|
|
|
|
### Production Profile (`prod`)
|
|
|
|
- **Port**: 80
|
|
- **Hot Reload**: Disabled
|
|
- **Build**: Optimized static build
|
|
- **Server**: Nginx with compression and caching
|
|
- **Health Check**: Enabled on /health endpoint
|
|
|
|
**Commands**:
|
|
```bash
|
|
# Build and start production
|
|
docker-compose --profile prod up -d
|
|
|
|
# Rebuild after code changes
|
|
docker-compose --profile prod up -d --build
|
|
|
|
# View logs
|
|
docker-compose --profile prod logs -f
|
|
|
|
# Stop
|
|
docker-compose --profile prod down
|
|
```
|
|
|
|
## Manual Docker Commands
|
|
|
|
### Build Images
|
|
|
|
```bash
|
|
# Development image
|
|
docker build -f Dockerfile.dev -t pradit:dev .
|
|
|
|
# Production image
|
|
docker build -f Dockerfile -t pradit:prod .
|
|
```
|
|
|
|
### Run Containers
|
|
|
|
```bash
|
|
# Development
|
|
docker run -p 3000:3000 -v $(pwd):/app -v /app/node_modules \
|
|
-e GEMINI_API_KEY=your_key pradit:dev
|
|
|
|
# Production
|
|
docker run -p 80:80 pradit:prod
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Development Container
|
|
|
|
- **Base**: node:20-alpine
|
|
- **Package Manager**: pnpm
|
|
- **Volumes**: Source code mounted for hot reload
|
|
- **Port**: 3000
|
|
- **Command**: `pnpm run dev`
|
|
|
|
### Production Container
|
|
|
|
Multi-stage build for minimal image size:
|
|
|
|
1. **Builder Stage**:
|
|
- Installs dependencies with pnpm
|
|
- Builds optimized production bundle
|
|
- Uses node:20-alpine
|
|
|
|
2. **Runtime Stage**:
|
|
- Serves static files with nginx:alpine
|
|
- Configured for SPA routing
|
|
- Gzip compression enabled
|
|
- Security headers added
|
|
- Health check endpoint at `/health`
|
|
|
|
## Configuration Files
|
|
|
|
### Dockerfile
|
|
Production multi-stage build configuration.
|
|
|
|
### Dockerfile.dev
|
|
Development container with hot reload support.
|
|
|
|
### docker-compose.yml
|
|
Orchestration for both dev and prod profiles.
|
|
|
|
### nginx.conf
|
|
Nginx configuration for production:
|
|
- SPA routing (serves index.html for all routes)
|
|
- Gzip compression
|
|
- Static asset caching (1 year)
|
|
- Security headers
|
|
- Health check endpoint
|
|
|
|
### .dockerignore
|
|
Excludes unnecessary files from Docker build context:
|
|
- node_modules
|
|
- Build artifacts
|
|
- Environment files
|
|
- IDE configurations
|
|
- Documentation
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Required | Description |
|
|
|----------|----------|-------------|
|
|
| `GEMINI_API_KEY` | Yes | API key for Gemini AI |
|
|
| `NODE_ENV` | No | Environment mode (development/production) |
|
|
|
|
**Security Note**: Never commit `.env` file. Use `.env.example` as template.
|
|
|
|
## Port Configuration
|
|
|
|
| Service | Port | Description |
|
|
|---------|------|-------------|
|
|
| Development | 3000 | Vite dev server |
|
|
| Production | 80 | Nginx web server |
|
|
|
|
To use different ports, edit `docker-compose.yml`:
|
|
|
|
```yaml
|
|
ports:
|
|
- "8080:80" # Host:Container
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Port Already in Use
|
|
|
|
```bash
|
|
# Find process using port 3000
|
|
netstat -ano | findstr :3000 # Windows
|
|
lsof -i :3000 # Linux/Mac
|
|
|
|
# Change port in docker-compose.yml
|
|
ports:
|
|
- "3001:3000"
|
|
```
|
|
|
|
### API Key Not Working
|
|
|
|
Ensure `.env` file exists and contains valid key:
|
|
```bash
|
|
cat .env # Linux/Mac
|
|
type .env # Windows
|
|
```
|
|
|
|
Restart containers after changing `.env`:
|
|
```bash
|
|
docker-compose --profile dev down
|
|
docker-compose --profile dev up
|
|
```
|
|
|
|
### Container Won't Start
|
|
|
|
Check logs for errors:
|
|
```bash
|
|
docker-compose --profile dev logs
|
|
docker-compose --profile prod logs
|
|
```
|
|
|
|
Remove containers and rebuild:
|
|
```bash
|
|
docker-compose down -v
|
|
docker-compose --profile prod up -d --build
|
|
```
|
|
|
|
### Volume Permission Issues (Linux)
|
|
|
|
If encountering permission issues with mounted volumes:
|
|
```bash
|
|
# Add user ID to docker-compose.yml
|
|
user: "${UID}:${GID}"
|
|
```
|
|
|
|
### Build Cache Issues
|
|
|
|
Clear Docker build cache:
|
|
```bash
|
|
docker builder prune -a
|
|
docker-compose build --no-cache
|
|
```
|
|
|
|
## Health Checks
|
|
|
|
Production container includes health check:
|
|
|
|
```bash
|
|
# Check container health
|
|
docker ps
|
|
|
|
# Manual health check
|
|
curl http://localhost/health
|
|
```
|
|
|
|
## Logs and Debugging
|
|
|
|
```bash
|
|
# Follow logs
|
|
docker-compose logs -f
|
|
|
|
# Specific service logs
|
|
docker-compose --profile dev logs pradit-dev
|
|
docker-compose --profile prod logs pradit-prod
|
|
|
|
# Enter running container
|
|
docker exec -it pradit-dev sh
|
|
docker exec -it pradit-prod sh
|
|
```
|
|
|
|
## Cleaning Up
|
|
|
|
```bash
|
|
# Stop and remove containers
|
|
docker-compose down
|
|
|
|
# Remove containers and volumes
|
|
docker-compose down -v
|
|
|
|
# Remove images
|
|
docker rmi pradit:dev pradit:prod
|
|
|
|
# Full cleanup (all unused Docker resources)
|
|
docker system prune -a
|
|
```
|
|
|
|
## Production Deployment
|
|
|
|
For cloud deployment (AWS, GCP, Azure, etc.):
|
|
|
|
1. Build and tag image:
|
|
```bash
|
|
docker build -t your-registry/pradit:latest .
|
|
```
|
|
|
|
2. Push to registry:
|
|
```bash
|
|
docker push your-registry/pradit:latest
|
|
```
|
|
|
|
3. Deploy to orchestration platform (Kubernetes, ECS, etc.)
|
|
|
|
## Performance Optimization
|
|
|
|
### Production Build
|
|
|
|
- Tree shaking removes unused code
|
|
- Minification reduces bundle size
|
|
- Gzip compression (nginx)
|
|
- Static asset caching (1 year)
|
|
- Multi-stage build minimizes image size
|
|
|
|
### Development Build
|
|
|
|
- Fast rebuild with hot module replacement
|
|
- Source maps for debugging
|
|
- No minification for faster builds
|
|
|
|
## Security Best Practices
|
|
|
|
1. **Never commit API keys** - Use environment variables
|
|
2. **Use multi-stage builds** - Minimize attack surface
|
|
3. **Run as non-root** - Production nginx runs as nginx user
|
|
4. **Keep images updated** - Regularly update base images
|
|
5. **Scan for vulnerabilities** - Use `docker scan pradit:prod`
|
|
6. **Use secrets management** - For production, use Docker secrets or cloud provider solutions
|
|
|
|
## Additional Resources
|
|
|
|
- [Docker Documentation](https://docs.docker.com/)
|
|
- [Docker Compose Documentation](https://docs.docker.com/compose/)
|
|
- [Vite Documentation](https://vitejs.dev/)
|
|
- [Nginx Documentation](https://nginx.org/en/docs/)
|
|
|
|
## Support
|
|
|
|
For issues specific to Docker setup, check:
|
|
1. Docker daemon is running
|
|
2. Environment variables are set correctly
|
|
3. Ports are not already in use
|
|
4. Sufficient disk space for images and containers
|
|
|
|
For application issues, refer to main [README.md](README.md).
|