From 8d37115e1d888f2beb41ba058351af52bb859a32 Mon Sep 17 00:00:00 2001 From: Sepehr Ramezani Date: Tue, 21 Apr 2026 23:07:00 +0200 Subject: [PATCH] docs: add complete deployment guide (DEPLOY.md) Covers: server setup, Gitea Runner installation (systemd + Docker), SSH key configuration, CI/CD workflow explanation, Nginx reverse proxy config with SSE support, HTTPS with Let's Encrypt, admin user creation, and a full deployment checklist. Co-Authored-By: Claude Opus 4.5 --- DEPLOY.md | 358 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 358 insertions(+) create mode 100644 DEPLOY.md diff --git a/DEPLOY.md b/DEPLOY.md new file mode 100644 index 0000000..8ecd38e --- /dev/null +++ b/DEPLOY.md @@ -0,0 +1,358 @@ +# Memento - Guide de deploiement complet + +## Table des matieres +1. [Architecture](#architecture) +2. [Setup du serveur 192.168.1.190](#setup-serveur) +3. [Installation de Gitea Runner](#gitea-runner) +4. [Configuration CI/CD](#cicd) +5. [Nginx reverse proxy](#nginx) +6. [Checklist de deploiement](#checklist) + +--- + +## Architecture + +``` +Internet/LAN + | + [Nginx] ── port 80/443 ── notes.parsanet.org + | + ├── / ──► [memento-web] ── port 3000 ── Next.js App + | + └── /mcp ──► [memento-mcp] ── port 3001 ── MCP Server (SSE) + | + [postgres] ── port 5432 (interne seulement) +``` + +**Machine 192.168.1.190** (Proxmox Docker container): +- Docker + Docker Compose +- Nginx reverse proxy +- 3 conteneurs: memento-web, memento-mcp, memento-postgres + +**Serveur Gitea** (gitea.parsanet.org): +- Gitea + act_runner +- Se connecte en SSH a 192.168.1.190 pour deployer + +--- + +## Setup serveur + +### 1. Creer l'utilisateur de deploiement sur 192.168.1.190 + +```bash +# Sur 192.168.1.190, en root : + +# Creer l'utilisateur +useradd -m -s /bin/bash memento-deploy + +# Donner acces a Docker +usermod -aG docker memento-deploy + +# Creer le repertoire projet +mkdir -p /opt/memento +chown memento-deploy:memento-deploy /opt/memento + +# Cloner le repo +su - memento-deploy +cd /opt/memento +git clone https://gitea.parsanet.org/sepehr/Momento.git . + +# Configurer git pour le pull automatique +git config credential.helper store +# Le premier pull demandera le login, apres ca sera automatique +``` + +### 2. Generer le .env.docker + +```bash +cd /opt/memento +bash scripts/deploy.sh --full +``` + +Le script demande interactivement: +- URL (mettre `http://192.168.1.190` ou `http://notes.parsanet.org`) +- Provider AI + cle API +- Email (optionnel) + +Il genere automatiquement: +- NEXTAUTH_SECRET (random) +- POSTGRES_PASSWORD (random) + +### 3. Premier deploiement manuel + +```bash +cd /opt/memento +bash scripts/deploy.sh --build +``` + +Verifier: +```bash +docker compose ps +# Les 3 conteneurs doivent etre "healthy" +``` + +### 4. Creer le premier admin + +```bash +# S'inscrire sur http://192.168.1.190/register +# Puis promouvoir en admin: +docker compose exec -T postgres psql -U memento -d memento \ + -c "UPDATE \"User\" SET role='ADMIN' WHERE email='VOTRE_EMAIL';" +``` + +--- + +## Gitea Runner + +### Option A: Installer le Runner sur le serveur Gitea + +```bash +# Sur le serveur Gitea, en root : + +# Telecharger act_runner +wget https://gitea.com/gitea/act_runner/releases/latest/download/act_runner-linux-amd64 +chmod +x act_runner-linux-amd64 +mv act_runner-linux-amd64 /usr/local/bin/act_runner + +# Enregistrer le runner +# Aller sur gitea.parsanet.org > Site administration > Actions > Runners > "Create new Runner" +# Copier le token, puis : +act_runner register \ + --instance https://gitea.parsanet.org \ + --token VOTRE_TOKEN \ + --name memento-deploy \ + --labels ubuntu-latest:docker://node:22-bookworm + +# Lancer le runner +act_runner daemon + +# Ou en tant que service systemd : +cat > /etc/systemd/system/gitea-runner.service << 'EOF' +[Unit] +Description=Gitea Actions Runner +After=network.target + +[Service] +Type=simple +User=runner +WorkingDirectory=/home/runner +ExecStart=/usr/local/bin/act_runner daemon +Restart=always +RestartSec=5 + +[Install] +WantedBy=multi-user.target +EOF + +systemctl daemon-reload +systemctl enable gitea-runner +systemctl start gitea-runner +``` + +### Option B: Runner en Docker + +```bash +# Sur le serveur Gitea : +docker run -d --name gitea-runner \ + -v /var/run/docker.sock:/var/run/docker.sock \ + -v act-runner-data:/data \ + -e GITEA_INSTANCE_URL=https://gitea.parsanet.org \ + -e GITEA_RUNNER_REGISTRATION_TOKEN=VOTRE_TOKEN \ + gitea/act_runner:latest +``` + +### Configurer les secrets SSH + +Le Runner doit pouvoir se connecter en SSH a 192.168.1.190. + +```bash +# Sur le serveur Gitea (la ou tourne le runner) : + +# Generer une paire de cles SSH +ssh-keygen -t ed25519 -C "gitea-runner-deploy" -N "" -f /root/.ssh/memento-deploy + +# Afficher la cle publique +cat /root/.ssh/memento-deploy.pub +``` + +```bash +# Sur 192.168.1.190, en tant que memento-deploy : + +mkdir -p ~/.ssh +chmod 700 ~/.ssh +echo "COLLER_LA_CLE_PUBLIQUE_ICI" >> ~/.ssh/authorized_keys +chmod 600 ~/.ssh/authorized_keys +``` + +```bash +# Tester la connexion SSH depuis le serveur Gitea : +ssh -i /root/.ssh/memento-deploy memento-deploy@192.168.1.190 "echo OK" +# Doit afficher "OK" sans demander de mot de passe +``` + +### Ajouter les secrets dans Gitea + +Sur gitea.parsanet.org : +1. Aller dans le repo **Momento** +2. **Settings > Actions > Secrets** +3. Ajouter les secrets suivants : + +| Nom du secret | Valeur | +|---|---| +| `DEPLOY_HOST` | `192.168.1.190` | +| `DEPLOY_USER` | `memento-deploy` | +| `DEPLOY_SSH_KEY` | Le contenu de `/root/.ssh/memento-deploy` (cle privee) | +| `DEPLOY_PATH` | `/opt/memento` | +| `DEPLOY_PORT` | `22` | + +--- + +## CI/CD + +Le workflow est deja dans `.gitea/workflows/deploy.yaml`. + +### Ce qui se passe a chaque push sur `main` : + +1. Le Runner recupere le workflow +2. Il se connecte en SSH a 192.168.1.190 +3. Il execute `bash scripts/deploy.sh --build` +4. Le script : + - `git pull origin main` + - `docker compose build --parallel` + - `docker compose up -d` + - Attend les healthchecks + - Initialise la DB si necessaire + - Affiche le status + +### Verifier que le Runner fonctionne + +```bash +# Sur le serveur Gitea : +act_runner list +# Doit afficher le runner "memento-deploy" + +# Faire un push test sur le repo et verifier dans +# gitea.parsanet.org > Momento > Actions +``` + +--- + +## Nginx + +### Installation + +```bash +# Sur 192.168.1.190 : +apt install -y nginx +``` + +### Configuration + +```bash +cat > /etc/nginx/sites-available/memento << 'EOF' +# Memento - Nginx reverse proxy +server { + listen 80; + server_name notes.parsanet.org 192.168.1.190; + + # Rediriger HTTP vers HTTPS (decommenter quand HTTPS est pret) + # return 301 https://$host$request_uri; + + # Next.js app + location / { + proxy_pass http://127.0.0.1:3000; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_read_timeout 86400; + } + + # MCP Server (SSE) + location /mcp { + proxy_pass http://127.0.0.1:3001/mcp; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_read_timeout 86400; + proxy_buffering off; + proxy_cache off; + } +} +EOF + +ln -sf /etc/nginx/sites-available/memento /etc/nginx/sites-enabled/memento +rm -f /etc/nginx/sites-enabled/default +nginx -t && systemctl reload nginx +``` + +### HTTPS avec Let's Encrypt (optionnel, plus tard) + +```bash +apt install -y certbot python3-certbot-nginx +certbot --nginx -d notes.parsanet.org +``` + +Puis mettre a jour `NEXTAUTH_URL` dans `.env.docker`: +```bash +# Sur 192.168.1.190 : +cd /opt/memento +nano .env.docker +# Changer NEXTAUTH_URL="https://notes.parsanet.org" +docker compose restart memento-note +``` + +--- + +## Checklist + +### Premier deploiement (une seule fois) + +- [ ] Creer `memento-deploy` sur 192.168.1.190 avec acces Docker +- [ ] Cloner le repo dans `/opt/memento` +- [ ] Executer `bash scripts/deploy.sh --full` +- [ ] Verifier les 3 conteneurs healthy +- [ ] S'inscrire sur l'app +- [ ] Promouvoir le premier utilisateur en ADMIN +- [ ] Configurer Nginx + +### CI/CD (une seule fois) + +- [ ] Installer `act_runner` sur le serveur Gitea +- [ ] Enregistrer le runner dans Gitea +- [ ] Generer la cle SSH et la copier sur 192.168.1.190 +- [ ] Tester la connexion SSH +- [ ] Ajouter les 5 secrets dans Gitea +- [ ] Faire un push test et verifier dans Actions + +### Apres chaque push sur main (automatique) + +- [ ] Le Runner detecte le push +- [ ] SSH vers 192.168.1.190 +- [ ] git pull +- [ ] docker compose build + up +- [ ] Conteneurs healthy + +--- + +## Variables d'environnement requises dans .env.docker + +| Variable | Description | Exemple | +|---|---|---| +| `NEXTAUTH_URL` | URL publique de l'app | `http://192.168.1.190` | +| `NEXTAUTH_SECRET` | Cle secrete (auto-genere) | random base64 | +| `ALLOW_REGISTRATION` | Inscription publique | `true` ou `false` | +| `POSTGRES_DB` | Nom de la base | `memento` | +| `POSTGRES_USER` | Utilisateur Postgres | `memento` | +| `POSTGRES_PASSWORD` | Mot de passe (auto-genere) | random hex | +| `MCP_MODE` | Mode MCP | `sse` | +| `AI_PROVIDER_TAGS` | Provider pour les tags | `openrouter` | +| `CUSTOM_OPENAI_API_KEY` | Cle API (si openrouter) | `sk-or-v1-...` | +| `CUSTOM_OPENAI_BASE_URL` | URL du provider | `https://openrouter.ai/api/v1` |