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:

   • Navigate to "Stacks" or "Deploy from Git"
   • Paste the repository URL: https://github.com/dlawler489/etsy-finance-tracker
   • Set the compose file path: docker-compose.deploy-local.yml
   • Stack name: etsy-finance-tracker

3. If you get "unauthorized" error:

   • GitHub image may still be building
   • Use local build instead: Set compose file path to docker-compose.deploy-local.yml
   • This will build the image locally (takes longer but works immediately)

4. Environment Variables (Optional):

   NODE_ENV=production
   PORT=8080
   

5. Deploy the Stack

   • Click "Deploy" or "Create Stack"
   • Wait for images to pull and containers to start

Method 2: Manual Container Creation

If your interface doesn't support stacks, create containers manually:

Container 1: Etsy API Server

• 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

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