sochboard/config/CONFIGURATION.md

# Configuration de Sochboard

## Structure générale

```yaml
site:
  # Informations du site
theme:
  # Apparence
authentication:
  # Authentification (optionnel)
sections:
  # Liste des sections et liens
```

## `site`

| Champ | Requis | Type | Défaut | Description |
|---|---|---|---|---|
| `name` | Oui | chaîne | — | Nom du site (ex: "Soch Family") |
| `title` | Oui | chaîne | — | Sous-titre affiché sous le nom |
| `description` | Non | chaîne | — | Texte optionnel dans le header |
| `favicon` | Non | chaîne | — | URL ou chemin du favicon |
| `logoUrl` | Non | chaîne (URL) | — | URL d'une photo/image qui remplace le "S" |
| `showFooter` | Non | booléen | `true` | `false` pour masquer le footer |

```yaml
site:
  name: "Soch Family"
  title: "Les applications de la famille"
  description: "Accès rapide à nos services"
  logoUrl: "https://example.com/photo.jpg"
  showFooter: true
```

## `theme`

| Champ | Requis | Type | Défaut | Description |
|---|---|---|---|---|
| `mode` | Non | `"dark"` ou `"light"` | `"dark"` | Mode de couleur |
| `accent` | Non | chaîne (hex) | `"#8b5cf6"` | Couleur d'accent (ex: `"#ff0000"`) |
| `background` | Non | `"gradient"` ou `"solid"` | `"gradient"` | Type d'arrière-plan |

```yaml
theme:
  mode: "dark"
  accent: "#8b5cf6"
  background: "gradient"
```

## `authentication`

Configuration optionnelle pour l'authentification via un reverse proxy (Authelia, Authentik, etc.).

| Champ | Requis | Type | Défaut | Description |
|---|---|---|---|---|
| `logout_url` | Oui | chaîne (URL) | — | URL de déconnexion (ex: `"https://auth.example.com/logout"`) |
| `header_format` | Non | chaîne | `"Remote-User"` | Nom de l'en-tête HTTP indiquant que l'utilisateur est connecté |
| `username` | Non | chaîne | — | Nom de l'en-tête HTTP contenant le nom d'utilisateur (ex: `"Remote-Name"`). Affiche "Hi {valeur}" dans le header. |
| `header_user` | Non | chaîne | — | Nom de l'en-tête HTTP pour filtrer par utilisateur (ex: `"Remote-User"`) |
| `header_group` | Non | chaîne | — | Nom de l'en-tête HTTP pour filtrer par groupe (ex: `"Remote-Groups"`) |

Quand l'en-tête défini par `header_format` est présent dans la requête, un bouton de déconnexion apparaît à droite du bouton thème.

```yaml
authentication:
  logout_url: "https://auth.example.com/logout"
  header_format: "Remote-User"
```

## `sections`

Tableau de sections. Chaque section contient :

| Champ | Requis | Type | Défaut | Description |
|---|---|---|---|---|
| `id` | Oui | chaîne | — | Identifiant unique |
| `title` | Oui | chaîne | — | Titre affiché |
| `description` | Non | chaîne | — | Texte sous le titre |
| `cardLayout` | Non | `"horizontal"` ou `"vertical"` | `"horizontal"` | Disposition des cartes dans la section |
| `links` | Non | tableau | `[]` | Liste des liens |
| `visible_by_user` | Non | chaîne | — | Nom d'utilisateur requis pour voir cette section |
| `visible_by_group` | Non | chaîne | — | Groupe requis pour voir cette section |

```yaml
sections:
  - id: "global"
    title: "Global"
    description: "Tous les services"
    cardLayout: "horizontal"
    links: []
```

### `links`

Tableau de liens. Chaque lien contient :

| Champ | Requis | Type | Défaut | Description |
|---|---|---|---|---|
| `id` | Oui | chaîne | — | Identifiant unique |
| `name` | Oui | chaîne | — | Nom affiché |
| `description` | Non | chaîne | — | Description sous le nom |
| `url` | Oui | chaîne (URL) | — | Lien de l'application |
| `icon` | Oui | chaîne | — | Nom de l'icône Lucide |
| `iconUrl` | Non | chaîne (URL) | — | URL d'une image personnalisée (remplace `icon`) |
| `color` | Non | chaîne (hex) | — | Couleur d'accent (ex: `"#2daae1"`) |
| `openInNewTab` | Non | booléen | `true` | `false` pour ouvrir dans le même onglet |
| `visible_by_user` | Non | chaîne | — | Nom d'utilisateur requis pour voir ce lien |
| `visible_by_group` | Non | chaîne | — | Groupe requis pour voir ce lien |

```yaml
links:
  - id: "nextcloud"
    name: "Nextcloud"
    description: "Fichiers et documents"
    url: "https://cloud.example.com"
    icon: "Cloud"
    iconUrl: "https://example.com/nextcloud-icon.svg"
    color: "#2daae1"
    openInNewTab: false
```

## Icônes Lucide disponibles

```
Cloud       Film        Music       Gamepad2    Router
Server      House       BookOpen    Calendar    Mail
Shield      Settings    Globe       ExternalLink
```

Si le nom de l'icône est inconnu, `ExternalLink` est utilisé par défaut.

Si `iconUrl` est fourni, l'URL est prioritaire et `icon` sert uniquement de fallback.

Des icônes pour les applications self-hostées sont disponibles sur [dashboardicons.com](https://dashboardicons.com/).

Format CDN : `https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/<nom>.svg`

## Exemple complet

```yaml
site:
  name: "Soch Family"
  title: "Mes applis"
  logoUrl: "https://example.com/logo.png"
  showFooter: false

theme:
  mode: "dark"
  accent: "#8b5cf6"
  background: "gradient"

authentication:
  logout_url: "https://auth.example.com/logout"
  header_format: "Remote-User"

sections:
  - id: "services"
    title: "Services"
    cardLayout: "horizontal"
    links:
      - id: "nextcloud"
        name: "Nextcloud"
        url: "https://cloud.example.com"
        icon: "Cloud"
        iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/nextcloud.svg"
        color: "#2daae1"
        openInNewTab: true

  - id: "admin"
    title: "Administration"
    cardLayout: "vertical"
    links:
      - id: "mon-app"
        name: "Mon App"
        url: "https://app.example.com"
        icon: "Globe"
        iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/home-assistant.svg"
        openInNewTab: false
```