michaelschiemer/deployment/stacks/semaphore/QUICKSTART.md

# ?? Quick Start: Semaphore mit Repository verbinden

Kurze Schritt-f?r-Schritt-Anleitung, um Semaphore mit deinem Git-Repository zu verbinden.

## Schritt 1: Semaphore starten

```bash
cd deployment/stacks/semaphore
cp env.example .env
```

**WICHTIG**: Generiere einen Encryption Key:
```bash
head -c32 /dev/urandom | base64
```
Kopiere den Key und setze ihn in `.env`:
```env
SEMAPHORE_ACCESS_KEY_ENCRYPTION=<dein-generierter-key>
```

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

## Schritt 2: Semaphore ?ffnen

?ffne im Browser: **http://localhost:9300**

**Login**:
- Username: `admin`
- Password: `admin`

## Schritt 3: Projekt erstellen

1. Klicke auf **"New Project"** oder **"Create Project"**
2. Name: **"michaelschiemer"**
3. Klicke auf **"Create"**

## Schritt 4: Inventory erstellen (Hosts definieren)

### 4.1 Inventory anlegen

1. Gehe zu **Inventories** ? **New Inventory**
2. Name: **"Production Hosts"**
3. Klicke auf **"Create"**

### 4.2 Host hinzuf?gen

1. Klicke auf dein Inventory ? **"Add Host"**
2. F?lle aus:

```
Name: production
Address: 94.16.110.151
SSH Username: deploy
SSH Port: 22
```

3. Klicke auf **"Save"**

### 4.3 SSH-Key hinzuf?gen

1. Gehe zu **Keys** (in der Seitenleiste)
2. Klicke auf **"New Key"**
3. Name: **"Deployment Key"**
4. F?ge deinen SSH Private Key ein (aus `~/.ssh/production`):
   ```bash
   cat ~/.ssh/production
   ```
5. Klicke auf **"Save"**
6. Gehe zur?ck zu deinem Inventory und w?hle den Key bei deinem Host aus

## Schritt 5: Template erstellen (Playbook verwenden)

### 5.1 Template f?r CI Tests

1. Gehe zu **Templates** ? **New Template**
2. **Name**: "Run CI Tests"
3. **Inventory**: W?hle "Production Hosts"
4. **Playbook Path**: `/tmp/semaphore/playbooks/ci-tests.yml`
5. **Variables** (klicke auf "Variables"):
   ```yaml
   repo_url: https://git.michaelschiemer.de/michael/michaelschiemer.git
   repo_branch: main
   ```
6. Klicke auf **"Save"**

### 5.2 Template f?r Docker Build

1. **Templates** ? **New Template**
2. **Name**: "Build Docker Image"
3. **Inventory**: "Production Hosts"
4. **Playbook Path**: `/tmp/semaphore/playbooks/docker-build.yml`
5. **Variables**:
   ```yaml
   repo_url: https://git.michaelschiemer.de/michael/michaelschiemer.git
   repo_branch: main
   registry_url: registry.michaelschiemer.de
   registry_user: admin
   registry_password: <dein-registry-passwort>
   image_name: framework
   image_tag: latest
   ```
6. **Save**

### 5.3 Template f?r Staging Deployment

1. **Templates** ? **New Template**
2. **Name**: "Deploy to Staging"
3. **Inventory**: "Production Hosts"
4. **Playbook Path**: `/tmp/semaphore/playbooks/deploy-staging.yml`
5. **Variables**:
   ```yaml
   registry_url: registry.michaelschiemer.de
   registry_user: admin
   registry_password: <dein-registry-passwort>
   image_name: framework
   image_tag: latest
   ```
6. **Save**

### 5.4 Template f?r Production Deployment

1. **Templates** ? **New Template**
2. **Name**: "Deploy to Production"
3. **Inventory**: "Production Hosts"
4. **Playbook Path**: `/tmp/semaphore/playbooks/deploy-production.yml`
5. **Variables**:
   ```yaml
   registry_url: registry.michaelschiemer.de
   registry_user: admin
   registry_password: <dein-registry-passwort>
   image_name: framework
   image_tag: latest
   ```
6. **Save**

## Schritt 6: Task ausf?hren

1. Gehe zu **Templates**
2. Klicke auf ein Template (z.B. "Run CI Tests")
3. Klicke auf **"Run"**
4. Beobachte die Ausf?hrung in Echtzeit

## ? Fertig!

Semaphore ist jetzt mit deinem Repository verbunden! Du kannst:

- ? CI/CD-Tasks manuell starten
- ? Playbooks aus dem Repository verwenden
- ? Deployments auf deine Server ausf?hren

## ?? Verf?gbare Playbooks

Die folgenden Playbooks sind bereits im Repository und k?nnen in Semaphore verwendet werden:

1. **`/tmp/semaphore/playbooks/ci-tests.yml`** - PHP Tests & Quality Checks
2. **`/tmp/semaphore/playbooks/docker-build.yml`** - Docker Image Build & Push
3. **`/tmp/semaphore/playbooks/deploy-staging.yml`** - Staging Deployment
4. **`/tmp/semaphore/playbooks/deploy-production.yml`** - Production Deployment

## ?? Vorhandene Ansible-Playbooks

Die vorhandenen Ansible-Playbooks aus `deployment/ansible/playbooks/` sind auch verf?gbar unter:
- `/tmp/semaphore/repo-playbooks/`

Zum Beispiel:
- `/tmp/semaphore/repo-playbooks/deploy-update.yml`
- `/tmp/semaphore/repo-playbooks/rollback.yml`

## ?? Tipps

### Docker Socket f?r Build-Tasks

Falls Docker-Build-Tasks ausgef?hrt werden sollen, f?ge den Docker Socket hinzu:

In `docker-compose.yml` bei Semaphore-Service:
```yaml
volumes:
  - /var/run/docker.sock:/var/run/docker.sock:ro
```

Dann Semaphore neu starten:
```bash
docker compose restart semaphore
```

### Git-Integration

Die Playbooks k?nnen direkt auf das Git-Repository zugreifen (HTTPS). F?r private Repositories oder SSH-Zugriff:

1. Erstelle einen SSH-Key f?r Git in Semaphore (Keys ? New Key)
2. F?ge den Public Key zu deinem Git-Repository hinzu
3. Verwende SSH-URL in Playbook-Variablen:
   ```yaml
   repo_url: git@git.michaelschiemer.de:michael/michaelschiemer.git
   ```

---

**Hilfe**: Weitere Details in `SETUP_REPOSITORY.md` und `README.md`