is-it-christmas/specs/001-christmas-checker/quickstart.md

# Quickstart Guide: Christmas Checker Website

**Feature**: Christmas Checker Website
**Branch**: 001-christmas-checker
**Last Updated**: 2025-11-11

## Prerequisites

Before you begin, ensure you have the following installed:

- **Docker**: Version 20.10 or higher
- **Docker Compose**: Version 2.0 or higher
- **Java Development Kit (JDK)**: Version 21 (for local development without Docker)
- **Git**: For version control

### Verify Prerequisites

```bash
# Check Docker version
docker --version
# Expected: Docker version 20.10.0 or higher

# Check Docker Compose version
docker compose version
# Expected: Docker Compose version v2.0.0 or higher

# Check Java version (optional, for local dev)
java -version
# Expected: openjdk version "21" or higher
```

## Quick Start (Docker Compose)

The fastest way to run the Christmas Checker application:

### 1. Clone and Navigate

```bash
# If not already in the repository
cd is-it-christmas

# Switch to feature branch
git checkout 001-christmas-checker
```

### 2. Build and Run

```bash
# Build and start both services (backend + frontend)
docker compose up --build

# Or run in detached mode (background)
docker compose up --build -d
```

### 3. Access the Application

Open your browser and navigate to:

```
http://localhost
```

You should see:
- **If today is NOT Christmas**: "No" with a sad smiley face
- **If today IS Christmas** (Dec 25-26): "Yes" with falling snow animation

### 4. Stop the Application

```bash
# Stop services (Ctrl+C if running in foreground)

# Or if running in detached mode:
docker compose down
```

## Project Structure

```
is-it-christmas/
├── backend/
│   ├── src/
│   │   └── main/
│   │       └── java/
│   │           └── christmas/
│   │               ├── ChristmasChecker.java    # Date checking logic
│   │               ├── ChristmasServer.java     # HTTP server
│   │               └── Main.java                # Application entry point
│   └── Dockerfile                               # Backend container definition
│
├── frontend/
│   ├── index.html                               # Main HTML page
│   ├── styles.css                               # Styling
│   ├── script.js                                # Date check + snow animation
│   └── Dockerfile                               # Frontend container (nginx)
│
├── docker-compose.yml                           # Service orchestration
│
└── specs/
    └── 001-christmas-checker/
        ├── spec.md                              # Feature specification
        ├── plan.md                              # Implementation plan
        ├── research.md                          # Technical research
        ├── data-model.md                        # Data model
        ├── quickstart.md                        # This file
        └── contracts/
            └── api.md                           # API contract
```

## Development Workflow

### Local Development (Without Docker)

#### Backend

```bash
# Navigate to backend directory
cd backend

# Compile Java files
javac -d build src/main/java/christmas/*.java

# Run the backend server
java -cp build christmas.Main

# Backend will start on http://localhost:8080
```

Test the backend API:
```bash
curl http://localhost:8080/api/christmas
# Response: {"isChristmas":false,"date":"2025-11-11"}
```

#### Frontend

```bash
# Navigate to frontend directory
cd frontend

# Serve static files using Python's built-in server
python3 -m http.server 80

# Or use any other static file server:
# - npx serve
# - php -S localhost:80
```

Open browser to `http://localhost`

### Testing the Application

#### Manual Testing

**Test Non-Christmas Day** (any day except Dec 25-26):
1. Open `http://localhost`
2. Verify page shows "No"
3. Verify sad smiley face is displayed
4. Verify no snow animation

**Test Christmas** (Dec 25-26):

Option 1: Wait until December 25th (not practical!)

Option 2: Modify system date temporarily:
```bash
# On Linux/Mac (requires sudo):
sudo date -s "2025-12-25"

# Access http://localhost
# Should show "Yes" and snow animation

# Reset date:
sudo ntpdate -s time.apple.com  # Mac
# or
sudo systemctl restart systemd-timesyncd  # Linux
```

Option 3: Modify code temporarily:
```javascript
// In frontend/script.js, change:
const today = new Date();
// To:
const today = new Date('2025-12-25');
```

#### Automated Testing

If tests were requested (they weren't in this feature), you would run:

```bash
# Backend tests (JUnit)
cd backend
javac -cp .:junit-5.10.0.jar -d build src/test/java/christmas/*.java
java -cp build:junit-5.10.0.jar org.junit.runner.JUnitCore christmas.ChristmasCheckerTest

# Frontend tests (would require test framework like Jest)
cd frontend
npm test  # (if package.json configured)
```

## Configuration

### Environment Variables

**Backend**:
- `PORT`: HTTP port for backend server (default: 8080)

```bash
# Set custom port
export PORT=9000
docker compose up --build
```

**Frontend**:
- No environment variables needed (static files)

### Docker Compose Configuration

Edit `docker-compose.yml` to customize:

```yaml
services:
  backend:
    build: ./backend
    ports:
      - "8080:8080"  # Change left number for different host port
    environment:
      - PORT=8080

  frontend:
    build: ./frontend
    ports:
      - "80:80"      # Change left number for different host port
    depends_on:
      - backend
```

## Troubleshooting

### Port Already in Use

**Error**: `Bind for 0.0.0.0:80 failed: port is already allocated`

**Solution**: Change port mapping in `docker-compose.yml`:
```yaml
frontend:
  ports:
    - "8081:80"  # Use port 8081 instead
```

Access via `http://localhost:8081`

### Backend Not Responding

**Check backend is running**:
```bash
docker compose ps
# Should show backend service as "Up"

# Check backend logs:
docker compose logs backend
```

**Test backend directly**:
```bash
curl http://localhost:8080/api/christmas
```

### Frontend Shows Error

**Check browser console** (F12 → Console tab) for errors

**Common issue**: Backend not accessible
- Verify backend is running: `docker compose ps`
- Verify backend URL in `frontend/script.js` matches backend port

### Snow Animation Not Showing

**Verify date is December 25th or 26th**:
```bash
curl http://localhost:8080/api/christmas
# Check: "isChristmas": true
```

**Check browser console** for JavaScript errors

**Check browser supports Canvas API**: All modern browsers (Chrome, Firefox, Safari, Edge) support Canvas

## Performance Optimization

### Production Recommendations

1. **Enable Response Compression** (nginx):
```nginx
gzip on;
gzip_types text/html text/css application/javascript;
```

2. **Add Cache Headers** for static assets:
```nginx
location ~* \.(js|css|html)$ {
    expires 1h;
    add_header Cache-Control "public, immutable";
}
```

3. **Optimize Snow Particle Count**:
Edit `frontend/script.js`:
```javascript
// Reduce particles for better performance
const maxParticles = window.innerWidth < 768 ? 50 : 100;  // Instead of 200
```

4. **Use Production Docker Images**:
- Multi-stage builds to reduce image size
- Alpine-based images for smaller footprint

## Deployment

### Deploy to Production

1. **Set production environment variables**
2. **Use production Docker Compose file**:

```yaml
# docker-compose.prod.yml
services:
  backend:
    build: ./backend
    restart: always
    environment:
      - PORT=8080

  frontend:
    build: ./frontend
    restart: always
    ports:
      - "80:80"
    depends_on:
      - backend
```

3. **Deploy**:
```bash
docker compose -f docker-compose.prod.yml up -d
```

### Deploy to Cloud

**AWS ECS / Azure Container Instances / Google Cloud Run**:
- Push Docker images to container registry
- Deploy using cloud-specific Docker Compose support or orchestration tools

**Kubernetes**:
```bash
# Generate Kubernetes manifests from Docker Compose
kompose convert -f docker-compose.yml

# Deploy to Kubernetes
kubectl apply -f backend-deployment.yaml
kubectl apply -f frontend-deployment.yaml
```

## Monitoring

### Health Checks

**Backend**:
```bash
# Check if backend is responding
curl http://localhost:8080/api/christmas

# Expected: 200 OK with JSON response
```

**Frontend**:
```bash
# Check if frontend is accessible
curl -I http://localhost

# Expected: 200 OK with HTML content
```

### Logs

**View real-time logs**:
```bash
# All services
docker compose logs -f

# Backend only
docker compose logs -f backend

# Frontend only
docker compose logs -f frontend
```

## Next Steps

After completing the quickstart:

1. **Generate Tasks**: Run `/speckit.tasks` to create implementation task list
2. **Implement**: Follow tasks.md to build the feature
3. **Validate**: Test against acceptance scenarios in spec.md
4. **Deploy**: Use production deployment steps above

## Additional Resources

- **Feature Specification**: [spec.md](spec.md)
- **Implementation Plan**: [plan.md](plan.md)
- **API Contract**: [contracts/api.md](contracts/api.md)
- **Data Model**: [data-model.md](data-model.md)
- **Research**: [research.md](research.md)

## Support

For issues or questions:
1. Check this quickstart guide
2. Review feature specification and plan
3. Check Docker Compose logs
4. Consult research.md for technical decisions