example: add and document dotfiles usage (#2046)

docs/workspaces.md

@@ -65,6 +65,11 @@ 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.

examples/templates/docker-with-dotfiles/README.md

@@ -0,0 +1,38 @@
+---
+name: Develop in Docker with a dotfiles URL
+description: Run workspaces on a Docker host using registry images 
+tags: [local, docker]
+---
+
+# docker-with-dotfiles
+
+This is an example for deploying workspaces with a prompt for the users' dotfiles repo URI.
+
+## Getting started
+
+Run `coder templates init` and select this template. Follow the instructions that appear. 
+
+## How it works
+
+During workspace creation, Coder prompts you to specify a dotfiles URL via a Terraform variable. Once the workspace starts, the Coder agent runs `coder dotfiles` via the startup script:
+
+```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
+}
+```
+
+# Managing images and workspaces
+
+Refer to the documentation in the [Docker template](../docker/README.md).

examples/templates/docker-with-dotfiles/main.tf

@@ -0,0 +1,68 @@
+# Note: this example demonstrates the use of
+# dotfiles with Coder templates.
+
+# The Docker aspect of the template only works
+# with MacOS/Linux amd64 systems. See the full
+# Docker example for details
+
+terraform {
+  required_providers {
+    coder = {
+      source  = "coder/coder"
+      version = "0.4.1"
+    }
+    docker = {
+      source  = "kreuzwerker/docker"
+      version = "~> 2.16.0"
+    }
+  }
+}
+
+provider "docker" {
+  host = "unix:///var/run/docker.sock"
+}
+
+provider "coder" {
+}
+
+data "coder_workspace" "me" {
+}
+
+variable "dotfiles_uri" {
+  description = <<-EOF
+  Dotfiles repo URI (optional)
+
+  see https://dotfiles.github.io
+  EOF
+  default     = ""
+}
+
+resource "coder_agent" "dev" {
+  arch           = "amd64"
+  os             = "linux"
+  startup_script = var.dotfiles_uri != "" ? "coder dotfiles -y ${var.dotfiles_uri}" : null
+}
+
+resource "docker_volume" "home_volume" {
+  name = "coder-${data.coder_workspace.me.owner}-${data.coder_workspace.me.name}-root"
+}
+
+resource "docker_container" "workspace" {
+  count = data.coder_workspace.me.start_count
+  image = "codercom/enterprise-base:ubuntu"
+  # Uses lower() to avoid Docker restriction on container names.
+  name = "coder-${data.coder_workspace.me.owner}-${lower(data.coder_workspace.me.name)}"
+  dns  = ["1.1.1.1"]
+  # Refer to Docker host when Coder is on localhost
+  command = ["sh", "-c", replace(coder_agent.dev.init_script, "127.0.0.1", "host.docker.internal")]
+  env     = ["CODER_AGENT_TOKEN=${coder_agent.dev.token}"]
+  host {
+    host = "host.docker.internal"
+    ip   = "host-gateway"
+  }
+  volumes {
+    container_path = "/home/coder/"
+    volume_name    = docker_volume.home_volume.name
+    read_only      = false
+  }
+}