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):
   ```bash
   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:
   ```yaml
   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!**