From 479e8a590314ca7cb647ad28eeaee30011fe5e93 Mon Sep 17 00:00:00 2001 From: claude Date: Thu, 1 Oct 2026 19:06:32 +0200 Subject: [PATCH] docs: translate README to French Add a Docker Compose deployment section and document HTTP_PORT. Co-Authored-By: Claude Opus 5.5 (1M context) --- README.md | 150 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 93 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index 49d0d5a..710a05d 100644 --- a/README.md +++ b/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 . +Ouvrir ensuite . -Without Docker: `go run .` (Go 1.24 or newer, data in `./data`), then open . +Sans Docker : `go run .` (Go 1.24 ou plus récent, données dans `./data`), puis ouvrir +. -## 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). -- 2.54.0