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)

# 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

# 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:

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:

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:

# Install dependencies locally
npm install

# Start development server
npm run dev

# Access at http://localhost:5173

Building for Production

# 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:

# 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

# 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

# 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)