Skip to content

Commit c0c95b1

Browse files
acmoreacmore
committed
docs(site): add config manifest reference and dark tech theme
1 parent b7c449a commit c0c95b1

4 files changed

Lines changed: 239 additions & 4 deletions

File tree

‎docs/config-manifest.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
# Config Manifest
2+
3+
`okdev` is configured by a single manifest (default: `.okdev.yaml`).
4+
5+
## Top-Level
6+
7+
```yaml
8+
apiVersion: okdev.io/v1alpha1
9+
kind: DevEnvironment
10+
metadata:
11+
name: my-project
12+
spec: {}
13+
```
14+
15+
## Field Reference
16+
17+
### `apiVersion` and `kind`
18+
19+
- `apiVersion`: must be `okdev.io/v1alpha1`
20+
- `kind`: must be `DevEnvironment`
21+
22+
### `metadata`
23+
24+
- `metadata.name` (`string`, required): logical project/env name.
25+
26+
### `spec`
27+
28+
- `spec.namespace` (`string`, default: `default`)
29+
- `spec.session` (`object`)
30+
- `spec.workspace` (`object`, required)
31+
- `spec.sync` (`object`)
32+
- `spec.ports` (`array`)
33+
- `spec.ssh` (`object`)
34+
- `spec.lifecycle` (`object`)
35+
- `spec.sidecar` (`object`)
36+
- `spec.podTemplate` (`object`)
37+
38+
## `spec.session`
39+
40+
- `defaultNameTemplate` (`string`): template for inferred session name.
41+
- `ttlHours` (`int`, default from template): reserved for lifecycle policy.
42+
- `idleTimeoutMinutes` (`int`, default from template): reserved for lifecycle policy.
43+
- `shareable` (`bool`): marks intent for team sharing workflows.
44+
45+
Validation:
46+
- `ttlHours >= 0`
47+
- `idleTimeoutMinutes >= 0`
48+
49+
## `spec.workspace`
50+
51+
- `mountPath` (`string`, required): workspace mount path in containers.
52+
- `pvc` (`object`):
53+
- `claimName` (`string`, optional): existing PVC to bind.
54+
- `size` (`string`, default: `50Gi`): requested PVC size.
55+
- `storageClassName` (`string`, optional)
56+
57+
## `spec.sync`
58+
59+
- `engine` (`string`, required, currently only `syncthing`)
60+
- `paths` (`[]string`): mappings in `local:remote` format.
61+
- `exclude` (`[]string`): local ignore patterns.
62+
- `remoteExclude` (`[]string`): remote-only ignore patterns (written to remote `.stignore`).
63+
- `syncthing` (`object`):
64+
- `version` (`string`, default: `v1.29.7`)
65+
- `autoInstall` (`bool`, default: `true`)
66+
- `image` (`string`, default: `ghcr.io/acmore/okdev:<okdev-version>` with `edge` fallback)
67+
68+
Validation:
69+
- `engine` must be `syncthing`
70+
- each `paths[]` entry must be `local:remote`
71+
- currently at most one `paths[]` entry
72+
73+
## `spec.ports`
74+
75+
Each item:
76+
77+
- `name` (`string`, optional)
78+
- `local` (`int`, required): local listening port
79+
- `remote` (`int`, required): remote target port in dev environment
80+
81+
Validation:
82+
- `local` and `remote` must be `1..65535`
83+
- `local` ports must be unique
84+
85+
## `spec.ssh`
86+
87+
- `user` (`string`, default: `root`)
88+
- `remotePort` (`int`, default: `22`)
89+
- `privateKeyPath` (`string`, optional)
90+
- `autoDetectPorts` (`bool`, default: `true`)
91+
- `persistentSession` (`bool`, default: `false`) enables tmux-backed interactive session mode
92+
- `keepAliveIntervalSeconds` (`int`, default: `10`)
93+
- `keepAliveTimeoutSeconds` (`int`, default: `15`)
94+
95+
Validation:
96+
- `remotePort` must be `1..65535`
97+
- `keepAliveIntervalSeconds > 0`
98+
- `keepAliveTimeoutSeconds > 0`
99+
- `keepAliveTimeoutSeconds >= keepAliveIntervalSeconds`
100+
101+
## `spec.lifecycle`
102+
103+
- `postCreate` (`string`, optional): command executed once after environment creation.
104+
- `preStop` (`string`, optional): command executed before pod termination.
105+
106+
## `spec.sidecar`
107+
108+
- `image` (`string`, required)
109+
110+
Recommended:
111+
- use release-aligned tag, for example `ghcr.io/acmore/okdev:v0.2.0`
112+
113+
## `spec.podTemplate`
114+
115+
Direct PodSpec overlay:
116+
117+
- `metadata.labels` (`map[string]string`, optional)
118+
- `spec` (`k8s PodSpec`, optional)
119+
120+
Use this to define the dev container image, resources, extra sidecars, env vars, and scheduling settings.
121+
122+
## Example Manifest
123+
124+
```yaml
125+
apiVersion: okdev.io/v1alpha1
126+
kind: DevEnvironment
127+
metadata:
128+
name: llm-project
129+
spec:
130+
namespace: ai-dev
131+
session:
132+
defaultNameTemplate: "{{ .Repo }}-{{ .Branch }}-{{ .User }}"
133+
ttlHours: 72
134+
idleTimeoutMinutes: 120
135+
shareable: true
136+
workspace:
137+
mountPath: /workspace
138+
pvc:
139+
size: 200Gi
140+
storageClassName: fast-ssd
141+
sync:
142+
engine: syncthing
143+
syncthing:
144+
version: v1.29.7
145+
autoInstall: true
146+
paths:
147+
- .:/workspace
148+
exclude:
149+
- .git/
150+
- .venv/
151+
- node_modules/
152+
- checkpoints/
153+
remoteExclude:
154+
- ".cache/"
155+
ports:
156+
- name: app
157+
local: 8080
158+
remote: 8080
159+
- name: tensorboard
160+
local: 6006
161+
remote: 6006
162+
ssh:
163+
user: root
164+
remotePort: 22
165+
persistentSession: true
166+
keepAliveIntervalSeconds: 10
167+
keepAliveTimeoutSeconds: 15
168+
sidecar:
169+
image: ghcr.io/acmore/okdev:v0.2.0
170+
podTemplate:
171+
spec:
172+
containers:
173+
- name: dev
174+
image: nvidia/cuda:12.4.1-devel-ubuntu22.04
175+
command: ["sleep", "infinity"]
176+
resources:
177+
requests:
178+
cpu: "8"
179+
memory: 32Gi
180+
nvidia.com/gpu: "1"
181+
limits:
182+
cpu: "16"
183+
memory: 64Gi
184+
nvidia.com/gpu: "1"
185+
```

‎docs/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,8 @@ It provisions and operates dev environments from `.okdev.yaml` using standard Po
1414
## Documentation
1515

1616
- [Quickstart](quickstart.md)
17+
- [Config Manifest](config-manifest.md)
1718
- [Command Reference](command-reference.md)
1819
- [Troubleshooting](troubleshooting.md)
19-
- [Design](okdev-design.md)
20-
- [Implementation Plan](okdev-implementation-plan.md)
2120
- [Release & Versioning](release.md)
21+
- [Repository](https://github.com/acmore/okdev)

‎docs/stylesheets/extra.css‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
:root {
2+
--okdev-grid: rgba(0, 255, 255, 0.08);
3+
--okdev-edge: rgba(0, 255, 255, 0.2);
4+
}
5+
6+
.md-typeset,
7+
.md-header__title,
8+
.md-nav__title,
9+
.md-nav__item,
10+
.md-typeset h1,
11+
.md-typeset h2,
12+
.md-typeset h3,
13+
.md-typeset code,
14+
.md-nav,
15+
.md-tabs {
16+
font-family: "JetBrains Mono", "SFMono-Regular", Menlo, Consolas, monospace;
17+
}
18+
19+
.md-main {
20+
background-image:
21+
linear-gradient(var(--okdev-grid) 1px, transparent 1px),
22+
linear-gradient(90deg, var(--okdev-grid) 1px, transparent 1px);
23+
background-size: 28px 28px;
24+
}
25+
26+
.md-typeset h1,
27+
.md-typeset h2 {
28+
letter-spacing: 0.02em;
29+
text-transform: uppercase;
30+
}
31+
32+
.md-typeset pre > code {
33+
border: 1px solid var(--okdev-edge);
34+
}
35+
36+
.md-header,
37+
.md-tabs {
38+
border-bottom: 1px solid var(--okdev-edge);
39+
}

‎mkdocs.yml‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,21 @@ repo_url: https://github.com/acmore/okdev
44
repo_name: acmore/okdev
55
theme:
66
name: material
7+
palette:
8+
- scheme: slate
9+
primary: black
10+
accent: cyan
711
features:
812
- navigation.sections
913
- navigation.expand
1014
- content.code.copy
15+
- navigation.top
16+
extra_css:
17+
- stylesheets/extra.css
18+
exclude_docs: |
19+
okdev-design.md
20+
okdev-implementation-plan.md
21+
plans/**
1122
markdown_extensions:
1223
- admonition
1324
- tables
@@ -16,8 +27,8 @@ markdown_extensions:
1627
nav:
1728
- Home: index.md
1829
- Quickstart: quickstart.md
30+
- Config Manifest: config-manifest.md
1931
- Command Reference: command-reference.md
20-
- Design: okdev-design.md
21-
- Implementation Plan: okdev-implementation-plan.md
2232
- Release: release.md
2333
- Troubleshooting: troubleshooting.md
34+
- Repository: https://github.com/acmore/okdev

0 commit comments

Comments
 (0)