173 lines
8.9 KiB
Markdown
173 lines
8.9 KiB
Markdown
# ForgeFlow
|
|
|
|
**Van lokale wijziging naar aantoonbaar juiste serverversie — zonder de Git- en deploymentcontext over verschillende tools te verspreiden.**
|
|
|
|
ForgeFlow is een desktopapp voor teams die met Git, Gitea en eigen servers werken. De app toont wat lokaal gewijzigd is, wat al op Gitea staat en welke exacte commit op de server draait. Daarna begeleidt ForgeFlow je door review, commit, push, deployment en verificatie.
|
|
|
|
> Huidige release: **0.10.1** · [download de laatste Windows-release](https://gitea.itworx.tech/Jens/ForgeFlow/releases/latest)
|
|
|
|
|
|
|
|
## Wat ForgeFlow voor je oplost
|
|
|
|
- **Eén duidelijke actielijst:** zie meteen welke repository aandacht nodig heeft en waarom.
|
|
- **Veilige Git-flow:** review wijzigingen, stage volledige bestanden of afzonderlijke hunks, commit, push en herstel conflicten zonder contextwissel.
|
|
- **Deployment op een exacte commit:** ForgeFlow gebruikt volledige commit-SHA's en toont lokaal, Gitea en server naast elkaar.
|
|
- **Volledige serverinventaris:** zie ook gestopte, DockerMan- en niet-Git-installaties, koppel twijfelgevallen handmatig en behoud hun bestaande Compose-identiteit.
|
|
- **Veilige server-pull:** Unraid haalt de exacte commit uit Gitea met een unieke, repository-scoped read-only deploy key en een vastgepinde SSH-hostsleutel.
|
|
- **Ingebouwde Git Validator:** controleer repository-identiteit, branch protection, synchronisatie-instellingen, documentatie, geheimen en grote bestanden; veilige verbeteringen kunnen gericht worden toegepast.
|
|
- **Lokale controle:** configuratie en credentials blijven op het toestel en diagnostische exports worden lokaal geredigeerd.
|
|
|
|
## Snel starten
|
|
|
|
### Aanbevolen: de Windows-app installeren
|
|
|
|
1. Open de [laatste ForgeFlow-release](https://gitea.itworx.tech/Jens/ForgeFlow/releases/latest).
|
|
2. Download de Windows-installer of portable executable.
|
|
3. Start ForgeFlow en doorloop de setupwizard.
|
|
4. Voeg je Gitea-server, token en lokale projectmappen toe.
|
|
5. Configureer optioneel een serververbinding en één of meer deploymentprofielen.
|
|
|
|
Na installatie kun je nieuwe packaged releases vanuit **Settings → Updates** ophalen. Downloads worden tegen de gepubliceerde SHA-256-checksums gecontroleerd. Zie [UPDATING.md](docs/UPDATING.md) wanneer een oudere of source-only build nog niet binair kan updaten.
|
|
|
|
### Eerst vrijblijvend bekijken
|
|
|
|
De interactieve demomodus gebruikt uitsluitend representatieve voorbeelddata en maakt geen verbinding met Git, Gitea of een server:
|
|
|
|
```powershell
|
|
npm install
|
|
npm run demo
|
|
```
|
|
|
|
Open daarna `http://127.0.0.1:4173`.
|
|
|
|
## De dagelijkse workflow
|
|
|
|
### 1. Begin bij wat aandacht vraagt
|
|
|
|
Het release-overzicht vertaalt technische status naar concrete acties: wijzigingen reviewen, commits pushen, synchroniseren, deployen of een ongezonde omgeving onderzoeken. De repositorylijst blijft beschikbaar zodat je snel van context kunt wisselen.
|
|
|
|
### 2. Review en publiceer code
|
|
|
|
|
|
|
|
In de repositorywerkruimte zie je de volledige keten **Local → Gitea → Server**. Je kunt wijzigingen selecteren, diffs bekijken, gedeeltelijke hunk-staging behouden, branch protection controleren en een pull request openen. Destructieve of publicerende acties vereisen altijd expliciete bevestiging.
|
|
|
|
### 3. Deploy en verifieer de live versie
|
|
|
|
|
|
|
|
Elke deploymentkaart benoemt repository, container, omgeving, uitvoeringsmethode, live commit, Gitea-commit, vorige versie en healthstatus. ForgeFlow ondersteunt gecontroleerde deployments via Gitea Actions en SSH/Unraid, met preflightcontrole en rollback waar beschikbaar.
|
|
|
|
Bij server discovery probeert ForgeFlow bestaande containers aan Gitea-repositories te koppelen. Een exacte overeenkomst tussen de volledige live SHA en de actuele Gitea-SHA wordt als gelijklopende versie weergegeven; een runtime-healthcheck blijft een afzonderlijke voorwaarde voor een gezonde deployment.
|
|
|
|
### 4. Verbeter de repository met Git Validator
|
|
|
|
|
|
|
|
Git Validator groepeert bevindingen per onderwerp en maakt onderscheid tussen geslaagde controles, aanbevelingen en kritieke problemen. Alleen fixes die ForgeFlow veilig en voorspelbaar kan uitvoeren worden als automatische actie aangeboden; governancewijzigingen zoals branch protection blijven zichtbaar en expliciet.
|
|
|
|
## Wanneer is een release werkelijk in orde?
|
|
|
|
ForgeFlow houdt drie soorten waarheid bewust apart:
|
|
|
|
| Controle | Betekenis |
|
|
| --- | --- |
|
|
| **Local ↔ Gitea** | De lokale branch volgt de juiste upstream en is niet onverwacht ahead, behind of divergent. |
|
|
| **Gitea ↔ Server** | De volledige commit-SHA op de server is exact gelijk aan de relevante commit op Gitea. |
|
|
| **Runtime health** | De container of applicatie draait en de geconfigureerde healthcheck slaagt. |
|
|
|
|
Een gelijke commit bewijst welke code draait; een geslaagde healthcheck bewijst dat die versie ook functioneert. ForgeFlow combineert beide signalen zonder het ene voor het andere te laten doorgaan.
|
|
|
|
## Belangrijkste functies
|
|
|
|
### Git en Gitea
|
|
|
|
- repositories ontdekken, favorieten beheren en ontbrekende lokale clones koppelen;
|
|
- status, diff, staging, partial hunks, commit, push, fetch, pull, stash en conflict recovery;
|
|
- branches maken, wisselen, vergelijken en opruimen;
|
|
- branch protection controleren en pull requests openen;
|
|
- Git Validator met assurance score, bewijs per controle en gerichte veilige fixes.
|
|
|
|
### Deployments
|
|
|
|
- deploymentprofielen per repository en omgeving;
|
|
- Gitea Actions en SSH/Unraid als gecontroleerde uitvoeringsroutes;
|
|
- serverinventaris van draaiende en gestopte Docker-, Compose- en DockerMan-workloads;
|
|
- automatische koppeling op exact bewijs en een handmatige koppelwizard voor twijfelgevallen;
|
|
- server-pull als aanbevolen route, met een afzonderlijke read-only deploy key per repository;
|
|
- directe checksum-gecontroleerde copy als alternatief zonder servertoegang tot Gitea;
|
|
- verificatie op volledige SHA, runtime health en recente serverwaarheid;
|
|
- preflight, live logs, deploymenthistoriek en rollback naar de vorige bekende versie.
|
|
|
|
### Veiligheid en beheer
|
|
|
|
- credentials versleuteld via de beveiligde opslag van het besturingssysteem;
|
|
- origin-checks voorkomen dat een Gitea-token naar een andere host wordt gestuurd;
|
|
- updatepakketten worden alleen vanaf de geconfigureerde Gitea-origin gedownload en met checksums geverifieerd;
|
|
- lokale redactie van tokens, wachtwoorden en gevoelige diagnostische data;
|
|
- versleutelde configuratieback-up, herstelvoorbeeld en lokale audittrail;
|
|
- packaged builds als Windows-installer en portable executable.
|
|
|
|
Meer achtergrond staat in [SECURITY.md](docs/SECURITY.md) en [ARCHITECTURE.md](docs/ARCHITECTURE.md).
|
|
|
|
## Eerste configuratie
|
|
|
|
Voor normaal gebruik heb je nodig:
|
|
|
|
- Windows 10 of 11;
|
|
- Git op het toestel;
|
|
- toegang tot een Gitea-account en een token met de benodigde repositoryrechten;
|
|
- minstens één lokale hoofdmap waarin ForgeFlow projecten mag ontdekken.
|
|
|
|
Voor serverdetectie en SSH-deployments heb je daarnaast een bereikbare Docker- of Unraid-host en een werkende SSH-configuratie nodig. Begin bij:
|
|
|
|
- [SETUP_GUIDE.md](docs/SETUP_GUIDE.md) — Gitea, projectmappen en eerste ingebruikname;
|
|
- [DEPLOYMENT_SETUP.md](docs/DEPLOYMENT_SETUP.md) — deploymentprofielen en verificatie;
|
|
- [SSH_UNRAID_DEPLOYMENT.md](docs/SSH_UNRAID_DEPLOYMENT.md) — SSH- en Unraid-vereisten;
|
|
- [DIAGNOSTICS.md](docs/DIAGNOSTICS.md) — veilige controles en supportbundels.
|
|
|
|
## Ontwikkelen vanuit de broncode
|
|
|
|
Vereisten: Node.js 22, npm en Git.
|
|
|
|
```powershell
|
|
npm ci
|
|
npm run check
|
|
npm start
|
|
```
|
|
|
|
Handige opdrachten:
|
|
|
|
| Opdracht | Doel |
|
|
| --- | --- |
|
|
| `npm run dev` | Start Electron in ontwikkelmodus. |
|
|
| `npm run demo` | Start de browserdemo met voorbeelddata. |
|
|
| `npm run check` | Voert bronverificatie en de volledige testset uit. |
|
|
| `npm run doctor` | Controleert de lokale ontwikkelomgeving. |
|
|
| `npm run acceptance` | Voert de release-acceptatiecontroles uit. |
|
|
| `npm run dist:win` | Bouwt Windows installer + portable package, schrijft checksums en ruimt oude dist-artifacts op. |
|
|
| `.\Publish-ForgeFlow-Release.ps1` | Publiceert broncode én de bijbehorende Windows-release-assets als één gecontroleerde release. |
|
|
| `.\Publish-Missing-Binary-Release.ps1` | Herstelt een reeds gepushte versie waarvoor de Gitea binary release ontbreekt. |
|
|
|
|
De belangrijkste onderdelen zijn:
|
|
|
|
```text
|
|
electron/ beveiligde desktopintegraties en IPC
|
|
src/ renderer, gebruikersflows en visuele componenten
|
|
scripts/ build-, release-, demo- en verificatiehulpmiddelen
|
|
tests/ unit- en integratietests
|
|
docs/ setup, deployment, beveiliging en release-informatie
|
|
```
|
|
|
|
Aanvullende kwaliteitsdocumentatie:
|
|
|
|
- [TEST_MATRIX.md](docs/TEST_MATRIX.md)
|
|
- [ACCEPTANCE.md](docs/ACCEPTANCE.md)
|
|
- [STATUS_ENDPOINT.md](docs/STATUS_ENDPOINT.md)
|
|
- [ROADMAP.md](docs/ROADMAP.md)
|
|
|
|
## Licentie
|
|
|
|
ForgeFlow is beschikbaar onder de [MIT-licentie](LICENSE).
|