igny8/docs/50-DEPLOYMENT/final-clean-best-deployment-plan/INFRASTRUCTURE-STACK.md

Infrastructure Stack Repository

Repository Name: igny8-stack Purpose: Reusable tech stack for Django + React applications

---

Complete Folder Structure

igny8-stack/
│
├── README.md                           # Stack overview and quick start
├── install.sh                          # Main installation script
├── uninstall.sh                        # Cleanup script
│
├── config/
│   ├── .env.example                    # Environment variables template
│   │
│   └── caddy/
│       └── Caddyfile                   # Reverse proxy configuration
│
├── docker/
│   ├── docker-compose.infra.yml        # Shared services (Postgres, Redis, Caddy)
│   └── docker-compose.app.yml          # App services template
│
├── backend/
│   ├── Dockerfile                      # Python 3.11 slim + dependencies
│   ├── requirements.txt                # Django, DRF, Celery, Gunicorn, etc.
│   ├── manage.py                       # Django CLI entry point
│   ├── container_startup.sh            # Container entrypoint script
│   └── create_groups.py                # Initial permission groups setup
│
├── frontend/
│   ├── Dockerfile.dev                  # Vite dev server with HMR
│   ├── Dockerfile.prod                 # Production build with Caddy
│   ├── Dockerfile.marketing.dev        # Marketing site dev server
│   ├── package.json                    # React, Vite, Tailwind, Zustand, etc.
│   ├── package-lock.json               # Locked dependency versions
│   ├── vite.config.ts                  # Vite configuration
│   ├── tsconfig.json                   # TypeScript base config
│   ├── tsconfig.app.json               # App TypeScript config
│   ├── tsconfig.node.json              # Node TypeScript config
│   ├── postcss.config.js               # PostCSS for Tailwind
│   ├── eslint.config.js                # ESLint rules
│   ├── index.html                      # Main app HTML template
│   └── marketing.html                  # Marketing site HTML template
│
└── scripts/
    ├── build-images.sh                 # Build all Docker images
    ├── migrate.sh                      # Run Django migrations
    ├── backup-db.sh                    # Database backup utility
    ├── restore-db.sh                   # Database restore utility
    └── health-check.sh                 # System health check

---

File Purposes

Root Files

File	Purpose
install.sh	Creates directories, symlinks, builds images, sets up network
uninstall.sh	Removes symlinks and cleans up (keeps data)

Config Folder

File	Purpose
.env.example	Template for environment variables (DB passwords, secrets, domains)
caddy/Caddyfile	Routes domains to containers, handles SSL, WebSocket proxying

Docker Folder

File	Purpose
docker-compose.infra.yml	Postgres, Redis, Caddy, PgAdmin, FileBrowser, Portainer
docker-compose.app.yml	Backend, Frontend, Celery Worker, Celery Beat, Flower

Backend Folder

File	Purpose
Dockerfile	Python 3.11 slim, installs requirements, runs Gunicorn
requirements.txt	All Python dependencies (Django 5.x, DRF, Celery, etc.)
manage.py	Django management command entry point
container_startup.sh	Logs startup, runs migrations if needed
create_groups.py	Creates initial Django permission groups

Frontend Folder

File	Purpose
Dockerfile.dev	Node 18, Vite dev server with hot reload
Dockerfile.prod	Multi-stage build, Caddy serves static files
Dockerfile.marketing.dev	Marketing site dev server (port 5174)
package.json	All npm dependencies
vite.config.ts	Build config, HMR settings, code splitting
tsconfig*.json	TypeScript compiler settings
postcss.config.js	Tailwind CSS processing
eslint.config.js	Code linting rules
index.html	Main app entry HTML
marketing.html	Marketing site entry HTML

Scripts Folder

Script	Purpose
build-images.sh	Builds all Docker images with proper tags
migrate.sh	Runs Django migrations inside container
backup-db.sh	Dumps PostgreSQL database to backup file
restore-db.sh	Restores database from backup file
health-check.sh	Checks all services are running

---

New Server Installation

Prerequisites

• Ubuntu 22.04+ or Debian 12+
• Docker and Docker Compose installed
• Git installed
• Domain DNS pointing to server IP

Step-by-Step Installation

1. Create directories
   mkdir -p /data/stack /data/app /data/logs

2. Clone stack repository
   cd /data/stack
   git clone https://github.com/yourorg/igny8-stack.git

3. Run installation script
   cd igny8-stack
   chmod +x install.sh
   ./install.sh

4. Verify installation
   docker images          # Should show app-backend, app-frontend images
   docker network ls      # Should show igny8_net
   ls -la /data/app/      # Should show prepared structure

What install.sh Does

1. Creates Docker network (igny8_net)
2. Creates directory structure under /data/app/
3. Builds Docker images:
   • app-backend:latest
   • app-frontend-dev:latest
   • app-marketing-dev:latest
4. Starts infrastructure services (Postgres, Redis, Caddy)
5. Creates symlinks for app folder structure
6. Prints next steps

---

Updating Stack on Existing Server

1. Pull latest changes
   cd /data/stack/igny8-stack
   git pull

2. Rebuild images if Dockerfile changed
   ./scripts/build-images.sh

3. Restart containers to use new images
   cd /data/app/igny8
   docker compose -f docker-compose.app.yml down
   docker compose -f docker-compose.app.yml up -d

4. Verify
   docker ps
   ./scripts/health-check.sh

---

Customizing for Different Apps

The stack is designed to run any Django + React application. To use it for a different app (not igny8):

1. Clone stack to new server
2. Run install.sh
3. Clone your app repo to /data/app/yourapp/
4. Update .env with your app's settings
5. Update Caddyfile with your domains
6. Start containers

The stack doesn't contain any igny8-specific logic - it's a generic Django+React runtime environment.

---

Environment Variables

Key variables to set in .env:

Variable	Purpose	Example
DB_HOST	PostgreSQL host	postgres
DB_NAME	Database name	igny8_db
DB_USER	Database user	igny8
DB_PASSWORD	Database password	secure_password
REDIS_HOST	Redis host	redis
SECRET_KEY	Django secret key	random_50_char_string
DOMAIN	Primary domain	igny8.com
DEBUG	Debug mode	False

---

Related Documentation

• TWO-REPO-ARCHITECTURE.md - Why two repos
• IGNY8-APP-STRUCTURE.md - App-specific code structure