Skip to content

Commit 2dcf91e

Browse files
bpmctmatifali
bpmct
authored and
matifali
committed
add guide for creating templates
1 parent ee2c576 commit 2dcf91e

13 files changed

+217
-104
lines changed

‎docs/admin/monitoring/README.md

+2
Original file line numberDiff line numberDiff line change
@@ -1 +1,3 @@
11
# Monitoring Coder
2+
3+
ssss

‎docs/admin/templates/README.md

+16-30
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,27 @@
1-
# Template Management
1+
# Template
22

3-
Templates define the underlying infrastructure that Coder workspaces run on. All workspaces are created from templates.
3+
Templates are written in [Terraform](https://developer.hashicorp.com/terraform/intro) and define the underlying infrastructure that all Coder workspaces run on.
44

5-
## Creating templates
5+
![Starter templates](../../images/admin/templates/starter-templates.png)
66

7-
The following are tutorials on creating templates in Coder for various platforms
7+
<small>The "Starter Templates" page within the Coder dashboard.</small>
88

9-
<!-- TODO: Use the tutorials widget component -->
9+
## Getting Started
1010

11-
- [From scratch](../../tutorials/template-from-scratch.md)
12-
- Kubernetes
13-
- GCP Compute Engine
14-
- AWS EC2
15-
- Azure
16-
- Template Registry
11+
Learn the underlying concepts by [creating your first template](../../tutorials/template-from-scratch.md). After that, visit the [Coder Registry](https://registry.coder.com/templates) to learn how to install example templates for various cloud providers and platforms (e.g. AWS, Kubernetes).
1712

18-
## Best practices
13+
## Best Practices
1914

20-
Learn about best practices running templates
15+
We recommend starting with a universal template that can be used for basic tasks. As your Coder deployment grows, you can create more templates to meet the needs of different teams.
2116

22-
- [Image Management](../../tutorials/image-management.md)
23-
- Dev Container support
24-
- Protecting resources (user disks)
25-
- Manage templates with Ci/Cd pipelines
17+
- [Image management](../../tutorials/image-management.md): Learn how to create and publish images for use within Coder workspaces & templates.
18+
- [Dev Container support](#): Enable dev containers to allow teams to bring their own tools into Coder workspaces.
19+
- [Template hardening](./): Configure your template to prevent certain resources from being destroyed (e.g. user disks).
20+
- [Manage templates with Ci/Cd pipelines](#): Learn how to source control your templates and use GitOps to ensure template changes are reviewed and tested.
2621

27-
## Workspace Lifecycle
22+
## Template Features
2823

29-
- Keep workspaces up to date
30-
- Clean up unused workspaces
31-
- Stop workspaces when not in use
24+
## Template Settings
3225

33-
## Concepts
34-
35-
- Variables
36-
- Parameters
37-
- Resource Persistance
38-
- Modules
39-
- Resource metadata
40-
- Resource ordering
41-
- Agent metadata
26+
- [Template Permissions]()
27+
- [Display name]

‎docs/admin/templates/best-practices.md

-9
This file was deleted.

‎docs/admin/templates/creating-templates.md

+103-62
Original file line numberDiff line numberDiff line change
@@ -1,93 +1,134 @@
1-
# Working with templates
1+
# Creating Templates
22

3-
You create and edit Coder templates as [Terraform](./tour.md) configuration
4-
files (`.tf`) and any supporting files, like a README or configuration files for
5-
other services.
3+
Users with the `Template Administrator` role or above can create templates
4+
within Coder.
65

7-
## Who creates templates?
6+
## From a starter template
87

9-
The [Template Admin](../admin/users.md) role (and above) can create templates.
10-
End users, like developers, create workspaces from them. Templates can also be
11-
[managed with git](./change-management.md), allowing any developer to propose
12-
changes to a template.
8+
In most cases, it is best to start with a starter template.
139

14-
You can give different users and groups access to templates with
15-
[role-based access control](../admin/rbac.md).
10+
<div class="tabs">
1611

17-
## Starter templates
12+
### Web UI
1813

19-
We provide starter templates for common cloud providers, like AWS, and
20-
orchestrators, like Kubernetes. From there, you can modify them to use your own
21-
images, VPC, cloud credentials, and so on. Coder supports all Terraform
22-
resources and properties, so fear not if your favorite cloud provider isn't
23-
here!
14+
After navigating to the Templates page in the Coder dashboard, choose
15+
`Create Template > Choose a starter template`.
2416

25-
![Starter templates](../../images/templates/starter-templates.png)
17+
![Create a template](../../images/admin/templates/create-template.png)
2618

27-
If you prefer to use Coder on the [command line](../cli.md), use
28-
`coder templates init`.
19+
From there, select a starter template for desired underlying infrastructure for
20+
workspaces.
2921

30-
> Coder starter templates are also available on our
31-
> [GitHub repo](https://github.com/coder/coder/tree/main/examples/templates).
22+
![Starter templates](../../images/admin/templates/starter-templates.png)
3223

33-
## Community Templates
24+
Give your template a name, description, and icon and press `Create template`.
3425

35-
As well as Coder's starter templates, you can see a list of community templates
36-
by our users
37-
[here](https://github.com/coder/coder/blob/main/examples/templates/community-templates.md).
26+
![Name and icon](../../images/admin/templates/import-template.png)
3827

39-
## Editing templates
28+
> **⚠️ Note**: If template creation fails, Coder is likely not authorized to
29+
> deploy infrastructure in the given location. Learn how to configure
30+
> [provisioner authentication](#TODO).
4031
41-
Our starter templates are meant to be modified for your use cases. You can edit
42-
any template's files directly in the Coder dashboard.
32+
### CLI
4333

44-
![Editing a template](../../images/templates/choosing-edit-template.gif)
34+
You can the [Coder CLI](../../install/cli.md) to manage templates for Coder.
35+
After [logging in](#TODO) to your deployment, create a folder to store your
36+
templates:
4537

46-
If you'd prefer to use the CLI, use `coder templates pull`, edit the template
47-
files, then `coder templates push`.
48-
49-
> Even if you are a Terraform expert, we suggest reading our
50-
> [guided tour](./tour.md).
38+
```sh
39+
# This snippet applies to macOS and Linux only
40+
mkdir $HOME/coder-templates
41+
cd $HOME/coder-templates
42+
```
5143

52-
## Updating templates
44+
Use the [`templates init`](../../reference/cli/templates_init.md) command to
45+
pull a starter template:
5346

54-
Coder tracks a template's versions, keeping all developer workspaces up-to-date.
55-
When you publish a new version, developers are notified to get the latest
56-
infrastructure, software, or security patches. Learn more about
57-
[change management](./change-management.md).
47+
```sh
48+
coder templates init
49+
```
5850

59-
![Updating a template](../../images/templates/update.png)
51+
After pulling the template to your local machine (e.g. `aws-linux`), you can
52+
rename it:
6053

61-
## Delete templates
54+
```sh
55+
# This snippet applies to macOS and Linux only
56+
mv aws-linux universal-template
57+
cd universal-template
58+
```
6259

63-
You can delete a template using both the coder CLI and UI. Only
64-
[template admins and owners](../admin/users.md) can delete a template, and the
65-
template must not have any running workspaces associated to it.
60+
Next, push it to Coder with the
61+
[`templates push`](../../reference/cli/templates_push.md) command:
6662

67-
In the UI, navigate to the template you want to delete, and select the dropdown
68-
in the right-hand corner of the page to delete the template.
63+
```sh
64+
coder templates push
65+
```
6966

70-
![delete-template](../../images/delete-template.png)
67+
> ⚠️ Note: If `template push` fails, Coder is likely not authorized to deploy
68+
> infrastructure in the given location. Learn how to configure
69+
> [provisioner authentication](#TODO).
7170
72-
Using the CLI, login to Coder and run the following command to delete a
73-
template:
71+
You can edit the metadata of the template such as the display name with the
72+
[`templates edit`](../../reference/cli/templates_edit.md) command:
7473

75-
```shell
76-
coder templates delete <template-name>
74+
```sh
75+
coder templates edit universal-template \
76+
--display-name "Universal Template" \
77+
--description "Virtual machine configured with Java, Python, Typescript, IntelliJ IDEA, and Ruby. Use this for starter projects. " \
78+
--icon "/emojis/2b50.png"
7779
```
7880

79-
### Delete workspaces
81+
### Git
82+
83+
Follow our tutorial to [manage templates via GitOps](#TODO).
84+
85+
</div>
86+
87+
## From an existing template
88+
89+
You can duplicate an existing template in your Coder deployment. This will copy
90+
the template code and metadata, allowing you to make changes without affecting
91+
the original template.
92+
93+
<div class="tabs">
94+
95+
### Web UI
96+
97+
After navigating to the page for a template, use the dropdown menu on the right
98+
to `Duplicate`.
99+
100+
![Duplicate menu](../../images/admin/templates/duplicate-menu.png)
101+
102+
Give the new template a name, icon, and description.
103+
104+
![Duplicate page](../../images/admin/templates/duplicate-page.png)
105+
106+
Press `Create template`. After the build, you will be taken to the new template
107+
page.
108+
109+
![New template](../../images/admin/templates/new-duplicate-template.png)
110+
111+
### CLI
112+
113+
</div>
114+
115+
## From scratch (advanced)
116+
117+
There may be cases where you want to create a template from scratch. You can use
118+
[any Terraform provider](https://registry.terraform.com) with Coder to create
119+
templates for additional clouds (e.g. Hetzner, Alibaba) or orchestrators
120+
(VMware, Proxmox) that we do not provide example templates for.
80121

81-
When a workspace is deleted, the Coder server essentially runs a
82-
[terraform destroy](https://www.terraform.io/cli/commands/destroy) to remove all
83-
resources associated with the workspace.
122+
Refer to the following resources:
84123

85-
> Terraform's
86-
> [prevent-destroy](https://www.terraform.io/language/meta-arguments/lifecycle#prevent_destroy)
87-
> and
88-
> [ignore-changes](https://www.terraform.io/language/meta-arguments/lifecycle#ignore_changes)
89-
> meta-arguments can be used to prevent accidental data loss.
124+
- [Tutorial: Create a template from scratch](../../tutorials/template-from-scratch.md)
125+
- [Extending templates](./editing-templates.md): Features and concepts around
126+
templates (agents, parameters, variables, etc)
127+
- [Coder Registry](https://registry.coder.com/templates): Official and community
128+
templates for Coder
129+
- [Coder Terraform Provider Reference](https://registry.terraform.io/providers/coder/coder)
90130

91131
## Next steps
92132

93-
- [Your first template](../templates/tutorial.md)
133+
- [Extending templates](#TODO)
134+
- [TODO](#TODO)

‎docs/admin/templates/managing-templates.md

+93
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Working with templates
2+
3+
You create and edit Coder templates as [Terraform](./tour.md) configuration
4+
files (`.tf`) and any supporting files, like a README or configuration files for
5+
other services.
6+
7+
## Who creates templates?
8+
9+
The [Template Admin](../admin/users.md) role (and above) can create templates.
10+
End users, like developers, create workspaces from them. Templates can also be
11+
[managed with git](./change-management.md), allowing any developer to propose
12+
changes to a template.
13+
14+
You can give different users and groups access to templates with
15+
[role-based access control](../admin/rbac.md).
16+
17+
## Starter templates
18+
19+
We provide starter templates for common cloud providers, like AWS, and
20+
orchestrators, like Kubernetes. From there, you can modify them to use your own
21+
images, VPC, cloud credentials, and so on. Coder supports all Terraform
22+
resources and properties, so fear not if your favorite cloud provider isn't
23+
here!
24+
25+
![Starter templates](../../images/templates/starter-templates.png)
26+
27+
If you prefer to use Coder on the [command line](../cli.md), use
28+
`coder templates init`.
29+
30+
> Coder starter templates are also available on our
31+
> [GitHub repo](https://github.com/coder/coder/tree/main/examples/templates).
32+
33+
## Community Templates
34+
35+
As well as Coder's starter templates, you can see a list of community templates
36+
by our users
37+
[here](https://github.com/coder/coder/blob/main/examples/templates/community-templates.md).
38+
39+
## Editing templates
40+
41+
Our starter templates are meant to be modified for your use cases. You can edit
42+
any template's files directly in the Coder dashboard.
43+
44+
![Editing a template](../../images/templates/choosing-edit-template.gif)
45+
46+
If you'd prefer to use the CLI, use `coder templates pull`, edit the template
47+
files, then `coder templates push`.
48+
49+
> Even if you are a Terraform expert, we suggest reading our
50+
> [guided tour](./tour.md).
51+
52+
## Updating templates
53+
54+
Coder tracks a template's versions, keeping all developer workspaces up-to-date.
55+
When you publish a new version, developers are notified to get the latest
56+
infrastructure, software, or security patches. Learn more about
57+
[change management](./change-management.md).
58+
59+
![Updating a template](../../images/templates/update.png)
60+
61+
## Delete templates
62+
63+
You can delete a template using both the coder CLI and UI. Only
64+
[template admins and owners](../admin/users.md) can delete a template, and the
65+
template must not have any running workspaces associated to it.
66+
67+
In the UI, navigate to the template you want to delete, and select the dropdown
68+
in the right-hand corner of the page to delete the template.
69+
70+
![delete-template](../../images/delete-template.png)
71+
72+
Using the CLI, login to Coder and run the following command to delete a
73+
template:
74+
75+
```shell
76+
coder templates delete <template-name>
77+
```
78+
79+
### Delete workspaces
80+
81+
When a workspace is deleted, the Coder server essentially runs a
82+
[terraform destroy](https://www.terraform.io/cli/commands/destroy) to remove all
83+
resources associated with the workspace.
84+
85+
> Terraform's
86+
> [prevent-destroy](https://www.terraform.io/language/meta-arguments/lifecycle#prevent_destroy)
87+
> and
88+
> [ignore-changes](https://www.terraform.io/language/meta-arguments/lifecycle#ignore_changes)
89+
> meta-arguments can be used to prevent accidental data loss.
90+
91+
## Next steps
92+
93+
- [Your first template](../templates/tutorial.md)

‎docs/admin/users/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Users
22

3-
By default, Coder is accessible via password authentication. Coder does not recommend using password authentication in production, and recommends using an authentication provider with properly configured multi-factor authentication (MFA). It is your responsibility to ensure the auth provider enforces MFA correctly.
3+
By default, Coder is accessible via password authentication. For production deployments, we recommend using an SSO authentication provider with multi-factor authentication (MFA). It is your responsibility to ensure the auth provider enforces MFA correctly.
44

55
## Configuring SSO
66

‎docs/images/admin/templates/create-template.png

164 KB
Loading

‎docs/images/admin/templates/duplicate-menu.png

161 KB
Loading

‎docs/images/admin/templates/duplicate-page.png

175 KB
Loading

‎docs/images/admin/templates/import-template.png

188 KB
Loading

‎docs/images/admin/templates/new-duplicate-template.png

410 KB
Loading

‎docs/images/admin/templates/starter-templates.png

190 KB
Loading

‎docs/manifest.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -168,7 +168,7 @@
168168
]
169169
},
170170
{
171-
"title": "User Management",
171+
"title": "Users",
172172
"description": "Learn how to manage and audit users",
173173
"path": "./admin/users/README.md",
174174
"children": [
@@ -209,7 +209,7 @@
209209
"path": "./admin/templates/creating-templates.md"
210210
},
211211
{
212-
"title": "Template Best Practices",
212+
"title": "Managing Templates",
213213
"description": "Learn best practices managing templates",
214214
"path": "./admin/templates/best-practices.md"
215215
},

0 commit comments

Comments
 (0)