hms-licht-ton/README.md

# HMS Licht & Ton – Homepage & Verwaltungssystem

Die offizielle Website und Verwaltungsplattform für HMS Licht & Ton (Hammerschmidt u. Mössle GbR) aus Leipheim/Ellzee. Professionelle Veranstaltungstechnik – Vermietung, Verkauf, Personal und Transport von Tontechnik und Lichttechnik.

---

## Tech Stack

| Komponente    | Technologie                        |
|---------------|-----------------------------------|
| Frontend      | Nuxt 3 (Vue 3, TypeScript, Tailwind CSS) |
| Backend       | FastAPI (Python 3.12, async)      |
| Database      | PostgreSQL 16                     |
| Cache         | Redis 7                           |
| Deployment    | Docker Compose via Coolify        |
| CI/CD         | Forgejo Actions                   |

---

## Prerequisites

- **Node.js** 20+
- **Python** 3.12+
- **Docker** & Docker Compose
- **Git**

---

## Setup

### 1. Repository klonen

```bash
git clone https://forgejo.media-on.de/Leopoldadmin/hms-licht-ton.git
cd hms-licht-ton
```

### 2. Environment konfigurieren

```bash
cp .env.example .env
# .env mit echten Werten ausfüllen (API-Token, Secrets, SMTP, etc.)
```

### 3. Anwendung starten (Docker)

```bash
docker compose up -d
```

Die Anwendung ist danach erreichbar unter:
- **Frontend:** http://localhost:3000
- **Backend API:** http://localhost:8000
- **API Docs (Swagger):** http://localhost:8000/docs

---

## Development

### Frontend (Nuxt 3)

```bash
cd frontend
npm ci
npm run dev          # Dev-Server auf http://localhost:3000
npm test             # Unit Tests (Vitest)
npx playwright test  # E2E Tests
npm run build        # Production Build
npm run typecheck    # TypeScript Type Check
npm run lint         # ESLint
```

### Backend (FastAPI)

```bash
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
pytest -v            # Tests ausführen
```

Weitere Build- und Test-Befehle siehe [AGENTS.md](AGENTS.md).

---

## Build (Docker)

### Alle Services bauen

```bash
docker compose build
```

### Einzelne Services bauen

```bash
docker compose build frontend
docker compose build backend
```

---

## Deployment (Coolify)

Die Anwendung wird über Coolify auf `coolify-01` (46.225.91.159) deployt.

1. In Coolify ein neues Projekt "HMS Licht & Ton" anlegen.
2. Als Source das Forgejo-Repository `Leopoldadmin/hms-licht-ton` auswählen.
3. Als Deployment-Methode "Docker Compose" wählen und `docker-compose.yml` referenzieren.
4. Environment-Variablen in Coolify setzen (entsprechend `.env.example`).
5. Domain für Frontend konfigurieren (z.B. `hms.media-on.de` → Port 3000).
6. Backend-Port (8000) nur intern暴露en oder über Traefik mit eigener Subdomain.
7. Deploy auslösen. Coolify baut die Images und startet alle Services.

### Health Checks

Alle Services haben Health Checks konfiguriert:
- **Frontend:** HTTP-Check auf Port 3000
- **Backend:** HTTP-Check auf `/health` Endpoint
- **PostgreSQL:** `pg_isready`
- **Redis:** `redis-cli ping`

---

## CI/CD Pipeline (Forgejo Actions)

Die Pipeline (`.forgejo/workflows/ci.yml`) läuft bei jedem Push und PR auf `main`:

1. **frontend-test:** `npm ci` → `npm test` → `npm run build`
2. **backend-test:** `pip install` → `pytest -v`
3. **docker-build:** Baut Frontend- und Backend-Docker-Images, validiert `docker-compose.yml`

---

## Projektstruktur

```
hms-licht-ton/
├── frontend/          # Nuxt 3 Frontend
│   ├── Dockerfile
│   ├── .dockerignore
│   ├── package.json
│   ├── nuxt.config.ts
│   ├── pages/
│   ├── components/
│   ├── composables/
│   ├── stores/
│   └── tests/
├── backend/           # FastAPI Backend
│   ├── Dockerfile
│   ├── .dockerignore
│   ├── requirements.txt
│   ├── app/
│   │   ├── main.py
│   │   ├── config.py
│   │   ├── database.py
│   │   ├── auth.py
│   │   ├── cache.py
│   │   ├── routers/
│   │   └── schemas/
│   └── tests/
├── docs/              # Projektdokumentation
├── .forgejo/
│   └── workflows/
│       └── ci.yml     # CI/CD Pipeline
├── docker-compose.yml # 4 Services: frontend, backend, postgres, redis
├── .env.example       # Environment-Vorlage
├── .gitignore
├── AGENTS.md          # Build & Test Guide
└── README.md
```

---

## License

© Hammerschmidt u. Mössle GbR. Alle Rechte vorbehalten.