diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4154806
--- /dev/null
+++ b/README.md
@@ -0,0 +1,158 @@
+# Folio
+
+Moteur de blog PHP minimaliste — articles Markdown, authentification SSO (OIDC) ou lien magique, commentaires, recherche, flux RSS.
+
+---
+
+## Prérequis
+
+- PHP ≥ 8.2 avec les extensions `pdo`, `pdo_pgsql`, `mbstring`, `openssl`
+- PostgreSQL ≥ 14
+- Composer
+- Apache avec `mod_rewrite` (ou Nginx — voir ci-dessous)
+
+## Installation
+
+### 1. Cloner et installer les dépendances
+
+```bash
+git clone https://git.abonnel.fr/cedricAbonnel/folio mon-site
+cd mon-site
+composer install --no-dev
+```
+
+### 2. Configurer l'environnement
+
+```bash
+cp .env.example .env
+```
+
+Remplir les valeurs dans `.env` :
+
+| Variable | Description |
+|---|---|
+| `APP_URL` | URL publique du site (`https://example.com`) |
+| `ADMIN_EMAIL` | Email de l'administrateur principal |
+| `SESSION_NAME` | Nom du cookie de session — doit être unique par instance |
+| `DATA_PATH` | Chemin absolu vers le répertoire des articles (ex. `/srv/data/mon-site`). Par défaut : `<racine>/data` |
+| `OIDC_ISSUER` / `OIDC_CLIENT_ID` / `OIDC_CLIENT_SECRET` | SSO OpenID Connect |
+| `DB_DSN` / `DB_USER` / `DB_PASS` | Connexion PostgreSQL |
+| `SMTP_*` | Serveur email sortant (commentaires, contact, lien magique) |
+| `CONTACT_EMAIL` | Destinataire du formulaire de contact |
+
+> En production, placer `DATA_PATH` **hors du document root** (ex. `/srv/data/mon-site`) pour que les articles ne soient pas accessibles directement via le serveur web.
+
+### 3. Créer la base de données
+
+```bash
+createdb monsite
+```
+
+### 4. Initialiser le schéma et jouer les migrations
+
+```bash
+php database/migrate.php
+```
+
+Ce script crée toutes les tables et applique les migrations dans l'ordre. À relancer après chaque mise à jour.
+
+### 5. Configurer le vhost Apache
+
+```apache
+<VirtualHost *:443>
+    ServerName example.com
+    DocumentRoot /var/www/mon-site/public
+
+    <Directory /var/www/mon-site/public>
+        AllowOverride All
+        Require all granted
+    </Directory>
+</VirtualHost>
+```
+
+Le fichier `public/.htaccess` gère le routage via `mod_rewrite`. `AllowOverride All` est requis.
+
+<details>
+<summary>Nginx</summary>
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name example.com;
+    root /var/www/mon-site/public;
+    index index.php;
+
+    location / {
+        try_files $uri $uri/ /index.php?$query_string;
+    }
+
+    location ~ \.php$ {
+        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
+        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
+        include fastcgi_params;
+    }
+}
+```
+
+</details>
+
+### 6. Permissions fichiers
+
+```bash
+# Répertoire des articles
+mkdir -p /srv/data/mon-site
+chown -R www-data:www-data /srv/data/mon-site
+
+# .env lisible par www-data uniquement
+chown user:www-data .env
+chmod 640 .env
+```
+
+PHP-FPM tourne en `www-data`. Le `.env` doit être lisible par `www-data` mais pas par les autres.
+
+> Le script `scripts/setup.sh` automatise la vérification des prérequis, la création des répertoires et les droits.
+
+### 7. Paramètres du site
+
+Au premier lancement, se connecter en tant qu'admin et aller dans **Administration → Paramètres du site** pour définir le titre, le claim, la langue et la licence.
+
+Ou créer directement `$DATA_PATH/site_settings.json` :
+
+```json
+{
+    "site_title": "Mon site",
+    "site_claim": "Un blog propulsé par Folio",
+    "site_lang": "fr-FR",
+    "site_license_label": "CC BY 4.0",
+    "site_license_url": "https://creativecommons.org/licenses/by/4.0/",
+    "posts_per_page": 12
+}
+```
+
+---
+
+## Mise à jour
+
+```bash
+git pull
+composer install --no-dev
+php database/migrate.php
+```
+
+## Structure du projet
+
+```
+├── config/         Configuration (charge .env, définit APP_URL et DATA_PATH)
+├── database/       Schéma SQL et runner de migrations
+├── docs/           Documentation technique
+├── public/         Racine web (index.php, assets, .htaccess)
+├── scripts/        Scripts utilitaires (setup.sh, migrations de contenu)
+├── src/            Code applicatif
+└── templates/      Vues PHP
+```
+
+Les articles sont stockés dans `DATA_PATH` (hors dépôt git).
+
+## Licence
+
+[MIT](LICENSE)