1- #A guided tour of a template
1+ #Write a template from scratch
22
3- This guided tour introduces you to the different parts of a Coder template by
4- showing you how to create a template from scratch.
3+ A template is a common configuration that you use to deploy workspaces.
54
6- You'll write a simple template that provisions aworkspace as a Docker container
7- with Ubuntu.
5+ This tutorial teaches you how to create atemplate that provisions a workspace
6+ as a Docker container with Ubuntu.
87
98##Before you start
109
11- To follow this guide, you'll need:
12-
13- - A computer or cloud computing instance with both
14- [ Docker] ( https://docs.docker.com/get-docker/ ) and[ Coder] ( ../install/index.md )
15- installed on it.
16-
17- - When setting up your computer or computing instance, make sure to install
18- Docker first, then Coder. Otherwise, you'll need to add the` coder ` user to
19- the` docker ` group.
20-
21- - The URL for your Coder instance. If you're running Coder locally, the default
22- URL is[ http://127.0.0.1:3000 ] ( http://127.0.0.1:3000 ) .
23-
24- - A text editor. For this tour, we use[ GNU nano] ( https://nano-editor.org/ ) .
10+ You'll need a computer or cloud computing instance with both
11+ [ Docker] ( https://docs.docker.com/get-docker/ ) and[ Coder] ( ../install/index.md )
12+ installed on it.
2513
2614##What's in a template
2715
@@ -37,22 +25,21 @@ started, or stopped.
3725> [ Getting Started Guides] ( https://developer.hashicorp.com/terraform/tutorials ) .
3826
3927Here's a simplified diagram that shows the main parts of the template we'll
40- create.
28+ create:
4129
4230![ Template architecture] ( ../images/templates/template-architecture.png )
4331
4432##1. Create template files
4533
4634On your local computer, create a directory for your template and create the
47- ` Dockerfile ` .
35+ ` Dockerfile ` . You will upload the files to your Coder instance later.
4836
4937``` sh
5038mkdir -p template-tour/build&& cd $_
51- nano Dockerfile
5239```
5340
54- You'll enter a simple ` Dockerfile ` that starts with the
55- [ official Ubuntu image] ( https://hub.docker.com/_/ubuntu/ ) . Inthe editor, enter
41+ Enter content into a ` Dockerfile ` that starts with the
42+ [ official Ubuntu image] ( https://hub.docker.com/_/ubuntu/ ) . Inyour editor, enter
5643and save the following text in` Dockerfile ` then exit the editor:
5744
5845``` dockerfile
@@ -72,22 +59,18 @@ USER ${USER}
7259WORKDIR /home/${USER}
7360```
7461
75- Notice how ` Dockerfile ` adds a few things to the parent` ubuntu ` image, which
76- your template needs later:
62+ ` Dockerfile ` adds a few things to the parent` ubuntu ` image, which your template
63+ needs later:
7764
7865- It installs the` sudo ` and` curl ` packages.
7966- It adds a` coder ` user, including a home directory.
8067
8168##2. Set up template providers
8269
83- Edit the Terraform file to provision the workspace's resources:
84-
85- ``` shell
86- nano main.tf
87- ```
70+ Edit the Terraform` main.tf ` file to provision the workspace's resources.
8871
89- We'll start by setting upour providers. At a minimum, we need the` coder `
90- provider. For this template, we also need the` docker ` provider:
72+ Start by setting upthe providers. At a minimum, we need the` coder ` provider.
73+ For this template, we also need the` docker ` provider:
9174
9275``` tf
9376terraform {
126109[ ` coder_workspace ` ] ( https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/workspace )
127110data source provides details about the state of a workspace, such as its name,
128111owner, and so on. The data source also lets us know when a workspace is being
129- started or stopped. We'lltake advantage of this information in later steps to:
112+ started or stopped. We'lluse this information in later steps to:
130113
131114- Set some environment variables based on the workspace owner.
132115- Manage ephemeral and persistent storage.
@@ -140,10 +123,9 @@ runs inside the compute aspect of your workspace, typically a VM or container.
140123In our case, it will run in Docker.
141124
142125You do not need to have any open ports on the compute aspect, but the agent
143- needs` curl ` access to the Coder server. Remember that we installed` curl ` in
144- ` Dockerfile ` , earlier.
126+ needs` curl ` access to the Coder server.
145127
146- Add this snippetbelow the last closing` } ` in` main.tf ` to create the agent:
128+ Add this snippetafter the last closing` } ` in` main.tf ` to create the agent:
147129
148130``` tf
149131resource "coder_agent" "main" {
@@ -184,29 +166,33 @@ resource "coder_agent" "main" {
184166
185167Because Docker is running locally in the Coder server, there is no need to
186168authenticate` coder_agent ` . But if your` coder_agent ` is running on a remote
187- host, your templatewould need
169+ host, your templatewill need
188170[ authentication credentials] ( ../admin/external-auth.md ) .
189171
190172This template's agent also runs a startup script, sets environment variables,
191173and provides metadata.
192174
193- The
194- [ ` startup script ` ] ( https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script )
195- installs[ code-server] ( https://coder.com/docs/code-server ) , a browser-based
196- [ VS Code] ( https://code.visualstudio.com/ ) app that runs in the workspace. We'll
197- give users access to code-server through` coder_app ` , later.
175+ - [ ` startup script ` ] ( https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script )
198176
199- The
200- [ ` env ` ] ( https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#env )
201- block sets environments variables for the workspace. We use the data source from
202- ` coder_workspace ` to set the environment variables based on the workspace's
203- owner. This way, the owner can make git commits immediately without any manual
204- configuration.
177+ - Installs[ code-server] ( https://coder.com/docs/code-server ) , a browser-based
178+ [ VS Code] ( https://code.visualstudio.com/ ) app that runs in the workspace.
179+
180+ We'll give users access to code-server through` coder_app ` , later.
181+
182+ - [ ` env ` block] ( https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#env )
183+
184+ - Sets environments variables for the workspace.
185+
186+ We use the data source from` coder_workspace ` to set the environment
187+ variables based on the workspace's owner. This way, the owner can make git
188+ commits immediately without any manual configuration.
205189
206- Your template can use metadata to show information to the workspace owner. Coder
207- displays this metadata in the Coder dashboard. Our template has
208- [ ` metadata ` ] ( ../admin/templates/extending-templates/agent-metadata.md ) blocks
209- for CPU and RAM usage.
190+ - [ ` metadata ` ] ( ../admin/templates/extending-templates/agent-metadata.md ) blocks
191+
192+ - Your template can use metadata to show information to the workspace owner
193+ Coder displays this metadata in the Coder dashboard.
194+
195+ Our template has` metadata ` blocks for CPU and RAM usage.
210196
211197##4. coder_app
212198
@@ -220,10 +206,9 @@ This is commonly used for
220206[ web IDEs] ( ../user-guides/workspace-access/web-ides.md ) such as
221207[ code-server] ( https://coder.com/docs/code-server ) , RStudio, and JupyterLab.
222208
223- To install code-server in the workspace, remember that we installed it in the
224- ` startup_script ` argument in` coder_agent ` . We make it available from a
225- workspace with a` coder_app ` resource. See
226- [ web IDEs] ( ../user-guides/workspace-access/web-ides.md ) for more examples.
209+ We installed code-server in the` startup_script ` argument. To add code-server to
210+ the workspace, make it available in the workspace with a` coder_app ` resource.
211+ See[ web IDEs] ( ../user-guides/workspace-access/web-ides.md ) for more examples:
227212
228213``` tf
229214resource "coder_app" "code-server" {
@@ -272,10 +257,9 @@ We do this in 2 parts:
272257 workspace name change, we use an immutable parameter, like
273258` data.coder_workspace.me.id ` .
274259
275- You'll see later that we make sure that our Docker container is ephemeral with
276- the Terraform
260+ Later, we use the Terraform
277261[ count] ( https://developer.hashicorp.com/terraform/language/meta-arguments/count )
278- meta-argument.
262+ meta-argument to make sure that our Docker container is ephemeral .
279263
280264``` tf
281265resource "docker_volume" "home_volume" {
@@ -345,57 +329,58 @@ Save `main.tf` and exit the editor.
345329Now that we've created the files for our template, we can add them to our Coder
346330deployment.
347331
348- We can do this with the Coder CLI or the Coder dashboard.For thistour , we'll
332+ We can do this with the Coder CLI or the Coder dashboard.In thisexample , we'll
349333use the Coder CLI.
350334
351- First, you'll need to log in to your Coder deployment from the CLI. This is
352- where you need the URL for your deployment:
335+ 1 . Log in to your Coder deployment from the CLI. This is where you need the URL
336+
353337
354- ``` sh
355- $ coder login https://coder.example.com
356- Your browser has been opened to visit:
338+ ``` console
339+
340+
357341
358- https://coder.example.com/cli-auth
342+
359343
360- > Paste your token here:
361- ```
344+
345+ ```
362346
363- In your web browser, enter your credentials:
347+ 1 .
364348
365- ![ Logging in to your Coder deployment] ( ../images/templates/coder-login-web.png )
349+ ![ Logging in to your Coder deployment] ( ../images/templates/coder-login-web.png )
366350
367- Copy the session token into the clipboard:
351+ 1 .
368352
369- ![ Logging in to your Coder deployment] ( ../images/templates/coder-session-token.png )
353+ ![ Logging in to your Coder deployment] ( ../images/templates/coder-session-token.png )
370354
371- And paste it into the CLI:
355+ 1 . Paste it into the CLI:
372356
373- ``` sh
374- > Welcome to Coder, marc! You' re authenticated.
375- $
376- ```
357+ ``` output
358+
359+
360+ ```
377361
378- Now you can add your template files to your Coder deployment:
362+ 1 . Add your template files to your Coder deployment:
379363
380- ```sh
381- $ pwd
382- /home/marc /template-tour
383- $ coder templates create
384- > Upload "."? (yes/no) yes
385- ```
364+ ``` console
365+
366+ docs /template-tour
367+
368+
369+ ```
386370
387- The Coder CLI tool gives progress information then prompts you to confirm:
371+ 1 .
388372
389- ```sh
390- > Confirm create? (yes/no) yes
373+ ``` console
374+
391375
392- The template-tour template has been created! Developers can provision a workspace with this template using:
376+
393377
394- coder create --template="template-tour" [workspace name]
395- ```
378+ coder create --template="template-tour" [workspace name]
379+ ```
380+
381+ 1 . In your web browser, log in to your Coder dashboard, select** Templates** .
396382
397- In your web browser, log in to your Coder dashboard, select **Templates**. Your
398- template is ready to use for new workspaces.
383+ Your template is ready to use for new workspaces.
399384
400385![ Your new template, ready to use] ( ../images/templates/template-tour.png )
401386