DevFW-CICD/website-and-documentation
23
0
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: consolidate root documentation to README-* structure
All checks were successful
ci / build (push) Successful in 53s
Details

Browse source 
- Created README-documentor.md: comprehensive guide for content contributors
- Created README-likec4.md: architecture modeling guide (merged from README-ARCHITECTURE.md + LIKEC4-QUICKSTART.md)
- Enhanced README-developer.md:
  - Added Docker/Container Build section (from DOCKER.md)
  - Expanded Testing section (from TESTING.md)
  - Added Version Management section (from VERSIONS.md)
  - Added LikeC4 tasks reference
- Updated README.md: modernized with badges and clear structure
- Deleted redundant files:
  - DOCUMENTOR-GUIDE.md (ASCII art, redundant to README-documentor.md)
  - DOCKER.md (integrated into README-developer.md)
  - TESTING.md (integrated into README-developer.md)
  - README-ARCHITECTURE.md (merged into README-likec4.md)
  - LIKEC4-QUICKSTART.md (merged into README-likec4.md)
  - VERSIONS.md (integrated into README-developer.md)
- Added devbox shell step to local-development.md

All hands-on documentation now follows README-* naming convention.
RELEASE.md retained as process documentation (not hands-on guide).
This commit is contained in:
Stephan Lo 2025-11-07 15:48:55 +01:00
parent 9921e07e3e
commit 9e509ed265
11 changed files with 1127 additions and 644 deletions
Download patch file Download diff file Expand all files Collapse all files

98
DOCKER.md
View file

@ -1,98 +0,0 @@
# Docker Build
This project uses a multi-stage Docker build that matches the local devbox development environment.
## Version Management
All tool versions are defined in `.env.versions` as the single source of truth:
```bash
NODE_VERSION=24.10.0
GO_VERSION=1.25.1
HUGO_VERSION=0.151.0
```
These versions are used in:
- `devbox.json` - Local development environment
- `Dockerfile` - Docker build arguments (with defaults)
- `.github/workflows/ci.yaml` - CI/CD pipeline
**Important:** When updating versions, modify `.env.versions` and sync with `devbox.json`.
## Local Build
### Using Task (recommended)
The easiest way to build the OCI image:
```bash
task build:oci-image
```
This automatically:
- Loads versions from `.env.versions`
- Builds the image with correct build arguments
- Tags with `latest` and git commit hash
To build and test:
```bash
task test:oci-image
```
### Automatic version loading
Use the helper script to load versions from `.env.versions`:
```bash
source scripts/get-versions.sh
```
This will show you the Docker build command with the correct versions.
### Manual build
```bash
docker build --network=host \
--build-arg NODE_VERSION=24.10.0 \
--build-arg GO_VERSION=1.25.1 \
--build-arg HUGO_VERSION=0.151.0 \
-t ipceicis-developerframework:latest .
```
### Test the image
```bash
docker run -d -p 8080:80 --name hugo-test ipceicis-developerframework:latest
curl http://localhost:8080
docker stop hugo-test && docker rm hugo-test
```
## CI/CD Pipeline
The GitHub Actions workflow (`.github/workflows/ci.yaml`) automatically:
1. Extracts versions from devbox environment
2. Builds multi-arch images (amd64 + arm64)
3. Pushes to the container registry with appropriate tags
### Required Secrets
Configure these secrets in your GitHub repository:
- `PACKAGES_USER`: Container registry username
- `PACKAGES_TOKEN`: Container registry token/password
## Image Structure
- **Build Stage**: Uses Node.js base image, installs Go and Hugo
- **Runtime Stage**: Uses nginx:alpine to serve static content (~50MB)
The build process:
1. Installs npm dependencies
2. Downloads Hugo modules
3. Builds static site with `hugo --gc --minify`
4. Copies built site to minimal nginx container

159
DOCUMENTOR-GUIDE.md
View file

@ -1,159 +0,0 @@
# Documentation Platform - Visual Overview
```text
┌─────────────────────────────────────────────────────────────────────────────┐
│ DOCUMENTATION REPOSITORY STRUCTURE │
└─────────────────────────────────────────────────────────────────────────────┘
📁 Repository Root
│
├── 📁 resources/
│ │
│ ├── 📁 edp-likec4/ ← Platform Architecture
│ │ ├── documentation-platform.c4 (Models for EDP systems)
│ │ ├── views.c4
│ │ ├── models/
│ │ └── views/
│ │
│ └── 📁 doc-likec4/ ← Documentation Platform Architecture
│ ├── documentation-platform.c4 (Models for this doc system)
│ ├── views.c4
│ ├── likec4.config.json
│ ├── package.json
│ └── README.md
│
├── 📁 content/en/docs/
│ │
│ ├── 📁 architecture/ ← Platform Architecture Docs
│ │ ├── highlevelarch.md
│ │ └── setup.md
│ │
│ └── 📁 documentation/ ← Documentation About Documentation
│ ├── _index.md (Overview for Documentors)
│ ├── local-development.md (How to work locally)
│ ├── testing.md (Quality assurance)
│ ├── cicd.md (CI/CD pipeline)
│ ├── publishing.md (Deployment to edge)
│ └── quick-reference.md (Cheat sheet)
│
├── 📄 Taskfile.yml ← Build Automation
├── 📄 .github/workflows/test.yml ← CI Pipeline
├── 📄 k8s-deployment.yaml ← Kubernetes Config
├── 📄 edgeconnectdeployment.yaml ← Edge Deployment Config
├── 📄 Dockerfile ← Container Definition
└── 📄 README-ARCHITECTURE.md ← This Overview
┌─────────────────────────────────────────────────────────────────────────────┐
│ DOCUMENTOR WORKFLOW │
└─────────────────────────────────────────────────────────────────────────────┘
👤 Documentor
│
├──> 1. Write Content
│ └── content/en/docs/**/*.md
│
├──> 2. Create Architecture Models
│ └── resources/doc-likec4/*.c4
│ resources/edp-likec4/*.c4
│
├──> 3. Local Development
│ └── task serve
│ http://localhost:1313
│
├──> 4. Test Locally
│ └── task test:quick
│ - Build validation
│ - Markdown lint
│
├──> 5. Commit & Push
│ └── git push origin feature-branch
│
└──> 6. CI/CD Pipeline
├── GitHub Actions
│ ├── Build Test
│ ├── Markdown Lint
│ ├── HTML Validation
│ └── Link Checking
│
├── Container Build
│ └── Docker Image
│
└── Edge Deployment
└── Kubernetes on Munich Cloudlet
└── http://<external-ip>
┌─────────────────────────────────────────────────────────────────────────────┐
│ ARCHITECTURE VISUALIZATION │
└─────────────────────────────────────────────────────────────────────────────┘
Two Separate LikeC4 Projects:
┌──────────────────────────────┐ ┌──────────────────────────────┐
│ resources/edp-likec4/ │ │ resources/doc-likec4/ │
│ ───────────────────── │ │ ───────────────────── │
│ │ │ │
│ Platform Architecture │ │ Documentation Platform │
│ ──────────────────── │ │ ──────────────────── │
│ │ │ │
│ • Systems │ │ • Hugo/Docsy │
│ • Services │ │ • LikeC4 Integration │
│ • Infrastructure │ │ • Taskfile │
│ • Deployment Environments │ │ • GitHub Actions │
│ │ │ • Edge Deployment │
│ What we BUILD │ │ How we DOCUMENT │
│ │ │ │
└──────────────────────────────┘ └──────────────────────────────┘
│ │
│ │
▼ ▼
content/en/docs/ content/en/docs/
architecture/ documentation/
┌─────────────────────────────────────────────────────────────────────────────┐
│ QUICK START │
└─────────────────────────────────────────────────────────────────────────────┘
For New Documentors:
1. 📖 Read the Guide
→ Open: content/en/docs/documentation/_index.md
→ Or browse: http://localhost:1313/docs/documentation/
2. 🚀 Start Development
$ task serve
3. 📊 View Architecture
$ cd resources/doc-likec4
$ npm install
$ npm start
→ Opens: http://localhost:5173
4. ✅ Test Your Changes
$ task test:quick
5. 📚 Reference
→ Quick Reference: content/en/docs/documentation/quick-reference.md
┌─────────────────────────────────────────────────────────────────────────────┐
│ AVAILABLE VIEWS │
└─────────────────────────────────────────────────────────────────────────────┘
In resources/doc-likec4/views.c4:
• overview → Complete system overview
• localDevelopment → Documentor workflow with Taskfile
• cicdPipeline → Automated testing via GitHub Actions
• deploymentFlow → Edge deployment process
• fullWorkflow → End-to-end content → production
• testingCapabilities → All automated tests
Embed in Markdown:
{{< likec4-view view="overview" project="documentation-platform" >}}
With custom title:
{{< likec4-view view="overview" project="documentation-platform" title="Platform Overview" >}}
```

112
LIKEC4-QUICKSTART.md
View file

@ -1,112 +0,0 @@
# LikeC4 Integration - Quick Start
Dieses Repository enthält jetzt die LikeC4-Architekturdokumentation aus edp-doc mit vollständiger Git-Historie.
## Was wurde gemacht?
1. ✅ **LikeC4-Modelle migriert** - `resources/likec4/` enthält alle C4-Modelle mit Git-Historie
2. ✅ **Hugo-Integration erstellt** - CSS, JS und Loader-Scripte für Hugo/Docsy
3. ✅ **Beispielseiten erstellt** - Dokumentation unter `content/en/docs/architecture/`
4. ✅ **Konfiguration** - `hugo.toml` und Layout-Hooks konfiguriert
## Nächste Schritte
### 1. Webcomponent generieren
```bash
cd resources/likec4
# Dependencies installieren (nur einmalig)
npm install
# Webcomponent generieren
npx likec4 codegen webcomponent \
--webcomponent-prefix likec4 \
--outfile ../../static/js/likec4-webcomponent.js
```
Dies erzeugt `static/js/likec4-webcomponent.js` (~2-3 MB).
### 2. Hugo Server starten
```bash
# Im Repository-Root
hugo server -D
# Öffne http://localhost:1313/docs/architecture/highlevelarch/
```
### 3. Änderungen committen
```bash
git add resources/likec4/
git add static/
git add layouts/
git add content/en/docs/architecture/
git add hugo.toml
git commit -m "feat: integrate LikeC4 architecture documentation from edp-doc"
```
## Verfügbare Seiten
- `/docs/architecture/` - Architektur-Übersicht
- `/docs/architecture/highlevelarch/` - High-Level Architektur mit interaktivem Diagramm
- `/docs/architecture/setup/` - Setup und Verwendungs-Anleitung
## Workflow für Architektur-Änderungen
1. **Modelle bearbeiten**: `.c4` Dateien in `resources/likec4/models/` oder `views/`
2. **Vorschau**: `cd resources/likec4 && npx likec4 start` (öffnet http://localhost:5173)
3. **Generieren**: Webcomponent neu generieren (siehe oben)
4. **Testen**: Hugo Server starten und Seiten prüfen
5. **Committen**: Sowohl `.c4` Dateien als auch `static/js/likec4-webcomponent.js`
## Technische Details
### Integration-Komponenten
- `resources/likec4/` - LikeC4 Quellcode (migriert mit Git-Historie)
- `static/js/likec4-loader.js` - Dynamischer Module Loader
- `static/css/likec4-styles.css` - Styling inkl. Dark Mode
- `layouts/partials/hooks/head-end.html` - Hugo Hook für JS/CSS Einbindung
- `hugo.toml` - Konfiguration (`params.likec4.enable = true`)
### Verwendung in Markdown
```html
<div class="likec4-container">
<div class="likec4-header">
Dein Diagramm-Titel
</div>
<likec4-view view-id="otc-faas" browser="true"></likec4-view>
<div class="likec4-loading" id="likec4-loading">
Loading...
</div>
</div>
```
### Verfügbare View-IDs finden
```bash
cd resources/likec4
grep -r "view\s\+\w" views/ models/ --include="*.c4"
```
## Häufige View-IDs
- `otc-faas` - OTC FaaS Deployment
- `edp` - EDP Übersicht
- `landscape` - Developer Landscape
- `edpbuilderworkflow` - Builder Workflow
- `keycloak`, `forgejo`, `argoCD`, etc. - Komponenten-Views
## Migration von edp-doc
Dieses Repository ist jetzt die primäre Quelle für LikeC4-Architektur. Das edp-doc Repository kann diese Modelle bei Bedarf als Git Submodule referenzieren.
## Support
Bei Problemen siehe:
- `resources/likec4/INTEGRATION.md` - Detaillierte Integration-Dokumentation
- `content/en/docs/architecture/setup.md` - Setup-Anleitung
- https://likec4.dev/ - LikeC4 Dokumentation

92
README-ARCHITECTURE.md
View file

@ -1,92 +0,0 @@
# Documentation Platform - Overview
This repository contains two distinct LikeC4 architecture documentation projects:
## 📁 Structure
### `resources/edp-likec4/`
**Enterprise Developer Platform (EDP) Architecture**
Contains architecture models for the platform itself - the systems, services, and infrastructure that make up the EDP.
**Purpose:** Document what we build
### `resources/doc-likec4/`
**Documentation Platform Architecture**
Contains architecture models that explain how this documentation system works - the Hugo/Docsy setup, CI/CD pipeline, and deployment process.
**Purpose:** Document how we document (meta-documentation)
## 🎯 For New Documentors
If you're new to the documentor role and want to understand the documentation platform:
1. **Read the documentation about documentation:**
→ `content/en/docs/documentation/`
2. **View the architecture diagrams:**
→ The documentation pages embed interactive LikeC4 diagrams
3. **Key sections:**
- [Overview](content/en/docs/documentation/_index.md) - What is a documentor?
- [Local Development](content/en/docs/documentation/local-development.md) - Get started
- [Testing](content/en/docs/documentation/testing.md) - Quality assurance
- [CI/CD](content/en/docs/documentation/cicd.md) - Automated pipeline
- [Publishing](content/en/docs/documentation/publishing.md) - Deployment to edge
## 🚀 Quick Start
```bash
# Start development server
task serve
# Run tests
task test:quick
# View architecture models
cd resources/doc-likec4
npm install
npm start
```
## 📊 Architecture Views
The documentation platform is visualized with these views:
- **Overview** - Complete system overview
- **Local Development** - Documentor workflow
- **CI/CD Pipeline** - Automated testing
- **Deployment Flow** - Edge deployment process
- **Full Workflow** - End-to-end journey
- **Testing Capabilities** - Quality assurance
## 🔗 Related Files
- `Taskfile.yml` - Automation for local development and CI
- `.github/workflows/test.yml` - GitHub Actions CI pipeline
- `k8s-deployment.yaml` - Kubernetes deployment manifest
- `edgeconnectdeployment.yaml` - Edge Connect configuration
- `Dockerfile` - Container image definition
## 📚 Documentation
The documentation is built with:
- **Hugo** - Static site generator
- **Docsy** - Documentation theme
- **LikeC4** - Architecture visualization
- **Task** - Build automation
- **GitHub Actions** - CI/CD
- **Edge Connect** - Deployment platform
## 🎓 Learn More
For complete information, browse to the documentation section after starting the server:
```bash
task serve
# Then open: http://localhost:1313/docs/documentation/
```

191
README-developer.md
View file

@ -12,7 +12,11 @@ curl -fsSL https://get.jetify.com/devbox | bash
### Setup
1. Clone the repository
2. Start devbox shell:
2. Install dependencies:
```bash
task deps:install
```
3. Start devbox shell:
```bash
devbox shell
```
@ -25,6 +29,8 @@ Devbox automatically installs all required tools:
- htmltest
- go-task
> **Note:** For content contributors, see [README-documentor.md](./README-documentor.md) for a simplified guide.
## 📚 Technology Stack
### Hugo (v0.151.0+extended)
@ -49,6 +55,22 @@ Key directories:
- `assets/scss/` - Custom styles
- `static/` - Static assets (images, etc.)
### LikeC4 (v1.43.0)
LikeC4 is used for interactive architecture diagrams:
- C4 model-based architecture visualization
- Web Components for embedding diagrams
- Real-time preview during development
Architecture models:
- `resources/edp-likec4/` - Platform architecture models
- `resources/doc-likec4/` - Documentation platform models
LikeC4 tasks available:
- `task likec4:generate` - Generate web components
- `task likec4:validate` - Validate C4 models
- `task likec4:update` - Update LikeC4 version
### Task (Taskfile)
Task is a task runner / build tool that replaces Makefiles. It uses `Taskfile.yml` for defining tasks.
@ -90,6 +112,140 @@ task deps:install # Install all dependencies
task deps:update # Update all dependencies
```
#### LikeC4
```bash
task likec4:generate # Generate web components from C4 models
task likec4:validate # Validate C4 model syntax
task likec4:update # Update LikeC4 to latest version
```
#### Build & Test OCI Image
```bash
task build:oci-image # Build Docker/OCI image
task test:oci-image # Build and test image
```
#### CI/CD
```bash
task ci # Run full CI pipeline locally
```
## 🧪 Testing
This project uses multiple automated tests for quality assurance.
### Test Configuration Files
- `.htmltest.yml` - Link checker configuration
- `.htmlvalidate.json` - HTML validation rules
- `.markdownlint.json` - Markdown linting rules
### CI/CD Integration
GitHub Actions runs these tests automatically on every push/PR via `.github/workflows/test.yml`.
### Local Development Workflow
**Before commit:**
```bash
task test:quick
```
**Before push:**
```bash
task test
```
## 🐳 Docker / Container Build
### Version Management
All tool versions are defined in `.env.versions` as the single source of truth:
```bash
NODE_VERSION=24.10.0
GO_VERSION=1.25.1
HUGO_VERSION=0.151.0
```
These versions are used in:
- `devbox.json` - Local development (manual sync required)
- `Dockerfile` - Build arguments with defaults
- `.github/workflows/ci.yaml` - CI/CD pipeline (automatic)
**Updating versions:**
1. Edit `.env.versions`
2. Manually sync `devbox.json`:
```json
{
"packages": [
"hugo@0.151.0",
"go@1.25.1",
"nodejs@24.10.0"
]
}
```
3. Rebuild: `devbox shell --refresh`
### Local Build
**Using Task (recommended):**
```bash
task build:oci-image # Build OCI image
task test:oci-image # Build and test
```
This automatically loads versions from `.env.versions` and tags with `latest` and git commit hash.
**Helper script for manual builds:**
```bash
source scripts/get-versions.sh
# Shows Docker build command with correct versions
```
**Manual build:**
```bash
docker build --network=host \
--build-arg NODE_VERSION=24.10.0 \
--build-arg GO_VERSION=1.25.1 \
--build-arg HUGO_VERSION=0.151.0 \
-t ipceicis-developerframework:latest .
```
**Test the image:**
```bash
docker run -d -p 8080:80 --name hugo-test ipceicis-developerframework:latest
curl http://localhost:8080
docker stop hugo-test && docker rm hugo-test
```
### Image Structure
- **Build Stage**: Node.js base, installs Go and Hugo
- **Runtime Stage**: nginx:alpine serves static content (~50MB)
Build process:
1. Install npm dependencies
2. Download Hugo modules
3. Build static site (`hugo --gc --minify`)
4. Copy to nginx container
### CI/CD Pipeline
`.github/workflows/ci.yaml` automatically:
1. Extracts versions from devbox environment
2. Builds multi-arch images (amd64 + arm64)
3. Pushes to container registry
**Required GitHub Secrets:**
- `PACKAGES_USER` - Registry username
- `PACKAGES_TOKEN` - Registry token/password
#### CI/CD
```bash
task ci # Run full CI pipeline locally
@ -128,16 +284,27 @@ hugo version
│ └── en/ # English content
│ ├── docs/ # Documentation
│ └── blog/ # Blog posts
├── resources/ # LikeC4 architecture models
│ ├── edp-likec4/ # Platform architecture (C4 models)
│ └── doc-likec4/ # Documentation platform architecture
├── layouts/ # Custom HTML templates
│ └── shortcodes/ # Custom shortcodes (e.g., likec4-view)
├── static/ # Static files
│ └── js/ # JavaScript (LikeC4 webcomponents)
├── assets/ # Assets (SCSS, images)
├── public/ # Generated site (not in Git)
├── resources/ # Hugo cache (not in Git)
├── hugo.toml # Hugo configuration
├── go.mod # Hugo modules (Docsy theme)
├── Taskfile.yml # Task definitions
├── package.json # NPM dependencies & scripts
└── devbox.json # Devbox configuration
├── devbox.json # Devbox configuration
├── .env.versions # Version definitions (SSOT)
├── Dockerfile # Multi-stage container build
├── README.md # Main README
├── README-developer.md # This file
├── README-documentor.md # Guide for content contributors
├── README-likec4.md # LikeC4 architecture modeling guide
└── RELEASE.md # Release process documentation
```
## 📝 Content Creation
@ -197,6 +364,18 @@ Important information
{{</* /alert */>}}
```
#### LikeC4 Architecture Diagrams
```markdown
{{</* likec4-view view="overview" project="architecture" title="System Overview" */>}}
```
Parameters:
- `view` - View ID from C4 model
- `project` - `"architecture"` or `"documentation-platform"`
- `title` - Optional custom title
See [README-documentor.md](./README-documentor.md) for detailed LikeC4 workflow.
## 🧪 Testing
See [TESTING.md](TESTING.md) for detailed testing documentation.
@ -285,9 +464,15 @@ devbox shell --refresh
- [Hugo Documentation](https://gohugo.io/documentation/)
- [Docsy Documentation](https://www.docsy.dev/docs/)
- [LikeC4 Documentation](https://likec4.dev/)
- [Taskfile Documentation](https://taskfile.dev/)
- [Devbox Documentation](https://www.jetify.com/devbox/docs/)
**Project-specific guides:**
- [README-documentor.md](./README-documentor.md) - Content contributor guide
- [TESTING.md](./TESTING.md) - Detailed testing documentation
- [DOCUMENTOR-GUIDE.md](./DOCUMENTOR-GUIDE.md) - Quick reference for documentors
## 🤝 Contributing
1. Create a feature branch

434
README-documentor.md Normal file
View file

@ -0,0 +1,434 @@
# Documentor Guide
Welcome! This guide helps you contribute to the IPCEI-CIS Developer Framework documentation.
## Prerequisites
- Basic knowledge of Markdown
- Git installed
- Either **Devbox** (recommended) or manual tool installation
## Quick Start
### 1. Clone and Setup
```bash
# Clone the repository
git clone <repository-url>
cd ipceicis-developerframework
# Install dependencies
task deps:install
# If using Devbox
devbox shell
```
### 2. Start Development Server
```bash
task serve
```
Open your browser at `http://localhost:1313` - changes appear instantly!
### 3. Create Content
Create a new page:
```bash
# Example: Add a new guide
vim content/en/docs/your-topic/_index.md
```
Add frontmatter:
```yaml
---
title: "Your Topic"
linkTitle: "Your Topic"
weight: 10
description: >
Brief description of your topic.
---
Your content here...
```
### 4. Test and Commit
```bash
# Run tests
task test:quick
# Commit your changes
git add .
git commit -m "docs: Add guide for X"
git push
```
## Documentation Structure
```
content/en/
├── _index.md # Homepage
├── docs/
│ ├── architecture/ # Architecture documentation
│ │ └── highlevelarch.md
│ ├── documentation/ # Documentation guides
│ │ ├── local-development.md
│ │ ├── testing.md
│ │ └── cicd.md
│ ├── decisions/ # ADRs (Architecture Decision Records)
│ └── v1/ # Legacy documentation
└── blog/ # Blog posts
└── 20250401_review.md
```
## Writing Documentation
### Markdown Basics
```markdown
# Heading 1
## Heading 2
### Heading 3
**Bold text**
*Italic text*
- Bullet list
- Item 2
1. Numbered list
2. Item 2
[Link text](https://example.com)
`inline code`
\`\`\`bash
# Code block
echo "Hello"
\`\`\`
```
### Using Shortcodes
#### Alerts
```markdown
{{< alert title="Note" >}}
Important information here
{{< /alert >}}
{{< alert title="Warning" color="warning" >}}
Warning message
{{< /alert >}}
```
#### Code Tabs
```markdown
{{< tabpane >}}
{{< tab header="Bash" >}}
\`\`\`bash
echo "Hello"
\`\`\`
{{< /tab >}}
{{< tab header="Python" >}}
\`\`\`python
print("Hello")
\`\`\`
{{< /tab >}}
{{< /tabpane >}}
```
## Creating Architecture Diagrams
### 1. Edit LikeC4 Models
Navigate to the appropriate project:
- `resources/edp-likec4/` - Platform architecture
- `resources/doc-likec4/` - Documentation platform architecture
Create or edit `.c4` files:
```likec4
specification {
element person
element system
}
model {
user = person 'User' {
description 'End user of the platform'
}
platform = system 'Platform' {
description 'The EDP platform'
}
user -> platform 'uses'
}
views {
view overview {
title "System Overview"
include user
include platform
autoLayout TopBottom
}
}
```
### 2. Generate Webcomponent
```bash
task likec4:generate
```
### 3. Embed in Documentation
```markdown
{{< likec4-view view="overview" project="architecture" title="System Overview" >}}
```
**Parameters:**
- `view` - View ID from your `.c4` file
- `project` - `"architecture"` or `"documentation-platform"`
- `title` - Custom header text (optional)
### 4. Find Available Views
```bash
# List all view IDs
grep -r "^view " resources/edp-likec4/ --include="*.c4"
```
## Available Tasks
View all tasks:
```bash
task --list
```
### Development Tasks
| Task | Description |
|------|-------------|
| `task serve` | Start dev server with hot reload |
| `task build` | Build production site |
| `task clean` | Remove build artifacts |
| `task test` | Run all tests (build, markdown, HTML, links) |
| `task test:quick` | Run quick tests (build, markdown) |
### LikeC4 Tasks
| Task | Description |
|------|-------------|
| `task likec4:generate` | Generate webcomponents from `.c4` files |
| `task likec4:validate` | Validate LikeC4 syntax |
| `task likec4:update` | Update LikeC4 to latest version |
### Dependency Tasks
| Task | Description |
|------|-------------|
| `task deps:install` | Install all dependencies |
| `task deps:update` | Update dependencies |
## Testing
### Quick Test (Recommended)
Before committing:
```bash
task test:quick
```
Validates:
- Hugo build succeeds
- Markdown syntax is correct
- LikeC4 models are valid
### Full Test
Includes link checking:
```bash
task test
```
**Note:** Link checking can be slow. Use `test:quick` during development.
## Best Practices
### Writing Style
✅ **Do:**
- Write in present tense: "The system processes..."
- Use code blocks with syntax highlighting
- Keep sections concise (3-5 paragraphs max)
- Add diagrams for complex concepts
- Use bullet points for lists
- Test locally before committing
❌ **Don't:**
- Use future tense: "The system will process..."
- Write long paragraphs (split into sections)
- Forget to add descriptions in frontmatter
- Commit without testing
### Frontmatter
Always include:
```yaml
---
title: "Page Title" # Full title
linkTitle: "Short Title" # Used in navigation
weight: 10 # Order in menu (lower = higher)
description: > # Used in SEO and cards
Brief description of the page content.
---
```
Optional:
```yaml
---
date: 2025-01-15 # Publication date (for blog posts)
author: "Your Name" # Author name
categories: ["Category"] # Categories
tags: ["tag1", "tag2"] # Tags
---
```
### File Naming
- Use lowercase
- Use hyphens, not underscores: `my-guide.md` not `my_guide.md`
- Main page in a section: `_index.md`
- Single page: `page-name.md`
### Images
Place images in the same folder as your markdown file:
```
docs/my-guide/
├── _index.md
├── screenshot.png
└── diagram.svg
```
Reference them:
```markdown
![Alt text](screenshot.png)
```
## Common Issues
### Port 1313 already in use
```bash
# Find and kill the process
lsof -ti:1313 | xargs kill -9
```
### Build errors
```bash
# Clean and rebuild
task clean
task build:dev
```
### Hugo not found (when not using Devbox)
```bash
# Make sure you're in devbox shell
devbox shell
# Or install Hugo manually
# See: https://gohugo.io/installation/
```
### LikeC4 validation fails
```bash
# Validate with detailed output
cd resources/edp-likec4
npx likec4 validate --verbose
# Ignore layout drift (common, not critical)
npx likec4 validate --ignore-layout
```
## Git Workflow
### Create a Branch
```bash
git checkout -b feature/my-new-guide
```
### Commit Changes
```bash
# Stage your changes
git add content/en/docs/my-guide/
# Commit with clear message
git commit -m "docs: Add guide for X feature"
```
### Commit Message Convention
Format: `<type>: <description>`
Types:
- `docs:` - Documentation changes
- `feat:` - New feature or content
- `fix:` - Bug fix or correction
- `chore:` - Maintenance tasks
- `style:` - CSS/styling changes
Examples:
```
docs: Add installation guide for Windows users
feat: Add interactive architecture diagram for OTC deployment
fix: Correct typo in API documentation
chore: Update LikeC4 to version 1.43.0
```
### Push and Create PR
```bash
# Push your branch
git push origin feature/my-new-guide
# Create Pull Request on Forgejo/GitHub
```
## Getting Help
- **Full Documentation**: See `/content/en/docs/documentation/`
- **LikeC4 Documentation**: https://likec4.dev/
- **Hugo Documentation**: https://gohugo.io/documentation/
- **Docsy Theme**: https://www.docsy.dev/docs/
## Next Steps
1. Read the [Local Development Guide](./content/en/docs/documentation/local-development.md)
2. Explore [Architecture Documentation](./content/en/docs/architecture/)
3. Check [Testing Guide](./content/en/docs/documentation/testing.md)
4. Learn about [CI/CD Pipeline](./content/en/docs/documentation/cicd.md)
Happy documenting! 📝✨

383
README-likec4.md Normal file
View file

@ -0,0 +1,383 @@
# LikeC4 Architecture Modeling
This repository contains two distinct LikeC4 architecture projects for C4 model-based architecture visualization.
## 📁 Project Structure
### `resources/edp-likec4/`
**Enterprise Developer Platform (EDP) Architecture**
Contains architecture models for the platform itself - the systems, services, and infrastructure that make up the EDP.
- **Purpose:** Document what we build
- **Models:** Platform components, services, deployment environments
- **Views:** System overviews, component details, deployment diagrams
### `resources/doc-likec4/`
**Documentation Platform Architecture**
Contains architecture models that explain how this documentation system works - the Hugo/Docsy setup, CI/CD pipeline, and deployment process.
- **Purpose:** Document how we document (meta-documentation)
- **Models:** Hugo, LikeC4, Taskfile, GitHub Actions, Edge deployment
- **Views:** Documentation workflow, CI/CD pipeline, testing capabilities
## 🚀 Quick Start
### 1. Install Dependencies
```bash
# In the LikeC4 project directory
cd resources/edp-likec4
# or
cd resources/doc-likec4
# Install dependencies (only once)
npm install
```
### 2. Start LikeC4 Preview
Preview your architecture models in the browser:
```bash
npm start
# Opens http://localhost:5173
```
This launches the interactive LikeC4 viewer where you can:
- Navigate through all views
- Explore relationships
- Test changes in real-time
### 3. Edit Models
Edit `.c4` files in your project:
**Example structure:**
```text
resources/edp-likec4/
├── models/
│ ├── systems.c4 # System definitions
│ ├── services.c4 # Service components
│ └── infrastructure.c4 # Infrastructure elements
├── views/
│ ├── overview.c4 # High-level views
│ ├── deployment/ # Deployment views
│ └── components/ # Component details
├── deployment/
│ └── environments.c4 # Deployment configurations
└── likec4.config.json # LikeC4 configuration
```
**Example C4 model:**
```likec4
specification {
element system
element service
element database
}
model {
mySystem = system 'My System' {
description 'System description'
backend = service 'Backend API' {
description 'REST API service'
}
db = database 'Database' {
description 'PostgreSQL database'
}
backend -> db 'reads/writes'
}
}
views {
view systemOverview {
title "System Overview"
include mySystem
autoLayout TopBottom
}
}
```
### 4. Generate Web Components
After editing models, generate the web component for Hugo:
```bash
# From repository root
task likec4:generate
```
This creates `static/js/likec4-webcomponent.js` (~2-3 MB) with all views.
### 5. Embed in Hugo
Use the `likec4-view` shortcode in Markdown:
```markdown
{{</* likec4-view view="systemOverview" project="architecture" title="System Overview" */>}}
```
Parameters:
- `view` - View ID from your C4 model (required)
- `project` - `"architecture"` (edp-likec4) or `"documentation-platform"` (doc-likec4)
- `title` - Optional custom title
## 🔄 Development Workflow
### Architecture Changes Workflow
1. **Edit Models**
- Modify `.c4` files in `models/` or `views/`
2. **Preview Changes**
```bash
cd resources/edp-likec4 # or doc-likec4
npm start
```
Opens http://localhost:5173 for real-time preview
3. **Validate Models**
```bash
# From repository root
task likec4:validate
```
4. **Generate Web Components**
```bash
task likec4:generate
```
5. **Test in Hugo**
```bash
task serve
# Open http://localhost:1313
```
6. **Commit Changes**
```bash
git add resources/edp-likec4/
git add resources/doc-likec4/
git add static/js/likec4-webcomponent.js
git commit -m "feat: update architecture diagrams"
```
### Available Tasks
```bash
task likec4:generate # Generate web components from all projects
task likec4:validate # Validate C4 models (ignore layout drift)
task likec4:update # Update LikeC4 to latest version
```
## 🔍 Finding View IDs
To find available view IDs for embedding:
```bash
# In the project directory
cd resources/edp-likec4
grep -r "^view " views/ models/ --include="*.c4"
# Or search all C4 files
grep -r "view\s\+\w" . --include="*.c4"
```
View IDs are defined in your C4 files:
```likec4
views {
view myViewId { # ← This is the view ID
title "My View"
// ...
}
}
```
## 📚 LikeC4 Syntax
### Specification Block
Define element and relationship types:
```likec4
specification {
element person
element system
element container
element component
relationship async
relationship sync
}
```
### Model Block
Define your architecture:
```likec4
model {
customer = person 'Customer' {
description 'End user'
}
system = system 'My System' {
frontend = container 'Frontend' {
description 'React application'
}
backend = container 'Backend' {
description 'Node.js API'
}
frontend -> backend 'API calls'
}
customer -> system.frontend 'uses'
}
```
### Views Block
Create diagrams:
```likec4
views {
view overview {
title "System Overview"
include *
autoLayout TopBottom
}
view systemDetail {
title "System Details"
include system.*
autoLayout LeftRight
}
}
```
## 🎯 Common View IDs
### EDP Platform (resources/edp-likec4/)
- `edp` - EDP overview
- `landscape` - Developer landscape
- `otc-faas` - OTC FaaS deployment
- `edpbuilderworkflow` - Builder workflow
- Component views: `keycloak`, `forgejo`, `argoCD`, etc.
### Documentation Platform (resources/doc-likec4/)
- `overview` - Complete system overview
- `localDevelopment` - Documentor workflow
- `cicdPipeline` - CI/CD pipeline
- `deploymentFlow` - Edge deployment
- `fullWorkflow` - End-to-end workflow
- `testingCapabilities` - Testing overview
## 🛠️ Configuration
### likec4.config.json
Each project has a configuration file:
```json
{
"sources": [
"models/**/*.c4",
"views/**/*.c4",
"deployment/**/*.c4"
]
}
```
This tells LikeC4 where to find your model files.
## 🔗 Integration with Hugo
### How It Works
1. **Source:** `.c4` files contain your architecture models
2. **Codegen:** `task likec4:generate` creates a self-contained web component
3. **Static Asset:** `static/js/likec4-webcomponent.js` bundled with Hugo site
4. **Custom Element:** Web Components standard enables `<likec4-view>` tag
5. **Rendering:** Shadow DOM renders interactive diagrams
### Web Component Registration
The web component is automatically loaded via `layouts/partials/hooks/head-end.html`:
```html
<script type="module" src="/js/likec4-loader.js"></script>
```
This loader dynamically loads the LikeC4 web component only on pages that use it.
### Styling
Custom styles in `static/css/likec4-styles.css`:
- Dark mode support
- Telekom magenta color scheme
- Responsive sizing
- Loading indicators
## 📖 Resources
- [LikeC4 Documentation](https://likec4.dev/)
- [LikeC4 GitHub](https://github.com/likec4/likec4)
- [C4 Model](https://c4model.com/)
## 🔧 Troubleshooting
### Web Component Not Rendering
1. Check that view ID exists:
```bash
grep -r "view yourViewId" resources/
```
2. Regenerate web component:
```bash
task likec4:generate
```
3. Clear browser cache and reload
### Layout Drift Warnings
Layout drift warnings during validation are expected and can be ignored:
```bash
task likec4:validate # Ignores layout drift
task likec4:validate:layout # Full validation including layout
```
### NPM Errors
```bash
cd resources/edp-likec4
rm -rf node_modules package-lock.json
npm install
```
## 🎓 Learn More
For detailed usage in content creation, see:
- [README-documentor.md](./README-documentor.md) - Content contributor guide
- [content/en/docs/documentation/local-development.md](./content/en/docs/documentation/local-development.md) - Local development guide

163
README.md
View file

@ -1,88 +1,153 @@
# IPCEICIS-DeveloperFramework Documentation
# IPCEI-CIS Developer Framework Documentation
This repo contains business and architectural design and documentation of the DeveloperFramework subproject of IPCEI-CIS.
[![Built with Hugo](https://img.shields.io/badge/Built%20with-Hugo-pink.svg)](https://gohugo.io/)
[![Styled with Docsy](https://img.shields.io/badge/Styled%20with-Docsy-blue.svg)](https://www.docsy.dev/)
[![Architecture with LikeC4](https://img.shields.io/badge/Architecture-LikeC4-purple.svg)](https://likec4.dev/)
## How to read and contribute to this documentation locally
This repository contains the comprehensive documentation for the IPCEI-CIS Developer Framework, including:
The documentation is done in [Hugo-format](https://gohugo.io).
- 🏗️ **Architecture Documentation** - Interactive C4 diagrams and system design
- 📖 **User Guides** - How to use and develop with the platform
- 📝 **ADRs** - Architecture Decision Records
- 🚀 **Platform Features** - Component documentation and guides
Hugo is a static site renderer - so to get the documentation site presented you need a running Hugo processor. Therefore there is
## Quick Start
* either a Hugo [`.devcontainer`-definition](https://containers.dev/) - just run a devcontainer aware IDE or CLI, e.g. Visual Studio code
* or a Hugo [`Devbox`-definition](https://www.jetify.com/devbox/) - in this case just run a devbox shell
### For Documentors (Content Writers)
## Local installation of the Hugo documentation system
If you want to contribute to the documentation, see **[README-documentor.md](./README-documentor.md)** for detailed instructions.
We describe two possible ways (one with devcontainer, one with devbox) to get the Hugo-documentation system locally running.
**Quick start:**
For both prepare the following three steps:
```bash
# Clone the repository
git clone <repository-url>
cd ipceicis-developerframework
1. open a terminal on your local box
2. clone this repo: `git clone https://forgejo.edf-bootstrap.cx.fg1.ffm.osc.live/DevFW/website-and-documentation`
3. change to the repo working dir: `cd website-and-documentation`
# Install dependencies
task deps:install
### Possibility 1: Hugo in a devcontainer
# If using Devbox
devbox shell
[`devcontainers`](https://containers.dev/) are running containers as virtual systems on your local box. The defintion is in the `.devcontainer` folder.
Thus as preliminary you need a container daemon running, e.g. Docker.
# Start development server
task serve
There are several options to create and run the devcontainer - we present here two:
# Open browser at http://localhost:1313
```
#### Option 1: Run the container triggered by and connected to an IDE, e.g. VS Code
### For Readers
1. open the repo in an [Devcontainer-aware tool/IDE](https://containers.dev/supporting) (e.g. `code .`)
1. start the `devcontainer` (in VSC it's `F1 + Reopen in Devcontainer`)
1. when the container is up & running just open your browser with `http://localhost:1313/`
The documentation is published at:
- **Production**: `https://<production-url>`
- **Development**: `https://<dev-url>`
#### Option 2: Run the container natively
## Project Structure
An alternative to get the container image is the [devcontainer CLI](https://github.com/devcontainers/cli), then you can run the devcontainer without VS Code.
Thus as preliminary you need to do the install steps of the devconatiner cli.
```
.
├── content/ # Documentation content (Markdown)
│ └── en/
│ ├── docs/ # Main documentation
│ │ ├── architecture/ # Architecture docs with LikeC4
│ │ ├── documentation/ # Documentor guides
│ │ └── v1/ # Legacy documentation
│ └── blog/ # Blog posts
├── resources/ # LikeC4 architecture models
│ ├── edp-likec4/ # Platform architecture
│ └── doc-likec4/ # Documentation platform architecture
├── layouts/ # Hugo templates & shortcodes
├── assets/ # SCSS, fonts, images
├── static/ # Static files (JS, CSS, images)
├── Taskfile.yml # Task automation
└── devbox.json # Devbox environment definition
```
1. start the devcontainer by running: `devcontainer up --workspace-folder .`
1. find out the IP address of the devconatiner by using `docker ps` and `docker inspect <id of container>`
1. when the container is up & running just open your browser with `http://<DOCKER IP>:1313/`
## Technology Stack
### Possibility 2: Hugo in a devbox
- **[Hugo](https://gohugo.io/)** - Static site generator
- **[Docsy](https://www.docsy.dev/)** - Documentation theme
- **[LikeC4](https://likec4.dev/)** - Interactive architecture diagrams
- **[Task](https://taskfile.dev/)** - Task runner
- **[Devbox](https://www.jetify.com/devbox/)** - Development environment
[`Devboxes`](https://www.jetify.com/devbox/) are locally isolated environments, managed by the [Nix package manager](https://nix.dev/). So first [prepare the devbox](https://www.jetify.com/docs/devbox/installing_devbox/).
## Available Tasks
Then
View all tasks:
```bash
task --list
```
1. ```devbox shell```
1. In the shell: ```hugo serve```
Common tasks:
- `task serve` - Start development server
- `task build` - Build production site
- `task test` - Run all tests
- `task likec4:generate` - Generate LikeC4 webcomponents
- `task likec4:validate` - Validate LikeC4 models
## Development Environments
## Editing
### Option 1: Devbox (Recommended)
### Documentation language
[Devbox](https://www.jetify.com/devbox/) provides an isolated, reproducible environment:
The documentation is done in [Docsy-Theme](https://www.docsy.dev/).
```bash
# Install Devbox (if not already installed)
curl -fsSL https://get.jetify.com/devbox | bash
So for editing content just goto the `content`-folder and edit content arrording to the [Docsy documentation](https://www.docsy.dev/docs/adding-content/)
# Enter the shell
devbox shell
## Commiting
# All tools are now available in correct versions
hugo version
node --version
```
After having finished a unit of work commit and push.
### Option 2: VS Code Dev Container
# Annex
The `.devcontainer` folder contains the configuration for a containerized development environment:
## Installation steps illustrated
1. Open in VS Code
2. Press `F1` → "Reopen in Container"
3. Wait for container to build
4. Development server starts automatically
When you run the above installation, the outputs could typically look like this:
### Option 3: Manual Installation
### In Visual Studio Code
Install the following tools:
- Hugo Extended (v0.151.0+)
- Node.js (v24+)
- Go (for htmltest)
- Task (task runner)
#### Reopen in Container
## Contributing
![vsc-f1](./assets/images/vsc-f1.png)
We welcome contributions! Please:
#### Hugo server is running and (typically) listens to localhost:1313
1. Read [README-documentor.md](./README-documentor.md) for documentation guidelines
2. Check existing [ADRs](./content/en/docs/decisions/) for architectural context
3. Create a branch for your changes
4. Run `task test` before committing
5. Submit a pull request
After some installation time you have:
## Documentation Guidelines
![vsc-hugo](./assets/images/vsc-hugo.png)
- **Write in present tense** - "The system processes..." not "will process"
- **Use architecture diagrams** - LikeC4 for interactive diagrams
- **Keep it concise** - Readers appreciate brevity
- **Test locally** - Run `task serve` and verify changes
- **Update regularly** - Stale docs are worse than no docs
### Final result in a web browser
## License
![browser](./assets/images/browser.png)
[License information here]
## Support
- **Issues**: [Issue Tracker](https://forgejo.edf-bootstrap.cx.fg1.ffm.osc.live/DevFW/website-and-documentation/issues)
- **Discussions**: [Forum/Chat Link]
- **Documentation**: This repository
---
For detailed documentation contribution guidelines, see [README-documentor.md](./README-documentor.md).

62
TESTING.md
View file

@ -1,62 +0,0 @@
# Hugo Site Testing
Dieses Projekt verwendet mehrere automatisierte Tests zur Qualitätssicherung.
## Verfügbare Tests
### 1. Build-Test
```bash
npm run test:build
```
Prüft ob die Hugo-Seite überhaupt baut und zeigt Warnungen/Fehler an.
### 2. Markdown-Linting
```bash
npm run test:markdown
```
Validiert Markdown-Dateien auf Stilprobleme und Best Practices.
### 3. HTML-Validierung
```bash
npm run test:html
```
Prüft die generierte HTML auf HTML5-Konformität.
### 4. Link-Checker
```bash
npm run test:links
```
Testet alle internen und externen Links auf Gültigkeit.
### Alle Tests ausführen
```bash
npm test
```
### Schnelle Tests (ohne Link-Check)
```bash
npm run test:quick
```
## Konfigurationsdateien
- `.htmltest.yml` - Link-Checker-Konfiguration
- `.htmlvalidate.json` - HTML-Validierungs-Regeln
- `.markdownlint.json` - Markdown-Linting-Regeln
## CI/CD Integration
GitHub Actions führt diese Tests automatisch bei jedem Push/PR aus:
- `.github/workflows/test.yml`
## Lokale Entwicklung
Vor dem Commit empfohlen:
```bash
npm run test:quick # Schnelle Tests
```
Vor dem Push:
```bash
npm test # Alle Tests inkl. Link-Check
```

69
VERSIONS.md
View file

@ -1,69 +0,0 @@
# Version Management
## Single Source of Truth: `.env.versions`
All tool versions are centrally managed in `.env.versions`:
```bash
NODE_VERSION=24.10.0
GO_VERSION=1.25.1
HUGO_VERSION=0.151.0
```
## Where are versions used?
1. **devbox.json** - Local development environment (manual sync required)
2. **Dockerfile** - Build arguments with defaults
3. **.github/workflows/ci.yaml** - CI/CD pipeline (automatic)
4. **scripts/get-versions.sh** - Helper script for local builds
## Updating Versions
### Step 1: Update `.env.versions`
Edit the file with new versions:
```bash
NODE_VERSION=24.12.0
GO_VERSION=1.25.2
HUGO_VERSION=0.152.0
```
### Step 2: Update `devbox.json`
Manually sync the versions in `devbox.json`:
```json
{
"packages": [
"hugo@0.152.0",
"go@1.25.2",
"nodejs@24.12.0",
...
]
}
```
### Step 3: Rebuild devbox environment
```bash
devbox shell --refresh
```
### Step 4: Test Docker build
```bash
source scripts/get-versions.sh
# Follow the printed docker build command
```
## Why not automatic devbox sync?
- devbox.json uses a different version format (e.g., `@latest` vs specific versions)
- devbox package names may differ from Docker image names
- Keeps devbox.json simple and readable
- Manual sync ensures intentional version updates
## CI/CD
The GitHub Actions workflow automatically loads versions from `.env.versions` - no manual intervention needed.

8
content/en/docs/documentation/local-development.md
View file

@ -31,6 +31,14 @@ Before you start, ensure you have:
task deps:install
```
3. **If using Devbox**, enter the Devbox shell:
```bash
devbox shell
```
This ensures all tools (Hugo, Node.js, Go) are available in the correct versions.
## Local Development Workflow
{{< likec4-view view="localDevelopment" project="documentation-platform" >}}