igny8/INSTALLATION.md

IGNY8 Application - Installation Guide

Complete step-by-step installation on a clean Ubuntu server

---

Prerequisites

• Clean Ubuntu 22.04 LTS or later (stable version)
• Minimum Requirements: 4GB RAM, 20GB disk space, 2 CPU cores
• Root or sudo access
• Internet connection

---

Installation Steps

1. Initial System Setup

# Update system
sudo apt update && sudo apt upgrade -y

# Install required system packages
sudo apt install -y \
    git \
    curl \
    wget \
    ca-certificates \
    gnupg \
    lsb-release

---

2. Install Docker & Docker Compose

# 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 Docker 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 update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Verify installation
docker --version
docker compose version

# Add current user to docker group (optional - for non-root usage)
sudo usermod -aG docker $USER
newgrp docker

---

3. Install Portainer (Optional - for GUI management)

# Create Docker network
docker network create igny8_net

# Create Portainer volume
docker volume create portainer_data

# Run Portainer
docker run -d \
  --name portainer \
  --restart always \
  -p 9443:9443 \
  -p 8000:8000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  --network igny8_net \
  portainer/portainer-ce:latest

# Access Portainer at: https://YOUR_SERVER_IP:9443

---

4. Get IGNY8 Application

Option A: Clone from Git Repository

# Create application directory
sudo mkdir -p /data/app
cd /data/app

# Clone repository
git clone <YOUR_IGNY8_REPO_URL> igny8
cd igny8

Option B: Upload Application Package

# Create application directory
sudo mkdir -p /data/app
cd /data/app

# Upload igny8.tar.gz to server, then extract
tar -xzf igny8.tar.gz
cd igny8

---

5. Configure Environment Variables

# Create environment file
cat > .env << 'EOF'
# Database Configuration
DB_HOST=postgres
DB_NAME=igny8_db
DB_USER=igny8
DB_PASSWORD=CHANGE_THIS_PASSWORD

# Redis Configuration
REDIS_HOST=redis
REDIS_PORT=6379

# Django Settings
DEBUG=False
SECRET_KEY=CHANGE_THIS_TO_RANDOM_50_CHAR_STRING
ALLOWED_HOSTS=*

# Security
USE_SECURE_COOKIES=True
USE_SECURE_PROXY_HEADER=True

# Application URLs
VITE_BACKEND_URL=https://api.yourdomain.com/api
EOF

# Generate Django secret key
python3 -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())' >> .env.secret

---

6. Prepare Application Structure

What gets installed automatically (NO manual work needed):

✅ Backend (Python packages): Installed inside Docker container from requirements.txt

• Django, Celery, DRF, PostgreSQL drivers, etc.
• No local Python venv needed

✅ Frontend (Node packages): Installed inside Docker container from package.json

• React, Vite, TailwindCSS, etc.
• No local node_modules needed

✅ Database: PostgreSQL runs in Docker container

✅ Cache: Redis runs in Docker container

Your IGNY8 folder should contain ONLY:

igny8/
├── backend/
│   ├── igny8_core/          # Django application code
│   ├── manage.py            # Django management
│   ├── requirements.txt     # Python dependencies
│   └── Dockerfile           # Backend container build
├── frontend/
│   ├── src/                 # React application code
│   ├── public/              # Static assets
│   ├── package.json         # Node dependencies
│   └── Dockerfile.dev       # Frontend container build
├── docker-compose.app.yml   # Application stack definition
├── README.md
└── docs/

# These should NOT be present (automatically generated):
❌ backend/.venv/            # Will be built in Docker
❌ frontend/node_modules/    # Will be built in Docker
❌ frontend/dist/            # Will be built in Docker
❌ *.sql, *.sqlite3          # Database backups
❌ logs/                     # Runtime logs

---

7. Build Docker Images

cd /data/app/igny8

# Build backend image
cd backend
docker build -t igny8-backend:latest -f Dockerfile .

# Build frontend dev image
cd ../frontend
docker build -t igny8-frontend-dev:latest -f Dockerfile.dev .

# Build marketing dev image (if needed)
docker build -t igny8-marketing-dev:latest -f Dockerfile.marketing.dev .

cd ..

---

8. Start Infrastructure Services

# Create infrastructure stack (Postgres, Redis, Caddy, etc.)
cd /data/app

# Start infrastructure services
docker compose -f docker-compose.yml up -d

# Verify infrastructure is running
docker ps

---

9. Start IGNY8 Application

# Start application stack
cd /data/app/igny8
docker compose -f docker-compose.app.yml up -d

# Check all containers are running
docker ps -a

# View logs
docker logs igny8_backend
docker logs igny8_frontend
docker logs igny8_celery_worker

---

10. Initialize Database

# Run migrations
docker exec igny8_backend python manage.py migrate

# Create superuser
docker exec -it igny8_backend python manage.py createsuperuser

# Collect static files (if needed)
docker exec igny8_backend python manage.py collectstatic --noinput

---

11. Verify Installation

Check services:

# Backend API
curl http://localhost:8011/api/v1/system/status/

# Frontend
curl http://localhost:8021

# Access application
# Backend API: http://YOUR_SERVER_IP:8011
# Frontend App: http://YOUR_SERVER_IP:8021
# Marketing: http://YOUR_SERVER_IP:8023

Check container health:

docker ps --format "table {{.Names}}\t{{.Status}}"

---

What Happens Automatically vs. Manually

✅ AUTOMATIC (Docker handles everything):

1. Python environment setup: Docker builds venv inside container
2. Install Python packages: From requirements.txt
3. Node.js environment setup: Docker installs Node in container
4. Install npm packages: From package.json
5. Build frontend: Vite builds in dev mode
6. Database setup: PostgreSQL container starts
7. Cache setup: Redis container starts
8. Networking: Docker creates networks

🔧 MANUAL (You must do):

1. Install Docker on the host machine
2. Clone/upload the IGNY8 application folder
3. Create .env file with passwords and secrets
4. Build Docker images (docker build)
5. Start services (docker compose up)
6. Run database migrations (docker exec ... migrate)
7. Create admin user (docker exec ... createsuperuser)

---

Post-Installation

Set up SSL/HTTPS (Production)

# Update Caddyfile with your domain
# Edit /data/app/igny8/frontend/Caddyfile
# Caddy will automatically get SSL certificates from Let's Encrypt

Set up backups

# Database backup script
cat > /data/app/backup.sh << 'EOF'
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
docker exec igny8_postgres pg_dump -U igny8 igny8_db > /data/backups/pg/igny8_$DATE.sql
EOF

chmod +x /data/app/backup.sh

# Add to crontab for daily backups
crontab -e
# Add: 0 2 * * * /data/app/backup.sh

---

Updating the Application

# Pull latest code
cd /data/app/igny8
git pull origin main

# Rebuild images
docker compose -f docker-compose.app.yml build

# Restart services
docker compose -f docker-compose.app.yml down
docker compose -f docker-compose.app.yml up -d

# Run new migrations
docker exec igny8_backend python manage.py migrate

---

Troubleshooting

Containers won't start:

# Check logs
docker logs igny8_backend
docker logs igny8_postgres

# Check container status
docker ps -a

Database connection errors:

# Verify postgres is running
docker ps | grep postgres

# Check network
docker network inspect igny8_net

Port conflicts:

# Check what's using the port
sudo lsof -i :8011
sudo lsof -i :8021

---

Summary: Fresh Ubuntu to Running IGNY8

Time estimate: 15-30 minutes

1. ✅ Install Docker (5 min)
2. ✅ Install Portainer - optional (2 min)
3. ✅ Clone/upload IGNY8 app (2 min)
4. ✅ Create .env file (3 min)
5. ✅ Build Docker images (5-10 min - downloads dependencies)
6. ✅ Start infrastructure (2 min)
7. ✅ Start application (2 min)
8. ✅ Initialize database (3 min)
9. ✅ Verify and test (2 min)

Total manual commands: ~20 commands Everything else: Automated by Docker

---

Files You Need to Package

Minimum files to transfer to new server:

igny8/
├── backend/
│   ├── igny8_core/          ← Your Django code
│   ├── manage.py
│   ├── requirements.txt     ← Python deps list
│   └── Dockerfile
├── frontend/
│   ├── src/                 ← Your React code
│   ├── public/
│   ├── package.json         ← Node deps list
│   └── Dockerfile.dev
├── docker-compose.app.yml   ← Stack definition
├── .env                     ← Secrets (create on new server)
└── README.md

Total size: ~10-20 MB (without node_modules, .venv, dist)

DO NOT include:

• .venv/, node_modules/, dist/, *.sql, logs/, celerybeat-schedule

These are automatically created by Docker during build.