Configure Quartz for production
This commit is contained in:
vorpax
221
DEPLOYMENT.md
Normal file
221
DEPLOYMENT.md
Normal file
@@ -0,0 +1,221 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user