coder · ammario · Jun 16, 2022 · Jun 16, 2022
diff --git a/docs/dotfiles.md b/docs/dotfiles.md
@@ -0,0 +1,58 @@
+# Dotfiles
+
+Coder offers the `coder dotfiles <repo>` command which simplifies workspace
+personalization. Our behavior is consistent with Codespaces, so
+[their documentation](https://docs.github.com/en/codespaces/customizing-your-codespace/personalizing-codespaces-for-your-account#dotfiles)
+explains how it loads your repo.
+
+You can read more on dotfiles best practices [here](https://dotfiles.github.io).
+
+## Templates
+
+Templates can prompt users for their dotfiles repo using the following pattern:
+
+```hcl
+variable "dotfiles_uri" {
+  description = <<-EOF
+  Dotfiles repo URI (optional)
+
+  see https://dotfiles.github.io
+  EOF
+    # The codercom/enterprise-* images are only built for amd64
+  default = ""
+}
+
+resource "coder_agent" "dev" {
+  ...
+  startup_script = var.dotfiles_uri != "" ? "/tmp/tmp.coder*/coder dotfiles -y ${var.dotfiles_uri}" : null
+}
+```
+
+[Here's a complete example.](https://github.com/coder/coder/tree/main/examples/templates/docker-with-dotfiles#how-it-works)
+
+## Persistent Home
+
+Sometimes you wants to support personalization without
+requiring dotfiles.
+
+In such cases:
+
+- Mount a persistent volume to the `/home` directory
+- Set the `startup_script` to call a `~/personalize` script that the user can edit
+
+```hcl
+resource "coder_agent" "dev" {
+  ...
+  startup_script = "/home/coder/personalize"
+}
+```
+
+The user can even fill `personalize` with `coder dotfiles <repo>`, but those
+looking for a simpler approach can inline commands like so:
+
+```bash
+#!/bin/bash
+sudo apt update
+# Install some of my favorite tools every time my workspace boots
+sudo apt install -y neovim fish cargo
+```
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -35,7 +35,8 @@
             {
               "title": "Authentication & Secrets",
               "description": "Learn how to authenticate the provisioner",
-              "path": "./templates/authentication.md"
+              "path": "./templates/authentication.md",
+              "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>"
             }
           ]
     },
@@ -51,6 +52,12 @@
       "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>",
       "path": "./ides.md"
     },
+    {
+      "title": "Dotfiles",
+      "description": "Learn how to personalize your workspace",
+      "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>",
+      "path": "./dotfiles.md"
+    },
     {
       "title": "Contributing",
       "description": "Learn how to contribute to Coder.",

diff --git a/docs/workspaces.md b/docs/workspaces.md
@@ -40,13 +40,6 @@ resources](./templates.md#persistent-and-ephemeral-resources).
 
 When a workspace is deleted, all of the workspace's resources are deleted.
 
-## Dotfiles
-
-Users can install configuration from a personal [dotfiles
-repository](https://dotfiles.github.io) with the `coder dotfiles <repo>` command
-in their workspace. Templates can also prompt users for their dotfiles repo
-[(example)](../examples/templates/docker-with-dotfiles/README.md#how-it-works).
-
 ## Updating workspaces
 
 Use the following command to update a workspace to the latest template version.
@@ -58,4 +51,7 @@ coder update <workspace-name>
 
 ---
 
-Next: [IDEs](./ides.md)
+## Up next
+
+- Learn about how to personalize your workspace with [Dotfiles](./dotfiles.md)
+- Learn about using [IDEs](./ides.md)