workout/docs/SELF-HOSTING.md

Self-Hosting Workout-Cool

Deploy Workout-Cool on your own server using Docker. This guide provides two deployment options with step-by-step instructions.

---

📑 Table of Contents

• Prerequisites
• Quick Start
  • Common Setup Steps
  • Option 1: Docker Compose (All-in-One)
  • Option 2: Docker Only (External Database)
• Management Commands
• Troubleshooting
• Resources & Support

---

📋 Prerequisites

Before you begin, ensure your server meets these requirements:

• Operating System: Linux server or VPS (Ubuntu 20.04+ recommended)
• Docker: Install Docker
• Docker Compose: Install Docker Compose
• Git: Install Git
• Basic Knowledge: Familiarity with command line operations

---

🚀 Quick Start

Common Setup Steps

These steps are required for both deployment options:

1. Connect to Your Server

ssh your-user@your-server-ip

2. Clone the Repository

mkdir -p ~/apps
cd ~/apps
git clone https://github.com/Snouzy/workout-cool.git
cd workout-cool

3. Configure Environment Variables

cp .env.example .env
nano .env

Essential Environment Variables:

# Application Configuration (Required for both options)
NEXTAUTH_SECRET=your-secret-key-here
NEXTAUTH_URL=http://your-server-ip:3000

# Optional: Seed sample data on first run
SEED_SAMPLE_DATA=true

4. Customize Sample Data (Optional)

nano data/sample-exercises.csv

📚 See Exercise Database Import section in the README.

---

Option 1: Docker Compose (All-in-One)

This option automatically sets up both the application and PostgreSQL database.

Additional Environment Variables:

# Database Configuration (Docker Compose)
POSTGRES_USER=my-user
POSTGRES_PASSWORD=my-password
POSTGRES_DB=workout-cool
DB_HOST=postgres
DB_PORT=5432

DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${DB_HOST}:${DB_PORT}/${POSTGRES_DB}

Deploy:

docker compose up -d

Access:

Visit http://your-server-ip:3000

---

Option 2: Docker Only (External Database)

Use this option if you have an existing PostgreSQL database.

Additional Environment Variables:

# Database Configuration (External Database)
DATABASE_URL=postgresql://username:password@your-db-host:5432/workout_cool

Deploy:

docker build -t workout-cool .
docker run -d --name workout-cool -p 3000:3000 --env-file .env workout-cool

Access:

Visit http://your-server-ip:3000

---

🛠️ Management Commands

Docker Compose Commands

# Start/Stop services
docker compose up -d
docker compose down

# View logs
docker compose logs -f

# Update and restart
git pull
docker compose down
docker compose up -d --build

Docker Commands

# Start/Stop container
docker start workout-cool
docker stop workout-cool

# View logs
docker logs -f workout-cool

# Update application
git pull
docker build -t workout-cool .
docker stop workout-cool
docker rm workout-cool
docker run -d --name workout-cool -p 3000:3000 --env-file .env workout-cool

---

🐛 Troubleshooting

Common Issues

Application Won't Start

# Check logs
docker compose logs workout_cool  # or docker logs workout-cool

# Verify environment variables using docker compose
docker compose exec workout_cool env | grep DATABASE_URL  # or docker exec workout-cool env | grep DATABASE_URL

Database Connection Issues

# Test database connectivity (Docker Compose)
docker compose exec postgres psql -U postgres -d workout_cool -c "SELECT 1;"

# Check database status
docker compose ps postgres

Port Already in Use

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

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

Getting Help

If you encounter issues:

1. Check the logs: Use docker compose logs or docker logs
2. Verify configuration: Ensure all environment variables are set correctly
3. Database connectivity: Test database connection manually
4. Search existing issues or create a new one on GitHub
5. Join our Discord community for support

---

📚 Resources & Support

Documentation

• Docker Documentation
• Docker Compose Documentation
• PostgreSQL Documentation
• Next.js Deployment Guide

Community & Support

• GitHub: Repository | Issues
• Discord: Join our community

---

Last updated: June 2025