Skip to content

Commit 2c84f2e

Browse files
bpmctbpmct
committed
reorganize some things
1 parent 7119be1 commit 2c84f2e

File tree

4 files changed

+110
-49
lines changed

4 files changed

+110
-49
lines changed

‎docs/manifest.json

+52-42
Original file line numberDiff line numberDiff line change
@@ -139,46 +139,61 @@
139139
"icon_path": "./images/icons/picture.svg",
140140
"children": [
141141
{
142-
"title": "Writing templates",
143-
"description": "Learn how to create & modify Coder templates",
144-
"path": "./templates/writing/index.md"
145-
},
146-
{
147-
"title": "Resource Persistence",
148-
"description": "Learn how resource persistence works in Coder",
149-
"path": "./templates/resource-persistence.md",
150-
"icon_path": "./images/icons/infinity.svg"
151-
},
152-
{
153-
"title": "Provider Authentication",
154-
"description": "Learn how to authenticate the provisioner",
155-
"path": "./templates/authentication.md",
156-
"icon_path": "./images/icons/key.svg"
157-
},
158-
{
159-
"title": "Change Management",
160-
"description": "Learn how to source-control templates with git and CI",
161-
"path": "./templates/change-management.md",
162-
"icon_path": "./images/icons/git.svg"
163-
},
164-
{
165-
"title": "Resource Metadata",
166-
"description": "Learn how to expose resource data to users",
167-
"path": "./templates/resource-metadata.md",
168-
"icon_path": "./images/icons/table-rows.svg"
169-
},
170-
{
171-
"title": "Agent Metadata",
172-
"description": "Learn how to expose live agent information to users",
173-
"path": "./templates/agent-metadata.md",
174-
"icon_path": "./images/icons/table-rows.svg"
142+
"title": "Templates & Terraform",
143+
"description": "Learn what makes up a template",
144+
"path": "./templates/concepts.md",
145+
"children": [
146+
{
147+
"title": "Parameters",
148+
"description": "Use parameters to customize templates",
149+
"path": "./templates/parameters.md",
150+
"icon_path": "./images/icons/code.svg"
151+
},
152+
{
153+
"title": "Terraform Modules",
154+
"description": "Reuse code across Coder templates",
155+
"path": "./templates/modules.md"
156+
},
157+
{
158+
"title": "Agent Metadata",
159+
"description": "Learn how to expose live agent information to users",
160+
"path": "./templates/agent-metadata.md",
161+
"icon_path": "./images/icons/table-rows.svg"
162+
},
163+
{
164+
"title": "Resource Metadata",
165+
"description": "Learn how to expose resource data to users",
166+
"path": "./templates/resource-metadata.md",
167+
"icon_path": "./images/icons/table-rows.svg"
168+
}
169+
]
175170
},
176171
{
177-
"title": "Parameters",
178-
"description": "Use parameters to customize templates",
179-
"path": "./templates/parameters.md",
180-
"icon_path": "./images/icons/code.svg"
172+
"title": "Best Practices",
173+
"description": "Best practices for writing/managing templates",
174+
"path": "./templates/best-practices.md",
175+
"children": [
176+
{
177+
"title": "Provider Authentication",
178+
"description": "Learn how to authenticate the provisioner",
179+
"path": "./templates/authentication.md",
180+
"icon_path": "./images/icons/key.svg"
181+
},
182+
{
183+
"title": "Resource Persistence",
184+
"description": "Learn how resource persistence works in Coder",
185+
"path": "./templates/resource-persistence.md",
186+
"icon_path": "./images/icons/infinity.svg"
187+
},
188+
{
189+
"title": "Change Management",
190+
"description": "Learn how to source-control templates with git and CI",
191+
"path": "./templates/change-management.md",
192+
"icon_path": "./images/icons/git.svg"
193+
}
194+
]
181195
},
196+
182197
{
183198
"title": "Open in Coder",
184199
"description": "Learn how to add an \"Open in Coder\" button to your repos",
@@ -196,11 +211,6 @@
196211
"description": "Use devcontainers in workspaces",
197212
"path": "./templates/devcontainers.md",
198213
"state": "alpha"
199-
},
200-
{
201-
"title": "Terraform Modules",
202-
"description": "Reuse code across Coder templates",
203-
"path": "./templates/modules.md"
204214
}
205215
]
206216
},

‎docs/templates/best-practices.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Template best practices
2+
3+
Templates are very flexible

‎docs/templates/writing/index.md renamed to ‎docs/templates/concepts.md

+53-6
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
1-
# Template structure
1+
# Template concepts
22

33
Coder templates are written in [Terraform](https://terraform.io). All Terraform modules, resources, and properties can be provisioned by Coder. The Coder server essentially runs a `terraform apply` every time a workspace is created/started/stopped.
44

55
Haven't written Terraform before? Check out Hashicorp's [Getting Started Guides](https://developer.hashicorp.com/terraform/tutorials).
66

77
## Architecture
88

9-
This is a simplified diagram of our [Kubernetes example template](https://github.com/coder/coder/tree/main/examples/templates/kubernetes). Keep reading for a breakdown of each concept.
9+
This is a simplified diagram of our [Kubernetes example template](https://github.com/coder/coder/blob/main/examples/templates/kubernetes/main.tf). Keep reading for a breakdown of each concept.
1010

1111
![Template architecture](https://user-images.githubusercontent.com/22407953/257021139-8c95a731-c131-4c4d-85cc-eed6a52e015c.png)
1212

@@ -24,7 +24,7 @@ terraform {
2424
}
2525
```
2626

27-
## coder_agent
27+
### coder_agent
2828

2929
All templates need to create & run a Coder agent in order for developers to connect to their workspaces. The Coder agent is a service that runs inside the compute aspect of your workspace (typically a VM or container). You do not need to have any open ports, but the compute will need `curl` access to the Coder server.
3030

@@ -45,7 +45,7 @@ resource "kubernetes_deployment" "workspace" {
4545

4646
Agents can also run startup scripts, set environment variables, and provide [metadata](../agent-metadata.md) about the workspace (e.g. CPU usage). Read the [coder_agent docs](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) for more details.
4747

48-
## coder_workspace
48+
### coder_workspace
4949

5050
This data source provides details about the state of a workspace, such as its name, owner, and whether the workspace is being started or stopped.
5151

@@ -64,7 +64,7 @@ resource "kubernetes_deployment" "workspace" {
6464
resource "docker_volume" "projects" {}
6565
```
6666

67-
## coder_app
67+
### coder_app
6868

6969
Web apps that are running inside the workspace (e.g. `http://localhost:8080`) can be forwarded to the Coder dashboard with the `coder_app` resource. This is commonly used for [web IDEs](../../ides/web-ides.md) such as code-server, RStudio, and JupyterLab. External apps, such as links to internal wikis or cloud consoles can also be embedded here.
7070

@@ -104,4 +104,51 @@ resource "coder_app" "getting-started" {
104104
}
105105
```
106106

107-
Lorem ipsum
107+
### coder_parameter
108+
109+
Parameters are inputs that users fill in when creating their workspace.
110+
111+
![Parameters in templates](https://user-images.githubusercontent.com/22407953/256707889-18baf2be-2dae-4eb2-ae89-71e5b00248f8.png)
112+
113+
```hcl
114+
data "coder_parameter" "repo" {
115+
name = "repo"
116+
display_name = "Repository (auto)"
117+
order = 1
118+
description = "Select a repository to automatically clone and start working with a devcontainer."
119+
mutable = true
120+
option {
121+
name = "vercel/next.js"
122+
description = "The React Framework"
123+
value = "https://github.com/vercel/next.js"
124+
}
125+
option {
126+
name = "home-assistant/core"
127+
description = "🏡 Open source home automation that puts local control and privacy first."
128+
value = "https://github.com/home-assistant/core"
129+
}
130+
# ...
131+
}
132+
```
133+
134+
## Terraform variables
135+
136+
Variables for templates are supported and can be managed in template settings.
137+
138+
![Template variables](https://user-images.githubusercontent.com/22407953/257079273-af4720c4-1aee-4451-8fd9-82a8c579f289.png)
139+
140+
> Per-workspace settings can be defined via [Parameters](./parameters.md).
141+
142+
## Best practices
143+
144+
Before making major changes or creating your own template, we recommend reading these best practices:
145+
146+
- [Resource Persistence](./resource-persistence.md): Control which resources are persistent/ephemeral and avoid accidental disk deletion.
147+
- [Provider Authentication](./provider-authentication.md): Securely authenticate with cloud APIs with Terraform
148+
- [Change Management](./change-management.md): Manage Coder templates in git with CI/CD pipelines.
149+
150+
## Use cases
151+
152+
- [Devcontainers](./devcontainers.md): Add devcontainer support to your Coder templates.
153+
- [Docker in Workspaces](./docker-in-workspaces.md): Add docker-in-Docker support or even run system-level services.
154+
- [Open in Coder](./open-in-coder.md): Auto-create a workspace from your GitHub repository or internal wiki with deep links.

‎docs/templates/index.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -48,4 +48,5 @@ Paramaters let users customize their individual workspaces:
4848
4949
## Next steps
5050

51-
- [Writing templates](./writing/index.md)
51+
- [Template structure](./structure.md)
52+
- [Template structure](./structure.md)

0 commit comments

Comments
 (0)