scriptshare-cursor/DOCKER.md

# Docker Setup for ScriptShare

This document explains how to build and run ScriptShare using Docker.

## Prerequisites

- Docker Desktop (for Windows/macOS) or Docker Engine (for Linux)
- Docker Compose (usually included with Docker Desktop)

## Quick Start

### Using Docker Compose (Recommended)

```bash
# Clone the repository
git clone <repository-url>
cd scriptshare-cursor

# Build and start the application
docker-compose up --build

# Access the application at http://localhost:3000
```

### Using Docker Build Directly

```bash
# Build the image
docker build -t scriptshare .

# Run the container
docker run -p 3000:80 scriptshare
```

## Configuration

### Build Arguments

You can customize the build using these arguments:

```bash
docker build \
  --build-arg VITE_APP_NAME="Your ScriptShare" \
  --build-arg VITE_APP_URL="https://your-domain.com" \
  --build-arg VITE_ANALYTICS_ENABLED="true" \
  -t scriptshare .
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `VITE_APP_NAME` | "ScriptShare" | Application name shown in UI |
| `VITE_APP_URL` | "https://scriptshare.example.com" | Base URL for the application |
| `VITE_ANALYTICS_ENABLED` | "false" | Enable/disable analytics tracking |

### Docker Compose Configuration

Update `docker-compose.yml` to customize build arguments:

```yaml
services:
  scriptshare:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        - VITE_APP_NAME=Your ScriptShare
        - VITE_APP_URL=https://your-domain.com
        - VITE_ANALYTICS_ENABLED=true
    ports:
      - "3000:80"
```

## Features

### Multi-Stage Build

The Dockerfile uses a multi-stage build for optimization:

1. **Builder Stage**: Builds the React application with all dependencies
2. **Production Stage**: Serves the built files using nginx

### Security Features

- Runs as non-root user (nginx)
- Minimal production image based on nginx:alpine
- Proper file permissions
- Health checks included

### Dependencies Handled

The build process properly handles:
- Native modules (bcrypt, etc.) with build dependencies
- React Syntax Highlighter
- All UI component libraries
- TypeScript compilation
- **Note**: For Docker builds, server-side dependencies (MySQL, bcrypt, JWT) are temporarily disabled to create a frontend-only demo build

### Health Checks

The container includes health checks at:
- Docker level: `curl -f http://localhost/health`
- nginx level: Configured in nginx.conf

## Development

### Development Build

For development with hot reloading:

```bash
# Install dependencies locally
npm install

# Start development server
npm run dev

# Access at http://localhost:5173
```

### Building for Production

```bash
# Build the application
npm run build

# Preview the build
npm run preview
```

## Production Deployment

### With Reverse Proxy (Recommended)

If using with a reverse proxy like Traefik or nginx:

```yaml
# docker-compose.yml
services:
  scriptshare:
    build: .
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.scriptshare.rule=Host(\`your-domain.com\`)"
      - "traefik.http.services.scriptshare.loadbalancer.server.port=80"
```

### Standalone Deployment

```bash
# Build for production
docker build -t scriptshare:latest .

# Run with custom port
docker run -d -p 80:80 --name scriptshare-app scriptshare:latest
```

## Volumes

The container uses these volumes:

- `scriptshare_logs:/var/log/nginx` - nginx logs

## Troubleshooting

### Build Issues

1. **Native dependency errors**: Ensure Docker has enough memory allocated
2. **Build timeout**: Increase Docker build timeout in Docker Desktop settings
3. **Permission errors**: Check that Docker has access to the project directory
4. **Server-side import errors**: The Dockerfile automatically handles server-side imports by creating a frontend-only build

### Runtime Issues

1. **Health check failures**: Check nginx logs in the container
2. **Static files not served**: Verify build output in `/usr/share/nginx/html`
3. **Environment variables**: Ensure they're set at build time, not runtime

### Checking Logs

```bash
# View application logs
docker-compose logs scriptshare

# View nginx access logs
docker exec <container-id> tail -f /var/log/nginx/access.log

# View nginx error logs
docker exec <container-id> tail -f /var/log/nginx/error.log
```

## Image Size Optimization

The production image is optimized by:

- Using Alpine Linux base images
- Multi-stage builds to exclude build dependencies
- .dockerignore to exclude unnecessary files
- Only copying built assets to production stage

Expected image size: ~25-30MB (compressed)

## Security Considerations

- Container runs as non-root user
- Minimal attack surface with alpine base
- No build tools in production image
- Proper file permissions set
- Health checks for monitoring

## Updates

To update the application:

1. Pull latest code changes
2. Rebuild the image: `docker-compose build`
3. Restart containers: `docker-compose up -d`

## Support

For issues with Docker setup:
1. Check Docker Desktop is running
2. Verify Docker version compatibility
3. Review build logs for specific errors
4. Check system resources (memory, disk space)