From 555cbd78d4ec4298a38aa7b75ce31715891dd6bd Mon Sep 17 00:00:00 2001 From: ammario Date: Thu, 16 Jun 2022 22:42:41 +0000 Subject: [PATCH] docs: expand dotfiles section --- docs/dotfiles.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++ docs/manifest.json | 9 ++++++- docs/workspaces.md | 12 ++++------ 3 files changed, 70 insertions(+), 9 deletions(-) create mode 100644 docs/dotfiles.md diff --git a/docs/dotfiles.md b/docs/dotfiles.md new file mode 100644 index 0000000000000..08ff48f0bcd08 --- /dev/null +++ b/docs/dotfiles.md @@ -0,0 +1,58 @@ +# Dotfiles + +Coder offers the `coder dotfiles ` 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 `, 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 index 8d82de7a93b24..a1cd32e1ccfc9 100644 --- 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": "" } ] }, @@ -51,6 +52,12 @@ "icon": "\n\n\n", "path": "./ides.md" }, + { + "title": "Dotfiles", + "description": "Learn how to personalize your workspace", + "icon": "<\/g><\/g><\/svg>", + "path": "./dotfiles.md" + }, { "title": "Contributing", "description": "Learn how to contribute to Coder.", diff --git a/docs/workspaces.md b/docs/workspaces.md index 5e3a7a8f20eaa..a445cd6d1fd53 100644 --- 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 ` 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 --- -Next: [IDEs](./ides.md) +## Up next + +- Learn about how to personalize your workspace with [Dotfiles](./dotfiles.md) +- Learn about using [IDEs](./ides.md)