etsy-finance-tracker/DOCKER_DEPLOYMENT.md

Docker Deployment Guide for Mac Mini

This guide will help you deploy the Etsy Finance Tracker on your Mac Mini using Docker with Nginx.

Architecture

The application uses a multi-container setup:

• Nginx: Serves static React files and proxies API requests
• Node.js API: Handles backend logic and API endpoints
• Persistent Data: Your business data mounted as volumes

Prerequisites

1. Install Docker Desktop on your Mac Mini:

   # Option 1: Download from Docker website
   # Go to https://docs.docker.com/desktop/mac/install/
   
   # Option 2: Install with Homebrew (if available)
   brew install --cask docker
   

2. Install Git (if not already installed):

   brew install git
   

Deployment Steps

1. Clone the Repository

git clone https://github.com/dlawler489/etsy-finance-tracker.git
cd etsy-finance-tracker

2. Prepare Your Data

# Create the data directory structure
mkdir -p data/{csv,pdf,spreadsheets}

# Copy your business files to the data directory
# Example:
# cp ~/Documents/BusinessData/*.csv data/csv/
# cp ~/Documents/BusinessData/*.pdf data/pdf/
# cp ~/Documents/BusinessData/*.xlsx data/spreadsheets/

3. Build and Deploy

# Option 1: Use the automated build script (recommended)
./build-deploy.sh

# Option 2: Manual deployment
cd client && npm install && npm run build && cd ..
docker-compose up --build -d

4. Access Your Application

• Web Interface: http://localhost:3000
• API Health Check: http://localhost:3000/health
• Direct API: http://localhost:3000/api/ (proxied through nginx)

Management Commands

Start/Stop the Application

# Start
docker-compose up -d

# Stop
docker-compose down

# Restart
docker-compose restart

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f etsy-tracker

Update the Application

# Pull latest code
git pull origin main

# Rebuild and restart
docker-compose down
docker-compose up --build -d

Backup Your Data

# Your business data in the data/ directory is automatically persisted
# To backup:
tar -czf etsy-tracker-backup-$(date +%Y%m%d).tar.gz data/

Troubleshooting

Check Application Health

# Test the health endpoint
curl http://localhost:3000/health

# Check container logs
docker-compose logs etsy-tracker

Common Issues

1. Port Already in Use:

   # Change port in docker-compose.yml
   ports:
     - "3001:3000"  # Change 3000 to 3001
   

2. Permission Issues:

   # Fix data directory permissions
   sudo chown -R $(whoami):$(whoami) data/
   

3. Memory Issues:

   # Add memory limits to docker-compose.yml
   deploy:
     resources:
       limits:
         memory: 512M
   

File Structure

Your deployment will look like this:

etsy-finance-tracker/
├── data/                 # Your business data (persistent)
│   ├── csv/             # CSV files
│   ├── pdf/             # PDF documents  
│   └── spreadsheets/    # Excel files
├── docker-compose.yml   # Container orchestration
├── Dockerfile          # Container configuration
└── ... (application code)

Security Notes

• The data/ directory contains your sensitive business files
• This directory is mounted as a volume and persists between container restarts
• Never commit the data/ directory to git
• Change default passwords in .env file for production use

Performance Optimization

For better performance on Mac Mini:

1. Allocate more resources to Docker Desktop:

   • Open Docker Desktop preferences
   • Go to Resources → Advanced
   • Increase Memory to at least 4GB
   • Increase CPU to at least 2 cores

2. Enable BuildKit for faster builds:

   export DOCKER_BUILDKIT=1
   

Support

If you encounter issues:

1. Check the logs: docker-compose logs
2. Verify Docker is running: docker version
3. Check port availability: lsof -i :3000
4. Review the troubleshooting section above