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

# 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

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

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

2. Build and Run

# 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

# 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

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

curl http://localhost:8080/api/christmas
# Response: {"isChristmas":false,"date":"2025-11-11"}

Frontend

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

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

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

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

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

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:

frontend:
  ports:
    - "8081:80"  # Use port 8081 instead

Access via http://localhost:8081

Backend Not Responding

Check backend is running:

docker compose ps
# Should show backend service as "Up"

# Check backend logs:
docker compose logs backend

Test backend directly:

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:

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

gzip on;
gzip_types text/html text/css application/javascript;

2. Add Cache Headers for static assets:

location ~* \.(js|css|html)$ {
    expires 1h;
    add_header Cache-Control "public, immutable";
}

3. Optimize Snow Particle Count: Edit frontend/script.js:

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

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

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:

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

# Check if backend is responding
curl http://localhost:8080/api/christmas

# Expected: 200 OK with JSON response

Frontend:

# Check if frontend is accessible
curl -I http://localhost

# Expected: 200 OK with HTML content

Logs

View real-time logs:

# 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
• Implementation Plan: plan.md
• API Contract: contracts/api.md
• Data Model: data-model.md
• Research: 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