docs: Add FreeBSD build guide
Complete guide for building and deploying on FreeBSD including: - Go installation instructions - Build process and troubleshooting - Production deployment with rc.d service - Common issues and solutions
This commit is contained in:
296
docs/FREEBSD_BUILD.md
Normal file
296
docs/FREEBSD_BUILD.md
Normal file
@ -0,0 +1,296 @@
|
||||
# Guide de Build pour FreeBSD
|
||||
|
||||
## Prérequis
|
||||
|
||||
### Installation de Go sur FreeBSD
|
||||
|
||||
```bash
|
||||
# Installer Go depuis les packages
|
||||
pkg install go
|
||||
|
||||
# Ou compiler depuis les ports
|
||||
cd /usr/ports/lang/go && make install clean
|
||||
|
||||
# Vérifier l'installation
|
||||
go version
|
||||
```
|
||||
|
||||
## Clonage du projet
|
||||
|
||||
```bash
|
||||
# Cloner le repository
|
||||
git clone https://github.com/mathieu/project-notes.git
|
||||
cd project-notes
|
||||
|
||||
# Vérifier que tous les fichiers Go sont présents
|
||||
find . -name "*.go" | sort
|
||||
```
|
||||
|
||||
**Fichiers Go requis :**
|
||||
```
|
||||
./cmd/server/main.go # Point d'entrée principal
|
||||
./internal/api/daily_notes.go # Gestion des notes quotidiennes
|
||||
./internal/api/favorites.go # API des favoris
|
||||
./internal/api/handler.go # Handler HTTP principal
|
||||
./internal/api/handler_test.go # Tests unitaires
|
||||
./internal/api/rest_handler.go # API REST
|
||||
./internal/indexer/indexer.go # Indexation et recherche
|
||||
./internal/indexer/indexer_test.go # Tests indexeur
|
||||
./internal/watcher/watcher.go # Surveillance fichiers
|
||||
```
|
||||
|
||||
## Build
|
||||
|
||||
### 1. Télécharger les dépendances
|
||||
|
||||
```bash
|
||||
go mod download
|
||||
```
|
||||
|
||||
**Dépendances requises :**
|
||||
- `github.com/fsnotify/fsnotify v1.7.0` - Surveillance système de fichiers
|
||||
- `gopkg.in/yaml.v3 v3.0.1` - Parsing YAML front matter
|
||||
- `golang.org/x/sys v0.4.0` - API système (indirect)
|
||||
|
||||
### 2. Vérifier les dépendances
|
||||
|
||||
```bash
|
||||
go mod tidy
|
||||
```
|
||||
|
||||
**Note :** Si `go mod tidy` ne produit aucune sortie, c'est normal ! Cela signifie que le fichier `go.mod` est déjà à jour.
|
||||
|
||||
### 3. Compiler
|
||||
|
||||
```bash
|
||||
# Compilation standard
|
||||
go build -o server ./cmd/server
|
||||
|
||||
# Avec optimisations
|
||||
go build -ldflags="-s -w" -o server ./cmd/server
|
||||
|
||||
# Build statique (recommandé pour FreeBSD)
|
||||
CGO_ENABLED=0 go build -ldflags="-s -w" -o server ./cmd/server
|
||||
```
|
||||
|
||||
### 4. Vérifier le binaire
|
||||
|
||||
```bash
|
||||
file ./server
|
||||
./server --help
|
||||
```
|
||||
|
||||
## Lancement
|
||||
|
||||
### Mode développement
|
||||
|
||||
```bash
|
||||
# Lancer directement avec go run
|
||||
go run ./cmd/server
|
||||
|
||||
# Ou avec le binaire compilé
|
||||
./server
|
||||
```
|
||||
|
||||
Le serveur démarre sur `http://localhost:8080`
|
||||
|
||||
### Mode production
|
||||
|
||||
```bash
|
||||
# Copier le binaire
|
||||
cp server /usr/local/bin/project-notes
|
||||
|
||||
# Créer un utilisateur dédié
|
||||
pw useradd -n notes -c "Project Notes" -d /var/notes -s /usr/sbin/nologin
|
||||
|
||||
# Créer le dossier de notes
|
||||
mkdir -p /var/notes/notes
|
||||
chown -R notes:notes /var/notes
|
||||
|
||||
# Lancer avec l'utilisateur dédié
|
||||
su -m notes -c '/usr/local/bin/project-notes'
|
||||
```
|
||||
|
||||
## Dépannage
|
||||
|
||||
### Problème : `go mod tidy` ne fait rien
|
||||
|
||||
**C'est normal !** Si `go mod tidy` ne produit aucune sortie et retourne immédiatement, cela signifie que :
|
||||
- Toutes les dépendances sont déjà listées dans `go.mod`
|
||||
- Aucune dépendance inutilisée n'est présente
|
||||
- Le fichier `go.sum` est à jour
|
||||
|
||||
Pour vérifier que tout est OK :
|
||||
```bash
|
||||
# Vérifier les dépendances
|
||||
go list -m all
|
||||
|
||||
# Télécharger les dépendances si nécessaire
|
||||
go mod download
|
||||
|
||||
# Compiler pour vérifier
|
||||
go build ./cmd/server
|
||||
```
|
||||
|
||||
### Problème : Erreurs de compilation
|
||||
|
||||
```bash
|
||||
# Nettoyer le cache
|
||||
go clean -cache -modcache -testcache
|
||||
|
||||
# Re-télécharger les dépendances
|
||||
go mod download
|
||||
|
||||
# Recompiler
|
||||
go build ./cmd/server
|
||||
```
|
||||
|
||||
### Problème : Dépendances manquantes
|
||||
|
||||
```bash
|
||||
# Vérifier que go.mod et go.sum sont présents
|
||||
ls -la go.mod go.sum
|
||||
|
||||
# Re-synchroniser
|
||||
go mod tidy
|
||||
go mod download
|
||||
```
|
||||
|
||||
### Problème : Fichiers Go manquants
|
||||
|
||||
Si des fichiers `.go` sont manquants, c'était dû à un bug dans le `.gitignore` qui ignorait le dossier `cmd/server/`.
|
||||
|
||||
**Vérifié et corrigé !** Le `.gitignore` a été corrigé pour utiliser `/server` au lieu de `server`, ce qui ignore uniquement le binaire à la racine et non le dossier source.
|
||||
|
||||
Vérifier que tous les fichiers sont présents :
|
||||
```bash
|
||||
git ls-files | grep -E '\.(go|mod|sum)$'
|
||||
```
|
||||
|
||||
Devrait afficher 11 fichiers (1 go.mod, 1 go.sum, 9 fichiers .go).
|
||||
|
||||
## Tests
|
||||
|
||||
```bash
|
||||
# Lancer tous les tests
|
||||
go test ./...
|
||||
|
||||
# Tests avec verbosité
|
||||
go test -v ./...
|
||||
|
||||
# Tests avec couverture
|
||||
go test -cover ./...
|
||||
|
||||
# Tests d'un package spécifique
|
||||
go test -v ./internal/api
|
||||
go test -v ./internal/indexer
|
||||
```
|
||||
|
||||
## Optimisations FreeBSD
|
||||
|
||||
### 1. Build statique
|
||||
|
||||
Pour éviter les dépendances dynamiques :
|
||||
```bash
|
||||
CGO_ENABLED=0 GOOS=freebsd GOARCH=amd64 go build -ldflags="-s -w" -o server ./cmd/server
|
||||
```
|
||||
|
||||
### 2. Service rc.d
|
||||
|
||||
Créer `/usr/local/etc/rc.d/project_notes` :
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
#
|
||||
# PROVIDE: project_notes
|
||||
# REQUIRE: NETWORKING
|
||||
# KEYWORD: shutdown
|
||||
|
||||
. /etc/rc.subr
|
||||
|
||||
name="project_notes"
|
||||
rcvar="project_notes_enable"
|
||||
command="/usr/local/bin/project-notes"
|
||||
command_args=""
|
||||
pidfile="/var/run/${name}.pid"
|
||||
project_notes_user="notes"
|
||||
project_notes_chdir="/var/notes"
|
||||
|
||||
load_rc_config $name
|
||||
run_rc_command "$1"
|
||||
```
|
||||
|
||||
Activer au démarrage :
|
||||
```bash
|
||||
chmod +x /usr/local/etc/rc.d/project_notes
|
||||
sysrc project_notes_enable="YES"
|
||||
service project_notes start
|
||||
```
|
||||
|
||||
### 3. Surveillance avec daemon(8)
|
||||
|
||||
```bash
|
||||
daemon -p /var/run/project-notes.pid -u notes -r /usr/local/bin/project-notes
|
||||
```
|
||||
|
||||
## Architecture du projet
|
||||
|
||||
```
|
||||
project-notes/
|
||||
├── cmd/
|
||||
│ └── server/
|
||||
│ └── main.go # Point d'entrée
|
||||
├── internal/
|
||||
│ ├── api/ # Handlers HTTP
|
||||
│ │ ├── handler.go # Handler principal
|
||||
│ │ ├── rest_handler.go # API REST
|
||||
│ │ ├── daily_notes.go # Notes quotidiennes
|
||||
│ │ ├── favorites.go # Favoris
|
||||
│ │ └── handler_test.go # Tests
|
||||
│ ├── indexer/ # Recherche full-text
|
||||
│ │ ├── indexer.go
|
||||
│ │ └── indexer_test.go
|
||||
│ └── watcher/ # Surveillance fichiers
|
||||
│ └── watcher.go
|
||||
├── frontend/ # Frontend Vite
|
||||
├── static/ # Assets statiques
|
||||
├── templates/ # Templates HTML
|
||||
├── notes/ # Notes Markdown
|
||||
├── go.mod # Dépendances Go
|
||||
├── go.sum # Checksums
|
||||
└── README.md # Documentation
|
||||
```
|
||||
|
||||
## Vérification finale
|
||||
|
||||
```bash
|
||||
# Tous les fichiers sont présents ?
|
||||
git ls-files | grep -E '\.(go|mod|sum)$' | wc -l
|
||||
# Doit afficher : 11
|
||||
|
||||
# Compilation réussie ?
|
||||
go build -o server ./cmd/server && echo "✅ Build OK"
|
||||
|
||||
# Tests passent ?
|
||||
go test ./... && echo "✅ Tests OK"
|
||||
|
||||
# Binaire fonctionne ?
|
||||
./server &
|
||||
sleep 2
|
||||
curl http://localhost:8080/ && echo "✅ Server OK"
|
||||
pkill -f ./server
|
||||
```
|
||||
|
||||
## Support
|
||||
|
||||
Pour toute question ou problème de build sous FreeBSD, vérifier :
|
||||
1. Version de Go : `go version` (minimum 1.22)
|
||||
2. Variables d'environnement : `go env`
|
||||
3. Fichiers présents : `git status` et `git ls-files`
|
||||
4. Logs de compilation : `go build -v ./cmd/server`
|
||||
|
||||
---
|
||||
|
||||
**Dernière mise à jour :** 11 novembre 2025
|
||||
**Testé sur :** FreeBSD 13.x et 14.x
|
||||
**Version Go minimale :** 1.22
|
||||
Reference in New Issue
Block a user