etsy-finance-tracker/DEPLOYMENT_GUIDE.md

🚀 Etsy Finance Tracker - Deployment Guide

Quick Start for Container Interfaces (Docker Desktop, Portainer, etc.)

Option 1: Local Build Deployment (Recommended)

File to Use: docker-compose.deploy-local.yml

This option builds the containers locally and includes enhanced debugging.

Steps:

1. Import Configuration

   • In Docker Desktop: Click "+" → "Import" → Select docker-compose.deploy-local.yml
   • In Portainer: Go to "Stacks" → "Add stack" → Upload docker-compose.deploy-local.yml

2. Configure Environment

   • Set Stack Name: etsy-finance-tracker-local
   • Environment Variables (optional):

     NODE_ENV=production
     PORT=8080
     

3. Deploy Stack

   • Click "Deploy" or "Create Stack"
   • Wait for both containers to build and start

4. Access Application

   • Frontend: http://localhost:8081
   • API: http://localhost:8081/api
   • Health Check: http://localhost:8081/api/health

Troubleshooting Tips:

• 404 Errors: Check container logs for file copying messages
• Build Failures: Ensure you have sufficient disk space (>2GB recommended)
• Port Conflicts: Change port 8081 to another available port

Option 2: Pre-built Images (GitHub Container Registry)

File to Use: docker-compose.deploy.yml

This uses pre-built images from GitHub Container Registry.

Prerequisites:

• Must have pulled images manually or have registry access

Steps:

1. Pull Images First (if needed):

   docker pull ghcr.io/your-username/etsy-finance-tracker:latest
   

2. Import Configuration

   • Use docker-compose.deploy.yml in your container interface
   • Set Stack Name: etsy-finance-tracker

3. Deploy and Access

   • Same as Option 1

Container Architecture

┌─────────────────────────────────────┐
│            nginx (Port 8081)        │
│  ┌─────────────────────────────────┐│
│  │      React Frontend             ││
│  │   (Static Files Served)         ││
│  └─────────────────────────────────┘│
│  ┌─────────────────────────────────┐│
│  │         API Proxy               ││
│  │    (Routes /api/* to backend)   ││
│  └─────────────────────────────────┘│
└─────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────┐
│     Node.js API Server (Port 8080) │
│  ┌─────────────────────────────────┐│
│  │     Express Backend             ││
│  │   (REST API + File Processing)  ││
│  └─────────────────────────────────┘│
└─────────────────────────────────────┘

Expected Startup Sequence

1. API Container Builds/Starts

   • Installs dependencies
   • Builds React client
   • Copies client files to shared volume
   • Starts Express server on port 8080
   • Reports healthy status

2. Nginx Container Starts

   • Waits for API container health check
   • Finds client files in shared volume
   • Starts nginx on port 8081
   • Serves React app and proxies API calls

Debugging Information

When containers start, you should see logs like:

etsy-finance-tracker-1  | 📂 Current directory contents:
etsy-finance-tracker-1  | total 123
etsy-finance-tracker-1  | drwxr-xr-x  8 root root  256 Jan  2 12:34 client
etsy-finance-tracker-1  | 
etsy-finance-tracker-1  | 📋 Creating shared directory...
etsy-finance-tracker-1  | 📥 Copying client files to shared volume...
etsy-finance-tracker-1  | './client/dist/index.html' -> '/shared/index.html'
etsy-finance-tracker-1  | './client/dist/assets' -> '/shared/assets'

Common Issues & Solutions

🚨 Getting 404 Errors

Symptoms: Browser shows 404 or "Starting Up..." page Causes:

• Client files not copied to shared volume
• Nginx started before files were ready
• Volume mounting issues

Solutions:

1. Check container logs for file copying messages
2. Restart the stack if timing issue
3. Try Option 1 (local build) if using Option 2

🚨 Build Failures

Symptoms: Container fails to start during build Causes:

• Insufficient disk space
• Network issues downloading dependencies
• Node.js version compatibility

Solutions:

1. Free up disk space (need ~2GB)
2. Check internet connection
3. Try restarting Docker service

🚨 Port Already in Use

Symptoms: "Port 8081 already in use" error Solutions:

1. Change port in docker-compose file:

   ports:
     - "3000:80"  # Use port 3000 instead
   

2. Stop other services using the port

Data Persistence

The application includes volume mounting for data persistence:

• MongoDB Data: ./data/mongo:/data/db
• Uploaded Files: ./data/uploads:/app/uploads
• Logs: ./data/logs:/app/logs

Your data will persist between container restarts.

Development vs Production

• Development: Use docker-compose.yml (includes hot reload)
• Production: Use docker-compose.deploy-local.yml or docker-compose.deploy.yml

Support

If you encounter issues:

1. Check container logs in your interface
2. Verify all containers are running
3. Test health endpoint: http://localhost:8081/api/health
4. Review this guide for common solutions

---

Container Interface Specific Instructions

Docker Desktop

1. Go to "Compose" tab
2. Click "Import" button
3. Select the appropriate docker-compose file
4. Click "Run"

Portainer

1. Go to "Stacks"
2. Click "Add stack"
3. Choose "Upload" method
4. Select the docker-compose file
5. Click "Deploy the stack"

Other Interfaces

Most container management tools support docker-compose file import. Look for:

• "Import Compose"
• "Deploy Stack"
• "Upload docker-compose"
• "Create from Compose file"

---

🎉 Once deployed successfully, you'll have a fully functional Etsy Finance Tracker with comprehensive profit analysis capabilities!