|
1 | | -# How to manage Coder templates |
2 | | - |
3 | | -Coder templates are the DNA used to create workspaces. They abstract the complexity of cloud environments, allowing developers to focus on their projects. |
4 | | - |
5 | | -[](./static/templates.png) |
6 | | - |
7 | | -## Organizing your templates |
8 | | - |
9 | | -There are many ways to organize your templates. You can use them to: |
10 | | - |
11 | | -- **Team based templates**: A template for each of your teams e.g. a template for your _frontend_ team and a template for your _backend_ team. |
12 | | - |
13 | | -- **Project based templates**: A template for each of your projects e.g. a template for your _cool-project_ and a template for your _awesome-project_. |
14 | | - |
15 | | -- **Image based templates**: A single template that is used for all your projects but with a different image for each project. |
16 | | - |
17 | | - |
18 | | - |
19 | | -## What is the difference between a template and an image? |
20 | | - |
21 | | -A template is a collection of settings that are used to create a workspace. An image is a collection of software that is used to create a workspace. A template can use one or more images. For example, you can have a template that uses the _ubuntu_ image and the _node_ image and the user will have the choice of which image to use when creating a workspace. Choices are managed by a terraform variable e.g. |
22 | | - |
23 | | -```hcl |
24 | | - variable "image" { |
25 | | - type = string |
26 | | - description = "The image to use for the workspace" |
27 | | - default = "ubuntu" |
28 | | - validation { |
29 | | - condition = contains(["ubuntu", "node"], var.image) |
30 | | - error_message = "The image must be either ubuntu or node" |
31 | | - } |
32 | | - } |
33 | | -``` |
34 | | - |
35 | | -## Creating your first template |
36 | | - |
37 | | - |
38 | | - |
39 | | - |
40 | | -1. Create a new repository in your GitHub account. This will be the repository that contains your Coder templates. |
41 | | - |
42 | | -2. Create a new directory in your repository called `deeplearning`. |
43 | | - |
44 | | -3. Create a new file in the `deeplearning` directory called `main.tf`. This is the terraform file that will be used to create your template. |
45 | | - |
46 | | - ```hcl |
47 | | - terraform { |
48 | | - required_providers { |
49 | | - coder = { |
50 | | - source = "coder/coder" |
51 | | - version = "0.6.14" |
52 | | - } |
53 | | - docker = { |
54 | | - source = "kreuzwerker/docker" |
55 | | - version = "3.0.1" |
56 | | - } |
57 | | - } |
58 | | - } |
59 | | - ... |
60 | | - ``` |
61 | | - |
62 | | -4. Create a rich-parameter variable of the form `data coder_parameter <name>`. This will be used to create a rich parameter in the template. For example: |
63 | | - |
64 | | - > See full list of available parameters [here](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/parameter) |
65 | | -
|
66 | | - ```hcl |
67 | | - data "coder_parameter" "framework" { |
68 | | - name = "Framework" |
69 | | - icon = "https://raw.githubusercontent.com/matifali/logos/main/memory.svg" |
70 | | - description = "Choose your preffered framework" |
71 | | - type = "string" |
72 | | - mutable = false |
73 | | - default = "no-conda" |
74 | | - option { |
75 | | - name = "PyTorch" |
76 | | - description = "PyTorch" |
77 | | - value = "pytorch" |
78 | | - icon = "https://raw.githubusercontent.com/matifali/logos/main/pytorch.svg" |
79 | | - } |
80 | | - option { |
81 | | - name = "PyTorch Nightly" |
82 | | - description = "PyTorch Nightly" |
83 | | - value = "pytorch-nightly" |
84 | | - icon = "https://raw.githubusercontent.com/matifali/logos/main/pytorch.svg" |
85 | | - } |
86 | | - option { |
87 | | - name = "Tensorflow" |
88 | | - description = "Tensorflow" |
89 | | - value = "tensorflow" |
90 | | - icon = "https://raw.githubusercontent.com/matifali/logos/main/tensorflow.svg" |
91 | | - } |
92 | | - option { |
93 | | - name = "Tensorflow + PyTorch" |
94 | | - description = "Tensorflow + PyTorch" |
95 | | - value = "no-conda" |
96 | | - icon = "https://raw.githubusercontent.com/matifali/logos/main/tf-torch.svg" |
97 | | - } |
98 | | - option { |
99 | | - name = "Tensorflow + PyTorch + conda" |
100 | | - description = "Tensorflow + PyTorch + conda" |
101 | | - value = "conda" |
102 | | - icon = "https://raw.githubusercontent.com/matifali/logos/main/tf-torch-conda.svg" |
103 | | - } |
104 | | - option { |
105 | | - name = "Conda" |
106 | | - description = "Only conda (install whatever you need)" |
107 | | - value = "conda-base" |
108 | | - icon = "https://raw.githubusercontent.com/matifali/logos/main/conda.svg" |
109 | | - } |
110 | | - } |
111 | | - ``` |
112 | | - |
113 | | -5. For this example, we will use the pre-built [DockerDL](https://github.com/matifali/dockerdl) images. |
114 | | - |
115 | | - > **Note**: You can use any image you want. You can use a pre-built image or coder can build an image for you from the Dockerfile in _images_ directory. See |
116 | | -
|
117 | | - ```hcl |
118 | | - data "docker_registry_image" "dockerdl" { |
119 | | - name = "matifali/dockerdl:${data.coder_parameter.framework.value}" |
120 | | - } |
121 | | -
|
122 | | - resource "docker_image" "dockerdl" { |
123 | | - name = data.docker_registry_image.dockerdl.name |
124 | | - pull_triggers = [data.docker_registry_image.dockerdl.sha256_digest] |
125 | | - # Keep alive for other workspaces to use upon deletion |
126 | | - keep_locally = true |
127 | | - } |
128 | | -
|
129 | | - ``` |
130 | | - |
131 | | -> Full example is available [here](https://github.com/matifali/coder-templates/blob/main/deeplearning/main.tf) |
132 | | -
|
133 | | -## Next steps |
134 | | - |
135 | | -- [How to keep your templates up to date](./keep-up-to-date) |
136 | | - - A guide on how to keep your templates up to date with the latest changes in the upstream repository using GitHub Actions. This will allow you to keep your templates up to date without having to manually update them. [Read more](./keep-up-to-date) |
| 1 | +# How to create Coder templates |
| 2 | + |
| 3 | +Coder templates are the DNA used to create workspaces. They abstract the complexity of cloud environments, allowing developers to focus on their projects. |
| 4 | + |
| 5 | +[](./static/templates.png) |
| 6 | + |
| 7 | +## Organizing your templates |
| 8 | + |
| 9 | +There are many ways to organize your templates. You can use them to: |
| 10 | + |
| 11 | +- **Team based templates**: A template for each of your teams e.g. a template for your _frontend_ team and a template for your _backend_ team. |
| 12 | + |
| 13 | +- **Project based templates**: A template for each of your projects e.g. a template for your _cool-project_ and a template for your _awesome-project_. |
| 14 | + |
| 15 | +- **Image based templates**: A single template that is used for all your projects but with a different image for each project. |
| 16 | + |
| 17 | + |
| 18 | + |
| 19 | +## What is the difference between a template and an image? |
| 20 | + |
| 21 | +A template is a collection of settings that are used to create a workspace. An image is a collection of software that is used to create a workspace. A template can use one or more images. For example, you can have a template that uses the _ubuntu_ image and the _node_ image and the user will have the choice of which image to use when creating a workspace. Choices are managed by a terraform variable e.g. |
| 22 | + |
| 23 | +```hcl |
| 24 | + variable "image" { |
| 25 | + type = string |
| 26 | + description = "The image to use for the workspace" |
| 27 | + default = "ubuntu" |
| 28 | + validation { |
| 29 | + condition = contains(["ubuntu", "node"], var.image) |
| 30 | + error_message = "The image must be either ubuntu or node" |
| 31 | + } |
| 32 | + } |
| 33 | +``` |
| 34 | + |
| 35 | +## Creating your first template |
| 36 | + |
| 37 | + |
| 38 | + |
| 39 | + |
| 40 | +1. Create a new repository in your GitHub account. This will be the repository that contains your Coder templates. |
| 41 | + |
| 42 | +2. Create a new directory in your repository called `deeplearning`. |
| 43 | + |
| 44 | +3. Create a new file in the `deeplearning` directory called `main.tf`. This is the terraform file that will be used to create your template. |
| 45 | + |
| 46 | + ```hcl |
| 47 | + terraform { |
| 48 | + required_providers { |
| 49 | + coder = { |
| 50 | + source = "coder/coder" |
| 51 | + version = "0.6.14" |
| 52 | + } |
| 53 | + docker = { |
| 54 | + source = "kreuzwerker/docker" |
| 55 | + version = "3.0.1" |
| 56 | + } |
| 57 | + } |
| 58 | + } |
| 59 | + ... |
| 60 | + ``` |
| 61 | + |
| 62 | +4. Create a rich-parameter variable of the form `data coder_parameter <name>`. This will be used to create a rich parameter in the template. For example: |
| 63 | + |
| 64 | + > See full list of available parameters [here](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/parameter) |
| 65 | +
|
| 66 | + ```hcl |
| 67 | + data "coder_parameter" "framework" { |
| 68 | + name = "Framework" |
| 69 | + icon = "https://raw.githubusercontent.com/matifali/logos/main/memory.svg" |
| 70 | + description = "Choose your preffered framework" |
| 71 | + type = "string" |
| 72 | + mutable = false |
| 73 | + default = "no-conda" |
| 74 | + option { |
| 75 | + name = "PyTorch" |
| 76 | + description = "PyTorch" |
| 77 | + value = "pytorch" |
| 78 | + icon = "https://raw.githubusercontent.com/matifali/logos/main/pytorch.svg" |
| 79 | + } |
| 80 | + option { |
| 81 | + name = "PyTorch Nightly" |
| 82 | + description = "PyTorch Nightly" |
| 83 | + value = "pytorch-nightly" |
| 84 | + icon = "https://raw.githubusercontent.com/matifali/logos/main/pytorch.svg" |
| 85 | + } |
| 86 | + option { |
| 87 | + name = "Tensorflow" |
| 88 | + description = "Tensorflow" |
| 89 | + value = "tensorflow" |
| 90 | + icon = "https://raw.githubusercontent.com/matifali/logos/main/tensorflow.svg" |
| 91 | + } |
| 92 | + option { |
| 93 | + name = "Tensorflow + PyTorch" |
| 94 | + description = "Tensorflow + PyTorch" |
| 95 | + value = "no-conda" |
| 96 | + icon = "https://raw.githubusercontent.com/matifali/logos/main/tf-torch.svg" |
| 97 | + } |
| 98 | + option { |
| 99 | + name = "Tensorflow + PyTorch + conda" |
| 100 | + description = "Tensorflow + PyTorch + conda" |
| 101 | + value = "conda" |
| 102 | + icon = "https://raw.githubusercontent.com/matifali/logos/main/tf-torch-conda.svg" |
| 103 | + } |
| 104 | + option { |
| 105 | + name = "Conda" |
| 106 | + description = "Only conda (install whatever you need)" |
| 107 | + value = "conda-base" |
| 108 | + icon = "https://raw.githubusercontent.com/matifali/logos/main/conda.svg" |
| 109 | + } |
| 110 | + } |
| 111 | + ``` |
| 112 | + |
| 113 | +5. For this example, we will use the pre-built [DockerDL](https://github.com/matifali/dockerdl) images. |
| 114 | + |
| 115 | + > **Note**: You can use any image you want. You can use a pre-built image or coder can build an image for you from the Dockerfile in _images_ directory. See |
| 116 | +
|
| 117 | + ```hcl |
| 118 | + data "docker_registry_image" "dockerdl" { |
| 119 | + name = "matifali/dockerdl:${data.coder_parameter.framework.value}" |
| 120 | + } |
| 121 | +
|
| 122 | + resource "docker_image" "dockerdl" { |
| 123 | + name = data.docker_registry_image.dockerdl.name |
| 124 | + pull_triggers = [data.docker_registry_image.dockerdl.sha256_digest] |
| 125 | + # Keep alive for other workspaces to use upon deletion |
| 126 | + keep_locally = true |
| 127 | + } |
| 128 | +
|
| 129 | + ``` |
| 130 | + |
| 131 | +> Full example is available [here](https://github.com/matifali/coder-templates/blob/main/deeplearning/main.tf) |
| 132 | +
|
| 133 | +## Next steps |
| 134 | + |
| 135 | +- [How to keep your templates up to date](./keep-up-to-date) |
| 136 | + - A guide on how to keep your templates up to date with the latest changes in the upstream repository using GitHub Actions. This will allow you to keep your templates up to date without having to manually update them. [Read more](./keep-up-to-date) |
0 commit comments