myTradeTracker/LINUX_DEPLOYMENT.md

Linux Server Deployment Guide

Complete guide for deploying myFidelityTracker on a Linux server.

Prerequisites

Linux Server Requirements

• OS: Ubuntu 20.04+, Debian 11+, CentOS 8+, or similar
• RAM: 4GB minimum (8GB recommended)
• Disk: 20GB free space
• Network: Open ports 3000, 8000 (or configure firewall)

Required Software

• Docker Engine 20.10+
• Docker Compose 1.29+ (or Docker Compose V2)
• Git (optional, for cloning)

Step 1: Install Docker on Linux

Ubuntu/Debian

# Update package index
sudo apt-get update

# Install dependencies
sudo apt-get install -y \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

# Add Docker's official GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Set up repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Add your user to docker group (optional, to run without sudo)
sudo usermod -aG docker $USER
newgrp docker

# Verify installation
docker --version
docker compose version

CentOS/RHEL

# Install Docker
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Start Docker
sudo systemctl start docker
sudo systemctl enable docker

# Add user to docker group (optional)
sudo usermod -aG docker $USER
newgrp docker

# Verify
docker --version
docker compose version

Step 2: Transfer Files to Linux Server

Option A: Direct Transfer (from your Mac)

# From your Mac, transfer the entire project directory
# Replace USER and SERVER_IP with your values
cd /Users/chris/Desktop
scp -r fidelity USER@SERVER_IP:~/

# Example:
# scp -r fidelity ubuntu@192.168.1.100:~/

Option B: Using rsync (faster for updates)

# From your Mac
rsync -avz --progress /Users/chris/Desktop/fidelity/ USER@SERVER_IP:~/fidelity/

# Exclude node_modules and other large dirs
rsync -avz --progress \
  --exclude 'node_modules' \
  --exclude '__pycache__' \
  --exclude '*.pyc' \
  /Users/chris/Desktop/fidelity/ USER@SERVER_IP:~/fidelity/

Option C: Git (if using version control)

# On your Linux server
cd ~
git clone YOUR_REPO_URL fidelity
cd fidelity

Option D: Manual ZIP Transfer

# On your Mac - create zip
cd /Users/chris/Desktop
zip -r fidelity.zip fidelity/ -x "*/node_modules/*" "*/__pycache__/*" "*.pyc"

# Transfer the zip
scp fidelity.zip USER@SERVER_IP:~/

# On Linux server - extract
cd ~
unzip fidelity.zip

Step 3: Configure for Linux Environment

SSH into your Linux server:

ssh USER@SERVER_IP
cd ~/fidelity

Make scripts executable

chmod +x start-linux.sh
chmod +x stop.sh

Configure environment variables

# Create .env file
cp .env.example .env

# Edit .env file to add your server IP for CORS
nano .env  # or use vim, vi, etc.

Update the CORS_ORIGINS line:

CORS_ORIGINS=http://localhost:3000,http://YOUR_SERVER_IP:3000

Replace YOUR_SERVER_IP with your actual server IP address.

Create imports directory

mkdir -p imports

Step 4: Start the Application

# Start all services
./start-linux.sh

# Or manually:
docker-compose up -d

The script will:

• Check Docker is running
• Create necessary directories
• Start all containers (postgres, backend, frontend)
• Display access URLs

Step 5: Access the Application

From the Server Itself

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs

From Other Computers on the Network

• Frontend: http://YOUR_SERVER_IP:3000
• Backend API: http://YOUR_SERVER_IP:8000
• API Docs: http://YOUR_SERVER_IP:8000/docs

From the Internet (if server has public IP)

First configure firewall (see Security section below), then:

• Frontend: http://YOUR_PUBLIC_IP:3000
• Backend API: http://YOUR_PUBLIC_IP:8000

Step 6: Configure Firewall (Ubuntu/Debian)

# Allow SSH (important - don't lock yourself out!)
sudo ufw allow 22/tcp

# Allow application ports
sudo ufw allow 3000/tcp  # Frontend
sudo ufw allow 8000/tcp  # Backend API

# Enable firewall
sudo ufw enable

# Check status
sudo ufw status

For CentOS/RHEL (firewalld)

# Allow ports
sudo firewall-cmd --permanent --add-port=3000/tcp
sudo firewall-cmd --permanent --add-port=8000/tcp
sudo firewall-cmd --reload

# Check status
sudo firewall-cmd --list-all

Step 7: Load Demo Data (Optional)

# Copy your CSV to imports directory
cp History_for_Account_X38661988.csv imports/

# Run seeder
docker-compose exec backend python seed_demo_data.py

Common Linux-Specific Commands

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f postgres

# Last 100 lines
docker-compose logs --tail=100

Check Container Status

docker-compose ps
docker ps

Restart Services

docker-compose restart
docker-compose restart backend

Stop Application

./stop.sh
# or
docker-compose down

Update Application

# Stop containers
docker-compose down

# Pull latest code (if using git)
git pull

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

Access Database

docker-compose exec postgres psql -U fidelity -d fidelitytracker

Shell Access to Containers

# Backend shell
docker-compose exec backend bash

# Frontend shell
docker-compose exec frontend sh

# Database shell
docker-compose exec postgres bash

Troubleshooting

Port Already in Use

# Check what's using the port
sudo lsof -i :3000
sudo lsof -i :8000
sudo lsof -i :5432

# Or use netstat
sudo netstat -tlnp | grep 3000

# Kill the process
sudo kill <PID>

Permission Denied Errors

# If you get permission errors with Docker
sudo usermod -aG docker $USER
newgrp docker

# If import directory has permission issues
sudo chown -R $USER:$USER imports/
chmod 755 imports/

Docker Out of Space

# Clean up unused containers, images, volumes
docker system prune -a

# Remove only dangling images
docker image prune

Services Won't Start

# Check Docker is running
sudo systemctl status docker
sudo systemctl start docker

# Check logs for errors
docker-compose logs

# Rebuild from scratch
docker-compose down -v
docker-compose up -d --build

Cannot Access from Other Computers

# Check firewall
sudo ufw status
sudo firewall-cmd --list-all

# Check if services are listening on all interfaces
sudo netstat -tlnp | grep 3000
# Should show 0.0.0.0:3000, not 127.0.0.1:3000

# Update CORS in .env
nano .env
# Add your server IP to CORS_ORIGINS

Production Deployment (Optional)

Use Docker Compose in Production Mode

Create docker-compose.prod.yml:

version: '3.8'

services:
  postgres:
    restart: always

  backend:
    restart: always
    environment:
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}  # Use strong password

  frontend:
    restart: always

Start with:

docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Set Up as System Service (Systemd)

Create /etc/systemd/system/fidelity-tracker.service:

[Unit]
Description=myFidelityTracker
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/home/YOUR_USER/fidelity
ExecStart=/usr/bin/docker-compose up -d
ExecStop=/usr/bin/docker-compose down
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable fidelity-tracker
sudo systemctl start fidelity-tracker
sudo systemctl status fidelity-tracker

Enable HTTPS with Nginx Reverse Proxy

Install Nginx:

sudo apt-get install nginx certbot python3-certbot-nginx

Configure /etc/nginx/sites-available/fidelity:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }

    location /api {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Enable and get SSL:

sudo ln -s /etc/nginx/sites-available/fidelity /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
sudo certbot --nginx -d your-domain.com

Backup Database

# Create backup script
cat > backup-db.sh << 'EOF'
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
docker-compose exec -T postgres pg_dump -U fidelity fidelitytracker > backup_$DATE.sql
gzip backup_$DATE.sql
echo "Backup created: backup_$DATE.sql.gz"
EOF

chmod +x backup-db.sh

# Run backup
./backup-db.sh

# Schedule with cron (daily at 2 AM)
crontab -e
# Add: 0 2 * * * /home/YOUR_USER/fidelity/backup-db.sh

Security Best Practices

1. Change default passwords in .env
2. Use firewall to restrict access
3. Enable HTTPS for production
4. Regular backups of database
5. Keep Docker updated: sudo apt-get update && sudo apt-get upgrade
6. Monitor logs for suspicious activity
7. Use strong passwords for PostgreSQL
8. Don't expose ports to the internet unless necessary

Performance Optimization

Increase Docker Resources

Edit /etc/docker/daemon.json:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

Restart Docker:

sudo systemctl restart docker

Monitor Resources

# Container resource usage
docker stats

# System resources
htop
free -h
df -h

Summary

Your app is now running on Linux! The main differences from macOS:

• Use start-linux.sh instead of start.sh
• Configure firewall for remote access
• CORS needs your server IP
• Use systemctl for Docker management

The application itself runs identically - Docker handles all the platform differences.

---

Questions? Check the main README.md or run docker-compose logs to diagnose issues.