michaelschiemer/deployment/stacks/semaphore/SETUP_REPOSITORY.md

# Git-Repository in Semaphore Self-Hosted integrieren

Diese Anleitung beschreibt, wie du dein Git-Repository in Semaphore Self-Hosted (Ansible-UI) integrierst.

## ?? ?bersicht

Semaphore Self-Hosted ist eine Web-UI f?r Ansible, die es erm?glicht:
- Ansible-Playbooks ?ber eine grafische Oberfl?che auszuf?hren
- CI/CD-Workflows mit Ansible zu automatisieren
- Git-Repositories als Playbook-Quellen zu verwenden

## ?? Schritt 1: Semaphore starten

### 1.1 Environment-Datei erstellen

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

### 1.2 Encryption Key generieren (WICHTIG!)

```bash
# Linux/WSL
head -c32 /dev/urandom | base64

# Windows PowerShell
-join ((48..57) + (65..90) + (97..122) | Get-Random -Count 32 | % {[char]$_}) | ConvertTo-Base64
```

Kopiere den generierten Key und setze ihn in `.env`:
```env
SEMAPHORE_ACCESS_KEY_ENCRYPTION=<dein-generierter-key>
```

### 1.3 Stack starten

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

### 1.4 Web-UI ?ffnen

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

?? **WICHTIG**: Semaphore ist NUR lokal zug?nglich (127.0.0.1). Es gibt KEINEN externen Zugriff aus Sicherheitsgr?nden!

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

## ?? Schritt 2: Projekt in Semaphore erstellen

### 2.1 Neues Projekt anlegen

1. Melde dich in Semaphore an
2. Klicke auf **"New Project"** oder **"Create Project"**
3. Gib einen Projektnamen ein: **"michaelschiemer"**
4. Klicke auf **"Create"**

### 2.2 Git-Repository als Playbook-Quelle hinzuf?gen

Semaphore Self-Hosted kann Playbooks direkt aus Git-Repositories laden. Du hast zwei Optionen:

**Option A: Playbooks aus Repository-Clone verwenden** (Empfohlen)

1. Clone dein Repository lokal:
```bash
git clone https://git.michaelschiemer.de/michael/michaelschiemer.git
cd michaelschiemer
```

2. Erstelle ein Playbook-Verzeichnis f?r Semaphore:
```bash
mkdir -p deployment/stacks/semaphore/playbooks
cp deployment/ansible/playbooks/*.yml deployment/stacks/semaphore/playbooks/
```

**Option B: Playbooks direkt in Semaphore einf?gen**

Semaphore kann auch Playbooks direkt im Web-UI erstellen/bearbeiten. F?r Git-Integration ist Option A besser.

## ??? Schritt 3: Inventory erstellen

Ein Inventory definiert die Hosts, auf denen Playbooks ausgef?hrt werden.

### 3.1 Inventory anlegen

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

### 3.2 Host hinzuf?gen

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

**F?r Production-Deployment:**
```
Name: production
Address: 94.16.110.151
SSH Username: deploy
SSH Port: 22
```

**F?r Staging-Deployment:**
```
Name: staging
Address: 94.16.110.151  # oder dein Staging-Host
SSH Username: deploy
SSH Port: 22
```

### 3.3 SSH-Key hinzuf?gen

1. Gehe zu **Keys** (Seitenleiste)
2. Klicke auf **"New Key"**
3. Gib einen Namen ein: **"Deployment Key"**
4. F?ge deinen SSH Private Key ein (aus `~/.ssh/production` oder ?hnlich)
5. W?hle den Key im Host-Inventory aus

## ?? Schritt 4: Template erstellen

Templates verbinden Playbooks mit Inventories und definieren Parameter.

### 4.1 Template f?r Tests erstellen

1. Gehe zu **Templates** ? **New Template**
2. Template-Name: **"Run PHP Tests"**
3. Inventory: W?hle dein Inventory
4. Playbook: Erstelle ein Playbook oder verwende ein vorhandenes:

```yaml
---
- name: Run PHP Tests
  hosts: localhost
  gather_facts: no
  tasks:
    - name: Checkout repository
      git:
        repo: https://git.michaelschiemer.de/michael/michaelschiemer.git
        dest: /tmp/ci-build
        version: main

    - name: Install dependencies
      command: composer install --no-interaction --prefer-dist
      args:
        chdir: /tmp/ci-build

    - name: Run tests
      command: ./vendor/bin/pest
      args:
        chdir: /tmp/ci-build
      register: test_result

    - name: Show test results
      debug:
        var: test_result.stdout_lines
```

5. Speichere das Template

### 4.2 Template f?r Build erstellen

Erstelle ein Template f?r Docker Image Build:

```yaml
---
- name: Build and Push Docker Image
  hosts: localhost
  gather_facts: no
  tasks:
    - name: Checkout repository
      git:
        repo: https://git.michaelschiemer.de/michael/michaelschiemer.git
        dest: /tmp/ci-build
        version: main

    - name: Login to Docker registry
      docker_login:
        username: "{{ registry_user }}"
        password: "{{ registry_password }}"
        registry_url: "{{ registry_url }}"
      vars:
        registry_user: "admin"
        registry_url: "registry.michaelschiemer.de"

    - name: Build Docker image
      docker_image:
        name: "{{ registry_url }}/framework:{{ image_tag }}"
        tag: "{{ image_tag }}"
        source: build
        build:
          path: /tmp/ci-build
          dockerfile: Dockerfile.production
        push: yes
      vars:
        registry_url: "registry.michaelschiemer.de"
        image_tag: "latest"
```

### 4.3 Template f?r Deployment erstellen

Erstelle ein Template f?r Production-Deployment (verwendet die vorhandenen Ansible-Playbooks):

```yaml
---
- name: Deploy to Production
  hosts: production
  gather_facts: yes
  become: yes
  tasks:
    - name: Checkout deployment scripts
      git:
        repo: https://git.michaelschiemer.de/michael/michaelschiemer.git
        dest: /tmp/deployment
        version: main

    - name: Include deployment playbook
      include_role:
        name: deployment/ansible/playbooks/deploy-update.yml
```

Oder verwende die vorhandenen Ansible-Playbooks direkt:

**Vorteil**: Die vorhandenen Playbooks in `deployment/ansible/playbooks/` k?nnen direkt verwendet werden!

1. Erstelle ein Template: **"Deploy to Production"**
2. W?hle Inventory: **"Production Hosts"**
3. Playbook-Pfad: **`deployment/ansible/playbooks/deploy-update.yml`**
4. Speichere

## ?? Schritt 5: CI/CD-Workflow einrichten

### 5.1 Git-Webhook konfigurieren (Optional)

Semaphore kann Webhooks von Git-Repositories empfangen, um automatisch Tasks zu starten.

1. Gehe zu deinem Git-Repository (Gitea)
2. Settings ? Webhooks ? Add Webhook
3. Webhook-URL: `http://localhost:9300/api/hook/git` (nur lokal!)
4. Content-Type: `application/json`
5. Secret: Optional, aber empfohlen

### 5.2 Task manuell starten

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

### 5.3 Task automatisch starten

Semaphore kann Tasks basierend auf Git-Events starten:

1. Gehe zu Template ? **Settings**
2. Aktiviere **"Auto Run on Push"**
3. W?hle Branch: `main` oder `staging`
4. Speichere

## ?? Verwendung vorhandener Ansible-Playbooks

### Vorhandene Playbooks verwenden

Die vorhandenen Ansible-Playbooks in `deployment/ansible/playbooks/` k?nnen direkt in Semaphore verwendet werden:

1. **Mounte Playbooks als Volume** (in `docker-compose.yml`):
```yaml
volumes:
  - ./../../ansible/playbooks:/tmp/semaphore/playbooks:ro
```

2. **Erstelle Templates**, die auf diese Playbooks verweisen:
   - Playbook-Pfad: `/tmp/semaphore/playbooks/deploy-update.yml`
   - Inventory: W?hle dein Production-Inventory

### Beispiel-Templates

#### Template: Deploy Update
- Name: "Deploy Update"
- Inventory: "Production Hosts"
- Playbook: `/tmp/semaphore/playbooks/deploy-update.yml`
- Variables:
  ```yaml
  registry_url: registry.michaelschiemer.de
  image_name: framework
  image_tag: latest
  ```

#### Template: Rollback
- Name: "Rollback"
- Inventory: "Production Hosts"
- Playbook: `/tmp/semaphore/playbooks/rollback.yml`
- Variables:
  ```yaml
  registry_url: registry.michaelschiemer.de
  image_name: framework
  ```

## ?? Erweiterte Konfiguration

### Docker Socket f?r Build-Tasks

F?r Docker-Build-Tasks muss der Semaphore-Container Zugriff auf den Docker-Socket haben:

**In `docker-compose.yml` hinzuf?gen:**
```yaml
volumes:
  - /var/run/docker.sock:/var/run/docker.sock:ro
```

### Environment-Variablen f?r Templates

Du kannst Environment-Variablen in Templates verwenden:

1. Gehe zu Template ? **Variables**
2. F?ge Variablen hinzu:
   - `registry_url`: `registry.michaelschiemer.de`
   - `registry_user`: `admin`
   - `image_name`: `framework`

### Git-Integration mit SSH-Keys

F?r private Repositories:

1. Gehe zu **Keys**
2. Erstelle einen SSH-Key f?r Git-Access
3. F?ge den Public Key zu deinem Git-Repository hinzu (Deploy Keys)
4. Verwende SSH-URL in Git-Tasks:
   ```yaml
   git:
     repo: git@git.michaelschiemer.de:michael/michaelschiemer.git
   ```

## ?? N?tzliche Links

- [Semaphore Self-Hosted Dokumentation](https://docs.ansible-semaphore.com/)
- [Ansible Semaphore GitHub](https://github.com/ansible-semaphore/semaphore)
- [Ansible Playbook Dokumentation](https://docs.ansible.com/ansible/latest/playbook_guide/index.html)

## ? Checkliste

- [ ] Semaphore gestartet (http://localhost:9300)
- [ ] Projekt erstellt
- [ ] Inventory mit Hosts erstellt
- [ ] SSH-Keys f?r Host-Zugriff konfiguriert
- [ ] Template f?r Tests erstellt
- [ ] Template f?r Build erstellt
- [ ] Template f?r Deployment erstellt
- [ ] Erstes Template erfolgreich ausgef?hrt
- [ ] Git-Webhook konfiguriert (optional)

---

**N?chste Schritte**: Starte Semaphore und erstelle dein erstes Template!