README.md

@@ -1,97 +1,133 @@
 # Searchgit
 
-Search GitHub repositories with criteria and browse the results in a clean web interface
-(light/dark theme, responsive, English/French UI). The interface reuses the look of
-[Logstream](https://gitea.vlab.bzh/cedric/logstream).
+Recherche de dépôts GitHub selon des critères, avec une interface web claire pour parcourir les
+résultats (thème clair/sombre, responsive, interface en anglais ou en français). L'interface reprend
+le style de [Logstream](https://gitea.vlab.bzh/cedric/logstream).
 
 ```
-browser ──/api/search──▶ searchgit (Go) ──REST──▶ api.github.com/search/repositories
-        ──/api/saved───▶      ├── 5 min cache
-                              └── scheduler ──▶ /data (JSON snapshots)
+navigateur ──/api/search──▶ searchgit (Go) ──REST──▶ api.github.com/search/repositories
+           ──/api/saved───▶      ├── cache 5 min
+                                 └── planificateur ──▶ /data (instantanés JSON)
 ```
 
-## Getting started
+## Démarrage rapide
 
 ```bash
-cp .env.example .env      # optional: set GITHUB_TOKEN
+cp .env.example .env      # facultatif : renseigner GITHUB_TOKEN
 docker compose up -d --build
 ```
 
-Then open <http://localhost:8080>.
+Ouvrir ensuite <http://localhost:8080>.
 
-Without Docker: `go run .` (Go 1.24 or newer, data in `./data`), then open <http://localhost:8080>.
+Sans Docker : `go run .` (Go 1.24 ou plus récent, données dans `./data`), puis ouvrir
+<http://localhost:8080>.
 
-## Criteria
+## Déploiement avec Docker Compose
 
-| Filter | GitHub qualifier |
+Le fichier `docker-compose.yml` construit l'image à partir du `Dockerfile` et lance un seul
+conteneur `searchgit` :
+
+- le port publié est `HTTP_PORT` (8080 par défaut), redirigé vers le port 8080 du conteneur ;
+- la configuration est lue dans `.env` (copie de `.env.example`) ;
+- les recherches programmées et leur historique sont stockés dans le volume nommé
+  `searchgit-data`, monté sur `/data` : ils survivent aux redémarrages et aux mises à jour ;
+- le conteneur redémarre automatiquement (`restart: unless-stopped`).
+
+Exemple de `.env` pour une instance exposée sur le port 8686 avec authentification :
+
+```bash
+HTTP_PORT=8686
+GITHUB_TOKEN=github_pat_...
+AUTH_USER=admin
+AUTH_PASS=un-mot-de-passe
+TZ=Europe/Paris
+```
+
+Mettre à jour une instance :
+
+```bash
+git pull
+docker compose up -d --build
+```
+
+Suivre les journaux : `docker compose logs -f searchgit`. L'état du service est exposé sur
+`/healthz` (sans authentification), utilisable pour une sonde de supervision.
+
+## Critères
+
+| Filtre | Qualificateur GitHub |
 |---|---|
-| Search field | free text, plus any GitHub qualifier (`user:`, `org:`, `NOT`, `"exact phrase"`, `size:`…) |
-| Everywhere / Name / Description / README | `in:name`, `in:description`, `in:readme` |
-| Language | `language:Go` (click a language in the list to filter on it) |
-| Stars | `stars:>=100` |
-| Activity | `pushed:>=YYYY-MM-DD` (1 month to 2 years) |
-| Creation date | `created:>=YYYY-MM-DD` |
-| License | `license:mit`… |
-| Topic | `topic:cli` (click a topic in the list to filter on it) |
+| Champ de recherche | texte libre, plus n'importe quel qualificateur GitHub (`user:`, `org:`, `NOT`, `"phrase exacte"`, `size:`…) |
+| Partout / Nom / Description / README | `in:name`, `in:description`, `in:readme` |
+| Langage | `language:Go` (cliquer sur un langage dans la liste pour filtrer dessus) |
+| Étoiles | `stars:>=100` |
+| Activité | `pushed:>=AAAA-MM-JJ` (de 1 semaine à 2 ans) |
+| Date de création | `created:>=AAAA-MM-JJ` |
+| Licence | `license:mit`… |
+| Topic | `topic:cli` (cliquer sur un topic dans la liste pour filtrer dessus) |
 | Good first issues | `good-first-issues:>0` |
-| Forks / Archived | forks and archived repositories are hidden unless enabled |
-| Sort | best match, stars, forks, recently updated, help wanted issues |
+| Forks / Archivés | les forks et les dépôts archivés sont masqués sauf s'ils sont activés |
+| Tri | pertinence, plus d'étoiles, plus de forks, mis à jour récemment, issues « help wanted » |
 
-The filters are kept in the page URL, so a search can be bookmarked or shared. The footer
-shows the exact query sent to GitHub (click it to open the same search on github.com).
-**CSV** downloads the loaded results (semicolon separated when the UI is in French, for Excel).
+Les filtres sont conservés dans l'URL de la page : une recherche peut donc être ajoutée aux favoris
+ou partagée. Le pied de page affiche la requête exacte envoyée à GitHub (un clic ouvre la même
+recherche sur github.com). **CSV** télécharge les résultats chargés (séparateur point-virgule
+quand l'interface est en français, pour Excel).
 
-GitHub returns at most the first 1,000 results of a search.
+GitHub ne renvoie au maximum que les 1 000 premiers résultats d'une recherche.
 
-## Scheduled searches (weekly review)
+## Veille (recherches programmées)
 
-**Schedule** saves the current filters as a search that the server runs on its own:
-every week (day and time), every day, or every N hours, in the server time zone (`TZ`).
-Each run keeps a snapshot of the first 30, 50 or 100 results.
+**Programmer** enregistre les filtres en cours comme une recherche que le serveur exécute seul :
+chaque semaine (jour et heure), chaque jour, ou toutes les N heures, dans le fuseau horaire du
+serveur (`TZ`). Chaque passage conserve un instantané des 30, 50 ou 100 premiers résultats.
 
-The **Watch** tab lists the scheduled searches with their last run, and a review page
-per search shows, for any run of its history:
+L'onglet **Veille** liste les recherches programmées avec leur dernier passage. Une page de revue
+par recherche affiche, pour n'importe quel passage de son historique :
 
-- **New**: repositories never returned by a previous run of this search;
-- **Rising**: repositories that gained the most stars since the previous run;
-- **All**: the whole snapshot, with the star gain of each repository.
+- **Nouveautés** : les dépôts jamais renvoyés par un passage précédent de cette recherche ;
+- **Progressions** : les dépôts qui ont gagné le plus d'étoiles depuis le passage précédent ;
+- **Tous** : l'instantané complet, avec le gain d'étoiles de chaque dépôt.
 
-A search runs once as soon as it is created: that first run is the baseline the next
-ones are compared with. A run missed while the server was stopped is made at startup.
-For a weekly "gems" review, a good start is: a topic or a language, *created < 1 month*
-(or *< 1 week*), sorted by *most stars*.
+Une recherche est exécutée une première fois dès sa création : ce premier passage sert de
+référence pour les suivants. Un passage manqué pendant l'arrêt du serveur est rattrapé au
+démarrage. Pour une revue hebdomadaire des « pépites », un bon point de départ : un topic ou un
+langage, *Créé < 1 mois* (ou *Créé < 1 semaine*), trié par *Plus d'étoiles*.
 
 ## Configuration
 
-| Variable | Default | Role |
+| Variable | Défaut | Rôle |
 |---|---|---|
-| `HTTP_ADDR` | `:8080` | listening address |
-| `GITHUB_TOKEN` | empty | GitHub token; raises the search quota from 10 to 30 requests per minute |
-| `CACHE_TTL` | `5m` | identical searches are served from memory for this long |
-| `AUTH_USER` / `AUTH_PASS` | empty | HTTP basic authentication (except `/healthz`) |
-| `GITHUB_API` | `https://api.github.com` | API base URL (GitHub Enterprise) |
-| `DATA_DIR` | `data` (`/data` in Docker) | scheduled searches and their snapshots (JSON files) |
-| `TZ` | `Europe/Paris` in compose | time zone of the schedules |
-| `HISTORY_KEEP` | `100` | runs kept per scheduled search (0 = all) |
+| `HTTP_ADDR` | `:8080` | adresse d'écoute |
+| `HTTP_PORT` | `8080` | port publié par Docker Compose |
+| `GITHUB_TOKEN` | vide | jeton GitHub ; fait passer le quota de recherche de 10 à 30 requêtes par minute |
+| `CACHE_TTL` | `5m` | durée pendant laquelle une recherche identique est servie depuis la mémoire |
+| `AUTH_USER` / `AUTH_PASS` | vide | authentification HTTP basique (sauf `/healthz`) ; vide = désactivée |
+| `GITHUB_API` | `https://api.github.com` | URL de base de l'API (GitHub Enterprise) |
+| `DATA_DIR` | `data` (`/data` sous Docker) | recherches programmées et leurs instantanés (fichiers JSON) |
+| `TZ` | `Europe/Paris` dans compose | fuseau horaire des programmations |
+| `HISTORY_KEEP` | `100` | passages conservés par recherche programmée (0 = tous) |
+
+Un jeton *fine-grained* sans aucune permission suffit pour les dépôts publics.
 
 ## API
 
 - `GET /api/search?q=&in=&language=&stars=&maxstars=&minforks=&topic=&license=&pushed=&created=&goodfirst=1&forks=1&archived=1&sort=&order=&page=&per_page=`
-  (`pushed` / `created`: `1w`, `1m`, `3m`, `6m`, `1y`, `2y`, `5y`)
-- `GET /api/status`: token configured, last known search quota, server time zone
-- `GET|POST /api/saved`, `GET|PUT|DELETE /api/saved/{id}`: scheduled searches
+  (`pushed` / `created` : `1w`, `1m`, `3m`, `6m`, `1y`, `2y`, `5y`)
+- `GET /api/status` : jeton configuré, dernier quota de recherche connu, fuseau horaire du serveur
+- `GET|POST /api/saved`, `GET|PUT|DELETE /api/saved/{id}` : recherches programmées
   (`{"name", "params", "maxResults", "enabled", "schedule": {"every": "week|day|hours", "weekday", "hour", "minute", "hours"}}`,
-  `params` being the `/api/search` query string)
-- `POST /api/saved/{id}/run`: run now
-- `GET /api/saved/{id}/runs`, `GET /api/saved/{id}/runs/{run|latest}`: history and snapshots
+  `params` étant la chaîne de requête de `/api/search`)
+- `POST /api/saved/{id}/run` : exécuter maintenant
+- `GET /api/saved/{id}/runs`, `GET /api/saved/{id}/runs/{run|latest}` : historique et instantanés
 - `GET /healthz`
 
-## Development
+## Développement
 
 ```bash
 go test ./...
 go run .
 ```
 
-The web interface is plain HTML, CSS and JavaScript in `web/`, embedded in the binary
-(no build step).
+L'interface web est en HTML, CSS et JavaScript simples dans `web/`, embarqués dans le binaire
+(aucune étape de build).