Skip to content

Commit de21393

Browse files
ammarioammario
authored
docs: expand dotfiles section (#2444)
1 parent 5354811 commit de21393

File tree

3 files changed

+70
-9
lines changed

3 files changed

+70
-9
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
@@ -35,7 +35,8 @@
3535
{
3636
"title": "Authentication & Secrets",
3737
"description": "Learn how to authenticate the provisioner",
38-
"path": "./templates/authentication.md"
38+
"path": "./templates/authentication.md",
39+
"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>"
3940
}
4041
]
4142
},
@@ -51,6 +52,12 @@
5152
"icon": "<svg viewBox=\"0 0 512 466\" xmlns=\"http://www.w3.org/2000/svg\">\n<path d=\"M46.5 0.837754C20.5 0.837754 0 22.3052 0 49.5321V122.94V196.348V221.062V245.776V270.489V343.898V417.306C0 444.533 20.5 466 46.5 466H256H465.5C491.5 466 512 444.533 512 417.306V343.898V244.205V195.511V122.102V48.6944C512 21.4674 491.5 0 465.5 0H256H46.5V0.837754Z\" />\n<path d=\"M70.1 73.1V99.1L140.2 140.1L70.1 181.1V207.1L186.7 140.1L70.1 73.1ZM185.9 186.5V210.1H302.5V186.5H185.9Z\" fill=\"white\" />\n</svg>",
5253
"path": "./ides.md"
5354
},
55+
{
56+
"title": "Dotfiles",
57+
"description": "Learn how to personalize your workspace",
58+
"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>",
59+
"path": "./dotfiles.md"
60+
},
5461
{
5562
"title": "Contributing",
5663
"description": "Learn how to contribute to Coder.",

‎docs/workspaces.md

+4-8
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.
@@ -58,4 +51,7 @@ coder update <workspace-name>
5851

5952
---
6053

61-
Next: [IDEs](./ides.md)
54+
## Up next
55+
56+
- Learn about how to personalize your workspace with [Dotfiles](./dotfiles.md)
57+
- Learn about using [IDEs](./ides.md)

0 commit comments

Comments
 (0)