wiki/DEPLOYMENT.md

# Déploiement Quartz Wiki

Ce document explique comment déployer le site Quartz sur votre infrastructure homelab.

## 📋 Prérequis

- Instance Gitea avec Gitea Actions activé
- Gitea Container Registry configuré
- Secret `REGISTRY_TOKEN` configuré dans votre dépôt Gitea
- Serveur avec Docker et Docker Compose
- Traefik configuré comme reverse proxy (réseau `public`)

## 🔧 Configuration Initiale

### 1. Créer le Token Registry Gitea

1. Aller dans **Settings → Applications** de votre compte Gitea
2. Créer un nouveau token avec les permissions `write:package`
3. Ajouter ce token comme secret `REGISTRY_TOKEN` dans votre dépôt

### 2. Configurer Traefik (Optionnel)

Si vous utilisez Traefik, ajoutez ces labels dans `docker-compose.yml`:

```yaml
services:
  quartz:
    image: gitea.vorpax.dev/vorpax/quartz-wiki:latest
    container_name: quartz-wiki
    restart: unless-stopped

    networks:
      - public

    labels:
      # Enable Traefik
      - "traefik.enable=true"

      # HTTP Router
      - "traefik.http.routers.quartz.rule=Host(`wiki.vorpax.dev`)"
      - "traefik.http.routers.quartz.entrypoints=websecure"
      - "traefik.http.routers.quartz.tls=true"
      - "traefik.http.routers.quartz.tls.certresolver=letsencrypt"

      # Service
      - "traefik.http.services.quartz.loadbalancer.server.port=80"

      # HTTP to HTTPS redirect
      - "traefik.http.routers.quartz-http.rule=Host(`wiki.vorpax.dev`)"
      - "traefik.http.routers.quartz-http.entrypoints=web"
      - "traefik.http.routers.quartz-http.middlewares=redirect-to-https"
```

## 🚀 Déploiement

### Workflow Automatique (Recommandé)

1. **Commit et Push vers v4**:
   ```bash
   git add .
   git commit -m "Update content"
   git push origin v4
   ```

2. **Le workflow Gitea Actions va automatiquement**:
   - Builder l'image Docker
   - Pusher vers `gitea.vorpax.dev/vorpax/quartz-wiki`
   - Tagger avec `latest`, `v4`, et le SHA du commit

3. **Sur votre serveur de production**:
   ```bash
   # Se connecter au registry Gitea
   docker login gitea.vorpax.dev

   # Pull la nouvelle image
   docker compose pull

   # Redémarrer le container
   docker compose up -d
   ```

### Build Local (Pour Testing)

```bash
# Build l'image localement
docker compose build

# Ou utiliser Dockerfile.prod directement
docker build -f Dockerfile.prod -t quartz-wiki:local .

# Lancer
docker compose up -d
```

### Développement Local

Pour le développement avec hot-reload:

```bash
# Option 1: npx quartz
npx quartz build --serve
# Accessible sur http://localhost:8080

# Option 2: Docker dev
docker build -f Dockerfile.dev -t quartz-dev .
docker run -p 8080:8080 quartz-dev
```

## 📁 Structure du Projet

```
.
├── content/                    # Contenu du site
│   ├── blog/                  # Articles de blog
│   ├── homelab/               # Documentation homelab
│   │   ├── hardware/          # Pages hardware
│   │   ├── infrastructure/    # Infra docs
│   │   ├── services/          # Services docs
│   │   └── guides/            # Guides
│   └── templates/             # Templates Templater (non publiés)
├── quartz/                    # Code source Quartz
├── quartz.config.ts           # Configuration Quartz
├── quartz.layout.ts           # Layout et composants
├── Dockerfile.prod            # Dockerfile production (Nginx)
├── Dockerfile.dev             # Dockerfile dev (--serve)
├── nginx.conf                 # Config Nginx
├── docker-compose.yml         # Orchestration Docker
└── .gitea/workflows/          # CI/CD Gitea Actions
```

## 🔄 Workflow de Publication

### Avec Obsidian

1. **Éditer dans Obsidian**:
   - Ouvrir le vault pointant vers `/content`
   - Utiliser les templates dans `content/templates/`
   - Ajouter `publish: true` dans le frontmatter

2. **Utiliser Templater**:
   - Installer le plugin Templater dans Obsidian
   - Configurer le dossier de templates: `content/templates`
   - Créer une nouvelle note avec un template (Ctrl+P → "Templater: Create new note from template")

3. **Publier**:
   ```bash
   git add content/
   git commit -m "Add new blog post"
   git push origin v4
   ```

### Sans Obsidian

Créer un fichier markdown dans `content/blog/` ou `content/homelab/`:

```yaml
---
title: "Mon Article"
publish: true
date: 2026-01-05
tags:
  - homelab
  - docker
description: "Description courte"
---

# Contenu ici
```

## 🏷️ Tags d'Images Disponibles

Le workflow crée plusieurs tags:

- `gitea.vorpax.dev/vorpax/quartz-wiki:latest` - Dernière version de la branche v4
- `gitea.vorpax.dev/vorpax/quartz-wiki:v4` - Tag de branche
- `gitea.vorpax.dev/vorpax/quartz-wiki:<sha>` - Tag par commit SHA

## 🔍 Troubleshooting

### L'image ne se build pas dans Gitea Actions

Vérifier que:
- Le secret `REGISTRY_TOKEN` est configuré
- Gitea Container Registry est activé
- Le runner Gitea Actions fonctionne

### Les changements n'apparaissent pas

```bash
# Forcer un nouveau pull
docker compose down
docker compose pull
docker compose up -d

# Vérifier les logs
docker logs quartz-wiki
```

### 404 sur certaines pages

Vérifier que:
- La page a `publish: true` dans le frontmatter
- Le fichier est dans `content/`
- Les wikilinks utilisent le bon chemin

## 📊 Métriques

Le site est configuré avec Plausible Analytics sur `wiki.vorpax.dev`. Vérifiez `quartz.config.ts:15-17` pour la configuration.

## 🔐 Sécurité

- Les fichiers dans `content/templates/` ne sont jamais publiés
- Les fichiers dans `content/private/` sont exclus du build
- Le dossier `.obsidian/` n'est pas versionné
- Nginx inclut des headers de sécurité (X-Frame-Options, X-Content-Type-Options, etc.)

## 📚 Resources

- [Documentation Quartz](https://quartz.jzhao.xyz/)
- [Gitea Actions Docs](https://docs.gitea.com/usage/actions/overview)
- [Gitea Container Registry](https://docs.gitea.com/usage/packages/container)