Skip to content

Commit 68bc538

Browse files
lukaskratzellukaskratzel
committed
Restructure docs around personas and implement developer docs
1 parent 094aa8a commit 68bc538

39 files changed

Lines changed: 3015 additions & 180 deletions

‎docs/admins/intro.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
title: Admin Overview
3+
description: Mock admin-facing documentation landing page.
4+
---
5+
6+
# Admin Overview
7+
8+
This section is for platform operators and administrators.
9+
10+
It is kept separate from the other sections so platform governance, access control, and incident handling stay isolated from classroom or developer concerns.
11+
12+
## What lives here
13+
14+
- Provisioning and environment management
15+
- Role and access administration
16+
- Monitoring and incident procedures

‎docs/admins/operations/incident-response.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
title: Incident Response
3+
description: Mock incident guide for admins.
4+
---
5+
6+
# Incident Response
7+
8+
This placeholder page represents the runbook structure admins would follow during outages or degraded service.
9+
10+
## Mock sequence
11+
12+
1. Confirm impact scope
13+
2. Triage root symptom
14+
3. Apply mitigation
15+
4. Communicate status
16+
5. Record follow-up actions

‎docs/admins/operations/monitoring-basics.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
title: Monitoring Basics
3+
description: Mock observability guide for admins.
4+
---
5+
6+
# Monitoring Basics
7+
8+
This mock content marks the future home of dashboards, alerts, and operational health checks.
9+
10+
## Mock signals
11+
12+
- Workspace launch latency
13+
- Authentication error rate
14+
- Submission processing backlog
15+
- Capacity saturation warnings

‎docs/admins/platform/access-control.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
title: Access Control
3+
description: Mock access-control guide for admins.
4+
---
5+
6+
# Access Control
7+
8+
This placeholder page is where role design, permission reviews, and access exception handling would live.
9+
10+
## Mock control areas
11+
12+
- SSO and identity provider mapping
13+
- Role assignment rules
14+
- Elevated access approval paths
15+
- Audit log review cadence

‎docs/admins/platform/provisioning.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
title: Provisioning
3+
description: Mock provisioning guide for admins.
4+
---
5+
6+
# Provisioning
7+
8+
This mock page represents environment bootstrap and lifecycle management guidance.
9+
10+
## Mock provisioning flow
11+
12+
1. Create the environment
13+
2. Connect identity and course providers
14+
3. Define quotas and scaling defaults
15+
4. Validate monitoring and backups

‎docs/developer/guides/deploying-pull-requests.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
---
2+
title: Deploying Pull Requests
3+
description: How to deploy PR artifacts from EduIDE Cloud, EduIDE Deployment, and Theia Cloud Helm.
4+
---
5+
6+
# Deploying Pull Requests
7+
8+
EduIDE uses preview-style deployment workflows across multiple repositories. The details differ slightly by repository, but the pattern is the same:
9+
10+
- a pull request build publishes preview artifacts on each commit
11+
- those artifacts are tagged with a PR-specific identifier
12+
- EduIDE Deployment is then used to deploy those artifacts to a test environment
13+
14+
For most contributor workflows, EduIDE Deployment is the final place where preview artifacts are selected and combined into a running system.
15+
16+
## The Common Tagging Pattern
17+
18+
The important idea is that pull request artifacts are not published as `latest`.
19+
20+
Instead, they are published with PR-specific tags such as:
21+
22+
- `pr-123`
23+
- `pr-123-<short-sha>` for image variants that also carry a commit suffix
24+
- `<chart-version>.pr-123` for Helm chart previews
25+
26+
This allows multiple pull requests to coexist without overwriting each other.
27+
28+
## Deploying EduIDE Cloud Pull Requests
29+
30+
EduIDE Cloud publishes preview images for pull requests through its `Build and Push Theia Cloud Images` workflow.
31+
32+
For pull requests, the workflow computes:
33+
34+
- `base_tag=pr-<pull-request-number>`
35+
- `sha_tag=pr-<pull-request-number>-<short-sha>`
36+
37+
Those tags are then pushed for the main cloud components:
38+
39+
- `ghcr.io/eduide/eduide-cloud/operator`
40+
- `ghcr.io/eduide/eduide-cloud/service`
41+
- `ghcr.io/eduide/eduide-cloud/landing-page`
42+
43+
### How to deploy that PR
44+
45+
Go to the EduIDE Deployment repository and run the `Deploy PR to Environment` workflow manually.
46+
47+
The relevant `workflow_dispatch` inputs are:
48+
49+
- `environment`
50+
- `theia_cloud_tag`
51+
- `ide_images_tag`
52+
- `helm_chart_tag`
53+
54+
For an EduIDE Cloud PR, set:
55+
56+
- `environment` to the target test environment such as `test1`, `test2`, or `test3`
57+
- `theia_cloud_tag` to `pr-<number>`
58+
- `ide_images_tag` to `latest` unless you also need preview IDE images
59+
- `helm_chart_tag` empty unless you also need preview Helm charts
60+
61+
Internally, EduIDE Deployment maps `theia_cloud_tag` to:
62+
63+
- `theia-cloud.operator.image`
64+
- `theia-cloud.service.image`
65+
- `theia-cloud.landingPage.image`
66+
- the landing page preloading image
67+
68+
So one workflow input updates the whole EduIDE Cloud component set consistently.
69+
70+
## Deploying EduIDE Pull Requests
71+
72+
The same idea applies to pull requests in the EduIDE image repository.
73+
74+
Those pull requests publish preview IDE image tags, and EduIDE Deployment consumes them through the `ide_images_tag` input.
75+
76+
This affects:
77+
78+
- the default app definition image tag
79+
- the preloading image list for the language-specific IDE images
80+
81+
### How to deploy that PR
82+
83+
Run the `Deploy PR to Environment` workflow in EduIDE Deployment and set:
84+
85+
- `environment` to the target test environment
86+
- `theia_cloud_tag` to `latest` unless you also need a cloud preview
87+
- `ide_images_tag` to `pr-<number>`
88+
- `helm_chart_tag` empty unless you also need preview Helm charts
89+
90+
Use this when your pull request changes the actual IDE images, bundled tools, or application-definition-backed environment contents.
91+
92+
## Deploying Theia Cloud Helm Pull Requests
93+
94+
Pull requests in Theia Cloud Helm publish preview OCI chart versions through the `release-pr-preview` workflow.
95+
96+
The preview version format is:
97+
98+
- `<base-chart-version>.pr-<number>`
99+
100+
This is published for:
101+
102+
- `theia-cloud-base`
103+
- `theia-cloud-crds`
104+
- `theia-cloud`
105+
106+
EduIDE Deployment supports consuming those preview charts through the `helm_chart_tag` input.
107+
108+
### How to deploy that PR
109+
110+
Run the `Deploy PR to Environment` workflow in EduIDE Deployment and set:
111+
112+
- `environment` to the target test environment
113+
- `helm_chart_tag` to `pr-<number>`
114+
- `theia_cloud_tag` and `ide_images_tag` as needed, usually `latest`
115+
116+
When `helm_chart_tag` is set, EduIDE Deployment patches the combined chart dependency version and also adjusts the base and CRD chart versions so they resolve to the preview OCI artifacts.
117+
118+
Use this when your PR changes upstream chart behavior, CRDs, or chart packaging rather than the runtime images themselves.
119+
120+
## Deploying EduIDE Deployment Pull Requests
121+
122+
Pull requests in EduIDE Deployment itself are slightly different. In this case the thing being previewed is the deployment logic, chart composition, values handling, or workflow behavior in the deployment repository itself.
123+
124+
The principle is still the same:
125+
126+
- your PR branch contains the deployment change
127+
- the deployment workflow is run from that PR context
128+
- the selected environment receives the chart and values logic from the PR branch
129+
130+
### How to deploy that PR
131+
132+
Open the pull request in EduIDE Deployment or run the `Deploy PR to Environment` workflow from the PR branch context, then choose the target test environment.
133+
134+
Use the extra tag inputs only if your deployment PR also depends on preview artifacts from other repositories:
135+
136+
- `theia_cloud_tag` for EduIDE Cloud previews
137+
- `ide_images_tag` for EduIDE image previews
138+
- `helm_chart_tag` for Theia Cloud Helm previews
139+
140+
This is the normal way to validate deployment-logic changes before merging them.
141+
142+
## Combining Multiple Pull Requests
143+
144+
One of the strengths of the workflow is that you can combine preview artifacts from multiple repositories in one test deployment.
145+
146+
Examples:
147+
148+
- EduIDE Cloud PR + EduIDE Deployment PR
149+
- EduIDE image PR + EduIDE Deployment PR
150+
- Theia Cloud Helm PR + EduIDE Cloud PR + EduIDE Deployment PR
151+
152+
The combination point is always EduIDE Deployment, because that is where the final test environment is assembled.
153+
154+
## Recommended Workflow
155+
156+
Use this sequence:
157+
158+
1. Open the pull request in the repository that builds the artifact.
159+
2. Wait for the preview images or charts to be published.
160+
3. Open EduIDE Deployment.
161+
4. Run `Deploy PR to Environment`.
162+
5. Set the inputs that correspond to the repositories you want to preview.
163+
6. Validate the result in the chosen test environment.
164+
165+
## Quick Mapping
166+
167+
| Repository | Preview artifact | Deployment input |
168+
| --- | --- | --- |
169+
| EduIDE Cloud | operator, service, landing-page images tagged `pr-<number>` | `theia_cloud_tag` |
170+
| EduIDE | IDE images tagged `pr-<number>` | `ide_images_tag` |
171+
| Theia Cloud Helm | OCI chart versions suffixed with `.pr-<number>` | `helm_chart_tag` |
172+
| EduIDE Deployment | deployment logic from the PR branch itself | run deployment workflow from that PR context |
173+
174+
## Summary
175+
176+
Pull request deployment in EduIDE is centered around PR-tagged preview artifacts and a single assembly point in EduIDE Deployment. Most of the time, the only thing you really need to know is which repository produced the preview artifact and which input in `Deploy PR to Environment` selects it.

‎docs/developer/guides/local-development.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
title: Local Development
3+
description: How local development is used in the EduIDE ecosystem.
4+
---
5+
6+
# Local Development
7+
8+
Local development in EduIDE is different from a typical monolith workflow. The normal goal is not to boot the entire platform on a laptop and do all validation locally. Most changes are made in the repository that owns the feature, then deployed to a shared test environment through EduIDE Deployment.
9+
10+
## Default Development Model
11+
12+
The usual workflow is:
13+
14+
1. Make the change in the relevant repository.
15+
2. Validate that repository locally as far as it makes sense.
16+
3. Build preview artifacts if the repository publishes them for pull requests.
17+
4. Deploy the change to one of the test environments through EduIDE Deployment.
18+
5. Validate behavior against a real running cluster.
19+
20+
This is the preferred approach because the platform depends on Kubernetes behavior, routing, authentication, storage, and multiple interacting services. Those parts are usually easier to validate in the test clusters than in a fully local setup.
21+
22+
## Why Full Local Development Is Not the Default
23+
24+
Running the whole EduIDE system locally is usually not how feature work is done.
25+
26+
The main reasons are:
27+
28+
- the complete platform depends on Kubernetes-native behavior
29+
- routing and authentication flows are part of the actual runtime behavior
30+
- service and operator changes usually only make sense against a realistic cluster
31+
- test environments already exist and are closer to the production shape than an ad hoc local stack
32+
33+
In practice, this means "local development" usually means local work on one component, not full local reproduction of the whole platform.
34+
35+
## When Local Testing Still Makes Sense
36+
37+
Local testing is still useful for focused tasks where only one part of the stack matters.
38+
39+
Typical examples include:
40+
41+
- testing a Theia or VS Code extension inside a local Theia application
42+
- iterating on frontend behavior for a landing page or dashboard
43+
- validating isolated service logic or request handling
44+
- running repository-local unit tests, linters, and build steps
45+
- checking generated output such as charts, docs, or API clients
46+
47+
This kind of local work is especially effective when the change does not depend on real cluster reconciliation or real session routing behavior.
48+
49+
## Extensions and Theia-Specific Work
50+
51+
For extension work, local feedback loops are often good enough and much faster than deploying every small iteration.
52+
53+
Examples:
54+
55+
- testing UI behavior in Theia
56+
- validating command registration and configuration handling
57+
- checking extension-side integration logic
58+
- iterating on runtime injection consumers inside the IDE
59+
60+
This is one of the main exceptions to the "deploy to test clusters" rule.
61+
62+
## Service and Operator Work
63+
64+
Changes involving the EduIDE Cloud service and operator usually need the real system shape.
65+
66+
That is because these tasks often involve:
67+
68+
- custom resources
69+
- reconciliation logic
70+
- session lifecycle handling
71+
- routing updates
72+
- authentication interactions
73+
- persistent storage behavior
74+
- concurrency under burst load
75+
76+
For those cases, the easiest and most reliable validation path is usually the shared test cluster, not a fully local stack.
77+
78+
## Recommended Rule of Thumb
79+
80+
Use local development when:
81+
82+
- the change is isolated to one repository or one runtime component
83+
- the behavior can be meaningfully validated without the full cluster
84+
- fast iteration matters more than end-to-end realism
85+
86+
Use the test environments when:
87+
88+
- the change affects service and operator interaction
89+
- the change depends on routing or authentication
90+
- the change affects session lifecycle behavior
91+
- the change needs a realistic end-to-end deployment
92+
93+
## Summary
94+
95+
EduIDE development is repository-local first and environment-based second. You usually do not run the complete platform locally. Instead, you validate locally where that is efficient and deploy to the test clusters when the change depends on the real cloud runtime.

0 commit comments

Comments
 (0)