DAW/furt
2
0
Fork 0
Code Issues 11 Pull requests Projects Releases 3 Packages 1 Wiki Activity Actions

Wiki-based Documentation: Replace monster scripts with user-friendly guides #87

New issue
Closed
opened 2025-08-14 06:27:05 +02:00 by michael · 4 comments
michael commented 2025-08-14 06:27:05 +02:00
Owner
Copy link

Documentation Problem

Current state:

  • ❌ Monster deployment scripts (700-800+ lines) - unmaintainable
  • ❌ No installation guides for different distributions
  • ❌ No clear configuration documentation
  • ❌ Missing development setup instructions
  • ❌ No API documentation

Problems with monster scripts:

  • Too complex for developers to understand/modify
  • Each server needs custom script (walter 700 lines, tiamat 800 lines)
  • Permission issues and deployment failures
  • Not suitable for Open Source distribution

Solution: Wiki + Small Helper Scripts

Wiki Structure (Forgejo Wiki)

Home.md                    # Project overview + quick links
Installation.md            # Distribution-specific installation
├── OpenBSD-Install.md     # OpenBSD-specific steps
├── Ubuntu-Install.md      # Ubuntu/Debian steps
├── Arch-Install.md        # Arch Linux steps
└── FreeBSD-Install.md     # FreeBSD steps

Configuration.md           # Config system documentation
├── Config-Locations.md    # Where configs go per distribution
├── Environment-Setup.md   # Environment variables
└── Secrets-Management.md  # Secure credential handling

Development.md             # Local development setup
API-Documentation.md       # API endpoints and usage
Troubleshooting.md         # Common issues and solutions
Contributing.md            # How to contribute to project

Small Helper Scripts (replace monsters)

scripts/
├── setup-user.sh         # Create _furt user (10 lines)
├── setup-directories.sh  # Create directory structure (15 lines)
├── sync-files.sh          # Simple file transfer (20 lines)
├── create-service.sh      # OpenBSD service creation (25 lines)
├── validate-config.sh     # Config validation (30 lines)
└── health-check.sh        # Basic health check (15 lines)

Tasks

Wiki Creation

  • Create Forgejo Wiki for furt repository
  • Write Installation.md with distribution-specific sections
  • Document Configuration.md based on Issue DAW/furt#71 research
  • Create Development.md for contributor onboarding
  • Add Troubleshooting.md with common deployment issues

API Documentation

  • Document all current endpoints (/health, /v1/mail/send)
  • Create OpenAPI specification (relates to Issue DAW/furt#53)
  • Add usage examples and error codes
  • Document authentication and rate limiting

Helper Scripts Development

  • Replace deploy_walter.sh with modular scripts
  • Replace deploy_tiamat.sh with modular scripts
  • Create distribution-agnostic installation helpers
  • Add config validation and health check utilities
  • Test all scripts on clean systems

Migration Documentation

  • Create migration guide from monster scripts to manual process
  • Document walter and tiamat current state for reference
  • Add rollback procedures for failed deployments

Success Criteria

  • Complete Wiki documentation for all supported distributions
  • Monster scripts replaced with <100 line helper tools
  • Clear step-by-step installation process
  • New users can install furt without debugging complex scripts
  • Developers can understand and modify installation process

Related Issues

## Documentation Problem **Current state:** - ❌ **Monster deployment scripts** (700-800+ lines) - unmaintainable - ❌ **No installation guides** for different distributions - ❌ **No clear configuration documentation** - ❌ **Missing development setup instructions** - ❌ **No API documentation** **Problems with monster scripts:** - Too complex for developers to understand/modify - Each server needs custom script (walter 700 lines, tiamat 800 lines) - Permission issues and deployment failures - Not suitable for Open Source distribution ## Solution: Wiki + Small Helper Scripts ### Wiki Structure (Forgejo Wiki) ``` Home.md # Project overview + quick links Installation.md # Distribution-specific installation ├── OpenBSD-Install.md # OpenBSD-specific steps ├── Ubuntu-Install.md # Ubuntu/Debian steps ├── Arch-Install.md # Arch Linux steps └── FreeBSD-Install.md # FreeBSD steps Configuration.md # Config system documentation ├── Config-Locations.md # Where configs go per distribution ├── Environment-Setup.md # Environment variables └── Secrets-Management.md # Secure credential handling Development.md # Local development setup API-Documentation.md # API endpoints and usage Troubleshooting.md # Common issues and solutions Contributing.md # How to contribute to project ``` ### Small Helper Scripts (replace monsters) ``` scripts/ ├── setup-user.sh # Create _furt user (10 lines) ├── setup-directories.sh # Create directory structure (15 lines) ├── sync-files.sh # Simple file transfer (20 lines) ├── create-service.sh # OpenBSD service creation (25 lines) ├── validate-config.sh # Config validation (30 lines) └── health-check.sh # Basic health check (15 lines) ``` ## Tasks ### Wiki Creation - [ ] Create Forgejo Wiki for furt repository - [ ] Write Installation.md with distribution-specific sections - [ ] Document Configuration.md based on Issue DAW/furt#71 research - [ ] Create Development.md for contributor onboarding - [ ] Add Troubleshooting.md with common deployment issues ### API Documentation - [ ] Document all current endpoints (/health, /v1/mail/send) - [ ] Create OpenAPI specification (relates to Issue DAW/furt#53) - [ ] Add usage examples and error codes - [ ] Document authentication and rate limiting ### Helper Scripts Development - [ ] Replace deploy_walter.sh with modular scripts - [ ] Replace deploy_tiamat.sh with modular scripts - [ ] Create distribution-agnostic installation helpers - [ ] Add config validation and health check utilities - [ ] Test all scripts on clean systems ### Migration Documentation - [ ] Create migration guide from monster scripts to manual process - [ ] Document walter and tiamat current state for reference - [ ] Add rollback procedures for failed deployments ## Success Criteria - Complete Wiki documentation for all supported distributions - Monster scripts replaced with <100 line helper tools - Clear step-by-step installation process - New users can install furt without debugging complex scripts - Developers can understand and modify installation process ## Related Issues - Issue DAW/furt#71: Config-Strategy Research (foundation) - Issue DAW/furt#86: Repository Redesign Issue (structure) - Issue DAW/furt#55: Native Installation Scripts - Issue DAW/furt#53: OpenAPI Documentation
michael added the
effort
large
priority
high
type
docs
 labels 2025-08-14 06:27:05 +02:00
michael added this to the v0.1.2 - Gateway Basics milestone 2025-08-14 06:27:37 +02:00
michael commented 2025-08-15 12:21:05 +02:00
Author
Owner
Copy link

DEPLOYMENT-ARCHITEKTUR geklärt - 4-stufige Pipeline

Neue Deployment-Strategie nach Diskussion:

Pipeline:

  1. karl/erna (git dev)
  2. walter2 (git quick test) ← NEUER SERVER nötig
  3. walter (package test)
  4. tiamat (package production)

Impact auf #87 Deployment-System-Redesign:

  • Zwei Deployment-Systeme nötig:
    • Git-basiert: karl → walter2 (schnelle Dev-Zyklen)
    • Package-basiert: walter → tiamat (sichere Production-Pipeline)

DAW/furt#88 Package-System wird zentral für walter → tiamat Pipeline.

Dependencies:

  • Infrastruktur: walter2-Server creation (neues Issue)
  • DAW/furt#88: Package-Distribution-System
  • DAW/furt#83: Package-Versioning
  • Git-Deployment-Scripts für karl → walter2

Status: Architektur geklärt, ready for implementation planning

**DEPLOYMENT-ARCHITEKTUR geklärt - 4-stufige Pipeline** Neue Deployment-Strategie nach Diskussion: **Pipeline:** 1. karl/erna (git dev) 2. walter2 (git quick test) ← NEUER SERVER nötig 3. walter (package test) 4. tiamat (package production) **Impact auf #87 Deployment-System-Redesign:** - **Zwei Deployment-Systeme** nötig: - Git-basiert: karl → walter2 (schnelle Dev-Zyklen) - Package-basiert: walter → tiamat (sichere Production-Pipeline) **DAW/furt#88 Package-System** wird zentral für walter → tiamat Pipeline. **Dependencies:** - Infrastruktur: walter2-Server creation (neues Issue) - DAW/furt#88: Package-Distribution-System - DAW/furt#83: Package-Versioning - Git-Deployment-Scripts für karl → walter2 **Status:** Architektur geklärt, ready for implementation planning
michael commented 2025-08-15 18:39:41 +02:00
Author
Owner
Copy link

INTERDEPENDENT DESIGN SESSION NEEDED

Circular Dependencies identified:

  • Helper Scripts need Config + Package structure
  • Package Structure needs Config + Installation process
  • Config System needs Installation + Package layout

Solution: Combined design session for DAW/furt#87 + #88 + #89

Approach: Define all three systems together:

  1. Overall architecture design
  2. Config-structure decisions
  3. Package-layout consensus
  4. Installation-process definition
  5. Then implement all three iteratively

Cannot be done sequentially - must be designed holistically.

## INTERDEPENDENT DESIGN SESSION NEEDED **Circular Dependencies identified:** - Helper Scripts need Config + Package structure - Package Structure needs Config + Installation process - Config System needs Installation + Package layout **Solution:** Combined design session for DAW/furt#87 + #88 + #89 **Approach:** Define all three systems together: 1. Overall architecture design 2. Config-structure decisions 3. Package-layout consensus 4. Installation-process definition 5. Then implement all three iteratively **Cannot be done sequentially - must be designed holistically.**
michael commented 2025-08-15 19:19:23 +02:00
Author
Owner
Copy link

DESIGN SESSION RESULTS - Architecture Decisions Complete (Updated)

Holistic Design Decisions (Issues #87 + #88 + #89)

Config System (Decision 1):

  • Clean cut zu Multi-Tenant furt.conf (nginx-style)
  • Keine Backward Compatibility zu environment files
  • Distribution-agnostic locations via install.sh detection

Package Strategy (Decision 3):

  • Universal tar.gz für alle Distributionen
  • SemVer: ungerade=test, gerade=production
  • Forgejo Generic Packages: furt-api-gateway-v1.0.0.tar.gz

Helper Scripts Philosophy (Decision 4):

  • <100 Zeilen pro Script, ein Zweck pro Script
  • Wiki: Schritt-für-Schritt alles von Hand
  • install.sh: Orchestriert helper scripts transparent

DUAL INSTALLATION STRATEGY (Critical Addition)

Git Installation (Production-ready, nicht nur Development):

git clone https://github.com/dragons-at-work/furt.git
cd furt
./install.sh
  • Admins mit Git-Präferenz: Immer neueste Version
  • Einfache Updates: git pull + ./install.sh --upgrade
  • walter2 Pipeline: Git-based quick testing

Package Installation (Stable Production):

curl -O .../furt-api-gateway-v1.0.0.tar.gz
tar xzf furt-api-gateway-v1.0.0.tar.gz  
cd furt-api-gateway-v1.0.0
./install.sh
  • walter → tiamat Pipeline: Package-based stable testing
  • Feste Versionen für Production
  • Keine Git-Dependency

Implementation-Ready Architecture

Repository Structure (Git + Package Source):

furt/ (Git Repository)
├── src/                    # Lua/C source
├── config/                 # furt.conf.example templates
├── scripts/               # Helper scripts (<100 lines each)
├── docs/                  # Distribution-specific Wiki content
├── install.sh             # Works for Git + Package
└── build-package.sh       # Creates clean tar.gz (Git-only)

Package Structure (Clean Subset):

furt-api-gateway-v1.0.0/ (Package)
├── src/                    # Same source  
├── config/                 # Same templates
├── scripts/               # Same helpers
├── docs/                  # Same docs
└── install.sh             # Same installer
# Excluded: .git/, build-package.sh, dev files

User Categories (Complete)

  1. Entwickler: Git für active development
  2. Admins mit Git-Präferenz: Production via Git (neueste Version)
  3. Admins mit Package-Präferenz: Production via Package (stabile Version)
  4. Pipeline-Testing: walter2 (Git), walter→tiamat (Package)

Next Steps

  1. Repository structure implementation
  2. install.sh with --upgrade support for Git installations
  3. Helper scripts modularization
  4. Wiki documentation for both installation methods
  5. walter/tiamat migration to new config

Status: Complete design phase - ready for parallel implementation of #87/#88/#89

## DESIGN SESSION RESULTS - Architecture Decisions Complete (Updated) ### Holistic Design Decisions (Issues #87 + #88 + #89) **Config System (Decision 1):** - Clean cut zu Multi-Tenant furt.conf (nginx-style) - Keine Backward Compatibility zu environment files - Distribution-agnostic locations via install.sh detection **Package Strategy (Decision 3):** - Universal tar.gz für alle Distributionen - SemVer: ungerade=test, gerade=production - Forgejo Generic Packages: furt-api-gateway-v1.0.0.tar.gz **Helper Scripts Philosophy (Decision 4):** - <100 Zeilen pro Script, ein Zweck pro Script - Wiki: Schritt-für-Schritt alles von Hand - install.sh: Orchestriert helper scripts transparent ### DUAL INSTALLATION STRATEGY (Critical Addition) **Git Installation (Production-ready, nicht nur Development):** ``` git clone https://github.com/dragons-at-work/furt.git cd furt ./install.sh ``` - Admins mit Git-Präferenz: Immer neueste Version - Einfache Updates: git pull + ./install.sh --upgrade - walter2 Pipeline: Git-based quick testing **Package Installation (Stable Production):** ``` curl -O .../furt-api-gateway-v1.0.0.tar.gz tar xzf furt-api-gateway-v1.0.0.tar.gz cd furt-api-gateway-v1.0.0 ./install.sh ``` - walter → tiamat Pipeline: Package-based stable testing - Feste Versionen für Production - Keine Git-Dependency ### Implementation-Ready Architecture **Repository Structure (Git + Package Source):** ``` furt/ (Git Repository) ├── src/ # Lua/C source ├── config/ # furt.conf.example templates ├── scripts/ # Helper scripts (<100 lines each) ├── docs/ # Distribution-specific Wiki content ├── install.sh # Works for Git + Package └── build-package.sh # Creates clean tar.gz (Git-only) ``` **Package Structure (Clean Subset):** ``` furt-api-gateway-v1.0.0/ (Package) ├── src/ # Same source ├── config/ # Same templates ├── scripts/ # Same helpers ├── docs/ # Same docs └── install.sh # Same installer # Excluded: .git/, build-package.sh, dev files ``` ### User Categories (Complete) 1. **Entwickler:** Git für active development 2. **Admins mit Git-Präferenz:** Production via Git (neueste Version) 3. **Admins mit Package-Präferenz:** Production via Package (stabile Version) 4. **Pipeline-Testing:** walter2 (Git), walter→tiamat (Package) ### Next Steps 1. Repository structure implementation 2. install.sh with --upgrade support for Git installations 3. Helper scripts modularization 4. Wiki documentation for both installation methods 5. walter/tiamat migration to new config **Status:** Complete design phase - ready for parallel implementation of #87/#88/#89
michael added the
status
in-progress
 label 2025-08-18 19:37:03 +02:00
michael commented 2025-09-03 22:16:55 +02:00
Author
Owner
Copy link

Helper Scripts Implementation Complete

Monster Scripts Replacement:

  • ✅ install.sh orchestrator - Fresh install + upgrade support
  • ✅ 6 modular helper scripts - All <100 lines, single purpose each
  • ✅ Repository templates - deployment/linux/furt.service added
  • ✅ Platform-aware detection - OpenBSD/FreeBSD vs Linux
  • ✅ Update mechanism - Preserves config, updates source only

Created Helper Scripts:

  • setup-user.sh (12 lines) - System user creation
  • setup-directories.sh (18 lines) - Directory structure
  • sync-files.sh (24 lines) - Source file installation
  • create-service.sh (32 lines) - Service creation from templates
  • validate-config.sh (32 lines) - Configuration validation
  • health-check.sh (28 lines) - Health check functionality

Usage:

  • Fresh install: `./install.sh`
  • Upgrade: `./install.sh --upgrade`
  • All scripts executable and tested

Next: Wiki documentation for distribution-specific installation guides

## Helper Scripts Implementation Complete **Monster Scripts Replacement:** - ✅ **install.sh orchestrator** - Fresh install + upgrade support - ✅ **6 modular helper scripts** - All <100 lines, single purpose each - ✅ **Repository templates** - deployment/linux/furt.service added - ✅ **Platform-aware detection** - OpenBSD/FreeBSD vs Linux - ✅ **Update mechanism** - Preserves config, updates source only **Created Helper Scripts:** - **setup-user.sh** (12 lines) - System user creation - **setup-directories.sh** (18 lines) - Directory structure - **sync-files.sh** (24 lines) - Source file installation - **create-service.sh** (32 lines) - Service creation from templates - **validate-config.sh** (32 lines) - Configuration validation - **health-check.sh** (28 lines) - Health check functionality **Usage:** - Fresh install: \`./install.sh\` - Upgrade: \`./install.sh --upgrade\` - All scripts executable and tested **Next:** Wiki documentation for distribution-specific installation guides
michael added
status
done
 and removed
status
in-progress
 labels 2025-09-03 22:17:10 +02:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
feature/structured-logging-health-monitoring
v0.1.4
v0.1.3
v0.1.2
generation-1-archive
debug-monster-anti-pattern
Labels
Clear labels   
apache

Auto-generated label

  
api

Auto-generated label

  
api-contract

Furt: api_design

  
api-gateway

Auto-generated label

  
authentication

Auto-generated label

  
automation

Auto-generated label

  
breaking-change

Breaking Change - Version Bump nötig

  
comments

Auto-generated label

  
component/deployment

Auto-generated label

  
component/documentation

Auto-generated label

  
component/service-management

Auto-generated label

  
configuration

Konfiguration und Setup

  
contact-form

Auto-generated label

  
coordination/cross-repo

Betrifft mehrere Repositories

  
coordination/needed

Benötigt Abstimmung zwischen Teams/Projekten

  
core

Auto-generated label

  
deployment

Build Deploy und DevOps

  
development

Auto-generated label

  
development-ready

Auto-generated label

  
digital-sovereignty

Fördert digitale Souveränität

  
distribution

Auto-generated label

  
effort
large
Großer Aufwand - mehr als 3 Sessions

  
effort
medium
Mittlerer Aufwand - 1-3 Sessions

  
effort
small
Kleiner Aufwand - weniger als 1 Session

  
enhancement

Verbesserung oder neue Funktion

  
frontend

Auto-generated label

  
furt-service

Auto-generated label

  
furt/gateway

Auto-generated label

  
furt/installation

Auto-generated label

  
gateway

API-Gateway Kern-Funktionalität

  
gateway-integration

Auto-generated label

  
generator

Auto-generated label

  
gitea-testing

Auto-generated label

  
health-check

Auto-generated label

  
help-wanted

Community-Input erwünscht

  
hugo

Auto-generated label

  
hugo-integration

Furt: frontend

  
infrastructure

Infrastructure-related

  
installation

Auto-generated label

  
logging

Auto-generated label

  
low-tech

Im Einklang mit Low-Tech-Prinzipien

  
mail

Auto-generated label

  
meta

Auto-generated label

  
meta/duplicate

Duplikat eines anderen Issues

  
meta/planning

Projekt-Management, Planung, Organisation

  
meta/wontfix

Wird bewusst nicht umgesetzt

  
monitoring

Auto-generated label

  
observability

Auto-generated label

  
openapi

Auto-generated label

  
organization

Auto-generated label

  
packaging

Auto-generated label

  
performance

Performance und Optimierung

  
planning

Auto-generated label

  
platform/linux

Auto-generated label

  
priority
high
Hohe Priorität - sofort bearbeiten

  
priority
low
Niedrige Priorität - wenn Zeit vorhanden

  
priority
medium
Mittlere Priorität - normale Bearbeitung

  
production

Auto-generated label

  
question

Frage oder Hilfe benötigt

  
sagjan

Auto-generated label

  
security

Sicherheit und Authentifizierung

  
service

Auto-generated label

  
service-analytics

Furt: service_integration

  
service-development

Service-specific label

  
service-formular2mail

Formular-zu-E-Mail Service

  
service-newsletter

Furt: newsletter

  
service-request

Anfrage für neuen Service

  
service-sagjan

Sagjan Kommentarsystem Integration

  
session
blocker
Blockiert aktuelle Session - muss zuerst gelöst werden

  
session
handover
Session-Übergabe - Dokumentation für nächste Session

  
session
next
Für nächste Session geplant

  
shortcode

Auto-generated label

  
specs

Auto-generated label

  
ssl

Auto-generated label

  
status
blocked
Blockiert durch andere Issues/Dependencies

  
status
done
Abgeschlossen und getestet

  
status
in-progress
Aktuell in Bearbeitung

  
status
review
Fertig - wartet auf Review/Testing

  
status
to-go
Bereit zum Start - keine Blocker

  
systemd

Auto-generated label

  
testing

Tests und Qualitätssicherung

  
tooling

Auto-generated label

  
type
admin
Administrative Aufgaben, Verwaltung

  
type
bug
Fehler beheben

  
type
config
Konfiguration ändern/anpassen

  
type
deployment
Code/Services auf Server deployen

  
type
docs
Dokumentation erstellen/aktualisieren

  
type
enhancement
Bestehende Funktionalität verbessern

  
type
feature
Neue Funktionalität entwickeln

  
type
handover
Session-Übergabe-Dokumentation

  
type
infrastructure
Server, Domains, Infrastruktur-Management

  
type
installation
Software installieren und einrichten

  
type
maintenance
Wartung, Cleanup, Refactoring

  
type
migration
Daten/Services migrieren

  
type/refactor

Auto-generated label

  
type
research
Recherche, Exploration, Konzept-Evaluation

  
type
security
Sicherheitsbezogene Aufgaben

  
type/testing

Auto-generated label

  
v0.1.0

Auto-generated label

No labels
apache
api
api-contract
api-gateway
authentication
automation
breaking-change
comments
component/deployment
component/documentation
component/service-management
configuration
contact-form
coordination/cross-repo
coordination/needed
core
deployment
development
development-ready
digital-sovereignty
distribution
effort
large
effort
medium
effort
small
enhancement
frontend
furt-service
furt/gateway
furt/installation
gateway
gateway-integration
generator
gitea-testing
health-check
help-wanted
hugo
hugo-integration
infrastructure
installation
logging
low-tech
mail
meta
meta/duplicate
meta/planning
meta/wontfix
monitoring
observability
openapi
organization
packaging
performance
planning
platform/linux
priority
high
priority
low
priority
medium
production
question
sagjan
security
service
service-analytics
service-development
service-formular2mail
service-newsletter
service-request
service-sagjan
session
blocker
session
handover
session
next
shortcode
specs
ssl
status
blocked
status
done
status
in-progress
status
review
status
to-go
systemd
testing
tooling
type
admin
type
bug
type
config
type
deployment
type
docs
type
enhancement
type
feature
type
handover
type
infrastructure
type
installation
type
maintenance
type
migration
type/refactor
type
research
type
security
type/testing
v0.1.0
Milestone
Clear milestone
No items
No milestone
v0.1.2 - Gateway Basics
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: DAW/furt#87
No description provided.
Delete branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?