Skip to content

Commit 75b5aca

Browse files
kairoaraujokairoaraujo
authored
Webapp deploy guide (#461)
* docs: add plugin to reuse doc add plugin to allow reusing doc accross different place for easy maintenance Signed-off-by: Kairo Araujo <kairo@dearaujo.nl> * docs: add install guide for otterdog webapp Signed-off-by: Kairo Araujo <kairo@dearaujo.nl> --------- Signed-off-by: Kairo Araujo <kairo@dearaujo.nl>
1 parent 999f8d4 commit 75b5aca

5 files changed

Lines changed: 243 additions & 67 deletions

File tree

‎docs/contributing.md‎

Lines changed: 11 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -285,67 +285,17 @@ We use [tailscale on Kubernetes](https://tailscale.com/learn/managing-access-to-
285285

286286
#### Create a GitHub App
287287

288-
Note: It is required if you are developing the integration with GitHub
289-
290-
[Create a GitHub app](https://docs.github.com/en/organizations/managing-programmatic-access-to-your-organization/adding-and-removing-github-app-managers-in-your-organization#giving-someone-the-ability-to-manage-all-github-apps-owned-by-the-organization)
291-
292-
1. Go to your organization `https://github.com/organizations/otterdog-<github username>`
293-
2. Click Settings.
294-
3. In the left sidebar, select <> Developer settings
295-
4. Click GitHub Apps
296-
5. New GitHub App
297-
298-
**Basic Information**
299-
300-
- Add GitHub App name: <choose a name>
301-
- Homepage URL: otterdog.<tailscale DNS> (example: `otterdog.tail<hash>.ts.net`)
302-
303-
Note:
304-
You can always double check the URL at https://login.tailscale.com/admin/machines as multiple instances
305-
of your development environment can generate `otterdog-1`, `otterdog-2` ...
306-
307-
**Webhook**
308-
309-
- [X] Active
310-
- Webhook url: otterdog.<tailscale DNS> (example: `otterdog.tail<hash>.ts.net/github-webhook/receive`)
311-
- Secret: Choose the secret
312-
313-
Add the following permissions and events:
314-
315-
Repository Permissions:
316-
317-
- Actions: read and write
318-
- Administration: read and write
319-
- Commit statuses: read and write
320-
- Contents: read and write
321-
- Environments: read and write
322-
- Issues: read only
323-
- Metadata: read only
324-
- Pages: read and write
325-
- Pull requests: read and write
326-
- Secrets: read and write
327-
- Variables: read and write
328-
- Webhooks: read and write
329-
- Workflows: read and write
330-
331-
Organization Permissions:
332-
333-
- Administration: read and write
334-
- Custom Organization Roles: read and write
335-
- Members: read only
336-
- Plan: read only
337-
- Secrets: read and write
338-
- Variables: read and write
339-
- Webhooks: read and write
340-
341-
Events:
342-
343-
- Issue comment
344-
- Pull request
345-
- Pull request review
346-
- Push
347-
- Workflow job
348-
- Workflow run
288+
**NOTES**:
289+
290+
- Replace `<OTTERDOG-WEBAPP>` by your `tail<some hash>.ts.net`
291+
- You can always double check the URL at https://login.tailscale.com/admin/machines as multiple instances
292+
of your development environment can generate `otterdog-1`, `otterdog-2` ...
293+
294+
{%
295+
include-markdown "./install.md"
296+
start="<!--github-app-start-->"
297+
end="<!--github-app-end-->"
298+
%}
349299

350300

351301
#### Configure the `values.yaml` to setup your otterdog webapp

‎docs/install.md‎

Lines changed: 183 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
Otterdog requires Python 3.11+ to run.
22

3-
## System requirements
3+
## Otterdog tool (command line interface)
4+
### System requirements
45

56
A few system dependencies are required to be installed:
67

7-
### Mandatory system dependencies
8+
#### Mandatory system dependencies
89

910
* [`python 3.11+`](https://www.python.org/): Python 3 + pip + pipx
1011

@@ -24,7 +25,7 @@ pipx install poetry>=2.0.1
2425
apt install git
2526
```
2627

27-
### Optional system dependencies
28+
#### Optional system dependencies
2829

2930
Depending on the type of credential system you are using, install one of the following tools:
3031

@@ -40,7 +41,7 @@ snap install bw
4041
apt install pass
4142
```
4243

43-
## Build instructions
44+
### Build instructions
4445

4546
After installing the required system dependencies, a virtual python environment needs to be setup
4647
and populated with all python dependencies:
@@ -61,7 +62,7 @@ Additionally, `make init` creates a symlink called `otterdog` in `~/.local/bin`,
6162
$ otterdog --version
6263
```
6364

64-
## Shell integration
65+
### Shell integration
6566

6667
To enable shell completion, add the following snippet to your shell configuration file (`~/.bashrc` or `~/.zshrc`):
6768

@@ -77,3 +78,180 @@ To enable shell completion, add the following snippet to your shell configuratio
7778

7879
When running `otterdog` in a directory that contains a `otterdog.json` file, shell completion will be able to suggest
7980
organizations found in the `otterdog.json` file.
81+
82+
83+
## Otterdog WebApp
84+
85+
Otterdog WebApp is available as a container image, with releases published to the [GitHub Container Registry (GHCR)](https://github.com/eclipse-csi/otterdog/pkgs/container/otterdog).
86+
87+
For Kubernetes environments, we also provide Helm charts to simplify deployment and configuration.
88+
89+
This guide covers how to deploy the Otterdog WebApp using **Helm charts**.
90+
91+
### System Requirements
92+
93+
Make sure the following requirements are met before deployment:
94+
95+
- A running Kubernetes cluster
96+
- [Helm](https://helm.sh) installed
97+
98+
99+
### GitHub requirements
100+
101+
#### Create a GitHub App
102+
103+
<!--github-app-start-->
104+
105+
It is required if you are the integration with GitHub ([Create a GitHub app](https://docs.github.com/en/organizations/managing-programmatic-access-to-your-organization/adding-and-removing-github-app-managers-in-your-organization#giving-someone-the-ability-to-manage-all-github-apps-owned-by-the-organization))
106+
107+
1. Go to your organization `https://github.com/organizations/<ORG>`
108+
2. Click Settings.
109+
3. In the left sidebar, select <> Developer settings
110+
4. Click GitHub Apps
111+
5. New GitHub App
112+
113+
**Basic Information**
114+
115+
- Add GitHub App name: `<choose a name>`
116+
- Homepage URL: `<OTTERDOG-WEBAPP>`
117+
118+
**Webhook**
119+
120+
- [X] Active
121+
- Webhook url: `<OTTERDOG-WEBAPP>`
122+
- Secret: Choose the secret
123+
124+
Add the following permissions and events:
125+
126+
127+
Repository Permissions
128+
129+
| Permission | Access Level |
130+
|----------------------|--------------|
131+
| Actions | Read & Write |
132+
| Administration | Read & Write |
133+
| Commit statuses | Read & Write |
134+
| Contents | Read & Write |
135+
| Environments | Read & Write |
136+
| Issues | Read only |
137+
| Metadata | Read only |
138+
| Pages | Read & Write |
139+
| Pull requests | Read & Write |
140+
| Secrets | Read & Write |
141+
| Variables | Read & Write |
142+
| Webhooks | Read & Write |
143+
| Workflows | Read & Write |
144+
145+
Organization Permissions
146+
147+
| Permission | Access Level |
148+
|-----------------------------|--------------|
149+
| Administration | Read & Write |
150+
| Custom Organization Roles | Read & Write |
151+
| Members | Read only |
152+
| Plan | Read only |
153+
| Secrets | Read & Write |
154+
| Variables | Read & Write |
155+
| Webhooks | Read & Write |
156+
157+
Events
158+
159+
| Event |
160+
|-------------------------|
161+
| Issue comment |
162+
| Pull request |
163+
| Pull request review |
164+
| Push |
165+
| Workflow job |
166+
| Workflow run |
167+
168+
<!--github-app-end-->
169+
170+
### Deployment Steps
171+
172+
#### Step 1: Add the Helm Repository
173+
174+
```bash
175+
helm repo add eclipse-csi https://eclipse-csi.github.io/helm-charts
176+
helm repo update
177+
```
178+
179+
#### Step 2: Prepare Configuration
180+
181+
Create a `values.yaml` file to define your deployment configuration:
182+
183+
This is an example
184+
185+
```yaml
186+
valkey:
187+
auth:
188+
enabled: false
189+
190+
mongodb:
191+
auth:
192+
enabled: true
193+
rootPassword: <DEFINE MONGODB PASSWORD>
194+
195+
ghproxy:
196+
redisAddress: otterdog-valkey-primary.default.svc.cluster.local:6379
197+
198+
config:
199+
configOwner: "<ORGANIZATION>"
200+
configToken: "<GITHUB TOKEN (BASE64)>"
201+
configRepo: "otterdog-configs"
202+
configPath: "otterdog.json"
203+
mongoUri: "mongodb://root:secret@otterdog-mongodb.default.svc.cluster.local:27017/otterdog"
204+
redisUri: "redis://otterdog-valkey-primary.default.svc.cluster.local:6379"
205+
ghProxyUri: "http://otterdog-ghproxy.default.svc.cluster.local:8888"
206+
dependecyTrackUrl: "https://otterdog-dt.default.svc.cluster"
207+
dependecyTrackToken: "faketoken"
208+
209+
github:
210+
webhookSecret: "<WEBHOOK SECRET (BASE64)>"
211+
appId: "<GITHUB APP ID>"
212+
appPrivateKey: "<GITHUB APP PRIVATE KEY (BASE64)>"
213+
webhookValidationContext: "otterdog/otterdog-validation"
214+
webhookSyncContext: "otterdog/otterdog-sync"
215+
216+
```
217+
218+
#### Step 3: Install Otterdog WebApp
219+
220+
```bash
221+
helm install eclipse-csi otterdog -f values.yaml
222+
```
223+
224+
### Step 4: Verify the Deployment
225+
226+
Use the following commands to verify that the WebApp is running:
227+
228+
```bash
229+
kubectl get pods
230+
kubectl get svc
231+
kubectl get ingress
232+
```
233+
234+
235+
### Updating the Deployment
236+
237+
To upgrade to the latest chart or image version:
238+
239+
```bash
240+
helm repo update
241+
helm upgrade eclipse-csi otterdog -f values.yaml
242+
```
243+
244+
### Uninstalling Otterdog
245+
246+
To remove the WebApp from your cluster:
247+
248+
```bash
249+
helm uninstall otterdog
250+
```
251+
252+
### Additional Resources
253+
254+
- [Otterdog GitHub Repository](https://github.com/eclipse-csi/otterdog)
255+
- [Otterdog Container Images (GHCR)](https://github.com/eclipse-csi/otterdog/pkgs/container/otterdog)
256+
- [Helm Documentation](https://helm.sh/docs/)
257+
- [GitHub Container Registry Docs](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry)

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,7 @@ markdown_extensions:
124124
watch: []
125125

126126
plugins:
127+
- include-markdown
127128
- search
128129
- exclude:
129130
glob:

‎poetry.lock‎

Lines changed: 47 additions & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎pyproject.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,7 @@ mkdocs = "^1.5"
131131
mkdocs-material = "^9.5"
132132
mkdocs-exclude = "^1.0"
133133
pymdown-extensions = "^10.7"
134+
mkdocs-include-markdown-plugin = "^7.1.6"
134135

135136
[tool.poetry-dynamic-versioning]
136137
enable = true

0 commit comments

Comments
 (0)