diff options
| -rw-r--r-- | Makefile | 47 | ||||
| -rw-r--r-- | README.md | 267 | ||||
| -rw-r--r-- | internal/orchestrator/README.md | 235 |
3 files changed, 121 insertions, 428 deletions
@@ -1,4 +1,4 @@ -.PHONY: build run test clean proto docker-build docker-run docker-stop docker-clean docker-logs +.PHONY: build run test clean proto build: go build -o bin/server ./cmd/server @@ -7,10 +7,7 @@ run: go run ./cmd/server test: - go test ./... - -test-orchestrator: - go test ./internal/orchestrator -v + go test ./... -v proto: protoc \ @@ -19,42 +16,4 @@ proto: proto/*.proto clean: - rm -rf bin/ - -# Docker commands -docker-build: - docker build -t sovrabase:latest . - -docker-run: - docker compose up -d - -docker-stop: - docker compose stop - -docker-down: - docker compose down - -docker-clean: - docker compose down -v - docker rmi sovrabase:latest || true - -docker-logs: - docker compose logs -f sovrabase - -docker-shell: - docker compose exec sovrabase sh - -# Setup config from example -setup-config: - @if [ ! -f config.yaml ]; then \ - cp config.example.yaml config.yaml; \ - echo "✅ config.yaml created from example. Please edit it before running!"; \ - else \ - echo "⚠️ config.yaml already exists"; \ - fi - -# Quick start (setup + build + run) -start: setup-config docker-build docker-run - @echo "🚀 Sovrabase is starting..." - @echo "📝 Check logs with: make docker-logs" - @echo "🔍 Health check: curl http://localhost:8080/health" + rm -rf bin/* @@ -11,14 +11,28 @@ Sovrabase est une alternative souveraine à Firebase/Supabase : contrôle total, ## 🚀 Quick Start ```bash +# 1. Cloner le dépôt git clone https://github.com/ketsuna-org/sovrabase.git cd sovrabase -cp config.example.yaml config.yaml # Éditez config.yaml + +# 2. Créer votre fichier de configuration +cp config.example.yaml config.yaml + +# 3. Éditer config.yaml et modifier au minimum : +# - super_user.password (OBLIGATOIRE !) +# - api.api_addr (par défaut "0.0.0.0:8080") +# - orchestrator.docker_host (par défaut "unix:///var/run/docker.sock") + +# 4. Lancer Sovrabase avec Docker Compose docker compose up -d + +# 5. Vérifier que tout fonctionne curl http://localhost:8080/health ``` -Voir [docs/config.md](docs/config.md) pour la config détaillée. +> **⚠️ Important** : Modifiez impérativement le mot de passe du super utilisateur dans `config.yaml` avant le premier lancement ! + +Voir [docs/config.md](docs/config.md) pour la configuration détaillée. ## 📦 Fonctionnalités principales @@ -144,217 +158,172 @@ Sovrabase est conçu pour les entreprises exigeantes en matière de conformité --- -## 🐳 Installation et Déploiement avec Docker +## 🐳 Installation et Déploiement + +Sovrabase utilise Docker pour orchestrer les bases de données des projets. L'application s'exécute dans un conteneur et communique avec le daemon Docker de l'hôte. + +### Prérequis + +- Docker Engine 20.10+ +- Docker Compose V2 -Sovrabase utilise Docker pour orchestrer les bases de données des projets. L'application elle-même s'exécute dans un conteneur et a besoin d'accéder au daemon Docker de l'hôte. +### Déploiement avec Docker Compose (recommandé) -### 🚀 Quick Start +Le projet inclut un fichier `docker-compose.yml` prêt à l'emploi : ```bash -# 1. Cloner le repository +# 1. Cloner le dépôt git clone https://github.com/ketsuna-org/sovrabase.git cd sovrabase # 2. Créer votre fichier de configuration cp config.example.yaml config.yaml -# Éditez config.yaml avec vos paramètres (notamment le JWT secret!) -# 3. Démarrer avec Docker Compose +# 3. Éditer config.yaml et modifier : +# - super_user.password (OBLIGATOIRE !) +# - api.api_addr (par défaut "0.0.0.0:8080") +# - orchestrator.docker_host (par défaut "unix:///var/run/docker.sock") +# - region (ex: "eu-west-1") + +# 4. Lancer Sovrabase docker compose up -d -# 4. Vérifier que tout fonctionne +# 5. Vérifier que tout fonctionne curl http://localhost:8080/health ``` -Ou utilisez le Makefile : +> **⚠️ Important** : Modifiez impérativement le mot de passe du super utilisateur dans `config.yaml` avant le premier lancement ! -```bash -make start # Setup + build + run -make docker-logs # Voir les logs -make docker-stop # Arrêter -``` - -### Prérequis +### Configuration des volumes -- Docker Engine 20.10+ -- Un fichier `config.yaml` configuré (voir [docs/config.md](docs/config.md)) - -### Configuration requise - -Sovrabase nécessite **deux volumes montés** pour fonctionner correctement : +Le `docker-compose.yml` configure automatiquement les volumes nécessaires : #### 1. Fichier de configuration : `config.yaml` +- **Montage** : `./config.yaml:/config.yaml:ro` (lecture seule) +- **Contenu** : configuration de l'API, orchestrateur, base de données interne, super utilisateur -Montage : `./config.yaml:/config/config.yaml:ro` +#### 2. Socket Docker +- **Montage** : `/var/run/docker.sock:/var/run/docker.sock` +- **Rôle** : permet à Sovrabase de créer et gérer les conteneurs de bases de données pour chaque projet -Ce fichier contient toute la configuration de Sovrabase : -- Le type d'orchestrateur (Docker) -- Les informations de connexion -- Les paramètres de l'API et CORS -- La configuration JWT -- La base de données interne (SQLite, PostgreSQL, MySQL) +#### 3. Volume de données : `sovrabase-data` +- **Montage** : `sovrabase-data:/data` +- **Contenu** : base de données interne SQLite (`/data/sovrabase.db` par défaut) +- **Persistance** : les données survivent aux redémarrages et suppressions du conteneur -**Exemple de `config.yaml` minimal :** +### Structure du fichier `config.yaml` + +Voici les paramètres principaux à configurer : ```yaml +# Configuration de l'API api: - host: "0.0.0.0" - port: 8080 - cors: - allowed_origins: - - "http://localhost:3000" - -jwt: - secret: "votre-secret-jwt-tres-securise" - expiration: "24h" + api_addr: "0.0.0.0:8080" # Adresse d'écoute + domain: "api.example.com" # Domaine public (optionnel) + cors_allow: # Origines CORS autorisées + - "http://localhost:3000" + - "https://example.com" +# Orchestrateur (Docker ou Kubernetes) orchestrator: type: "docker" docker_host: "unix:///var/run/docker.sock" -database: - type: "sqlite" - connection_string: "/data/sovrabase.db" -``` - -#### 2. Socket Docker - -Montage : `/var/run/docker.sock:/var/run/docker.sock` +# Base de données interne (SQLite par défaut) +internal_db: + manager: "sqlite" + uri: "/data/sovrabase.db" -Ce volume permet à Sovrabase de communiquer avec le daemon Docker de l'hôte pour : -- Créer des conteneurs PostgreSQL pour chaque projet -- Gérer le cycle de vie des bases de données -- Lister et inspecter les conteneurs existants +# Super utilisateur (à modifier OBLIGATOIREMENT) +super_user: + username: "admin" + password: "CHANGE-THIS-TO-A-SECURE-PASSWORD" + email: "admin@example.com" -#### 3. Volume de données (si SQLite) - -Montage : `sovrabase-data:/data` (volume nommé Docker) - -Si vous utilisez SQLite comme base de données interne, ce volume persiste les données : -- Survit à la suppression du conteneur -- Permet les mises à jour sans perte de données -- Stocke la base SQLite (`/data/sovrabase.db`) +# Région de déploiement +region: "eu-west-1" +``` -> **Note** : Si vous utilisez PostgreSQL ou MySQL comme base interne, ce volume n'est pas nécessaire. +Voir [docs/config.md](docs/config.md) pour la documentation complète. -### Lancement avec Docker +### Commandes utiles ```bash -# Créer un réseau Docker (optionnel mais recommandé) -docker network create sovrabase-network +# Voir les logs en temps réel +docker compose logs -f -# Créer un volume pour SQLite -docker volume create sovrabase-data +# Voir les logs du conteneur Sovrabase uniquement +docker compose logs -f sovrabase -# Lancer Sovrabase -docker run -d \ - --name sovrabase \ - --network sovrabase-network \ - -p 8080:8080 \ - -v $(pwd)/config.yaml:/config/config.yaml:ro \ - -v /var/run/docker.sock:/var/run/docker.sock \ - -v sovrabase-data:/data \ - -e CONFIG_PATH=/config/config.yaml \ - ghcr.io/ketsuna-org/sovrabase:latest -``` +# Arrêter Sovrabase +docker compose down -### Lancement avec Docker Compose +# Arrêter et supprimer les volumes (⚠️ perte de données) +docker compose down -v -Créez un fichier `docker-compose.yml` : +# Redémarrer après modification de config.yaml +docker compose restart -```yaml -version: '3.8' - -services: - sovrabase: - image: ghcr.io/ketsuna-org/sovrabase:latest - container_name: sovrabase - restart: unless-stopped - ports: - - "8080:8080" - volumes: - # Fichier de configuration (REQUIS) - - ./config.yaml:/config/config.yaml:ro - # Socket Docker pour l'orchestration (REQUIS) - - /var/run/docker.sock:/var/run/docker.sock - # Volume pour SQLite (si utilisé) - - sovrabase-data:/data - environment: - - CONFIG_PATH=/config/config.yaml - networks: - - sovrabase-network - -networks: - sovrabase-network: - driver: bridge - -volumes: - sovrabase-data: - driver: local +# Mettre à jour vers la dernière version +docker compose pull +docker compose up -d ``` -Puis lancez avec : +### Vérification de l'installation + +Une fois lancé, testez l'API : ```bash -docker compose up -d +# Health check +curl http://localhost:8080/health +# Réponse attendue : {"status":"ok"} + +# Vérifier les logs +docker compose logs sovrabase ``` ### ⚠️ Considérations de sécurité -**Attention** : Monter le socket Docker (`/var/run/docker.sock`) donne au conteneur un accès privilégié au daemon Docker de l'hôte. Cela signifie que : +**Socket Docker** : Monter `/var/run/docker.sock` donne un accès privilégié au daemon Docker. Le conteneur peut créer, modifier et supprimer d'autres conteneurs. -- Le conteneur peut créer, modifier et supprimer d'autres conteneurs -- Il a accès à tous les volumes et réseaux Docker -- C'est équivalent à un accès root sur l'hôte +**Recommandations pour la production** : -**Recommandations** : +1. **Proxy Docker** : utilisez [docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy) pour limiter les permissions +2. **Mot de passe fort** : changez `super_user.password` dans `config.yaml` +3. **HTTPS** : utilisez un reverse proxy (Nginx, Caddy, Traefik) pour le TLS +4. **Firewall** : restreignez l'accès au port 8080 aux IPs autorisées +5. **Monitoring** : surveillez les logs et les actions Docker -1. **En production** : Utilisez un socket Docker avec des permissions restreintes ou un proxy Docker comme [docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy) -2. **Isolation réseau** : Utilisez des réseaux Docker dédiés -3. **Firewall** : Limitez l'accès à l'API Sovrabase aux IPs autorisées -4. **Monitoring** : Surveillez les actions Docker effectuées par Sovrabase +### Déploiement avec Docker Run -### Build depuis les sources +Si vous préférez utiliser `docker run` directement : ```bash -# Cloner le repository -git clone https://github.com/ketsuna-org/sovrabase.git -cd sovrabase - -# Builder l'image Docker -docker build -t sovrabase:local . +# Créer un volume pour les données +docker volume create sovrabase-data -# Lancer avec votre image locale +# Lancer Sovrabase docker run -d \ --name sovrabase \ + --restart unless-stopped \ -p 8080:8080 \ - -v $(pwd)/config.yaml:/config/config.yaml:ro \ + -v $(pwd)/config.yaml:/config.yaml:ro \ -v /var/run/docker.sock:/var/run/docker.sock \ - sovrabase:local -``` - -### Vérification de l'installation - -Une fois Sovrabase lancé, vérifiez qu'il fonctionne : - -```bash -# Health check -curl http://localhost:8080/health - -# Devrait retourner : {"status":"ok"} + -v sovrabase-data:/data \ + ghcr.io/ketsuna-org/sovrabase:latest ``` -### Logs et debugging - -```bash -# Voir les logs en temps réel -docker logs -f sovrabase +### Utilisation avec Podman -# Voir les dernières 100 lignes -docker logs --tail 100 sovrabase +Sovrabase est compatible avec Podman. Modifiez `orchestrator.docker_host` dans `config.yaml` : -# Inspecter le conteneur -docker inspect sovrabase +```yaml +orchestrator: + type: "docker" + # Podman rootless + docker_host: "unix:///run/user/1000/podman/podman.sock" + # Podman root + # docker_host: "unix:///run/podman/podman.sock" ``` --- diff --git a/internal/orchestrator/README.md b/internal/orchestrator/README.md deleted file mode 100644 index d681bd1..0000000 --- a/internal/orchestrator/README.md +++ /dev/null @@ -1,235 +0,0 @@ -# Orchestrator - Gestionnaire de bases de données - -Le package `orchestrator` permet de gérer automatiquement des instances de bases de données PostgreSQL via Docker/Podman ou Kubernetes. - -## Fonctionnalités - -- ✅ Création automatique de conteneurs PostgreSQL par projet -- ✅ Gestion des conflits et détection des bases existantes -- ✅ Assignment automatique des ports -- ✅ Génération sécurisée des mots de passe -- ✅ Limites de ressources (CPU/Mémoire) -- ✅ Attente automatique du démarrage de PostgreSQL -- ✅ Suppression propre des conteneurs et volumes -- ✅ Liste de toutes les bases gérées -- ✅ Support Docker, Podman et Kubernetes (en cours) - -## Configuration - -Fichier `config.toml` : - -```toml -[orchestrator] -type = "docker" -docker_host = "unix:///mnt/wsl/podman-sockets/podman-machine-default/podman-root.sock" - -# Pour Docker standard -# docker_host = "unix:///var/run/docker.sock" - -# Pour Podman rootless -# docker_host = "unix:///run/user/1000/podman/podman.sock" - -# Pour Kubernetes -# type = "kubernetes" -# kube_api = "https://kubernetes.default.svc" -# kube_token = "your-token" -# namespace = "sovrabase-databases" -``` - -## Utilisation - -### Création d'un orchestrateur - -```go -import ( - "github.com/ketsuna-org/sovrabase/internal/config" - "github.com/ketsuna-org/sovrabase/internal/orchestrator" -) - -// Charger la configuration -cfg, err := config.LoadConfig("config.toml") -if err != nil { - log.Fatal(err) -} - -// Créer l'orchestrateur -orch, err := orchestrator.NewOrchestrator(&cfg.Orchestrator) -if err != nil { - log.Fatal(err) -} -``` - -### Créer une base de données - -```go -ctx := context.Background() - -options := &orchestrator.DatabaseOptions{ - PostgresVersion: "16-alpine", - Port: 5434, // Auto-assigné si 0 - Memory: "512m", // Optionnel - CPUs: "0.5", // Optionnel - Password: "", // Généré si vide -} - -dbInfo, err := orch.CreateDatabase(ctx, "my-project", options) -if err != nil { - log.Fatal(err) -} - -fmt.Printf("Connection: %s\n", dbInfo.ConnectionString) -``` - -### Récupérer les informations - -```go -dbInfo, err := orch.GetDatabaseInfo(ctx, "my-project") -if err != nil { - log.Fatal(err) -} - -fmt.Printf("Database: %s\n", dbInfo.Database) -fmt.Printf("Port: %s\n", dbInfo.Port) -fmt.Printf("Status: %s\n", dbInfo.Status) -``` - -### Lister toutes les bases - -```go -databases, err := orch.ListDatabases(ctx) -if err != nil { - log.Fatal(err) -} - -for _, db := range databases { - fmt.Printf("%s - %s (port %s)\n", db.ProjectID, db.Status, db.Port) -} -``` - -### Supprimer une base - -```go -err := orch.DeleteDatabase(ctx, "my-project") -if err != nil { - log.Fatal(err) -} -``` - -### Vérifier l'existence - -```go -exists, err := orch.DatabaseExists(ctx, "my-project") -if err != nil { - log.Fatal(err) -} -``` - -## Structure DatabaseInfo - -```go -type DatabaseInfo struct { - ProjectID string // ID du projet - ContainerID string // ID du conteneur - ContainerName string // Nom du conteneur - Status string // "running" ou "stopped" - PostgresVersion string // Version PostgreSQL - Host string // Hôte (localhost) - Port string // Port de connexion - Database string // Nom de la DB - User string // Utilisateur - Password string // Mot de passe - ConnectionString string // String de connexion complète - CreatedAt time.Time // Date de création -} -``` - -## Gestion des erreurs - -Le package gère automatiquement : - -- **Conflits** : Détecte si une base existe déjà -- **Ports occupés** : Trouve automatiquement un port libre (5433-6000) -- **Échec de démarrage** : Nettoie le conteneur si PostgreSQL ne démarre pas -- **Timeout** : Attend max 30 secondes le démarrage de PostgreSQL -- **Nettoyage** : Supprime les volumes lors de la suppression - -## Labels des conteneurs - -Tous les conteneurs créés ont les labels suivants : - -``` -sovrabase.managed=true -sovrabase.project_id=<project-id> -sovrabase.type=postgres -sovrabase.version=<pg-version> -sovrabase.created_at=<timestamp> -``` - -## Scripts de test - -### Test complet de l'API - -```bash -cd scripts -go run test_orchestrator_api.go -``` - -### Test simple de création - -```bash -cd scripts -go run test_orchestrator.go -``` - -### Nettoyage - -```bash -cd scripts -go run cleanup_test.go -``` - -## Commandes utiles - -```bash -# Voir tous les conteneurs Sovrabase -podman ps -a --filter "label=sovrabase.managed=true" - -# Logs d'un conteneur -podman logs sovrabase-db-<project-id> - -# Se connecter à la DB -podman exec -it sovrabase-db-<project-id> psql -U <user> -d <database> - -# Supprimer tous les conteneurs Sovrabase -podman rm -f $(podman ps -aq --filter "label=sovrabase.managed=true") -``` - -## Architecture - -``` -orchestrator/ -├── orchestrator.go # Interface et implémentations -├── docker.go # Logique Docker/Podman -└── kubernetes.go # Logique Kubernetes (TODO) -``` - -## Roadmap - -- [x] Support Docker/Podman -- [x] Gestion des conflits -- [x] Assignment automatique des ports -- [x] Limites de ressources -- [x] Attente du démarrage -- [ ] Support Kubernetes -- [ ] Backup/Restore automatique -- [ ] Métriques et monitoring -- [ ] Mise à jour des versions PostgreSQL -- [ ] Réplication et haute disponibilité - -## Contribution - -Les contributions sont les bienvenues ! Assurez-vous que tous les tests passent : - -```bash -go test ./internal/orchestrator/... -``` |