selfhosted
/
coder
mirror of https://github.com/coder/coder.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: improve structure for example templates (#9842) 

Co-authored-by: Kyle Carberry <kyle@carberry.com>
Co-authored-by: Muhammad Atif Ali <atif@coder.com>
Co-authored-by: Muhammad Atif Ali <me@matifali.dev>
This commit is contained in:
Ben Potter 2023-12-17 08:05:13 -06:00 committed by GitHub
parent 3f6096b0d7
commit 2e86b76fb8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
38 changed files with 473 additions and 1343 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
cli/testdata/coder_templates_init_--help.golden vendored
View File

@ -6,7 +6,7 @@ USAGE:
Get started with a templated template.
OPTIONS:
--id aws-ecs-container|aws-linux|aws-windows|azure-linux|do-linux|docker|docker-with-dotfiles|gcp-linux|gcp-vm-container|gcp-windows|kubernetes|nomad-docker
--id aws-linux|aws-windows|azure-linux|do-linux|docker|gcp-linux|gcp-vm-container|gcp-windows|kubernetes|nomad-docker
Specify a given example template by ID.
———

6
docs/cli/templates_init.md generated
View File

@ -14,8 +14,8 @@ coder templates init [flags] [directory]
### --id
| | |
| ---- | ---------------------------- | --------- | ----------- | ----------- | -------- | ------ | -------------------- | --------- | ---------------- | ----------- | ---------- | -------------------- |
| Type | <code>enum[aws-ecs-container | aws-linux | aws-windows | azure-linux | do-linux | docker | docker-with-dotfiles | gcp-linux | gcp-vm-container | gcp-windows | kubernetes | nomad-docker]</code> |
| | |
| ---- | -------------------- | ----------- | ----------- | -------- | ------ | --------- | ---------------- | ----------- | ---------- | -------------------- |
| Type | <code>enum[aws-linux | aws-windows | azure-linux | do-linux | docker | gcp-linux | gcp-vm-container | gcp-windows | kubernetes | nomad-docker]</code> |
Specify a given example template by ID.

2
docs/dotfiles.md
View File

@ -32,8 +32,6 @@ resource "coder_agent" "main" {
}
```
[Here's a complete example.](https://github.com/coder/coder/tree/main/examples/templates/docker-with-dotfiles#how-it-works)
## Persistent Home
Sometimes you want to support personalization without requiring dotfiles.

4
docs/platforms/jfrog.md
View File

@ -8,7 +8,7 @@ within a workspace. We'll use Docker as the underlying compute. But, these
concepts apply to any compute platform.
The full example template can be found
[here](https://github.com/coder/coder/tree/main/examples/templates/jfrog/docker).
[here](https://github.com/coder/coder/tree/main/examples/jfrog/docker).
## Requirements
@ -249,7 +249,7 @@ for more information.
## More reading
- See the full example template
[here](https://github.com/coder/coder/tree/main/examples/templates/jfrog/docker).
[here](https://github.com/coder/coder/tree/main/examples/jfrog/docker).
- To serve extensions from your own VS Code Marketplace, check out
[code-marketplace](https://github.com/coder/code-marketplace#artifactory-storage).
- To store templates in Artifactory, check out our

4
docs/templates/docker-in-workspaces.md vendored
View File

@ -253,8 +253,8 @@ Before using Podman, please review the following documentation:
3. For systems running SELinux (typically Fedora-, CentOS-, and Red Hat-based
systems), you might need to disable SELinux or set it to permissive mode.
4. Import our
[kubernetes-with-podman](https://github.com/coder/coder/tree/main/examples/templates/kubernetes-with-podman)
4. Use this
[kubernetes-with-podman](https://github.com/coder/community-templates/tree/main/kubernetes-podman)
example template, or make your own.
```shell

130
examples/examples.gen.json
View File

@ -1,149 +1,131 @@
// Code generated by examplegen. DO NOT EDIT.
[
{
"id": "aws-ecs-container",
"url": "",
"name": "Develop in an ECS-hosted container",
"description": "Get started with Linux development on AWS ECS.",
"icon": "/icon/aws.png",
"tags": [
"cloud",
"aws"
],
"markdown": "\n# aws-ecs\n\nThis is a sample template for running a Coder workspace on ECS. It assumes there\nis a pre-existing ECS cluster with EC2-based compute to host the workspace.\n\n## Architecture\n\nThis workspace is built using the following AWS resources:\n\n- Task definition - the container definition, includes the image, command, volume(s)\n- ECS service - manages the task definition\n\n## code-server\n\n`code-server` is installed via the `startup_script` argument in the `coder_agent`\nresource block. The `coder_app` resource is defined to access `code-server` through\nthe dashboard UI over `localhost:13337`.\n"
},
{
"id": "aws-linux",
"url": "",
"name": "Develop in Linux on AWS EC2",
"description": "Get started with Linux development on AWS EC2.",
"name": "AWS EC2 (Linux)",
"description": "Provision AWS EC2 VMs as Coder workspaces",
"icon": "/icon/aws.png",
"tags": [
"cloud",
"aws"
"vm",
"linux",
"aws",
"persistent-vm"
],
"markdown": "\n# aws-linux\n\nTo get started, run `coder templates init`. When prompted, select this template.\nFollow the on-screen instructions to proceed.\n\n## Authentication\n\nThis template assumes that coderd is run in an environment that is authenticated\nwith AWS. For example, run `aws configure import` to import credentials on the\nsystem and user running coderd. For other ways to authenticate [consult the\nTerraform docs](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration).\n\n## Required permissions / policy\n\nThe following sample policy allows Coder to create EC2 instances and modify\ninstances provisioned by Coder:\n\n```json\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Sid\": \"VisualEditor0\",\n \"Effect\": \"Allow\",\n \"Action\": [\n \"ec2:GetDefaultCreditSpecification\",\n \"ec2:DescribeIamInstanceProfileAssociations\",\n \"ec2:DescribeTags\",\n \"ec2:DescribeInstances\",\n \"ec2:DescribeInstanceTypes\",\n \"ec2:CreateTags\",\n \"ec2:RunInstances\",\n \"ec2:DescribeInstanceCreditSpecifications\",\n \"ec2:DescribeImages\",\n \"ec2:ModifyDefaultCreditSpecification\",\n \"ec2:DescribeVolumes\"\n ],\n \"Resource\": \"*\"\n },\n {\n \"Sid\": \"CoderResources\",\n \"Effect\": \"Allow\",\n \"Action\": [\n \"ec2:DescribeInstanceAttribute\",\n \"ec2:UnmonitorInstances\",\n \"ec2:TerminateInstances\",\n \"ec2:StartInstances\",\n \"ec2:StopInstances\",\n \"ec2:DeleteTags\",\n \"ec2:MonitorInstances\",\n \"ec2:CreateTags\",\n \"ec2:RunInstances\",\n \"ec2:ModifyInstanceAttribute\",\n \"ec2:ModifyInstanceCreditSpecification\"\n ],\n \"Resource\": \"arn:aws:ec2:*:*:instance/*\",\n \"Condition\": {\n \"StringEquals\": {\n \"aws:ResourceTag/Coder_Provisioned\": \"true\"\n }\n }\n }\n ]\n}\n```\n\n## code-server\n\n`code-server` is installed via the `startup_script` argument in the `coder_agent`\nresource block. The `coder_app` resource is defined to access `code-server` through\nthe dashboard UI over `localhost:13337`.\n"
"markdown": "\n# Remote Development on AWS EC2 VMs (Linux)\n\nProvision AWS EC2 VMs as [Coder workspaces](https://coder.com/docs/coder-v2/latest) with this example template.\n\n\u003c!-- TODO: Add screenshot --\u003e\n\n## Prerequisites\n\n### Authentication\n\nBy default, this template authenticates to AWS using the provider's default [authentication methods](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration).\n\nThe simplest way (without making changes to the template) is via environment variables (e.g. `AWS_ACCESS_KEY_ID`) or a [credentials file](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-format). If you are running Coder on a VM, this file must be in `/home/coder/aws/credentials`.\n\nTo use another [authentication method](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication), edit the template.\n\n## Required permissions / policy\n\nThe following sample policy allows Coder to create EC2 instances and modify\ninstances provisioned by Coder:\n\n```json\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Sid\": \"VisualEditor0\",\n \"Effect\": \"Allow\",\n \"Action\": [\n \"ec2:GetDefaultCreditSpecification\",\n \"ec2:DescribeIamInstanceProfileAssociations\",\n \"ec2:DescribeTags\",\n \"ec2:DescribeInstances\",\n \"ec2:DescribeInstanceTypes\",\n \"ec2:CreateTags\",\n \"ec2:RunInstances\",\n \"ec2:DescribeInstanceCreditSpecifications\",\n \"ec2:DescribeImages\",\n \"ec2:ModifyDefaultCreditSpecification\",\n \"ec2:DescribeVolumes\"\n ],\n \"Resource\": \"*\"\n },\n {\n \"Sid\": \"CoderResources\",\n \"Effect\": \"Allow\",\n \"Action\": [\n \"ec2:DescribeInstanceAttribute\",\n \"ec2:UnmonitorInstances\",\n \"ec2:TerminateInstances\",\n \"ec2:StartInstances\",\n \"ec2:StopInstances\",\n \"ec2:DeleteTags\",\n \"ec2:MonitorInstances\",\n \"ec2:CreateTags\",\n \"ec2:RunInstances\",\n \"ec2:ModifyInstanceAttribute\",\n \"ec2:ModifyInstanceCreditSpecification\"\n ],\n \"Resource\": \"arn:aws:ec2:*:*:instance/*\",\n \"Condition\": {\n \"StringEquals\": {\n \"aws:ResourceTag/Coder_Provisioned\": \"true\"\n }\n }\n }\n ]\n}\n```\n\n## Architecture\n\nThis template provisions the following resources:\n\n- AWS Instance\n\nCoder uses `aws_ec2_instance_state` to start and stop the VM. This example template is fully persistent, meaning the full filesystem is preserved when the workspace restarts. See this [community example](https://github.com/bpmct/coder-templates/tree/main/aws-linux-ephemeral) of an ephemeral AWS instance.\n\n\u003e **Note**\n\u003e This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.\n\n## code-server\n\n`code-server` is installed via the `startup_script` argument in the `coder_agent`\nresource block. The `coder_app` resource is defined to access `code-server` through\nthe dashboard UI over `localhost:13337`.\n"
},
{
"id": "aws-windows",
"url": "",
"name": "Develop in Windows on AWS",
"description": "Get started with Windows development on AWS.",
"name": "AWS EC2 (Windows)",
"description": "Provision AWS EC2 VMs as Coder workspaces",
"icon": "/icon/aws.png",
"tags": [
"cloud",
"vm",
"windows",
"aws"
],
"markdown": "\n# aws-windows\n\n## Getting started\n\nTo get started, run `coder templates init`. When prompted, select this template.\nFollow the on-screen instructions to proceed.\n\n## Authentication\n\nThis template assumes that coderd is run in an environment that is authenticated\nwith AWS. For example, run `aws configure import` to import credentials on the\nsystem and user running coderd. For other ways to authenticate [consult the\nTerraform docs](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration).\n\n## Required permissions / policy\n\nThe following sample policy allows Coder to create EC2 instances and modify\ninstances provisioned by Coder:\n\n```json\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Sid\": \"VisualEditor0\",\n \"Effect\": \"Allow\",\n \"Action\": [\n \"ec2:GetDefaultCreditSpecification\",\n \"ec2:DescribeIamInstanceProfileAssociations\",\n \"ec2:DescribeTags\",\n \"ec2:DescribeInstances\",\n \"ec2:DescribeInstanceTypes\",\n \"ec2:CreateTags\",\n \"ec2:RunInstances\",\n \"ec2:DescribeInstanceCreditSpecifications\",\n \"ec2:DescribeImages\",\n \"ec2:ModifyDefaultCreditSpecification\",\n \"ec2:DescribeVolumes\"\n ],\n \"Resource\": \"*\"\n },\n {\n \"Sid\": \"CoderResources\",\n \"Effect\": \"Allow\",\n \"Action\": [\n \"ec2:DescribeInstanceAttribute\",\n \"ec2:UnmonitorInstances\",\n \"ec2:TerminateInstances\",\n \"ec2:StartInstances\",\n \"ec2:StopInstances\",\n \"ec2:DeleteTags\",\n \"ec2:MonitorInstances\",\n \"ec2:CreateTags\",\n \"ec2:RunInstances\",\n \"ec2:ModifyInstanceAttribute\",\n \"ec2:ModifyInstanceCreditSpecification\"\n ],\n \"Resource\": \"arn:aws:ec2:*:*:instance/*\",\n \"Condition\": {\n \"StringEquals\": {\n \"aws:ResourceTag/Coder_Provisioned\": \"true\"\n }\n }\n }\n ]\n}\n```\n"
"markdown": "\n# Remote Development on AWS EC2 VMs (Windows)\n\nProvision AWS EC2 VMs as [Coder workspaces](https://coder.com/docs/coder-v2/latest) with this example template.\n\n\u003c!-- TODO: Add screenshot --\u003e\n\n## Prerequisites\n\n### Authentication\n\nBy default, this template authenticates to AWS with using the provider's default [authentication methods](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration).\n\nThe simplest way (without making changes to the template) is via environment variables (e.g. `AWS_ACCESS_KEY_ID`) or a [credentials file](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-format). If you are running Coder on a VM, this file must be in `/home/coder/aws/credentials`.\n\nTo use another [authentication method](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication), edit the template.\n\n## Required permissions / policy\n\nThe following sample policy allows Coder to create EC2 instances and modify\ninstances provisioned by Coder:\n\n```json\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Sid\": \"VisualEditor0\",\n \"Effect\": \"Allow\",\n \"Action\": [\n \"ec2:GetDefaultCreditSpecification\",\n \"ec2:DescribeIamInstanceProfileAssociations\",\n \"ec2:DescribeTags\",\n \"ec2:DescribeInstances\",\n \"ec2:DescribeInstanceTypes\",\n \"ec2:CreateTags\",\n \"ec2:RunInstances\",\n \"ec2:DescribeInstanceCreditSpecifications\",\n \"ec2:DescribeImages\",\n \"ec2:ModifyDefaultCreditSpecification\",\n \"ec2:DescribeVolumes\"\n ],\n \"Resource\": \"*\"\n },\n {\n \"Sid\": \"CoderResources\",\n \"Effect\": \"Allow\",\n \"Action\": [\n \"ec2:DescribeInstanceAttribute\",\n \"ec2:UnmonitorInstances\",\n \"ec2:TerminateInstances\",\n \"ec2:StartInstances\",\n \"ec2:StopInstances\",\n \"ec2:DeleteTags\",\n \"ec2:MonitorInstances\",\n \"ec2:CreateTags\",\n \"ec2:RunInstances\",\n \"ec2:ModifyInstanceAttribute\",\n \"ec2:ModifyInstanceCreditSpecification\"\n ],\n \"Resource\": \"arn:aws:ec2:*:*:instance/*\",\n \"Condition\": {\n \"StringEquals\": {\n \"aws:ResourceTag/Coder_Provisioned\": \"true\"\n }\n }\n }\n ]\n}\n```\n\n## Architecture\n\nThis template provisions the following resources:\n\n- AWS Instance\n\nCoder uses `aws_ec2_instance_state` to start and stop the VM. This example template is fully persistent, meaning the full filesystem is preserved when the workspace restarts. See this [community example](https://github.com/bpmct/coder-templates/tree/main/aws-linux-ephemeral) of an ephemeral AWS instance.\n\n\u003e **Note**\n\u003e This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.\n\n## code-server\n\n`code-server` is installed via the `startup_script` argument in the `coder_agent`\nresource block. The `coder_app` resource is defined to access `code-server` through\nthe dashboard UI over `localhost:13337`.\n"
},
{
"id": "azure-linux",
"url": "",
"name": "Develop in Linux on Azure",
"description": "Get started with Linux development on Microsoft Azure.",
"name": "Azure VM (Linux)",
"description": "Provision Azure VMs as Coder workspaces",
"icon": "/icon/azure.png",
"tags": [
"cloud",
"azure",
"linux"
"vm",
"linux",
"azure"
],
"markdown": "\n# azure-linux\n\nTo get started, run `coder templates init`. When prompted, select this template.\nFollow the on-screen instructions to proceed.\n\n## Authentication\n\nThis template assumes that coderd is run in an environment that is authenticated\nwith Azure. For example, run `az login` then `az account set --subscription=\u003cid\u003e`\nto import credentials on the system and user running coderd. For other ways to\nauthenticate [consult the Terraform docs](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs#authenticating-to-azure).\n"
"markdown": "\n# Remote Development on Azure VMs (Linux)\n\nProvision AWS EC2 VMs as [Coder workspaces](https://coder.com/docs/coder-v2/latest) with this example template.\n\n\u003c!-- TODO: Add screenshot --\u003e\n\n## Prerequisites\n\n### Authentication\n\nThis template assumes that coderd is run in an environment that is authenticated\nwith Azure. For example, run `az login` then `az account set --subscription=\u003cid\u003e`\nto import credentials on the system and user running coderd. For other ways to\nauthenticate, [consult the Terraform docs](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs#authenticating-to-azure).\n\n## Architecture\n\nThis template provisions the following resources:\n\n- Azure VM (ephemeral, deleted on stop)\n- Managed disk (persistent, mounted to `/home/coder`)\n\nThis means, when the workspace restarts, any tools or files outside of the home directory are not persisted. To pre-bake tools into the workspace (e.g. `python3`), modify the VM image, or use a [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script). Alternatively, individual developers can [personalize](https://coder.com/docs/v2/latest/dotfiles) their workspaces with dotfiles.\n\n\u003e **Note**\n\u003e This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.\n\n## code-server\n\n`code-server` is installed via the `startup_script` argument in the `coder_agent`\nresource block. The `coder_app` resource is defined to access `code-server` through\nthe dashboard UI over `localhost:13337`.\n"
},
{
"id": "do-linux",
"url": "",
"name": "Develop in Linux on a Digital Ocean Droplet",
"description": "Get started with Linux development on a Digital Ocean Droplet.",
"name": "DigitalOcean Droplet (Linux)",
"description": "Provision DigitalOcean Droplets as Coder workspaces",
"icon": "/icon/do.png",
"tags": [
"cloud",
"vm",
"linux",
"digitalocean"
],
"markdown": "\n# do-linux\n\nTo deploy workspaces as DigitalOcean Droplets, you'll need:\n\n- DigitalOcean [personal access token\n (PAT)](https://docs.digitalocean.com/reference/api/create-personal-access-token/)\n\n- DigitalOcean project ID (you can get your project information via the `doctl`\n CLI by running `doctl projects list`)\n\n - Remove the following sections from the `main.tf` file if you don't want to\n associate your workspaces with a project:\n\n - `variable \"step2_do_project_id\"`\n - `resource \"digitalocean_project_resources\" \"project\"`\n\n- **Optional:** DigitalOcean SSH key ID (obtain via the `doctl` CLI by running\n `doctl compute ssh-key list`)\n\n - Note that this is only required for Fedora images to work.\n\n## Authentication\n\nThis template assumes that coderd is run in an environment that is authenticated\nwith Digital Ocean. Obtain a [Digital Ocean Personal Access\nToken](https://cloud.digitalocean.com/account/api/tokens) and set the\nenvironment variable `DIGITALOCEAN_TOKEN` to the access token before starting\ncoderd. For other ways to authenticate [consult the Terraform\ndocs](https://registry.terraform.io/providers/digitalocean/digitalocean/latest/docs).\n"
"markdown": "\n# Remote Development on DigitalOcean Droplets\n\nProvision DigitalOcean Droplets as [Coder workspaces](https://coder.com/docs/coder-v2/latest) with this example template.\n\n\u003c!-- TODO: Add screenshot --\u003e\n\n## Prerequisites\n\nTo deploy workspaces as DigitalOcean Droplets, you'll need:\n\n- DigitalOcean [personal access token (PAT)](https://docs.digitalocean.com/reference/api/create-personal-access-token/)\n\n- DigitalOcean project ID (you can get your project information via the `doctl`\n CLI by running `doctl projects list`)\n\n- Remove the following sections from the `main.tf` file if you don't want to\n associate your workspaces with a project:\n\n - `variable \"step2_do_project_id\"`\n - `resource \"digitalocean_project_resources\" \"project\"`\n\n- **Optional:** DigitalOcean SSH key ID (obtain via the `doctl` CLI by running\n `doctl compute ssh-key list`)\n\n- Note that this is only required for Fedora images to work.\n\n### Authentication\n\nThis template assumes that coderd is run in an environment that is authenticated\nwith Digital Ocean. Obtain a [Digital Ocean Personal Access\nToken](https://cloud.digitalocean.com/account/api/tokens) and set the\nenvironment variable `DIGITALOCEAN_TOKEN` to the access token before starting\ncoderd. For other ways to authenticate [consult the Terraform docs](https://registry.terraform.io/providers/digitalocean/digitalocean/latest/docs).\n\n## Architecture\n\nThis template provisions the following resources:\n\n- Azure VM (ephemeral, deleted on stop)\n- Managed disk (persistent, mounted to `/home/coder`)\n\nThis means, when the workspace restarts, any tools or files outside of the home directory are not persisted. To pre-bake tools into the workspace (e.g. `python3`), modify the VM image, or use a [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script).\n\n\u003e **Note**\n\u003e This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.\n"
},
{
"id": "docker",
"url": "",
"name": "Develop in Docker",
"description": "Develop inside Docker containers using your local daemon",
"name": "Docker Containers",
"description": "Provision Docker containers as Coder workspaces",
"icon": "/icon/docker.png",
"tags": [
"local",
"docker"
"docker",
"container"
],
"markdown": "\n# docker\n\nTo get started, run `coder templates init`. When prompted, select this template.\nFollow the on-screen instructions to proceed.\n\n## Editing the image\n\nEdit the `Dockerfile` and run `coder templates push` to update workspaces.\n\n## code-server\n\n`code-server` is installed via the `startup_script` argument in the `coder_agent`\nresource block. The `coder_app` resource is defined to access `code-server` through\nthe dashboard UI over `localhost:13337`.\n\n## Extending this template\n\nSee the [kreuzwerker/docker](https://registry.terraform.io/providers/kreuzwerker/docker) Terraform provider documentation to\nadd the following features to your Coder template:\n\n- SSH/TCP docker host\n- Registry authentication\n- Build args\n- Volume mounts\n- Custom container spec\n- More\n\nWe also welcome contributions!\n"
},
{
"id": "docker-with-dotfiles",
"url": "",
"name": "Develop in Docker with a dotfiles URL",
"description": "Develop inside Docker containers using your local daemon",
"icon": "/icon/docker.png",
"tags": [
"local",
"docker"
],
"markdown": "\n# docker-with-dotfiles\n\nThis is an example for deploying workspaces with a prompt for the users' dotfiles repo URI.\n\n## Getting started\n\nRun `coder templates init` and select this template. Follow the instructions that appear.\n\n## How it works\n\nDuring 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:\n\n```hcl\nvariable \"dotfiles_uri\" {\n description = \u003c\u003c-EOF\n Dotfiles repo URI (optional)\n\n see https://dotfiles.github.io\n EOF\n # The codercom/enterprise-* images are only built for amd64\n default = \"\"\n}\n\nresource \"coder_agent\" \"main\" {\n ...\n startup_script = var.dotfiles_uri != \"\" ? \"/tmp/tmp.coder*/coder dotfiles -y ${var.dotfiles_uri}\" : null\n}\n```\n\n# Managing images and workspaces\n\nRefer to the documentation in the [Docker template](../docker/README.md).\n"
"markdown": "\n# Remote Development on Docker Containers\n\nProvision Docker containers as [Coder workspaces](https://coder.com/docs/coder-v2/latest) with this example template.\n\n\u003c!-- TODO: Add screenshot --\u003e\n\n## Prerequisites\n\n### Infrastructure\n\nThe VM you run Coder on must have a running Docker socket and the `coder` user must be added to the Docker group:\n\n```sh\n# Add coder user to Docker group\nsudo adduser coder docker\n\n# Restart Coder server\nsudo systemctl restart coder\n\n# Test Docker\nsudo -u coder docker ps\n```\n\n## Architecture\n\nThis template provisions the following resources:\n\n- Docker image (built by Docker socket and kept locally)\n- Docker container pod (ephemeral)\n- Docker volume (persistent on `/home/coder`)\n\nThis means, when the workspace restarts, any tools or files outside of the home directory are not persisted. To pre-bake tools into the workspace (e.g. `python3`), modify the container image. Alternatively, individual developers can [personalize](https://coder.com/docs/v2/latest/dotfiles) their workspaces with dotfiles.\n\n\u003e **Note**\n\u003e This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.\n\n### Editing the image\n\nEdit the `Dockerfile` and run `coder templates push` to update workspaces.\n"
},
{
"id": "gcp-linux",
"url": "",
"name": "Develop in Linux on Google Cloud",
"description": "Get started with Linux development on Google Cloud.",
"name": "Google Compute Engine (Linux)",
"description": "Provision Google Compute Engine instances as Coder workspaces",
"icon": "/icon/gcp.png",
"tags": [
"cloud",
"google"
"vm",
"linux",
"gcp"
],
"markdown": "\n# gcp-linux\n\nTo get started, run `coder templates init`. When prompted, select this template,\nand follow the on-screen instructions to proceed.\n\n## Authentication\n\nThis template assumes that coderd is run in an environment that is authenticated\nwith Google Cloud. For example, run `gcloud auth application-default login` to\nimport credentials on the system and user running coderd. For other ways to\nauthenticate [consult the Terraform\ndocs](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/getting_started#adding-credentials).\n\n## Service account\n\nCoder requires a Google Cloud Service Account to provision workspaces. To create\na service account:\n\n1. Navigate to the [CGP\n console](https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts/create),\n and select your Cloud project (if you have more than one project associated\n with your account)\n\n1. Provide a service account name (this name is used to generate the service\n account ID)\n\n1. Click **Create and continue**, and choose the following IAM roles to grant to\n the service account:\n\n - Compute Admin\n - Service Account User\n\n Click **Continue**.\n\n1. Click on the created key, and navigate to the **Keys** tab.\n\n1. Click **Add key** \u003e **Create new key**.\n\n1. Generate a **JSON private key**, which will be what you provide to Coder\n during the setup process.\n\n## code-server\n\n`code-server` is installed via the `startup_script` argument in the `coder_agent`\nresource block. The `coder_app` resource is defined to access `code-server` through\nthe dashboard UI over `localhost:13337`.\n"
"markdown": "\n# Remote Development on Google Compute Engine (Linux)\n\n## Prerequisites\n\n### Authentication\n\nThis template assumes that coderd is run in an environment that is authenticated\nwith Google Cloud. For example, run `gcloud auth application-default login` to\nimport credentials on the system and user running coderd. For other ways to\nauthenticate [consult the Terraform\ndocs](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/getting_started#adding-credentials).\n\nCoder requires a Google Cloud Service Account to provision workspaces. To create\na service account:\n\n1. Navigate to the [CGP\n console](https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts/create),\n and select your Cloud project (if you have more than one project associated\n with your account)\n\n1. Provide a service account name (this name is used to generate the service\n account ID)\n\n1. Click **Create and continue**, and choose the following IAM roles to grant to\n the service account:\n\n - Compute Admin\n - Service Account User\n\n Click **Continue**.\n\n1. Click on the created key, and navigate to the **Keys** tab.\n\n1. Click **Add key** \u003e **Create new key**.\n\n1. Generate a **JSON private key**, which will be what you provide to Coder\n during the setup process.\n\n## Architecture\n\nThis template provisions the following resources:\n\n- GCP VM (ephemeral)\n- GCP Disk (persistent, mounted to root)\n\nCoder persists the root volume. The full filesystem is preserved when the workspace restarts. See this [community example](https://github.com/bpmct/coder-templates/tree/main/aws-linux-ephemeral) of an ephemeral AWS instance.\n\n\u003e **Note**\n\u003e This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.\n\n## code-server\n\n`code-server` is installed via the `startup_script` argument in the `coder_agent`\nresource block. The `coder_app` resource is defined to access `code-server` through\nthe dashboard UI over `localhost:13337`.\n"
},
{
"id": "gcp-vm-container",
"url": "",
"name": "Develop in a container on a Google Cloud VM",
"description": "Get started with Linux development on Google Cloud.",
"name": "Google Compute Engine (VM Container)",
"description": "Provision Google Compute Engine instances as Coder workspaces",
"icon": "/icon/gcp.png",
"tags": [
"cloud",
"google",
"container"
"vm-container",
"linux",
"gcp"
],
"markdown": "\n# gcp-vm-container\n\nTo get started, run `coder templates init`. When prompted, select this template,\nand follow the on-screen instructions to proceed.\n\n## Authentication\n\nThis template assumes that coderd is run in an environment that is authenticated\nwith Google Cloud. For example, run `gcloud auth application-default login` to\nimport credentials on the system and user running coderd. For other ways to\nauthenticate [consult the Terraform\ndocs](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/getting_started#adding-credentials).\n\n## Service account\n\nCoder requires a Google Cloud Service Account to provision workspaces. To create\na service account:\n\n1. Navigate to the [CGP\n console](https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts/create),\n and select your Cloud project (if you have more than one project associated\n with your account)\n\n1. Provide a service account name (this name is used to generate the service\n account ID)\n\n1. Click **Create and continue**, and choose the following IAM roles to grant to\n the service account:\n\n - Compute Admin\n - Service Account User\n\n Click **Continue**.\n\n1. Click on the created key, and navigate to the **Keys** tab.\n\n1. Click **Add key** \u003e **Create new key**.\n\n1. Generate a **JSON private key**, which will be what you provide to Coder\n during the setup process.\n\n## code-server\n\n`code-server` is installed via the `startup_script` argument in the `coder_agent`\nresource block. The `coder_app` resource is defined to access `code-server` through\nthe dashboard UI over `localhost:13337`.\n"
"markdown": "\n# Remote Development on Google Compute Engine (VM Container)\n\n## Prerequisites\n\n### Authentication\n\nThis template assumes that coderd is run in an environment that is authenticated\nwith Google Cloud. For example, run `gcloud auth application-default login` to\nimport credentials on the system and user running coderd. For other ways to\nauthenticate [consult the Terraform\ndocs](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/getting_started#adding-credentials).\n\nCoder requires a Google Cloud Service Account to provision workspaces. To create\na service account:\n\n1. Navigate to the [CGP\n console](https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts/create),\n and select your Cloud project (if you have more than one project associated\n with your account)\n\n1. Provide a service account name (this name is used to generate the service\n account ID)\n\n1. Click **Create and continue**, and choose the following IAM roles to grant to\n the service account:\n\n - Compute Admin\n - Service Account User\n\n Click **Continue**.\n\n1. Click on the created key, and navigate to the **Keys** tab.\n\n1. Click **Add key** \u003e **Create new key**.\n\n1. Generate a **JSON private key**, which will be what you provide to Coder\n during the setup process.\n\n## Architecture\n\nThis template provisions the following resources:\n\n- GCP VM (ephemeral, deleted on stop)\n - Container in VM\n- Managed disk (persistent, mounted to `/home/coder` in container)\n\nThis means, when the workspace restarts, any tools or files outside of the home directory are not persisted. To pre-bake tools into the workspace (e.g. `python3`), modify the container image, or use a [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script).\n\n\u003e **Note**\n\u003e This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.\n\n## code-server\n\n`code-server` is installed via the `startup_script` argument in the `coder_agent`\nresource block. The `coder_app` resource is defined to access `code-server` through\nthe dashboard UI over `localhost:13337`.\n"
},
{
"id": "gcp-windows",
"url": "",
"name": "Develop in Windows on Google Cloud",
"description": "Get started with Windows development on Google Cloud.",
"name": "Google Compute Engine (Windows)",
"description": "Provision Google Compute Engine instances as Coder workspaces",
"icon": "/icon/gcp.png",
"tags": [
"cloud",
"google"
"vm",
"windows",
"gcp"
],
"markdown": "\n# gcp-windows\n\nTo get started, run `coder templates init`. When prompted, select this template,\nand follow the on-screen instructions to proceed.\n\n## Authentication\n\nThis template assumes that coderd is run in an environment that is authenticated\nwith Google Cloud. For example, run `gcloud auth application-default login` to\nimport credentials on the system and user running coderd. For other ways to\nauthenticate [consult the Terraform\ndocs](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/getting_started#adding-credentials).\n\n## Service account\n\nCoder requires a Google Cloud Service Account to provision workspaces. To create\na service account:\n\n1. Navigate to the [CGP\n console](https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts/create),\n and select your Cloud project (if you have more than one project associated\n with your account)\n\n1. Provide a service account name (this name is used to generate the service\n account ID)\n\n1. Click **Create and continue**, and choose the following IAM roles to grant to\n the service account:\n\n - Compute Admin\n - Service Account User\n\n Click **Continue**.\n\n1. Click on the created key, and navigate to the **Keys** tab.\n\n1. Click **Add key** \u003e **Create new key**.\n\n1. Generate a **JSON private key**, which will be what you provide to Coder\n during the setup process.\n"
"markdown": "\n# Remote Development on Google Compute Engine (Windows)\n\n## Prerequisites\n\n### Authentication\n\nThis template assumes that coderd is run in an environment that is authenticated\nwith Google Cloud. For example, run `gcloud auth application-default login` to\nimport credentials on the system and user running coderd. For other ways to\nauthenticate [consult the Terraform\ndocs](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/getting_started#adding-credentials).\n\nCoder requires a Google Cloud Service Account to provision workspaces. To create\na service account:\n\n1. Navigate to the [CGP\n console](https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts/create),\n and select your Cloud project (if you have more than one project associated\n with your account)\n\n1. Provide a service account name (this name is used to generate the service\n account ID)\n\n1. Click **Create and continue**, and choose the following IAM roles to grant to\n the service account:\n\n - Compute Admin\n - Service Account User\n\n Click **Continue**.\n\n1. Click on the created key, and navigate to the **Keys** tab.\n\n1. Click **Add key** \u003e **Create new key**.\n\n1. Generate a **JSON private key**, which will be what you provide to Coder\n during the setup process.\n\n## Architecture\n\nThis template provisions the following resources:\n\n- GCP VM (ephemeral)\n- GCP Disk (persistent, mounted to root)\n\nCoder persists the root volume. The full filesystem is preserved when the workspace restarts. See this [community example](https://github.com/bpmct/coder-templates/tree/main/aws-linux-ephemeral) of an ephemeral AWS instance.\n\n\u003e **Note**\n\u003e This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.\n\n## code-server\n\n`code-server` is installed via the `startup_script` argument in the `coder_agent`\nresource block. The `coder_app` resource is defined to access `code-server` through\nthe dashboard UI over `localhost:13337`.\n"
},
{
"id": "kubernetes",
"url": "",
"name": "Develop in Kubernetes",
"description": "Get started with Kubernetes development.",
"name": "Kubernetes (Deployment)",
"description": "Provision Kubernetes Deployments as Coder workspaces",
"icon": "/icon/k8s.png",
"tags": [
"cloud",
"kubernetes"
"kubernetes",
"container"
],
"markdown": "\n# Getting started\n\nThis template creates a deployment running the `codercom/enterprise-base:ubuntu` image.\n\n## Prerequisites\n\nThis template uses [`kubernetes_deployment`](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs/resources/deployment) terraform resource, which requires the `coder` service account to have permission to create deploymnets. For example if you are using [helm](https://coder.com/docs/v2/latest/install/kubernetes#install-coder-with-helm) to install Coder, you should set `coder.serviceAccount.enableDeployments=true` in your `values.yaml`\n\n```diff\ncoder:\nserviceAccount:\n workspacePerms: true\n- enableDeployments: false\n+ enableDeployments: true\n annotations: {}\n name: coder\n```\n\n\u003e Note: This is only required for Coder versions \u003c 0.28.0, as this will be the default value for Coder versions \u003e= 0.28.0\n\n## Authentication\n\nThis template can authenticate using in-cluster authentication, or using a kubeconfig local to the\nCoder host. For additional authentication options, consult the [Kubernetes provider\ndocumentation](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs).\n\n### kubeconfig on Coder host\n\nIf the Coder host has a local `~/.kube/config`, you can use this to authenticate\nwith Coder. Make sure this is done with same user that's running the `coder` service.\n\nTo use this authentication, set the parameter `use_kubeconfig` to true.\n\n### In-cluster authentication\n\nIf the Coder host runs in a Pod on the same Kubernetes cluster as you are creating workspaces in,\nyou can use in-cluster authentication.\n\nTo use this authentication, set the parameter `use_kubeconfig` to false.\n\nThe Terraform provisioner will automatically use the service account associated with the pod to\nauthenticate to Kubernetes. Be sure to bind a [role with appropriate permission](#rbac) to the\nservice account. For example, assuming the Coder host runs in the same namespace as you intend\nto create workspaces:\n\n```yaml\napiVersion: v1\nkind: ServiceAccount\nmetadata:\n name: coder\n\n---\napiVersion: rbac.authorization.k8s.io/v1\nkind: RoleBinding\nmetadata:\n name: coder\nsubjects:\n - kind: ServiceAccount\n name: coder\nroleRef:\n kind: Role\n name: coder\n apiGroup: rbac.authorization.k8s.io\n```\n\nThen start the Coder host with `serviceAccountName: coder` in the pod spec.\n\n### Authenticate against external clusters\n\nYou may want to deploy workspaces on a cluster outside of the Coder control plane. Refer to the [Coder docs](https://coder.com/docs/v2/latest/platforms/kubernetes/additional-clusters) to learn how to modify your template to authenticate against external clusters.\n\n## Namespace\n\nThe target namespace in which the deployment will be deployed is defined via the `coder_workspace`\nvariable. The namespace must exist prior to creating workspaces.\n\n## Persistence\n\nThe `/home/coder` directory in this example is persisted via the attached PersistentVolumeClaim.\nAny data saved outside of this directory will be wiped when the workspace stops.\n\nSince most binary installations and environment configurations live outside of\nthe `/home` directory, we suggest including these in the `startup_script` argument\nof the `coder_agent` resource block, which will run each time the workspace starts up.\n\nFor example, when installing the `aws` CLI, the install script will place the\n`aws` binary in `/usr/local/bin/aws`. To ensure the `aws` CLI is persisted across\nworkspace starts/stops, include the following code in the `coder_agent` resource\nblock of your workspace template:\n\n```terraform\nresource \"coder_agent\" \"main\" {\n startup_script = \u003c\u003c-EOT\n set -e\n # install AWS CLI\n curl \"https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip\" -o \"awscliv2.zip\"\n unzip awscliv2.zip\n sudo ./aws/install\n EOT\n}\n```\n\n## code-server\n\n`code-server` is installed via the `startup_script` argument in the `coder_agent`\nresource block. The `coder_app` resource is defined to access `code-server` through\nthe dashboard UI over `localhost:13337`.\n\n## Deployment logs\n\nTo stream kubernetes pods events from the deployment, you can use Coder's [`coder-logstream-kube`](https://github.com/coder/coder-logstream-kube) tool. This can stream logs from the deployment to Coder's workspace startup logs. You just need to install the `coder-logstream-kube` helm chart on the cluster where the deployment is running.\n\n```shell\nhelm repo add coder-logstream-kube https://helm.coder.com/logstream-kube\nhelm install coder-logstream-kube coder-logstream-kube/coder-logstream-kube \\\n --namespace coder \\\n --set url=\u003cyour-coder-url-including-http-or-https\u003e\n```\n\nFor detailed instructions, see [Deployment logs](https://coder.com/docs/v2/latest/platforms/kubernetes/deployment-logs)\n"
"markdown": "\n# Remote Development on Kubernetes Pods\n\nProvision Kubernetes Pods as [Coder workspaces](https://coder.com/docs/coder-v2/latest) with this example template.\n\n\u003c!-- TODO: Add screenshot --\u003e\n\n## Prerequisites\n\n### Infrastructure\n\n**Cluster**: This template requires an existing Kubernetes cluster\n\n**Container Image**: This template uses the [codercom/enterprise-base:ubuntu image](https://github.com/coder/enterprise-images/tree/main/images/base) with some dev tools preinstalled. To add additional tools, extend this image or build it yourself.\n\n### Authentication\n\nThis template authenticates using a `~/.kube/config`, if present on the server, or via built-in authentication if the Coder provisioner is running on Kubernetes with an authorized ServiceAccount. To use another [authentication method](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs#authentication), edit the template.\n\n## Architecture\n\nThis template provisions the following resources:\n\n- Kubernetes pod (ephemeral)\n- Kubernetes persistent volume claim (persistent on `/home/coder`)\n\nThis means, when the workspace restarts, any tools or files outside of the home directory are not persisted. To pre-bake tools into the workspace (e.g. `python3`), modify the container image. Alternatively, individual developers can [personalize](https://coder.com/docs/v2/latest/dotfiles) their workspaces with dotfiles.\n\n\u003e **Note**\n\u003e This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.\n"
},
{
"id": "nomad-docker",
"url": "",
"name": "Develop in a Nomad Docker Container",
"description": "Get started with Nomad Workspaces.",
"name": "Nomad",
"description": "Provision Nomad Jobs as Coder workspaces",
"icon": "/icon/nomad.svg",
"tags": [
"cloud",
"nomad"
"nomad",
"container"
],
"markdown": "\n# Develop in a Nomad Docker Container\n\nThis example shows how to use Nomad service tasks to be used as a development environment using docker and host csi volumes.\n\n## Prerequisites\n\n- [Nomad](https://www.nomadproject.io/downloads)\n- [Docker](https://docs.docker.com/get-docker/)\n\n## Setup\n\n### 1. Start the CSI Host Volume Plugin\n\nThe CSI Host Volume plugin is used to mount host volumes into Nomad tasks. This is useful for development environments where you want to mount persistent volumes into your container workspace.\n\n1. Login to the Nomad server using SSH.\n\n2. Append the following stanza to your Nomad server configuration file and restart the nomad service.\n\n ```hcl\n plugin \"docker\" {\n config {\n allow_privileged = true\n }\n }\n ```\n\n ```shell\n sudo systemctl restart nomad\n ```\n\n3. Create a file `hostpath.nomad` with following content:\n\n ```hcl\n job \"hostpath-csi-plugin\" {\n datacenters = [\"dc1\"]\n type = \"system\"\n\n group \"csi\" {\n task \"plugin\" {\n driver = \"docker\"\n\n config {\n image = \"registry.k8s.io/sig-storage/hostpathplugin:v1.10.0\"\n\n args = [\n \"--drivername=csi-hostpath\",\n \"--v=5\",\n \"--endpoint=${CSI_ENDPOINT}\",\n \"--nodeid=node-${NOMAD_ALLOC_INDEX}\",\n ]\n\n privileged = true\n }\n\n csi_plugin {\n id = \"hostpath\"\n type = \"monolith\"\n mount_dir = \"/csi\"\n }\n\n resources {\n cpu = 256\n memory = 128\n }\n }\n }\n }\n ```\n\n4. Run the job:\n\n ```shell\n nomad job run hostpath.nomad\n ```\n\n### 2. Setup the Nomad Template\n\n1. Create the template by running the following command:\n\n ```shell\n coder template init nomad-docker\n cd nomad-docker\n coder template create\n ```\n\n2. Set up Nomad server address and optional authentication:\n\n3. Create a new workspace and start developing.\n"
"markdown": "\n# Remote Development on Nomad\n\nProvision Nomad Jobs as [Coder workspaces](https://coder.com/docs/coder-v2/latest) with this example template. This example shows how to use Nomad service tasks to be used as a development environment using docker and host csi volumes.\n\n\u003c!-- TODO: Add screenshot --\u003e\n\n\u003e **Note**\n\u003e This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.\n\n## Prerequisites\n\n- [Nomad](https://www.nomadproject.io/downloads)\n- [Docker](https://docs.docker.com/get-docker/)\n\n## Setup\n\n### 1. Start the CSI Host Volume Plugin\n\nThe CSI Host Volume plugin is used to mount host volumes into Nomad tasks. This is useful for development environments where you want to mount persistent volumes into your container workspace.\n\n1. Login to the Nomad server using SSH.\n\n2. Append the following stanza to your Nomad server configuration file and restart the nomad service.\n\n ```hcl\n plugin \"docker\" {\n config {\n allow_privileged = true\n }\n }\n ```\n\n ```shell\n sudo systemctl restart nomad\n ```\n\n3. Create a file `hostpath.nomad` with following content:\n\n ```hcl\n job \"hostpath-csi-plugin\" {\n datacenters = [\"dc1\"]\n type = \"system\"\n\n group \"csi\" {\n task \"plugin\" {\n driver = \"docker\"\n\n config {\n image = \"registry.k8s.io/sig-storage/hostpathplugin:v1.10.0\"\n\n args = [\n \"--drivername=csi-hostpath\",\n \"--v=5\",\n \"--endpoint=${CSI_ENDPOINT}\",\n \"--nodeid=node-${NOMAD_ALLOC_INDEX}\",\n ]\n\n privileged = true\n }\n\n csi_plugin {\n id = \"hostpath\"\n type = \"monolith\"\n mount_dir = \"/csi\"\n }\n\n resources {\n cpu = 256\n memory = 128\n }\n }\n }\n }\n ```\n\n4. Run the job:\n\n ```shell\n nomad job run hostpath.nomad\n ```\n\n### 2. Setup the Nomad Template\n\n1. Create the template by running the following command:\n\n ```shell\n coder template init nomad-docker\n cd nomad-docker\n coder template create\n ```\n\n2. Set up Nomad server address and optional authentication:\n\n3. Create a new workspace and start developing.\n"
}
]

2
examples/examples.go
View File

@ -23,13 +23,11 @@ var (
// Only some templates are embedded that we want to display inside the UI.
// The metadata in examples.gen.json is generated via scripts/examplegen.
//go:embed examples.gen.json
//go:embed templates/aws-ecs-container
//go:embed templates/aws-linux
//go:embed templates/aws-windows
//go:embed templates/azure-linux
//go:embed templates/do-linux
//go:embed templates/docker
//go:embed templates/docker-with-dotfiles
//go:embed templates/gcp-linux
//go:embed templates/gcp-vm-container
//go:embed templates/gcp-windows

0
examples/templates/jfrog/docker/README.md → examples/jfrog/docker/README.md
View File

0
examples/templates/jfrog/docker/build/Dockerfile → examples/jfrog/docker/build/Dockerfile
View File

0
examples/templates/jfrog/docker/main.tf → examples/jfrog/docker/main.tf
View File

0
examples/templates/jfrog/remote/main.tf → examples/jfrog/remote/main.tf
View File

4
examples/templates/README.md
View File

@ -6,11 +6,11 @@ List template examples in our CLI with `coder templates init`.
## Getting Started
Clone this repository to create a project from any example listed here:
Clone this repository to create a template from any example listed here:
```console
git clone https://github.com/coder/coder
cd examples/templates/aws-macos
cd examples/templates/aws-linux
coder templates create
```

24
examples/templates/aws-ecs-container/README.md
View File

@ -1,24 +0,0 @@
---
name: Develop in an ECS-hosted container
description: Get started with Linux development on AWS ECS.
tags: [cloud, aws]
icon: /icon/aws.png
---
# aws-ecs
This is a sample template for running a Coder workspace on ECS. It assumes there
is a pre-existing ECS cluster with EC2-based compute to host the workspace.
## Architecture
This workspace is built using the following AWS resources:
- Task definition - the container definition, includes the image, command, volume(s)
- ECS service - manages the task definition
## code-server
`code-server` is installed via the `startup_script` argument in the `coder_agent`
resource block. The `coder_app` resource is defined to access `code-server` through
the dashboard UI over `localhost:13337`.

135
examples/templates/aws-ecs-container/main.tf
View File

@ -1,135 +0,0 @@
terraform {
required_providers {
coder = {
source = "coder/coder"
}
aws = {
source = "hashicorp/aws"
}
}
}
provider "coder" {
feature_use_managed_variables = true
}
variable "ecs-cluster" {
description = "Input the ECS cluster ARN to host the workspace"
}
data "coder_parameter" "cpu" {
name = "cpu"
display_name = "CPU"
description = "The number of CPU units to reserve for the container"
type = "number"
default = "1024"
mutable = true
}
data "coder_parameter" "memory" {
name = "memory"
display_name = "Memory"
description = "The amount of memory (in MiB) to allow the container to use"
type = "number"
default = "2048"
mutable = true
}
# configure AWS provider with creds present on Coder server host
provider "aws" {
shared_config_files = ["$HOME/.aws/config"]
shared_credentials_files = ["$HOME/.aws/credentials"]
}
# coder workspace, created as an ECS task definition
resource "aws_ecs_task_definition" "workspace" {
family = "coder"
requires_compatibilities = ["EC2"]
cpu = data.coder_parameter.cpu.value
memory = data.coder_parameter.memory.value
container_definitions = jsonencode([
{
name = "coder-workspace-${data.coder_workspace.me.id}"
image = "codercom/enterprise-base:ubuntu"
cpu = tonumber(data.coder_parameter.cpu.value)
memory = tonumber(data.coder_parameter.memory.value)
essential = true
user = "coder"
command = ["sh", "-c", coder_agent.coder.init_script]
environment = [
{
"name" = "CODER_AGENT_TOKEN"
"value" = coder_agent.coder.token
}
]
mountPoints = [
{
# the name of the volume to mount
sourceVolume = "home-dir-${data.coder_workspace.me.id}"
# path on the container to mount the volume at
containerPath = "/home/coder"
}
]
portMappings = [
{
containerPort = 80
hostPort = 80
}
]
}
])
# workspace persistent volume definition
volume {
name = "home-dir-${data.coder_workspace.me.id}"
docker_volume_configuration {
# "shared" ensures that the disk is persisted upon workspace restart
scope = "shared"
autoprovision = true
driver = "local"
}
}
}
resource "aws_ecs_service" "workspace" {
name = "workspace-${data.coder_workspace.me.id}"
cluster = var.ecs-cluster
task_definition = aws_ecs_task_definition.workspace.arn
# scale the service to zero when the workspace is stopped
desired_count = data.coder_workspace.me.start_count
}
data "coder_workspace" "me" {}
resource "coder_agent" "coder" {
arch = "amd64"
auth = "token"
os = "linux"
dir = "/home/coder"
startup_script_timeout = 180
startup_script = <<-EOT
set -e
# install and start code-server
curl -fsSL https://code-server.dev/install.sh | sh -s -- --method=standalone --prefix=/tmp/code-server --version 4.11.0
/tmp/code-server/bin/code-server --auth none --port 13337 >/tmp/code-server.log 2>&1 &
EOT
}
resource "coder_app" "code-server" {
agent_id = coder_agent.coder.id
slug = "code-server"
display_name = "code-server"
icon = "/icon/code.svg"
url = "http://localhost:13337?folder=/home/coder"
subdomain = false
share = "owner"
healthcheck {
url = "http://localhost:13337/healthz"
interval = 3
threshold = 10
}
}

41
examples/templates/aws-linux/README.md
View File

@ -1,21 +1,27 @@
---
name: Develop in Linux on AWS EC2
description: Get started with Linux development on AWS EC2.
tags: [cloud, aws]
icon: /icon/aws.png
display_name: AWS EC2 (Linux)
description: Provision AWS EC2 VMs as Coder workspaces
icon: ../../../site/static/icon/aws.png
maintainer_github: coder
verified: true
tags: [vm, linux, aws, persistent-vm]
---
# aws-linux
# Remote Development on AWS EC2 VMs (Linux)
To get started, run `coder templates init`. When prompted, select this template.
Follow the on-screen instructions to proceed.
Provision AWS EC2 VMs as [Coder workspaces](https://coder.com/docs/coder-v2/latest) with this example template.
## Authentication
<!-- TODO: Add screenshot -->
This template assumes that coderd is run in an environment that is authenticated
with AWS. For example, run `aws configure import` to import credentials on the
system and user running coderd. For other ways to authenticate [consult the
Terraform docs](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration).
## Prerequisites
### Authentication
By default, this template authenticates to AWS using the provider's default [authentication methods](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration).
The simplest way (without making changes to the template) is via environment variables (e.g. `AWS_ACCESS_KEY_ID`) or a [credentials file](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-format). If you are running Coder on a VM, this file must be in `/home/coder/aws/credentials`.
To use another [authentication method](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication), edit the template.
## Required permissions / policy
@ -71,6 +77,17 @@ instances provisioned by Coder:
}
```
## Architecture
This template provisions the following resources:
- AWS Instance
Coder uses `aws_ec2_instance_state` to start and stop the VM. This example template is fully persistent, meaning the full filesystem is preserved when the workspace restarts. See this [community example](https://github.com/bpmct/coder-templates/tree/main/aws-linux-ephemeral) of an ephemeral AWS instance.
> **Note**
> This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.
## code-server
`code-server` is installed via the `startup_script` argument in the `coder_agent`

51
examples/templates/aws-linux/main.tf
View File

@ -212,36 +212,35 @@ resource "coder_app" "code-server" {
locals {
linux_user = "coder"
user_data = data.coder_workspace.me.start_count > 0 ? trimspace(<<EOT
Content-Type: multipart/mixed; boundary="//"
MIME-Version: 1.0
user_data = <<-EOT
Content-Type: multipart/mixed; boundary="//"
MIME-Version: 1.0
--//
Content-Type: text/cloud-config; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="cloud-config.txt"
--//
Content-Type: text/cloud-config; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="cloud-config.txt"
#cloud-config
cloud_final_modules:
- [scripts-user, always]
hostname: ${lower(data.coder_workspace.me.name)}
users:
- name: ${local.linux_user}
sudo: ALL=(ALL) NOPASSWD:ALL
shell: /bin/bash
#cloud-config
cloud_final_modules:
- [scripts-user, always]
hostname: ${lower(data.coder_workspace.me.name)}
users:
- name: ${local.linux_user}
sudo: ALL=(ALL) NOPASSWD:ALL
shell: /bin/bash
--//
Content-Type: text/x-shellscript; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="userdata.txt"
--//
Content-Type: text/x-shellscript; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="userdata.txt"
#!/bin/bash
sudo -u ${local.linux_user} sh -c '${coder_agent.dev[0].init_script}'
--//--
EOT
) : ""
#!/bin/bash
sudo -u ${local.linux_user} sh -c '${try(coder_agent.dev[0].init_script, "")}'
--//--
EOT
}
resource "aws_instance" "dev" {

47
examples/templates/aws-windows/README.md
View File

@ -1,23 +1,27 @@
---
name: Develop in Windows on AWS
description: Get started with Windows development on AWS.
tags: [cloud, aws]
icon: /icon/aws.png
display_name: AWS EC2 (Windows)
description: Provision AWS EC2 VMs as Coder workspaces
icon: ../../../site/static/icon/aws.png
maintainer_github: coder
verified: true
tags: [vm, windows, aws]
---
# aws-windows
# Remote Development on AWS EC2 VMs (Windows)
## Getting started
Provision AWS EC2 VMs as [Coder workspaces](https://coder.com/docs/coder-v2/latest) with this example template.
To get started, run `coder templates init`. When prompted, select this template.
Follow the on-screen instructions to proceed.
<!-- TODO: Add screenshot -->
## Authentication
## Prerequisites
This template assumes that coderd is run in an environment that is authenticated
with AWS. For example, run `aws configure import` to import credentials on the
system and user running coderd. For other ways to authenticate [consult the
Terraform docs](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration).
### Authentication
By default, this template authenticates to AWS with using the provider's default [authentication methods](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration).
The simplest way (without making changes to the template) is via environment variables (e.g. `AWS_ACCESS_KEY_ID`) or a [credentials file](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-format). If you are running Coder on a VM, this file must be in `/home/coder/aws/credentials`.
To use another [authentication method](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication), edit the template.
## Required permissions / policy
@ -72,3 +76,20 @@ instances provisioned by Coder:
]
}
```
## Architecture
This template provisions the following resources:
- AWS Instance
Coder uses `aws_ec2_instance_state` to start and stop the VM. This example template is fully persistent, meaning the full filesystem is preserved when the workspace restarts. See this [community example](https://github.com/bpmct/coder-templates/tree/main/aws-linux-ephemeral) of an ephemeral AWS instance.
> **Note**
> This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.
## code-server
`code-server` is installed via the `startup_script` argument in the `coder_agent`
resource block. The `coder_app` resource is defined to access `code-server` through
the dashboard UI over `localhost:13337`.

41
examples/templates/azure-linux/README.md
View File

@ -1,18 +1,41 @@
---
name: Develop in Linux on Azure
description: Get started with Linux development on Microsoft Azure.
tags: [cloud, azure, linux]
icon: /icon/azure.png
display_name: Azure VM (Linux)
description: Provision Azure VMs as Coder workspaces
icon: ../../../site/static/icon/azure.png
maintainer_github: coder
verified: true
tags: [vm, linux, azure]
---
# azure-linux
# Remote Development on Azure VMs (Linux)
To get started, run `coder templates init`. When prompted, select this template.
Follow the on-screen instructions to proceed.
Provision AWS EC2 VMs as [Coder workspaces](https://coder.com/docs/coder-v2/latest) with this example template.
## Authentication
<!-- TODO: Add screenshot -->
## Prerequisites
### Authentication
This template assumes that coderd is run in an environment that is authenticated
with Azure. For example, run `az login` then `az account set --subscription=<id>`
to import credentials on the system and user running coderd. For other ways to
authenticate [consult the Terraform docs](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs#authenticating-to-azure).
authenticate, [consult the Terraform docs](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs#authenticating-to-azure).
## Architecture
This template provisions the following resources:
- Azure VM (ephemeral, deleted on stop)
- Managed disk (persistent, mounted to `/home/coder`)
This means, when the workspace restarts, any tools or files outside of the home directory are not persisted. To pre-bake tools into the workspace (e.g. `python3`), modify the VM image, or use a [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script). Alternatively, individual developers can [personalize](https://coder.com/docs/v2/latest/dotfiles) their workspaces with dotfiles.
> **Note**
> This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.
## code-server
`code-server` is installed via the `startup_script` argument in the `coder_agent`
resource block. The `coder_app` resource is defined to access `code-server` through
the dashboard UI over `localhost:13337`.

36
examples/templates/azure-windows/README.md
View File

@ -1,23 +1,35 @@
---
name: Develop in Windows on Azure
description: Get started with Windows development on Microsoft Azure.
tags: [cloud, azure, windows]
icon: /icon/azure.png
display_name: Azure VM (Windows)
description: Provision Azure VMs as Coder workspaces
icon: ../../../site/static/icon/azure.png
maintainer_github: coder
verified: true
tags: [vm, windows, azure]
---
# azure-windows
# Remote Development on Azure VMs (Windows)
To get started, run `coder templates init`. When prompted, select this template.
Follow the on-screen instructions to proceed.
Provision AWS EC2 VMs as [Coder workspaces](https://coder.com/docs/coder-v2/latest) with this example template.
## Authentication
<!-- TODO: Add screenshot -->
## Prerequisites
### Authentication
This template assumes that coderd is run in an environment that is authenticated
with Azure. For example, run `az login` then `az account set --subscription=<id>`
to import credentials on the system and user running coderd. For other ways to
authenticate [consult the Terraform docs](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs#authenticating-to-azure).
authenticate, [consult the Terraform docs](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs#authenticating-to-azure).
## Dependencies
## Architecture
This template depends on the Azure CLI tool (`az`) to start and stop the Windows VM. Ensure this
tool is installed and available in the path on the machine that runs coderd.
This template provisions the following resources:
- Azure VM (ephemeral, deleted on stop)
- Managed disk (persistent, mounted to `F:`)
This means, when the workspace restarts, any tools or files outside of the data directory are not persisted. To pre-bake tools into the workspace (e.g. `python3`), modify the VM image, or use a [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script).
> **Note**
> This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.

58
examples/templates/devcontainer-docker/README.md
View File

@ -1,36 +1,50 @@
---
name: Devcontainers in Docker
description: Develop using devcontainers in Docker
tags: [local, docker]
icon: /icon/docker.png
display_name: Devcontainers (Docker)
description: Provision envbuilder containers as Coder workspaces
icon: ../../../site/static/icon/docker.png
maintainer_github: coder
verified: true
tags: [container, docker, devcontainer]
---
# devcontainer-docker
# Remote Development on Docker Containers (with Devcontainers)
Develop using [devcontainers](https://containers.dev) in Docker.
Provision Docker containers as [Coder workspaces](https://coder.com/docs/coder-v2/latest) with this example template.
To get started, run `coder templates init`. When prompted, select this template.
Follow the on-screen instructions to proceed.
<!-- TODO: Add screenshot -->
## How it works
## Prerequisites
### Infrastructure
The VM you run Coder on must have a running Docker socket and the `coder` user must be added to the Docker group:
```sh
# Add coder user to Docker group
sudo adduser coder docker
# Restart Coder server
sudo systemctl restart coder
# Test Docker
sudo -u coder docker ps
```
## Architecture
Coder supports devcontainers with [envbuilder](https://github.com/coder/envbuilder), an open source project. Read more about this in [Coder's documentation](https://coder.com/docs/v2/latest/templates/devcontainers).
## code-server
This template provisions the following resources:
`code-server` is installed via the `startup_script` argument in the `coder_agent`
resource block. The `coder_app` resource is defined to access `code-server` through
the dashboard UI over `localhost:13337`.
- Docker image (built by Docker socket and kept locally)
- Docker container pod (ephemeral)
- Docker volume (persistent on `/home/coder`)
## Extending this template
This means, when the workspace restarts, any tools or files outside of the home directory are not persisted. To pre-bake tools into the workspace (e.g. `python3`), modify the container image. Alternatively, individual developers can [personalize](https://coder.com/docs/v2/latest/dotfiles) their workspaces with dotfiles.
See the [kreuzwerker/docker](https://registry.terraform.io/providers/kreuzwerker/docker) Terraform provider documentation to add the following features to your Coder template:
> **Note**
> This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.
- SSH/TCP docker host
- Registry authentication
- Build args
- Volume mounts
- Custom container spec
- More
### Editing the image
We also welcome contributions!
Edit the `Dockerfile` and run `coder templates push` to update workspaces.

41
examples/templates/devcontainer-kubernetes/README.md
View File

@ -1,17 +1,40 @@
---
name: Devcontainers in Kubernetes
description: Develop using devcontainers in Kubernetes
tags: [local, kubernetes]
icon: /icon/kubernetes.png
display_name: Devcontainers (Kubernetes)
description: Provision envbuilder pods as Coder workspaces
icon: ../../../site/static/icon/k8s.png
maintainer_github: coder
verified: true
tags: [container, kubernetes, devcontainer]
---
# devcontainer-kubernetes
# Remote Development on Kubernetes Pods (with Devcontainers)
Develop using [devcontainers](https://containers.dev) in Kubernetes.
Provision Kubernetes Pods as [Coder workspaces](https://coder.com/docs/coder-v2/latest) with this example template.
To get started, run `coder templates init`. When prompted, select this template.
Follow the on-screen instructions to proceed.
<!-- TODO: Add screenshot -->
## How it works
## Prerequisites
### Infrastructure
**Cluster**: This template requires an existing Kubernetes cluster
**Container Image**: This template uses the [codercom/enterprise-base:ubuntu image](https://github.com/coder/enterprise-images/tree/main/images/base) with some dev tools preinstalled. To add additional tools, extend this image or build it yourself.
### Authentication
This template authenticates using a `~/.kube/config`, if present on the server, or via built-in authentication if the Coder provisioner is running on Kubernetes with an authorized ServiceAccount. To use another [authentication method](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs#authentication), edit the template.
## Architecture
Coder supports devcontainers with [envbuilder](https://github.com/coder/envbuilder), an open source project. Read more about this in [Coder's documentation](https://coder.com/docs/v2/latest/templates/devcontainers).
This template provisions the following resources:
- Kubernetes pod (ephemeral)
- Kubernetes persistent volume claim (persistent on `/home/coder`)
This means, when the workspace restarts, any tools or files outside of the home directory are not persisted. To pre-bake tools into the workspace (e.g. `python3`), modify the container image. Alternatively, individual developers can [personalize](https://coder.com/docs/v2/latest/dotfiles) their workspaces with dotfiles.
> **Note**
> This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.

48
examples/templates/do-linux/README.md
View File

@ -1,36 +1,54 @@
---
name: Develop in Linux on a Digital Ocean Droplet
description: Get started with Linux development on a Digital Ocean Droplet.
tags: [cloud, digitalocean]
icon: /icon/do.png
display_name: DigitalOcean Droplet (Linux)
description: Provision DigitalOcean Droplets as Coder workspaces
icon: ../../../site/static/icon/do.png
maintainer_github: coder
verified: true
tags: [vm, linux, digitalocean]
---
# do-linux
# Remote Development on DigitalOcean Droplets
Provision DigitalOcean Droplets as [Coder workspaces](https://coder.com/docs/coder-v2/latest) with this example template.
<!-- TODO: Add screenshot -->
## Prerequisites
To deploy workspaces as DigitalOcean Droplets, you'll need:
- DigitalOcean [personal access token
(PAT)](https://docs.digitalocean.com/reference/api/create-personal-access-token/)
- DigitalOcean [personal access token (PAT)](https://docs.digitalocean.com/reference/api/create-personal-access-token/)
- DigitalOcean project ID (you can get your project information via the `doctl`
CLI by running `doctl projects list`)
- Remove the following sections from the `main.tf` file if you don't want to
associate your workspaces with a project:
- Remove the following sections from the `main.tf` file if you don't want to
associate your workspaces with a project:
- `variable "step2_do_project_id"`
- `resource "digitalocean_project_resources" "project"`
- `variable "step2_do_project_id"`
- `resource "digitalocean_project_resources" "project"`
- **Optional:** DigitalOcean SSH key ID (obtain via the `doctl` CLI by running
`doctl compute ssh-key list`)
- Note that this is only required for Fedora images to work.
- Note that this is only required for Fedora images to work.
## Authentication
### Authentication
This template assumes that coderd is run in an environment that is authenticated
with Digital Ocean. Obtain a [Digital Ocean Personal Access
Token](https://cloud.digitalocean.com/account/api/tokens) and set the
environment variable `DIGITALOCEAN_TOKEN` to the access token before starting
coderd. For other ways to authenticate [consult the Terraform
docs](https://registry.terraform.io/providers/digitalocean/digitalocean/latest/docs).
coderd. For other ways to authenticate [consult the Terraform docs](https://registry.terraform.io/providers/digitalocean/digitalocean/latest/docs).
## Architecture
This template provisions the following resources:
- Azure VM (ephemeral, deleted on stop)
- Managed disk (persistent, mounted to `/home/coder`)
This means, when the workspace restarts, any tools or files outside of the home directory are not persisted. To pre-bake tools into the workspace (e.g. `python3`), modify the VM image, or use a [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script).
> **Note**
> This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.

39
examples/templates/docker-with-dotfiles/README.md
View File

@ -1,39 +0,0 @@
---
name: Develop in Docker with a dotfiles URL
description: Develop inside Docker containers using your local daemon
tags: [local, docker]
icon: /icon/docker.png
---
# 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" "main" {
...
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).

138
examples/templates/docker-with-dotfiles/main.tf
View File

@ -1,138 +0,0 @@
# 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"
}
docker = {
source = "kreuzwerker/docker"
}
}
}
data "coder_provisioner" "me" {
}
provider "docker" {
}
data "coder_workspace" "me" {
}
data "coder_parameter" "docker_image" {
name = "docker_image"
display_name = "Docker image"
description = "The Docker image will be used to build your workspace."
default = "codercom/enterprise-base:ubuntu"
icon = "/icon/docker.png"
type = "string"
mutable = false
}
data "coder_parameter" "dotfiles_uri" {
name = "dotfiles_uri"
display_name = "dotfiles URI"
description = <<-EOF
Dotfiles repo URI (optional)
see https://dotfiles.github.io
EOF
default = ""
type = "string"
mutable = true
}
resource "coder_agent" "main" {
arch = data.coder_provisioner.me.arch
os = "linux"
startup_script_timeout = 180
env = { "DOTFILES_URI" = data.coder_parameter.dotfiles_uri.value != "" ? data.coder_parameter.dotfiles_uri.value : null }
startup_script = <<-EOT
set -e
if [ -n "$DOTFILES_URI" ]; then
echo "Installing dotfiles from $DOTFILES_URI"
coder dotfiles -y "$DOTFILES_URI"
fi
EOT
}
resource "docker_volume" "home_volume" {
name = "coder-${data.coder_workspace.me.id}-home"
# Protect the volume from being deleted due to changes in attributes.
lifecycle {
ignore_changes = all
}
# Add labels in Docker to keep track of orphan resources.
labels {
label = "coder.owner"
value = data.coder_workspace.me.owner
}
labels {
label = "coder.owner_id"
value = data.coder_workspace.me.owner_id
}
labels {
label = "coder.workspace_id"
value = data.coder_workspace.me.id
}
# This field becomes outdated if the workspace is renamed but can
# be useful for debugging or cleaning out dangling volumes.
labels {
label = "coder.workspace_name_at_creation"
value = data.coder_workspace.me.name
}
}
resource "docker_container" "workspace" {
count = data.coder_workspace.me.start_count
image = data.coder_parameter.docker_image.value
# Uses lower() to avoid Docker restriction on container names.
name = "coder-${data.coder_workspace.me.owner}-${lower(data.coder_workspace.me.name)}"
# Hostname makes the shell more user friendly: coder@my-workspace:~$
hostname = data.coder_workspace.me.name
# Use the docker gateway if the access URL is 127.0.0.1
entrypoint = ["sh", "-c", replace(coder_agent.main.init_script, "/localhost|127\\.0\\.0\\.1/", "host.docker.internal")]
env = ["CODER_AGENT_TOKEN=${coder_agent.main.token}"]
host {
host = "host.docker.internal"
ip = "host-gateway"
}
volumes {
container_path = "/home/coder/"
volume_name = docker_volume.home_volume.name
read_only = false
}
# Add labels in Docker to keep track of orphan resources.
labels {
label = "coder.owner"
value = data.coder_workspace.me.owner
}
labels {
label = "coder.owner_id"
value = data.coder_workspace.me.owner_id
}
labels {
label = "coder.workspace_id"
value = data.coder_workspace.me.id
}
labels {
label = "coder.workspace_name"
value = data.coder_workspace.me.name
}
}
resource "coder_metadata" "container_info" {
count = data.coder_workspace.me.start_count
resource_id = docker_container.workspace[0].id
item {
key = "image"
value = data.coder_parameter.docker_image.value
}
}

69
examples/templates/docker/README.md
View File

@ -1,35 +1,48 @@
---
name: Develop in Docker
description: Develop inside Docker containers using your local daemon
tags: [local, docker]
icon: /icon/docker.png
display_name: Docker Containers
description: Provision Docker containers as Coder workspaces
icon: ../../../site/static/icon/docker.png
maintainer_github: coder
verified: true
tags: [docker, container]
---
# docker
# Remote Development on Docker Containers
To get started, run `coder templates init`. When prompted, select this template.
Follow the on-screen instructions to proceed.
Provision Docker containers as [Coder workspaces](https://coder.com/docs/coder-v2/latest) with this example template.
## Editing the image
<!-- TODO: Add screenshot -->
## Prerequisites
### Infrastructure
The VM you run Coder on must have a running Docker socket and the `coder` user must be added to the Docker group:
```sh
# Add coder user to Docker group
sudo adduser coder docker
# Restart Coder server
sudo systemctl restart coder
# Test Docker
sudo -u coder docker ps
```
## Architecture
This template provisions the following resources:
- Docker image (built by Docker socket and kept locally)
- Docker container pod (ephemeral)
- Docker volume (persistent on `/home/coder`)
This means, when the workspace restarts, any tools or files outside of the home directory are not persisted. To pre-bake tools into the workspace (e.g. `python3`), modify the container image. Alternatively, individual developers can [personalize](https://coder.com/docs/v2/latest/dotfiles) their workspaces with dotfiles.
> **Note**
> This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.
### Editing the image
Edit the `Dockerfile` and run `coder templates push` to update workspaces.
## code-server
`code-server` is installed via the `startup_script` argument in the `coder_agent`
resource block. The `coder_app` resource is defined to access `code-server` through
the dashboard UI over `localhost:13337`.
## Extending this template
See the [kreuzwerker/docker](https://registry.terraform.io/providers/kreuzwerker/docker) Terraform provider documentation to
add the following features to your Coder template:
- SSH/TCP docker host
- Registry authentication
- Build args
- Volume mounts
- Custom container spec
- More
We also welcome contributions!

9
examples/templates/envbox/README.md
View File

@ -1,3 +1,12 @@
---
display_name: Envbox (Kubernetes)
description: Provision envbox pods as Coder workspaces
icon: ../../../site/static/icon/k8s.png
maintainer_github: coder
verified: true
tags: [kubernetes, containers, docker-in-docker]
---
# envbox
## Introduction

31
examples/templates/gcp-linux/README.md
View File

@ -1,16 +1,17 @@
---
name: Develop in Linux on Google Cloud
description: Get started with Linux development on Google Cloud.
tags: [cloud, google]
icon: /icon/gcp.png
display_name: Google Compute Engine (Linux)
description: Provision Google Compute Engine instances as Coder workspaces
icon: ../../../site/static/icon/gcp.png
maintainer_github: coder
verified: true
tags: [vm, linux, gcp]
---
# gcp-linux
# Remote Development on Google Compute Engine (Linux)
To get started, run `coder templates init`. When prompted, select this template,
and follow the on-screen instructions to proceed.
## Prerequisites
## Authentication
### Authentication
This template assumes that coderd is run in an environment that is authenticated
with Google Cloud. For example, run `gcloud auth application-default login` to
@ -18,8 +19,6 @@ import credentials on the system and user running coderd. For other ways to
authenticate [consult the Terraform
docs](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/getting_started#adding-credentials).
## Service account
Coder requires a Google Cloud Service Account to provision workspaces. To create
a service account:
@ -46,6 +45,18 @@ a service account:
1. Generate a **JSON private key**, which will be what you provide to Coder
during the setup process.
## Architecture
This template provisions the following resources:
- GCP VM (ephemeral)
- GCP Disk (persistent, mounted to root)
Coder persists the root volume. The full filesystem is preserved when the workspace restarts. See this [community example](https://github.com/bpmct/coder-templates/tree/main/aws-linux-ephemeral) of an ephemeral AWS instance.
> **Note**
> This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.
## code-server
`code-server` is installed via the `startup_script` argument in the `coder_agent`

32
examples/templates/gcp-vm-container/README.md
View File

@ -1,16 +1,17 @@
---
name: Develop in a container on a Google Cloud VM
description: Get started with Linux development on Google Cloud.
tags: [cloud, google, container]
icon: /icon/gcp.png
display_name: Google Compute Engine (VM Container)
description: Provision Google Compute Engine instances as Coder workspaces
icon: ../../../site/static/icon/gcp.png
maintainer_github: coder
verified: true
tags: [vm-container, linux, gcp]
---
# gcp-vm-container
# Remote Development on Google Compute Engine (VM Container)
To get started, run `coder templates init`. When prompted, select this template,
and follow the on-screen instructions to proceed.
## Prerequisites
## Authentication
### Authentication
This template assumes that coderd is run in an environment that is authenticated
with Google Cloud. For example, run `gcloud auth application-default login` to
@ -18,8 +19,6 @@ import credentials on the system and user running coderd. For other ways to
authenticate [consult the Terraform
docs](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/getting_started#adding-credentials).
## Service account
Coder requires a Google Cloud Service Account to provision workspaces. To create
a service account:
@ -46,6 +45,19 @@ a service account:
1. Generate a **JSON private key**, which will be what you provide to Coder
during the setup process.
## Architecture
This template provisions the following resources:
- GCP VM (ephemeral, deleted on stop)
- Container in VM
- Managed disk (persistent, mounted to `/home/coder` in container)
This means, when the workspace restarts, any tools or files outside of the home directory are not persisted. To pre-bake tools into the workspace (e.g. `python3`), modify the container image, or use a [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script).
> **Note**
> This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.
## code-server
`code-server` is installed via the `startup_script` argument in the `coder_agent`

37
examples/templates/gcp-windows/README.md
View File

@ -1,16 +1,17 @@
---
name: Develop in Windows on Google Cloud
description: Get started with Windows development on Google Cloud.
tags: [cloud, google]
icon: /icon/gcp.png
display_name: Google Compute Engine (Windows)
description: Provision Google Compute Engine instances as Coder workspaces
icon: ../../../site/static/icon/gcp.png
maintainer_github: coder
verified: true
tags: [vm, windows, gcp]
---
# gcp-windows
# Remote Development on Google Compute Engine (Windows)
To get started, run `coder templates init`. When prompted, select this template,
and follow the on-screen instructions to proceed.
## Prerequisites
## Authentication
### Authentication
This template assumes that coderd is run in an environment that is authenticated
with Google Cloud. For example, run `gcloud auth application-default login` to
@ -18,8 +19,6 @@ import credentials on the system and user running coderd. For other ways to
authenticate [consult the Terraform
docs](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/getting_started#adding-credentials).
## Service account
Coder requires a Google Cloud Service Account to provision workspaces. To create
a service account:
@ -45,3 +44,21 @@ a service account:
1. Generate a **JSON private key**, which will be what you provide to Coder
during the setup process.
## Architecture
This template provisions the following resources:
- GCP VM (ephemeral)
- GCP Disk (persistent, mounted to root)
Coder persists the root volume. The full filesystem is preserved when the workspace restarts. See this [community example](https://github.com/bpmct/coder-templates/tree/main/aws-linux-ephemeral) of an ephemeral AWS instance.
> **Note**
> This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.
## code-server
`code-server` is installed via the `startup_script` argument in the `coder_agent`
resource block. The `coder_app` resource is defined to access `code-server` through
the dashboard UI over `localhost:13337`.

102
examples/templates/kubernetes-with-podman/README.md
View File

@ -1,102 +0,0 @@
---
name: Develop in Kubernetes
description: Get started with Kubernetes development.
tags: [cloud, kubernetes]
icon: /icon/k8s.png
---
# Getting started
This template creates [rootless podman](./images) pods with either an Ubuntu or Fedora base image.
> **Warning**: This template requires additional configuration on the Kubernetes cluster, such as installing `smarter-device-manager` for FUSE mounts. See our [Docker-in-Docker documentation](https://coder.com/docs/v2/latest/templates/docker-in-docker#rootless-podman) for instructions.
Base images are pushed to [Docker Hub](https://hub.docker.com//codercom)
## Authentication
This template can authenticate using in-cluster authentication, or using a kubeconfig local to the
Coder host. For additional authentication options, consult the [Kubernetes provider
documentation](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs).
### kubeconfig on Coder host
If the Coder host has a local `~/.kube/config`, you can use this to authenticate
with Coder. Make sure this is done with same user that's running the `coder` service.
To use this authentication, set the parameter `use_kubeconfig` to true.
### In-cluster authentication
If the Coder host runs in a Pod on the same Kubernetes cluster as you are creating workspaces in,
you can use in-cluster authentication.
To use this authentication, set the parameter `use_kubeconfig` to false.
The Terraform provisioner will automatically use the service account associated with the pod to
authenticate to Kubernetes. Be sure to bind a [role with appropriate permission](#rbac) to the
service account. For example, assuming the Coder host runs in the same namespace as you intend
to create workspaces:
```yaml
apiVersion: v1
kind: ServiceAccount
metadata:
name: coder
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: coder
subjects:
- kind: ServiceAccount
name: coder
roleRef:
kind: Role
name: coder
apiGroup: rbac.authorization.k8s.io
```
Then start the Coder host with `serviceAccountName: coder` in the pod spec.
### Authenticate against external clusters
You may want to deploy workspaces on a cluster outside of the Coder control plane. Refer to the [Coder docs](https://coder.com/docs/v2/latest/platforms/kubernetes/additional-clusters) to learn how to modify your template to authenticate against external clusters.
## Namespace
The target namespace in which the pod will be deployed is defined via the `coder_workspace`
variable. The namespace must exist prior to creating workspaces.
## Persistence
The `/home/coder` directory in this example is persisted via the attached PersistentVolumeClaim.
Any data saved outside of this directory will be wiped when the workspace stops.
Since most binary installations and environment configurations live outside of
the `/home` directory, we suggest including these in the `startup_script` argument
of the `coder_agent` resource block, which will run each time the workspace starts up.
For example, when installing the `aws` CLI, the install script will place the
`aws` binary in `/usr/local/bin/aws`. To ensure the `aws` CLI is persisted across
workspace starts/stops, include the following code in the `coder_agent` resource
block of your workspace template:
```terraform
resource "coder_agent" "main" {
startup_script = <<-EOT
set -e
# install AWS CLI
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install
EOT
}
```
## code-server
`code-server` is installed via the `startup_script` argument in the `coder_agent`
resource block. The `coder_app` resource is defined to access `code-server` through
the dashboard UI over `localhost:13337`.

35
examples/templates/kubernetes-with-podman/images/Dockerfile.fedora
View File

@ -1,35 +0,0 @@
FROM registry.fedoraproject.org/fedora:latest
LABEL org.opencontainers.image.description="Base Fedora image for rootless podman in Coder. See https://coder.com/docs/v2/latest/templates/docker-in-docker#rootless-podman"
RUN dnf -y update && \
rpm --setcaps shadow-utils 2>/dev/null && \
dnf -y install podman fuse-overlayfs openssh-clients \
--exclude container-selinux && \
dnf clean all && \
rm -rf /var/cache /var/log/dnf* /var/log/yum.*
RUN useradd podman; \
echo -e "podman:1:999\npodman:1001:64535" > /etc/subuid; \
echo -e "podman:1:999\npodman:1001:64535" > /etc/subgid;
ADD containers.conf /etc/containers/containers.conf
ADD storage.conf /etc/containers/storage.conf
RUN chmod 644 /etc/containers/containers.conf && \
chmod 644 /etc/containers/storage.conf
RUN mkdir -p /var/lib/shared/overlay-images \
/var/lib/shared/overlay-layers \
/var/lib/shared/vfs-images \
/var/lib/shared/vfs-layers && \
touch /var/lib/shared/overlay-images/images.lock && \
touch /var/lib/shared/overlay-layers/layers.lock && \
touch /var/lib/shared/vfs-images/images.lock && \
touch /var/lib/shared/vfs-layers/layers.lock
# Alias "docker" to "podman"
RUN ln -s /usr/bin/podman /usr/bin/docker
USER podman
ENV _CONTAINERS_USERNS_CONFIGURED=""

59
examples/templates/kubernetes-with-podman/images/Dockerfile.ubuntu
View File

@ -1,59 +0,0 @@
FROM ubuntu:22.04
LABEL org.opencontainers.image.description="Base Ubuntu image for rootless podman in Coder. See https://coder.com/docs/v2/latest/templates/docker-in-docker#rootless-podman"
USER root
# Install dependencies
RUN apt-get update && apt-get install -y sudo gnupg2 curl vim fuse-overlayfs libvshadow-utils openssh-client
# Install podman
RUN mkdir -p /etc/apt/keyrings
RUN curl -fsSL https://download.opensuse.org/repositories/devel:kubic:libcontainers:unstable/xUbuntu_22.04/Release.key \
| gpg --dearmor \
| tee /etc/apt/keyrings/devel_kubic_libcontainers_unstable.gpg > /dev/null
RUN echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/devel_kubic_libcontainers_unstable.gpg]\
https://download.opensuse.org/repositories/devel:kubic:libcontainers:unstable/xUbuntu_22.04/ /" \
| tee /etc/apt/sources.list.d/devel:kubic:libcontainers:unstable.list > /dev/null
RUN apt-get update && apt-get -y install podman
RUN setcap cap_setuid+ep /usr/bin/newuidmap
RUN setcap cap_setgid+ep /usr/bin/newgidmap
RUN chmod 0755 /usr/bin/newuidmap
RUN chmod 0755 /usr/bin/newgidmap
RUN useradd podman
RUN echo "podman:100000:65536" > /etc/subuid
RUN echo "podman:100000:65536" > /etc/subgid
RUN echo "podman ALL=(ALL) NOPASSWD:ALL" | sudo tee -a /etc/sudoers
ADD containers.conf /etc/containers/containers.conf
ADD storage.conf /etc/containers/storage.conf
RUN chmod 644 /etc/containers/containers.conf && \
chmod 644 /etc/containers/storage.conf
RUN mkdir -p /home/podman/.local/share/containers && \
chown podman:podman -R /home/podman && \
chmod 644 /etc/containers/containers.conf
RUN mkdir -p /var/lib/shared/overlay-images \
/var/lib/shared/overlay-layers \
/var/lib/shared/vfs-images \
/var/lib/shared/vfs-layers && \
touch /var/lib/shared/overlay-images/images.lock && \
touch /var/lib/shared/overlay-layers/layers.lock && \
touch /var/lib/shared/vfs-images/images.lock && \
touch /var/lib/shared/vfs-layers/layers.lock
ENV _CONTAINERS_USERNS_CONFIGURED=""
# Alias "docker" to "podman"
RUN ln -s /usr/bin/podman /usr/bin/docker
RUN chsh -s /bin/bash podman
USER podman
ENV SHELL=/bin/bash

16
examples/templates/kubernetes-with-podman/images/containers.conf
View File

@ -1,16 +0,0 @@
[containers]
netns="host"
userns="host"
ipcns="host"
utsns="host"
cgroupns="host"
cgroups="disabled"
log_driver = "k8s-file"
volumes = [
"/proc:/proc",
]
default_sysctls = []
[engine]
cgroup_manager = "cgroupfs"
events_logger="file"
runtime="crun"

233
examples/templates/kubernetes-with-podman/images/storage.conf
View File

@ -1,233 +0,0 @@
# This file is the configuration file for all tools
# that use the containers/storage library. The storage.conf file
# overrides all other storage.conf files. Container engines using the
# container/storage library do not inherit fields from other storage.conf
# files.
#
# Note: The storage.conf file overrides other storage.conf files based on this precedence:
# /usr/containers/storage.conf
# /etc/containers/storage.conf
# $HOME/.config/containers/storage.conf
# $XDG_CONFIG_HOME/containers/storage.conf (If XDG_CONFIG_HOME is set)
# See man 5 containers-storage.conf for more information
# The "container storage" table contains all of the server options.
[storage]
# Default Storage Driver, Must be set for proper operation.
driver = "overlay"
# Temporary storage location
runroot = "/run/containers/storage"
# Primary Read/Write location of container storage
# When changing the graphroot location on an SELINUX system, you must
# ensure the labeling matches the default locations labels with the
# following commands:
# semanage fcontext -a -e /var/lib/containers/storage /NEWSTORAGEPATH
# restorecon -R -v /NEWSTORAGEPATH
graphroot = "/var/lib/containers/storage"
# Storage path for rootless users
#
# rootless_storage_path = "$HOME/.local/share/containers/storage"
[storage.options]
# Storage options to be passed to underlying storage drivers
# AdditionalImageStores is used to pass paths to additional Read/Only image stores
# Must be comma separated list.
additionalimagestores = [
"/var/lib/shared",
]
# Allows specification of how storage is populated when pulling images. This
# option can speed the pulling process of images compressed with format
# zstd:chunked. Containers/storage looks for files within images that are being
# pulled from a container registry that were previously pulled to the host. It
# can copy or create a hard link to the existing file when it finds them,
# eliminating the need to pull them from the container registry. These options
# can deduplicate pulling of content, disk storage of content and can allow the
# kernel to use less memory when running containers.
# containers/storage supports four keys
# * enable_partial_images="true" | "false"
# Tells containers/storage to look for files previously pulled in storage
# rather then always pulling them from the container registry.
# * use_hard_links = "false" | "true"
# Tells containers/storage to use hard links rather then create new files in
# the image, if an identical file already existed in storage.
# * ostree_repos = ""
# Tells containers/storage where an ostree repository exists that might have
# previously pulled content which can be used when attempting to avoid
# pulling content from the container registry
pull_options = {enable_partial_images = "false", use_hard_links = "false", ostree_repos=""}
# Remap-UIDs/GIDs is the mapping from UIDs/GIDs as they should appear inside of
# a container, to the UIDs/GIDs as they should appear outside of the container,
# and the length of the range of UIDs/GIDs. Additional mapped sets can be
# listed and will be needed by libraries, but there are limits to the number of
# mappings which the kernel will allow when you later attempt to run a
# container.
#
# remap-uids = 0:1668442479:65536
# remap-gids = 0:1668442479:65536
# Remap-User/Group is a user name which can be used to look up one or more UID/GID
# ranges in the /etc/subuid or /etc/subgid file. Mappings are set up starting
# with an in-container ID of 0 and then a host-level ID taken from the lowest
# range that matches the specified name, and using the length of that range.
# Additional ranges are then assigned, using the ranges which specify the
# lowest host-level IDs first, to the lowest not-yet-mapped in-container ID,
# until all of the entries have been used for maps.
#
# remap-user = "containers"
# remap-group = "containers"
# Root-auto-userns-user is a user name which can be used to look up one or more UID/GID
# ranges in the /etc/subuid and /etc/subgid file. These ranges will be partitioned
# to containers configured to create automatically a user namespace. Containers
# configured to automatically create a user namespace can still overlap with containers
# having an explicit mapping set.
# This setting is ignored when running as rootless.
# root-auto-userns-user = "storage"
#
# Auto-userns-min-size is the minimum size for a user namespace created automatically.
# auto-userns-min-size=1024
#
# Auto-userns-max-size is the minimum size for a user namespace created automatically.
# auto-userns-max-size=65536
[storage.options.overlay]
# ignore_chown_errors can be set to allow a non privileged user running with
# a single UID within a user namespace to run containers. The user can pull
# and use any image even those with multiple uids. Note multiple UIDs will be
# squashed down to the default uid in the container. These images will have no
# separation between the users in the container. Only supported for the overlay
# and vfs drivers.
#ignore_chown_errors = "false"
# Inodes is used to set a maximum inodes of the container image.
# inodes = ""
# Path to an helper program to use for mounting the file system instead of mounting it
# directly.
mount_program = "/usr/bin/fuse-overlayfs"
# mountopt specifies comma separated list of extra mount options
mountopt = "nodev,fsync=0"
# Set to skip a PRIVATE bind mount on the storage home directory.
# skip_mount_home = "false"
# Size is used to set a maximum size of the container image.
# size = ""
# ForceMask specifies the permissions mask that is used for new files and
# directories.
#
# The values "shared" and "private" are accepted.
# Octal permission masks are also accepted.
#
# "": No value specified.
# All files/directories, get set with the permissions identified within the
# image.
# "private": it is equivalent to 0700.
# All files/directories get set with 0700 permissions. The owner has rwx
# access to the files. No other users on the system can access the files.
# This setting could be used with networked based homedirs.
# "shared": it is equivalent to 0755.
# The owner has rwx access to the files and everyone else can read, access
# and execute them. This setting is useful for sharing containers storage
# with other users. For instance have a storage owned by root but shared
# to rootless users as an additional store.
# NOTE: All files within the image are made readable and executable by any
# user on the system. Even /etc/shadow within your image is now readable by
# any user.
#
# OCTAL: Users can experiment with other OCTAL Permissions.
#
# Note: The force_mask Flag is an experimental feature, it could change in the
# future. When "force_mask" is set the original permission mask is stored in
# the "user.containers.override_stat" xattr and the "mount_program" option must
# be specified. Mount programs like "/usr/bin/fuse-overlayfs" present the
# extended attribute permissions to processes within containers rather than the
# "force_mask" permissions.
#
# force_mask = ""
[storage.options.thinpool]
# Storage Options for thinpool
# autoextend_percent determines the amount by which pool needs to be
# grown. This is specified in terms of % of pool size. So a value of 20 means
# that when threshold is hit, pool will be grown by 20% of existing
# pool size.
# autoextend_percent = "20"
# autoextend_threshold determines the pool extension threshold in terms
# of percentage of pool size. For example, if threshold is 60, that means when
# pool is 60% full, threshold has been hit.
# autoextend_threshold = "80"
# basesize specifies the size to use when creating the base device, which
# limits the size of images and containers.
# basesize = "10G"
# blocksize specifies a custom blocksize to use for the thin pool.
# blocksize="64k"
# directlvm_device specifies a custom block storage device to use for the
# thin pool. Required if you setup devicemapper.
# directlvm_device = ""
# directlvm_device_force wipes device even if device already has a filesystem.
# directlvm_device_force = "True"
# fs specifies the filesystem type to use for the base device.
# fs="xfs"
# log_level sets the log level of devicemapper.
# 0: LogLevelSuppress 0 (Default)
# 2: LogLevelFatal
# 3: LogLevelErr
# 4: LogLevelWarn
# 5: LogLevelNotice
# 6: LogLevelInfo
# 7: LogLevelDebug
# log_level = "7"
# min_free_space specifies the min free space percent in a thin pool require for
# new device creation to succeed. Valid values are from 0% - 99%.
# Value 0% disables
# min_free_space = "10%"
# mkfsarg specifies extra mkfs arguments to be used when creating the base
# device.
# mkfsarg = ""
# metadata_size is used to set the `pvcreate --metadatasize` options when
# creating thin devices. Default is 128k
# metadata_size = ""
# Size is used to set a maximum size of the container image.
# size = ""
# use_deferred_removal marks devicemapper block device for deferred removal.
# If the thinpool is in use when the driver attempts to remove it, the driver
# tells the kernel to remove it as soon as possible. Note this does not free
# up the disk space, use deferred deletion to fully remove the thinpool.
# use_deferred_removal = "True"
# use_deferred_deletion marks thinpool device for deferred deletion.
# If the device is busy when the driver attempts to delete it, the driver
# will attempt to delete device every 30 seconds until successful.
# If the program using the driver exits, the driver will continue attempting
# to cleanup the next time the driver is used. Deferred deletion permanently
# deletes the device and all data stored in device will be lost.
# use_deferred_deletion = "True"
# xfs_nospace_max_retries specifies the maximum number of retries XFS should
# attempt to complete IO when ENOSPC (no space) error is returned by
# underlying storage device.
# xfs_nospace_max_retries = "0"

180
examples/templates/kubernetes-with-podman/main.tf
View File

@ -1,180 +0,0 @@
terraform {
required_providers {
coder = {
source = "coder/coder"
}
kubernetes = {
source = "hashicorp/kubernetes"
}
}
}
provider "kubernetes" {
config_path = "~/.kube/config"
}
data "coder_workspace" "me" {}
data "coder_parameter" "os" {
name = "os"
display_name = "Operating system"
description = "The operating system to use for your workspace."
default = "ubuntu"
option {
name = "Ubuntu"
value = "ubuntu"
icon = "/icon/ubuntu.svg"
}
option {
name = "Fedora"
value = "fedora"
icon = "/icon/fedora.svg"
}
}
data "coder_parameter" "cpu" {
name = "cpu"
display_name = "CPU"
description = "The number of CPU cores"
default = "2"
option {
name = "2 Cores"
value = "2"
}
option {
name = "4 Cores"
value = "4"
}
option {
name = "6 Cores"
value = "6"
}
option {
name = "8 Cores"
value = "8"
}
}
data "coder_parameter" "memory" {
name = "memory"
display_name = "Memory"
description = "The amount of memory (in GB)"
default = "2"
option {
name = "2 GB"
value = "2"
}
option {
name = "4 GB"
value = "4"
}
option {
name = "6 GB"
value = "6"
}
option {
name = "8 GB"
value = "8"
}
}
resource "coder_agent" "dev" {
os = "linux"
arch = "amd64"
dir = "/home/podman"
startup_script = <<EOF
#!/bin/sh
# install and start code-server
curl -fsSL https://code-server.dev/install.sh | sh -s -- --method=standalone --prefix=/tmp/code-server --version 4.11.0
/tmp/code-server/bin/code-server --auth none --port 13337 >/tmp/code-server.log 2>&1 &
# Run once to avoid unnecessary warning: "/" is not a shared mount
podman ps
EOF
}
# code-server
resource "coder_app" "code-server" {
agent_id = coder_agent.dev.id
display_name = "code-server"
slug = "code-server"
icon = "/icon/code.svg"
url = "http://localhost:13337"
}
resource "kubernetes_pod" "main" {
count = data.coder_workspace.me.start_count
depends_on = [
kubernetes_persistent_volume_claim.home-directory
]
metadata {
name = "coder-${data.coder_workspace.me.id}"
namespace = "default"
annotations = {
# Disables apparmor, required for Debian- and Ubuntu-derived systems
"container.apparmor.security.beta.kubernetes.io/dev" = "unconfined"
}
}
spec {
security_context {
# Runs as the "podman" user
run_as_user = 1000
fs_group = 1000
}
container {
name = "dev"
# We recommend building your own from our reference: see ./images directory
image = "ghcr.io/coder/podman:${data.coder_parameter.os.value}"
image_pull_policy = "Always"
command = ["/bin/bash", "-c", coder_agent.dev.init_script]
security_context {
# Runs as the "podman" user
run_as_user = "1000"
}
resources {
requests = {
"cpu" = "250m"
"memory" = "500Mi"
}
limits = {
# Acquire a FUSE device, powered by smarter-device-manager
"github.com/fuse" : 1
cpu = "${data.coder_parameter.cpu.value}"
memory = "${data.coder_parameter.memory.value}Gi"
}
}
env {
name = "CODER_AGENT_TOKEN"
value = coder_agent.dev.token
}
volume_mount {
mount_path = "/home/podman"
name = "home-directory"
}
}
volume {
name = "home-directory"
persistent_volume_claim {
claim_name = kubernetes_persistent_volume_claim.home-directory.metadata.0.name
}
}
}
}
resource "kubernetes_persistent_volume_claim" "home-directory" {
metadata {
name = "coder-pvc-${data.coder_workspace.me.id}"
namespace = "default"
}
spec {
access_modes = ["ReadWriteOnce"]
resources {
requests = {
storage = "10Gi"
}
}
}
}

133
examples/templates/kubernetes/README.md
View File

@ -1,127 +1,38 @@
---
name: Develop in Kubernetes
description: Get started with Kubernetes development.
tags: [cloud, kubernetes]
icon: /icon/k8s.png
display_name: Kubernetes (Deployment)
description: Provision Kubernetes Deployments as Coder workspaces
icon: ../../../site/static/icon/k8s.png
maintainer_github: coder
verified: true
tags: [kubernetes, container]
---
# Getting started
# Remote Development on Kubernetes Pods
This template creates a deployment running the `codercom/enterprise-base:ubuntu` image.
Provision Kubernetes Pods as [Coder workspaces](https://coder.com/docs/coder-v2/latest) with this example template.
<!-- TODO: Add screenshot -->
## Prerequisites
This template uses [`kubernetes_deployment`](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs/resources/deployment) terraform resource, which requires the `coder` service account to have permission to create deploymnets. For example if you are using [helm](https://coder.com/docs/v2/latest/install/kubernetes#install-coder-with-helm) to install Coder, you should set `coder.serviceAccount.enableDeployments=true` in your `values.yaml`
### Infrastructure
```diff
coder:
serviceAccount:
workspacePerms: true
- enableDeployments: false
+ enableDeployments: true
annotations: {}
name: coder
```
**Cluster**: This template requires an existing Kubernetes cluster
> Note: This is only required for Coder versions < 0.28.0, as this will be the default value for Coder versions >= 0.28.0
**Container Image**: This template uses the [codercom/enterprise-base:ubuntu image](https://github.com/coder/enterprise-images/tree/main/images/base) with some dev tools preinstalled. To add additional tools, extend this image or build it yourself.
## Authentication
### Authentication
This template can authenticate using in-cluster authentication, or using a kubeconfig local to the
Coder host. For additional authentication options, consult the [Kubernetes provider
documentation](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs).
This template authenticates using a `~/.kube/config`, if present on the server, or via built-in authentication if the Coder provisioner is running on Kubernetes with an authorized ServiceAccount. To use another [authentication method](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs#authentication), edit the template.
### kubeconfig on Coder host
## Architecture
If the Coder host has a local `~/.kube/config`, you can use this to authenticate
with Coder. Make sure this is done with same user that's running the `coder` service.
This template provisions the following resources:
To use this authentication, set the parameter `use_kubeconfig` to true.
- Kubernetes pod (ephemeral)
- Kubernetes persistent volume claim (persistent on `/home/coder`)
### In-cluster authentication
This means, when the workspace restarts, any tools or files outside of the home directory are not persisted. To pre-bake tools into the workspace (e.g. `python3`), modify the container image. Alternatively, individual developers can [personalize](https://coder.com/docs/v2/latest/dotfiles) their workspaces with dotfiles.
If the Coder host runs in a Pod on the same Kubernetes cluster as you are creating workspaces in,
you can use in-cluster authentication.
To use this authentication, set the parameter `use_kubeconfig` to false.
The Terraform provisioner will automatically use the service account associated with the pod to
authenticate to Kubernetes. Be sure to bind a [role with appropriate permission](#rbac) to the
service account. For example, assuming the Coder host runs in the same namespace as you intend
to create workspaces:
```yaml
apiVersion: v1
kind: ServiceAccount
metadata:
name: coder
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: coder
subjects:
- kind: ServiceAccount
name: coder
roleRef:
kind: Role
name: coder
apiGroup: rbac.authorization.k8s.io
```
Then start the Coder host with `serviceAccountName: coder` in the pod spec.
### Authenticate against external clusters
You may want to deploy workspaces on a cluster outside of the Coder control plane. Refer to the [Coder docs](https://coder.com/docs/v2/latest/platforms/kubernetes/additional-clusters) to learn how to modify your template to authenticate against external clusters.
## Namespace
The target namespace in which the deployment will be deployed is defined via the `coder_workspace`
variable. The namespace must exist prior to creating workspaces.
## Persistence
The `/home/coder` directory in this example is persisted via the attached PersistentVolumeClaim.
Any data saved outside of this directory will be wiped when the workspace stops.
Since most binary installations and environment configurations live outside of
the `/home` directory, we suggest including these in the `startup_script` argument
of the `coder_agent` resource block, which will run each time the workspace starts up.
For example, when installing the `aws` CLI, the install script will place the
`aws` binary in `/usr/local/bin/aws`. To ensure the `aws` CLI is persisted across
workspace starts/stops, include the following code in the `coder_agent` resource
block of your workspace template:
```terraform
resource "coder_agent" "main" {
startup_script = <<-EOT
set -e
# install AWS CLI
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install
EOT
}
```
## code-server
`code-server` is installed via the `startup_script` argument in the `coder_agent`
resource block. The `coder_app` resource is defined to access `code-server` through
the dashboard UI over `localhost:13337`.
## Deployment logs
To stream kubernetes pods events from the deployment, you can use Coder's [`coder-logstream-kube`](https://github.com/coder/coder-logstream-kube) tool. This can stream logs from the deployment to Coder's workspace startup logs. You just need to install the `coder-logstream-kube` helm chart on the cluster where the deployment is running.
```shell
helm repo add coder-logstream-kube https://helm.coder.com/logstream-kube
helm install coder-logstream-kube coder-logstream-kube/coder-logstream-kube \
--namespace coder \
--set url=<your-coder-url-including-http-or-https>
```
For detailed instructions, see [Deployment logs](https://coder.com/docs/v2/latest/platforms/kubernetes/deployment-logs)
> **Note**
> This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.

19
examples/templates/nomad-docker/README.md
View File

@ -1,13 +1,20 @@
---
name: Develop in a Nomad Docker Container
description: Get started with Nomad Workspaces.
tags: [cloud, nomad]
icon: /icon/nomad.svg
display_name: Nomad
description: Provision Nomad Jobs as Coder workspaces
icon: ../../../site/static/icon/nomad.svg
maintainer_github: coder
verified: true
tags: [nomad, container]
---
# Develop in a Nomad Docker Container
# Remote Development on Nomad
This example shows how to use Nomad service tasks to be used as a development environment using docker and host csi volumes.
Provision Nomad Jobs as [Coder workspaces](https://coder.com/docs/coder-v2/latest) with this example template. This example shows how to use Nomad service tasks to be used as a development environment using docker and host csi volumes.
<!-- TODO: Add screenshot -->
> **Note**
> This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.
## Prerequisites

8
scripts/examplegen/main.go
View File

@ -67,7 +67,7 @@ func run() error {
return xerrors.Errorf("parse example %q front matter: %w", exampleID, err)
}
nameRaw, exists := frontMatter.FrontMatter["name"]
nameRaw, exists := frontMatter.FrontMatter["display_name"]
if !exists {
return xerrors.Errorf("example %q front matter does not contain name", exampleID)
}
@ -110,6 +110,12 @@ func run() error {
if !valid {
return xerrors.Errorf("example %q icon isn't a string", exampleID)
}
icon, err = filepath.Rel("../site/static/", filepath.Join(examplesDir, name, icon))
if err != nil {
return xerrors.Errorf("example %q icon is not in site/static: %w", exampleID, err)
}
// The FE needs a static path!
icon = "/" + icon
}
examples = append(examples, codersdk.TemplateExample{