doc(pos-doc): refactored README
This commit is contained in:
Stephan Lo
parent
13bd4343d9
commit
8d17325bcd
5 changed files with 113 additions and 93 deletions
81
README.md
81
README.md
|
|
@ -1,65 +1,58 @@
|
|||
# 🌟 EdgeDeveloperPlatform - EDP Release 'PoC'
|
||||
# 🌟 EDP - EdgeDeveloperPlatform
|
||||
|
||||
Telekom MMS & T-Systems, December 2024
|
||||
> * Owner: Telekom MMS & T-Systems
|
||||
> * Date: December 20, 2024
|
||||
> * Version: Release 1.0.0 ('PoC')
|
||||
|
||||
> **Tagline:** Change the way we work with IDP's.
|
||||
## About this Repository
|
||||
|
||||
---
|
||||
This repo [`edp-doc`](https://forgejo.edf-bootstrap.cx.fg1.ffm.osc.live/DevFW-CICD/edp-doc) is the documentation repository of the **EDP product**.
|
||||
|
||||
## 📋 Table of Contents
|
||||
## About the EDP Product
|
||||
|
||||
- [🌟 EdgeDeveloperPlatform - EDP Release 'PoC'](#-edgedeveloperplatform---edp-release-poc)
|
||||
- [📋 Table of Contents](#-table-of-contents)
|
||||
- [📖 About the Product](#-about-the-product)
|
||||
- [🛠️ Application Stack](#️-application-stack)
|
||||
- [📖 Access our Documentation](#-access-our-documentation)
|
||||
- [In our Open Sovereign Cloud](#in-our-open-sovereign-cloud)
|
||||
- [In a local kind cluster](#in-a-local-kind-cluster)
|
||||
- [In the Forgejo repository](#in-the-forgejo-repository)
|
||||
- [📝 License](#-license)
|
||||
EDP is a product developed by the IPCEI-CIS subproject 'edge Developer Framework'. The goal is to provide a cutting edge developer experience for developing and delivering applications in the cloud edge continuum.
|
||||
|
||||
---
|
||||
## What EDP contains
|
||||
|
||||
## 📖 About the Product
|
||||
The EDP product consists of three parts:
|
||||
|
||||
**edpbuilder** is a tool to quickly instantiate and manage **I**nternal **D**evelopment **P**latform's (**IDP**s).
|
||||
The **E**dge **D**evelopment **P**latform Builder(**edp**builder) can easily setup a Kubenetes cluster (local kind cluster or OSC instance) and deploy tools to manage the Kubernetes resources and the software lifecicle of an application.
|
||||
One usecase to demonstrate the capabilities of our tool is the PetClinic Application. (LINK)
|
||||
1. The platform orchestrator, processing declarative 'platform stack' descriptions
|
||||
1. The predefined stack for a Demo EDP instance
|
||||
1. The documentation
|
||||
|
||||
### 🛠️ Application Stack
|
||||
### Platform Orchestrator `edpbuilder`
|
||||
|
||||
- **Version-Control:** Forgejo
|
||||
- **CI:** Forgejo Actions
|
||||
- **CD:** ArgoCD
|
||||
- **Monitoring:** Grafana, Prometheus, Loki, Promtail
|
||||
- **SSO:** Keycloak
|
||||
- **Developer Portal:** Backstage
|
||||
- **Secret-Management:** OpenBao, external-secrets
|
||||
- **Infrastructur-Provisioning:** Crossplane
|
||||
[edpbuilder](https://forgejo.edf-bootstrap.cx.fg1.ffm.osc.live/DevFW/edpbuilder) is a tool to quickly instantiate and manage Internal Development Platforms (IDPs).
|
||||
The Edge Development Platform Builder (edpbuilder) can easily setup a Kubenetes cluster (local kind cluster or OSC instance) and deploy tools to manage the Kubernetes resources and the software lifecicle of an application.
|
||||
|
||||
## 📖 Access our Documentation
|
||||
### Predefined `Demo EDP` Stack
|
||||
|
||||
Our documentation is designed to be easily accessible regardless of your environment. Here are three primary ways to view it:
|
||||
There are predefined stack sets for deploying and orchestrating a whole platform.
|
||||
|
||||
### In our Open Sovereign Cloud
|
||||
At the time of writing (version PoC) we provide the [`Demo EDP`as PoC stack](https://forgejo.edf-bootstrap.cx.fg1.ffm.osc.live/DevFW-CICD/stacks).
|
||||
|
||||
Our documentation can be easily accessed through a Backstage instance hosted on our Open Sovereign Cloud (OSC). Simply log in to our OSC Backstage platform to read through the documentation.
|
||||
#### `Demo EDP` Stack
|
||||
|
||||
- URL: <https://edf-cc1.cx.fg1.ffm.osc.live/docs/edppoc/component/edp-documentation>
|
||||
- Username: user1
|
||||
- Password: PpMpfZYICG9MRRF-3QBY2Zz1-+URYB6+-JRe
|
||||
The `Demo EDP` Stack contains the follwing application components:
|
||||
|
||||
### In a local kind cluster
|
||||
* Version-Control: Forgejo
|
||||
* CI: Forgejo Actions
|
||||
* CD: ArgoCD
|
||||
* Monitoring: Grafana, Prometheus, Loki, Promtail
|
||||
* SSO: Keycloak
|
||||
* Developer Portal: Backstage
|
||||
* Secret-Management: OpenBao, external-secrets
|
||||
* Infrastructur-Provisioning: Crossplane
|
||||
|
||||
Using the edpbuilder, you can set up a local IDP that comes with a Backstage instance containing the documentation.
|
||||
*[How to set up a local IDP on a kind cluster](docs/userguide/edpbuilder.md)*
|
||||
One usecase to demonstrate the capabilities and development lifecycle flow through all stack components is the [PetClinic Application](./docs/user-documentation/petclinic.md)
|
||||
|
||||
### In the Forgejo repository
|
||||
### Documentation
|
||||
|
||||
If you prefer direct access, the content of our documentation is centrally defined and maintained within the docs folder of this repository.
|
||||
The EDP documentation is subject to this repo in folder [`docs`](./docs/). It is created in the [`mkdocs`](https://www.mkdocs.org/) documentation format and natively embedded in the [`Backstage TechDocs` documentation technology](https://backstage.io/docs/features/techdocs/).
|
||||
|
||||
---
|
||||
Thus it can be read in four ways by
|
||||
|
||||
## 📝 License
|
||||
|
||||
[LICENSE]
|
||||
1. [accessing the Backstage portal in a running Demo EDP](./docs/introduction/index.md#doc-in-backstage-in-a-running-demo-edp)
|
||||
2. [accessing the Backstage portal in a Demo EDP setup on your computer](./docs/introduction/index.md#doc-in-backstage-in-a-demo-edp-setup-on-your-computer)
|
||||
3. [browsing the documentaion repository](./docs/introduction/index.md#doc-in-the-repository)
|
||||
4. [browsing in a Backstage simulation on your computer](./docs/introduction/index.md#doc-in-a-backstage-simulation)
|
||||
|
|
|
|||
70
docs/introduction/index.md
Normal file
70
docs/introduction/index.md
Normal file
|
|
@ -0,0 +1,70 @@
|
|||
# EDP Documentation
|
||||
|
||||
## How to access the Documentation
|
||||
|
||||
The EDP documentation is subject to this repo in folder [`docs`](./docs/). It is created in the [`mkdocs`](https://www.mkdocs.org/) documentation format and natively embedded in the [`Backstage TechDocs` documentation technology](https://backstage.io/docs/features/techdocs/).
|
||||
|
||||
Thus it can be read in four ways:
|
||||
|
||||
### Doc in Backstage in a running Demo EDP
|
||||
|
||||
The documentation can be easily accessed through a Demo EDP instance hosted on our Open Sovereign Cloud (OSC).
|
||||
|
||||
Thus there you have a Backstage-Developer Portal running, containing the EDP documentation.
|
||||
|
||||
Simply log in to [Demo EDP Backstage](https://forgejo.edf-bootstrap.cx.fg1.ffm.osc.live/DevFW-CICD/stacks) to read through the documentation.
|
||||
|
||||
* [EDP Documentation URL](https://edf-cc1.cx.fg1.ffm.osc.live/docs/edppoc/component/edp-documentation)
|
||||
* Username: user1
|
||||
* Password: PpMpfZYICG9MRRF-3QBY2Zz1-+URYB6+-JRe
|
||||
|
||||
### Doc in Backstage in a Demo EDP setup on your computer
|
||||
|
||||
As `edpbuilder` is a infrastructure agnostic platform orchestrator, you also can boostrap the EDP Demo on your own laptop!
|
||||
|
||||
Using the edpbuilder, you can set up a local Demo EDP that comes with a Backstage instance containing the documentation:
|
||||
[How to set up a local IDP on a kind cluster](./docs/user-documentation/edpbuilder.md)
|
||||
|
||||
### Doc in the repository
|
||||
|
||||
If you prefer direct access, the content of our documentation is centrally defined and maintained within the [docs folder of this repository](./docs/).
|
||||
|
||||
### Doc in a Backstage simulation
|
||||
|
||||
The Backstage TechDocs embedding can also be [emulated in a Backstage portal frame running on your computer](./live-preview-integration/README-backstage-local.md).
|
||||
|
||||
## User Documentation
|
||||
|
||||
### 📋 Outline
|
||||
- [What is it? (short description what the software does, max 3 sentences)](#what-is-it)
|
||||
- A couple of use cases (different scopes)
|
||||
- Why do I need / want this? When should I pass?
|
||||
- Compare with other platforms
|
||||
- Compare with well-known tools (what parts of my stack / pipeline does this cover?)
|
||||
- argo -> vercel
|
||||
- monitoring -> data dog
|
||||
- forgejo -> graphite
|
||||
- [Main features (brief list of main features and enablers - why it is in the stack)](#main-features)
|
||||
- what are our opinions / core principles and believes that are backed in?
|
||||
- k8s > *
|
||||
- Developer Portal: Backstage
|
||||
- [Quick start guide](#quick-start-guide)
|
||||
- [Configuration](#configuration)
|
||||
- structure of the poc (where / how can I change something?)
|
||||
- how does it work? (bootstrapping++)
|
||||
- [Known Issues / TODOs](#known-issues)
|
||||
- [References (documentation links etc...)](#references)
|
||||
|
||||
### 🧐 What is it?
|
||||
|
||||
10:40 THU
|
||||
|
||||
### 📦 Main features
|
||||
|
||||
### ⏱️ Quick start guide
|
||||
|
||||
### ⚙️ Configuration
|
||||
|
||||
### 🔗 References
|
||||
|
||||
## Technical Documentation
|
||||
|
|
@ -1,7 +0,0 @@
|
|||
# Technical Documentation
|
||||
|
||||
## Outline
|
||||
|
||||
1. Concepts
|
||||
The underlying platforming concepts of the Edge Developer Framework (EDF) solution, i.e. the problem domain
|
||||
|
||||
|
|
@ -1,34 +0,0 @@
|
|||
# User Documentation
|
||||
|
||||
## 📋 Outline
|
||||
- [What is it? (short description what the software does, max 3 sentences)](#what-is-it)
|
||||
- A couple of use cases (different scopes)
|
||||
- Why do I need / want this? When should I pass?
|
||||
- Compare with other platforms
|
||||
- Compare with well-known tools (what parts of my stack / pipeline does this cover?)
|
||||
- argo -> vercel
|
||||
- monitoring -> data dog
|
||||
- forgejo -> graphite
|
||||
- [Main features (brief list of main features and enablers - why it is in the stack)](#main-features)
|
||||
- what are our opinions / core principles and believes that are backed in?
|
||||
- k8s > *
|
||||
- Developer Portal: Backstage
|
||||
- [Quick start guide](#quick-start-guide)
|
||||
- [Configuration](#configuration)
|
||||
- structure of the poc (where / how can I change something?)
|
||||
- how does it work? (bootstrapping++)
|
||||
- [Known Issues / TODOs](#known-issues)
|
||||
- [References (documentation links etc...)](#references)
|
||||
|
||||
## 🧐 What is it?
|
||||
|
||||
10:40 THU
|
||||
|
||||
## 📦 Main features
|
||||
|
||||
## ⏱️ Quick start guide
|
||||
|
||||
## ⚙️ Configuration
|
||||
|
||||
## 🔗 References
|
||||
- Technical Documentation
|
||||
14
mkdocs.yaml
14
mkdocs.yaml
|
|
@ -3,9 +3,7 @@ site_description: 'EDP documentation'
|
|||
|
||||
nav:
|
||||
- Home: index.md
|
||||
- Introduction:
|
||||
- User Documentation: introduction/user-documentation.md
|
||||
- Technical Documentation: introduction/technical-documentation.md
|
||||
- Contents: introduction/index.md
|
||||
- User Documentation:
|
||||
- ArgoCD: user-documentation/argocd.md
|
||||
- Backstage: user-documentation/backstage.md
|
||||
|
|
@ -19,8 +17,8 @@ nav:
|
|||
- PetClinic: user-documentation/petclinic.md
|
||||
- Technical Documentation:
|
||||
- Concepts:
|
||||
- Code: technical-documentation/concepts/1_software-and-workloads/_index.md
|
||||
- Engineers: technical-documentation/concepts/2_engineering-people/_index.md
|
||||
# - Code: technical-documentation/concepts/1_software-and-workloads/_index.md
|
||||
# - Engineers: technical-documentation/concepts/2_engineering-people/_index.md
|
||||
- Use Cases: technical-documentation/concepts/3_use-cases/_index.md
|
||||
- Platforms:
|
||||
- Platform Engineering: technical-documentation/concepts/4_digital-platforms/platform-engineering/_index.md
|
||||
|
|
@ -32,10 +30,10 @@ nav:
|
|||
- References: technical-documentation/concepts/4_digital-platforms/platform-components/references/_index.md
|
||||
- Orchestrators:
|
||||
- CNOE: technical-documentation/concepts/5_platforms/CNOE/_index.md
|
||||
- Humanitec: technical-documentation/concepts/5_platforms/Humanitec/_index.md
|
||||
# - Humanitec: technical-documentation/concepts/5_platforms/Humanitec/_index.md
|
||||
- Solution:
|
||||
- Design: technical-documentation/solution/design/_index.md
|
||||
- Scenarios: technical-documentation/solution/scenarios/_index.md
|
||||
# - Design: technical-documentation/solution/design/_index.md
|
||||
# - Scenarios: technical-documentation/solution/scenarios/_index.md
|
||||
- Tools:
|
||||
- Backstage:
|
||||
- Description: technical-documentation/solution/tools/Backstage/general-information/_index.md
|
||||
|
|
|
|||
Loading…
Reference in a new issue