etsy-finance-tracker/CONTAINER_INTERFACE_DEPLOYMENT.md

# Container Management Interface Deployment Guide

This guide shows how to deploy the Etsy Finance Tracker using container management interfaces like Portainer, Docker Desktop, or similar tools.

## 🚀 Quick Deployment Steps

### Method 1: Stack Deployment (Recommended)

1. **Copy the Repository URL**:
   ```
   https://github.com/dlawler489/etsy-finance-tracker
   ```

2. **In your container interface**:
## 🚀 Quick Deployment Steps

### Option 1: Simple Deployment (Recommended for First-Time Users)
**Use File:** `docker-compose.simple.yml`

This version includes enhanced error handling and automatic client building.

**Steps:**
1. **Import** the `docker-compose.simple.yml` file in your container interface
2. **Set Stack Name:** `etsy-finance-tracker-simple`
3. **Deploy** and wait for build completion (~3-5 minutes)
4. **Access:** http://localhost:8081

### Option 2: Enhanced Local Build
**Use File:** `docker-compose.deploy-local.yml`

This version includes detailed debugging and enhanced logging.

**Steps:**
1. **Import** the `docker-compose.deploy-local.yml` file
2. **Set Stack Name:** `etsy-finance-tracker-local`
3. **Deploy** and monitor logs for debugging info
4. **Access:** http://localhost:8081

### Option 3: Pre-built Images
**Use File:** `docker-compose.deploy.yml`

Uses pre-built images from GitHub Container Registry (may require authentication).

## 📋 Detailed Instructions by Platform

### Using Container Management Interface

1. **Import Compose File**:
   - **Docker Desktop**: Compose tab → Import → Select file
   - **Portainer**: Stacks → Add stack → Upload file
   - **Other tools**: Look for "Import Compose" or "Deploy Stack"

2. **Configure Stack**:
- **Image**: `ghcr.io/dlawler489/etsy-finance-tracker:main`
- **Name**: `etsy-finance-tracker`
- **Ports**: Internal port 8080 (don't expose externally)
- **Environment**:
  - `NODE_ENV=production`
  - `PORT=8080`
- **Volumes**:
  - `etsy_data:/app/data`
  - `etsy_uploads:/app/uploads`
  - `client_dist:/usr/share/nginx/html`
- **Networks**: Create/join `etsy-network`
- **Restart Policy**: Unless stopped

#### Container 2: Nginx Web Server
- **Image**: `nginx:alpine`
- **Name**: `etsy-nginx`
- **Ports**: `3000:80` (expose port 3000)
- **Volumes**:
  - Mount nginx config (see below)
  - `client_dist:/usr/share/nginx/html:ro`
- **Networks**: Join `etsy-network`
- **Depends on**: `etsy-finance-tracker`
- **Restart Policy**: Unless stopped

## 📁 Required Files

### docker-compose.deploy.yml
```yaml
version: '3.8'

services:
  nginx:
    image: nginx:alpine
    container_name: etsy-nginx
    ports:
      - "3000:80"
    volumes:
      - ./nginx.deploy.conf:/etc/nginx/nginx.conf:ro
      - client_dist:/usr/share/nginx/html:ro
    depends_on:
      - etsy-tracker
    restart: unless-stopped

  etsy-tracker:
    image: ghcr.io/dlawler489/etsy-finance-tracker:main
    container_name: etsy-finance-tracker
    expose:
      - "8080"
    environment:
      - NODE_ENV=production
      - PORT=8080
    volumes:
      - etsy_data:/app/data
      - etsy_uploads:/app/uploads
      - client_dist:/usr/share/nginx/html
    restart: unless-stopped
    command: >
      sh -c "
        cp -r /app/client/dist/* /usr/share/nginx/html/ 2>/dev/null || true;
        exec node server/dist/index.js
      "      

volumes:
  etsy_uploads:
  client_dist:
  etsy_data:

networks:
  etsy-network:
    driver: bridge
```

## 🔧 Configuration Options

### Port Mapping
- **External Port**: 3000 (change if needed)
- **Internal Ports**: 
  - Nginx: 80
  - API Server: 8080 (internal only)

### Storage Volumes
- **`etsy_data`**: Your business data (CSV, PDF, Excel files)
- **`etsy_uploads`**: File uploads and temporary files
- **`client_dist`**: React app static files (shared between containers)

### Environment Variables
- **`NODE_ENV`**: Set to `production`
- **`PORT`**: API server port (default: 8080)
- **`CLIENT_URL`**: Set to `http://nginx` for container communication

## 🌐 Access Your Application

After deployment:
- **Web Interface**: `http://your-server-ip:3000`
- **Health Check**: `http://your-server-ip:3000/health`

## 🔄 Updates and Management

### Update to Latest Version
1. **In your container interface**:
   - Go to Images or Registry
   - Pull latest: `ghcr.io/dlawler489/etsy-finance-tracker:main`
   - Recreate the `etsy-tracker` container with new image

2. **Or via Stack Update**:
   - Edit stack and click "Update"
   - Images will automatically update

### View Logs
- Container logs available in your interface
- Look for both `etsy-nginx` and `etsy-finance-tracker` containers

### Data Backup
- Your business data is in the `etsy_data` volume
- Back up this volume regularly through your interface

## 🛠 Troubleshooting

### Common Issues

1. **"unauthorized" Error When Pulling Image**
   ```
   Error: Head "https://ghcr.io/v2/.../manifests/main": unauthorized
   ```
   **Solutions**:
   - **Option 1**: Use `docker-compose.deploy-local.yml` instead (builds locally)
   - **Option 2**: Wait for GitHub Actions build to complete
   - **Option 3**: Check that GitHub Container Registry is public

2. **Port 3000 Already in Use**
   - Change external port mapping: `3001:80` instead of `3000:80`

3. **Containers Not Communicating**
   - Ensure both containers are on same network (`etsy-network`)
   - Check container names match the nginx upstream config

4. **Static Files Not Loading**
   - Verify `client_dist` volume is shared between containers
   - Check nginx container logs for file access issues

5. **API Calls Failing**
   - Verify `etsy-finance-tracker` container is running
   - Check health endpoint: `/health`
   - Review API container logs

### Health Checks
Both containers include health checks:
- **API**: `curl http://localhost:8080/health`
- **Nginx**: `wget http://localhost/`

## 📊 Monitoring

Your container interface should show:
- **Container Status**: Both containers running
- **Resource Usage**: CPU, memory consumption
- **Health Status**: Green/healthy status
- **Port Mappings**: Port 3000 accessible externally

## 🔒 Security Notes

- **Internal Communication**: API server not exposed externally
- **Reverse Proxy**: Nginx handles all external requests
- **Data Volumes**: Business data persists between updates
- **Health Monitoring**: Built-in container health checks

## 🎯 Best Practices

1. **Use Named Volumes**: Easier to manage and backup
2. **Set Restart Policies**: Containers restart automatically
3. **Monitor Resources**: Set memory/CPU limits if needed
4. **Regular Updates**: Pull latest images periodically
5. **Backup Data**: Regular backups of `etsy_data` volume