Skip to content

Commit fe2e370

Browse files
ammarioammario
committed
docs: expand dotfiles section
1 parent 0c9ff3a commit fe2e370

File tree

3 files changed

+70
-8
lines changed

3 files changed

+70
-8
lines changed

‎docs/dotfiles.md

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Dotfiles
2+
3+
Coder offers the `coder dotfiles <repo>` command which simplifies workspace
4+
personalization. Our behavior is consistent with Codespaces, so
5+
[their documentation](https://docs.github.com/en/codespaces/customizing-your-codespace/personalizing-codespaces-for-your-account#dotfiles)
6+
explains how it loads your repo.
7+
8+
You can read more on dotfiles best practices [here](https://dotfiles.github.io).
9+
10+
## Templates
11+
12+
Templates can prompt users for their dotfiles repo using the following pattern:
13+
14+
```hcl
15+
variable "dotfiles_uri" {
16+
description = <<-EOF
17+
Dotfiles repo URI (optional)
18+
19+
see https://dotfiles.github.io
20+
EOF
21+
# The codercom/enterprise-* images are only built for amd64
22+
default = ""
23+
}
24+
25+
resource "coder_agent" "dev" {
26+
...
27+
startup_script = var.dotfiles_uri != "" ? "/tmp/tmp.coder*/coder dotfiles -y ${var.dotfiles_uri}" : null
28+
}
29+
```
30+
31+
[Here's a complete example.](https://github.com/coder/coder/tree/main/examples/templates/docker-with-dotfiles#how-it-works)
32+
33+
## Persistent Home
34+
35+
Sometimes you wants to support personalization without
36+
requiring dotfiles.
37+
38+
In such cases:
39+
40+
- Mount a persistent volume to the `/home` directory
41+
- Set the `startup_script` to call a `~/personalize` script that the user can edit
42+
43+
```hcl
44+
resource "coder_agent" "dev" {
45+
...
46+
startup_script = "/home/coder/personalize"
47+
}
48+
```
49+
50+
The user can even fill `personalize` with `coder dotfiles <repo>`, but those
51+
looking for a simpler approach can inline commands like so:
52+
53+
```bash
54+
#!/bin/bash
55+
sudo apt update
56+
# Install some of my favorite tools every time my workspace boots
57+
sudo apt install -y neovim fish cargo
58+
```

‎docs/manifest.json

+8-1
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,8 @@
2828
{
2929
"title": "Authentication & Secrets",
3030
"description": "Learn how to authenticate the provisioner",
31-
"path": "./templates/authentication.md"
31+
"path": "./templates/authentication.md",
32+
"icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" height=\"24\" viewBox=\"0 0 24 24\" width=\"24\"><path d=\"M0 0h24v24H0z\" fill=\"none\"/><path d=\"M18 8h-1V6c0-2.76-2.24-5-5-5S7 3.24 7 6v2H6c-1.1 0-2 .9-2 2v10c0 1.1.9 2 2 2h12c1.1 0 2-.9 2-2V10c0-1.1-.9-2-2-2zm-6 9c-1.1 0-2-.9-2-2s.9-2 2-2 2 .9 2 2-.9 2-2 2zm3.1-9H8.9V6c0-1.71 1.39-3.1 3.1-3.1 1.71 0 3.1 1.39 3.1 3.1v2z\"/></svg>"
3233
}
3334
]
3435
},
@@ -38,6 +39,12 @@
3839
"icon": "<svg viewBox=\"0 0 16 16\" xmlns=\"http://www.w3.org/2000/svg\">\n<path d=\"M7.6 0.0984375L0.4 3.49844C0.2 3.59844 0.2 3.89844 0.4 3.99844L7.7 7.29844C7.9 7.39844 8.2 7.39844 8.4 7.29844L15.6 3.99844C15.8 3.89844 15.8 3.59844 15.6 3.49844L8.4 0.0984375C8.1 -0.0015625 7.9 -0.0015625 7.6 0.0984375Z\" />\n<path d=\"M15.6 7.79844L14.1 7.09844C13.9 6.99844 13.6 6.99844 13.4 7.09844L8.3 9.39844C8.1 9.49844 7.8 9.49844 7.6 9.39844L2.6 7.09844C2.3 6.99844 2.1 6.99844 1.9 7.09844L0.4 7.79844C0.2 7.89844 0.2 8.19844 0.4 8.29844L7.7 11.5984C7.9 11.6984 8.2 11.6984 8.4 11.5984L15.7 8.29844C15.8 8.19844 15.8 7.89844 15.6 7.79844Z\" />\n<path d=\"M15.5984 12.0984L14.0984 11.3984C13.8984 11.2984 13.5984 11.2984 13.3984 11.3984L8.29844 13.6984C8.09844 13.7984 7.79844 13.7984 7.59844 13.6984L2.49844 11.3984C2.29844 11.2984 1.99844 11.2984 1.79844 11.3984L0.298438 12.0984C0.0984375 12.1984 0.0984375 12.4984 0.298438 12.5984L7.59844 15.8984C7.79844 15.9984 8.09844 15.9984 8.29844 15.8984L15.5984 12.5984C15.7984 12.4984 15.7984 12.1984 15.5984 12.0984Z\"/></svg>",
3940
"path": "./workspaces.md"
4041
},
42+
{
43+
"title": "Dotfiles",
44+
"description": "Learn how to personalize your workspace",
45+
"icon": "<svg xmlns=\"http:\/\/www.w3.org\/2000\/svg\" enable-background=\"new 0 0 24 24\" height=\"24\" viewBox=\"0 0 24 24\" width=\"24\"><g><rect fill=\"none\" height=\"24\" width=\"24\"\/><\/g><g><path d=\"M12,2C6.49,2,2,6.49,2,12s4.49,10,10,10c1.38,0,2.5-1.12,2.5-2.5c0-0.61-0.23-1.2-0.64-1.67c-0.08-0.1-0.13-0.21-0.13-0.33 c0-0.28,0.22-0.5,0.5-0.5H16c3.31,0,6-2.69,6-6C22,6.04,17.51,2,12,2z M17.5,13c-0.83,0-1.5-0.67-1.5-1.5c0-0.83,0.67-1.5,1.5-1.5 s1.5,0.67,1.5,1.5C19,12.33,18.33,13,17.5,13z M14.5,9C13.67,9,13,8.33,13,7.5C13,6.67,13.67,6,14.5,6S16,6.67,16,7.5 C16,8.33,15.33,9,14.5,9z M5,11.5C5,10.67,5.67,10,6.5,10S8,10.67,8,11.5C8,12.33,7.33,13,6.5,13S5,12.33,5,11.5z M11,7.5 C11,8.33,10.33,9,9.5,9S8,8.33,8,7.5C8,6.67,8.67,6,9.5,6S11,6.67,11,7.5z\"\/><\/g><\/svg>",
46+
"path": "./dotfiles.md"
47+
},
4148
{
4249
"title": "Contributing",
4350
"description": "Learn how to contribute to Coder.",

‎docs/workspaces.md

+4-7
Original file line numberDiff line numberDiff line change
@@ -40,13 +40,6 @@ resources](./templates.md#persistent-and-ephemeral-resources).
4040
4141
When a workspace is deleted, all of the workspace's resources are deleted.
4242

43-
## Dotfiles
44-
45-
Users can install configuration from a personal [dotfiles
46-
repository](https://dotfiles.github.io) with the `coder dotfiles <repo>` command
47-
in their workspace. Templates can also prompt users for their dotfiles repo
48-
[(example)](../examples/templates/docker-with-dotfiles/README.md#how-it-works).
49-
5043
## Updating workspaces
5144

5245
Use the following command to update a workspace to the latest template version.
@@ -55,3 +48,7 @@ The workspace will be stopped and started:
5548
```sh
5649
coder update <workspace-name>
5750
```
51+
52+
## Up next
53+
54+
- Learn about how to personalize your workspace with [Dotfiles](./dotfiles.md)

0 commit comments

Comments
 (0)