# 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](TWO-REPO-ARCHITECTURE.md) - Why two repos
- [IGNY8-APP-STRUCTURE.md](IGNY8-APP-STRUCTURE.md) - App-specific code structure