docs: consolidate root documentation to README-* structure
- 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:
parent
9921e07e3e
commit
9e509ed265
11 changed files with 1127 additions and 644 deletions
98
DOCKER.md
98
DOCKER.md
|
|
@ -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
|
||||
|
|
@ -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" >}}
|
||||
```
|
||||
|
|
@ -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
|
||||
|
|
@ -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/
|
||||
```
|
||||
|
|
@ -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
434
README-documentor.md
Normal 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
|
||||
|
||||
```
|
||||
|
||||
## 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
383
README-likec4.md
Normal 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
163
README.md
|
|
@ -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.
|
||||
[](https://gohugo.io/)
|
||||
[](https://www.docsy.dev/)
|
||||
[](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
|
||||
|
||||
|
||||
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
|
||||
|
||||
|
||||
- **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
|
||||
|
||||
|
||||
[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
62
TESTING.md
|
|
@ -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
69
VERSIONS.md
|
|
@ -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.
|
||||
|
|
@ -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" >}}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue