From 2e86b76fb8e09ae039eae208a3f169607dbc9bf4 Mon Sep 17 00:00:00 2001 From: Ben Potter Date: Sun, 17 Dec 2023 08:05:13 -0600 Subject: [PATCH] docs: improve structure for example templates (#9842) Co-authored-by: Kyle Carberry Co-authored-by: Muhammad Atif Ali Co-authored-by: Muhammad Atif Ali --- .../coder_templates_init_--help.golden | 2 +- docs/cli/templates_init.md | 6 +- docs/dotfiles.md | 2 - docs/platforms/jfrog.md | 4 +- docs/templates/docker-in-workspaces.md | 4 +- examples/examples.gen.json | 130 +++++----- examples/examples.go | 2 - .../{templates => }/jfrog/docker/README.md | 0 .../jfrog/docker/build/Dockerfile | 0 examples/{templates => }/jfrog/docker/main.tf | 0 examples/{templates => }/jfrog/remote/main.tf | 0 examples/templates/README.md | 4 +- .../templates/aws-ecs-container/README.md | 24 -- examples/templates/aws-ecs-container/main.tf | 135 ---------- examples/templates/aws-linux/README.md | 41 ++- examples/templates/aws-linux/main.tf | 51 ++-- examples/templates/aws-windows/README.md | 47 +++- examples/templates/azure-linux/README.md | 41 ++- examples/templates/azure-windows/README.md | 36 ++- .../templates/devcontainer-docker/README.md | 58 +++-- .../devcontainer-kubernetes/README.md | 41 ++- examples/templates/do-linux/README.md | 48 ++-- .../templates/docker-with-dotfiles/README.md | 39 --- .../templates/docker-with-dotfiles/main.tf | 138 ----------- examples/templates/docker/README.md | 69 +++--- examples/templates/envbox/README.md | 9 + examples/templates/gcp-linux/README.md | 31 ++- examples/templates/gcp-vm-container/README.md | 32 ++- examples/templates/gcp-windows/README.md | 37 ++- .../kubernetes-with-podman/README.md | 102 -------- .../images/Dockerfile.fedora | 35 --- .../images/Dockerfile.ubuntu | 59 ----- .../images/containers.conf | 16 -- .../images/storage.conf | 233 ------------------ .../templates/kubernetes-with-podman/main.tf | 180 -------------- examples/templates/kubernetes/README.md | 133 ++-------- examples/templates/nomad-docker/README.md | 19 +- scripts/examplegen/main.go | 8 +- 38 files changed, 473 insertions(+), 1343 deletions(-) rename examples/{templates => }/jfrog/docker/README.md (100%) rename examples/{templates => }/jfrog/docker/build/Dockerfile (100%) rename examples/{templates => }/jfrog/docker/main.tf (100%) rename examples/{templates => }/jfrog/remote/main.tf (100%) delete mode 100644 examples/templates/aws-ecs-container/README.md delete mode 100644 examples/templates/aws-ecs-container/main.tf delete mode 100644 examples/templates/docker-with-dotfiles/README.md delete mode 100644 examples/templates/docker-with-dotfiles/main.tf delete mode 100644 examples/templates/kubernetes-with-podman/README.md delete mode 100644 examples/templates/kubernetes-with-podman/images/Dockerfile.fedora delete mode 100644 examples/templates/kubernetes-with-podman/images/Dockerfile.ubuntu delete mode 100644 examples/templates/kubernetes-with-podman/images/containers.conf delete mode 100644 examples/templates/kubernetes-with-podman/images/storage.conf delete mode 100644 examples/templates/kubernetes-with-podman/main.tf diff --git a/cli/testdata/coder_templates_init_--help.golden b/cli/testdata/coder_templates_init_--help.golden index c46f383c29..6d32c3a310 100644 --- a/cli/testdata/coder_templates_init_--help.golden +++ b/cli/testdata/coder_templates_init_--help.golden @@ -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. ——— diff --git a/docs/cli/templates_init.md b/docs/cli/templates_init.md index 76cea7242c..fb5df7fbfa 100644 --- a/docs/cli/templates_init.md +++ b/docs/cli/templates_init.md @@ -14,8 +14,8 @@ coder templates init [flags] [directory] ### --id -| | | -| ---- | ---------------------------- | --------- | ----------- | ----------- | -------- | ------ | -------------------- | --------- | ---------------- | ----------- | ---------- | -------------------- | -| Type | 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] | +| | | +| ---- | -------------------- | ----------- | ----------- | -------- | ------ | --------- | ---------------- | ----------- | ---------- | -------------------- | +| Type | enum[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. diff --git a/docs/dotfiles.md b/docs/dotfiles.md index 7ce12f5b22..ba5409ccd1 100644 --- a/docs/dotfiles.md +++ b/docs/dotfiles.md @@ -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. diff --git a/docs/platforms/jfrog.md b/docs/platforms/jfrog.md index d25cd491be..5862bd915d 100644 --- a/docs/platforms/jfrog.md +++ b/docs/platforms/jfrog.md @@ -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 diff --git a/docs/templates/docker-in-workspaces.md b/docs/templates/docker-in-workspaces.md index 9388450ae7..d6a873c68f 100644 --- a/docs/templates/docker-in-workspaces.md +++ b/docs/templates/docker-in-workspaces.md @@ -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 diff --git a/examples/examples.gen.json b/examples/examples.gen.json index 4dff0ecc53..cff675d1ad 100644 --- a/examples/examples.gen.json +++ b/examples/examples.gen.json @@ -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" } ] diff --git a/examples/examples.go b/examples/examples.go index 016804a073..5603f7db26 100644 --- a/examples/examples.go +++ b/examples/examples.go @@ -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 diff --git a/examples/templates/jfrog/docker/README.md b/examples/jfrog/docker/README.md similarity index 100% rename from examples/templates/jfrog/docker/README.md rename to examples/jfrog/docker/README.md diff --git a/examples/templates/jfrog/docker/build/Dockerfile b/examples/jfrog/docker/build/Dockerfile similarity index 100% rename from examples/templates/jfrog/docker/build/Dockerfile rename to examples/jfrog/docker/build/Dockerfile diff --git a/examples/templates/jfrog/docker/main.tf b/examples/jfrog/docker/main.tf similarity index 100% rename from examples/templates/jfrog/docker/main.tf rename to examples/jfrog/docker/main.tf diff --git a/examples/templates/jfrog/remote/main.tf b/examples/jfrog/remote/main.tf similarity index 100% rename from examples/templates/jfrog/remote/main.tf rename to examples/jfrog/remote/main.tf diff --git a/examples/templates/README.md b/examples/templates/README.md index e95d0d822f..38ade2345d 100644 --- a/examples/templates/README.md +++ b/examples/templates/README.md @@ -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 ``` diff --git a/examples/templates/aws-ecs-container/README.md b/examples/templates/aws-ecs-container/README.md deleted file mode 100644 index d93be65083..0000000000 --- a/examples/templates/aws-ecs-container/README.md +++ /dev/null @@ -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`. diff --git a/examples/templates/aws-ecs-container/main.tf b/examples/templates/aws-ecs-container/main.tf deleted file mode 100644 index ee1ebae0d7..0000000000 --- a/examples/templates/aws-ecs-container/main.tf +++ /dev/null @@ -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 - } -} diff --git a/examples/templates/aws-linux/README.md b/examples/templates/aws-linux/README.md index d3de4e849f..1854381f47 100644 --- a/examples/templates/aws-linux/README.md +++ b/examples/templates/aws-linux/README.md @@ -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 + -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` diff --git a/examples/templates/aws-linux/main.tf b/examples/templates/aws-linux/main.tf index de8f446d05..0f5bc5f0f5 100644 --- a/examples/templates/aws-linux/main.tf +++ b/examples/templates/aws-linux/main.tf @@ -212,36 +212,35 @@ resource "coder_app" "code-server" { locals { linux_user = "coder" - user_data = data.coder_workspace.me.start_count > 0 ? trimspace(< -## 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`. diff --git a/examples/templates/azure-linux/README.md b/examples/templates/azure-linux/README.md index 067631329e..ae875ce2ca 100644 --- a/examples/templates/azure-linux/README.md +++ b/examples/templates/azure-linux/README.md @@ -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 + + +## 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=` 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`. diff --git a/examples/templates/azure-windows/README.md b/examples/templates/azure-windows/README.md index 768e5f5e9e..f4de2a1942 100644 --- a/examples/templates/azure-windows/README.md +++ b/examples/templates/azure-windows/README.md @@ -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 + + +## 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=` 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. diff --git a/examples/templates/devcontainer-docker/README.md b/examples/templates/devcontainer-docker/README.md index bedbd0b0df..54c27a9b4d 100644 --- a/examples/templates/devcontainer-docker/README.md +++ b/examples/templates/devcontainer-docker/README.md @@ -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. + -## 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. diff --git a/examples/templates/devcontainer-kubernetes/README.md b/examples/templates/devcontainer-kubernetes/README.md index 6d95a668fe..a7c5cb1e12 100644 --- a/examples/templates/devcontainer-kubernetes/README.md +++ b/examples/templates/devcontainer-kubernetes/README.md @@ -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. + -## 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. diff --git a/examples/templates/do-linux/README.md b/examples/templates/do-linux/README.md index 8d0314fe3d..2d0df419aa 100644 --- a/examples/templates/do-linux/README.md +++ b/examples/templates/do-linux/README.md @@ -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. + + + +## 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. diff --git a/examples/templates/docker-with-dotfiles/README.md b/examples/templates/docker-with-dotfiles/README.md deleted file mode 100644 index 735416f1f5..0000000000 --- a/examples/templates/docker-with-dotfiles/README.md +++ /dev/null @@ -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). diff --git a/examples/templates/docker-with-dotfiles/main.tf b/examples/templates/docker-with-dotfiles/main.tf deleted file mode 100644 index 956a4308b9..0000000000 --- a/examples/templates/docker-with-dotfiles/main.tf +++ /dev/null @@ -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 - } -} diff --git a/examples/templates/docker/README.md b/examples/templates/docker/README.md index 052be54cd4..8f4de21e81 100644 --- a/examples/templates/docker/README.md +++ b/examples/templates/docker/README.md @@ -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 + + +## 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! diff --git a/examples/templates/envbox/README.md b/examples/templates/envbox/README.md index 29e1bd95c1..d5632294d6 100644 --- a/examples/templates/envbox/README.md +++ b/examples/templates/envbox/README.md @@ -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 diff --git a/examples/templates/gcp-linux/README.md b/examples/templates/gcp-linux/README.md index 7d84970cc5..15df06f70a 100644 --- a/examples/templates/gcp-linux/README.md +++ b/examples/templates/gcp-linux/README.md @@ -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` diff --git a/examples/templates/gcp-vm-container/README.md b/examples/templates/gcp-vm-container/README.md index 5568642a35..8c0826f1a4 100644 --- a/examples/templates/gcp-vm-container/README.md +++ b/examples/templates/gcp-vm-container/README.md @@ -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` diff --git a/examples/templates/gcp-windows/README.md b/examples/templates/gcp-windows/README.md index a0d55a0e1e..cbe1048b2d 100644 --- a/examples/templates/gcp-windows/README.md +++ b/examples/templates/gcp-windows/README.md @@ -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`. diff --git a/examples/templates/kubernetes-with-podman/README.md b/examples/templates/kubernetes-with-podman/README.md deleted file mode 100644 index d29a9ce7da..0000000000 --- a/examples/templates/kubernetes-with-podman/README.md +++ /dev/null @@ -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`. diff --git a/examples/templates/kubernetes-with-podman/images/Dockerfile.fedora b/examples/templates/kubernetes-with-podman/images/Dockerfile.fedora deleted file mode 100644 index 54a252ced7..0000000000 --- a/examples/templates/kubernetes-with-podman/images/Dockerfile.fedora +++ /dev/null @@ -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="" diff --git a/examples/templates/kubernetes-with-podman/images/Dockerfile.ubuntu b/examples/templates/kubernetes-with-podman/images/Dockerfile.ubuntu deleted file mode 100644 index 1dcada898b..0000000000 --- a/examples/templates/kubernetes-with-podman/images/Dockerfile.ubuntu +++ /dev/null @@ -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 diff --git a/examples/templates/kubernetes-with-podman/images/containers.conf b/examples/templates/kubernetes-with-podman/images/containers.conf deleted file mode 100644 index e4aee2bdf2..0000000000 --- a/examples/templates/kubernetes-with-podman/images/containers.conf +++ /dev/null @@ -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" diff --git a/examples/templates/kubernetes-with-podman/images/storage.conf b/examples/templates/kubernetes-with-podman/images/storage.conf deleted file mode 100644 index bfbe0bdd6c..0000000000 --- a/examples/templates/kubernetes-with-podman/images/storage.conf +++ /dev/null @@ -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" diff --git a/examples/templates/kubernetes-with-podman/main.tf b/examples/templates/kubernetes-with-podman/main.tf deleted file mode 100644 index 2a041c1e8d..0000000000 --- a/examples/templates/kubernetes-with-podman/main.tf +++ /dev/null @@ -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 = </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" - } - } - } -} diff --git a/examples/templates/kubernetes/README.md b/examples/templates/kubernetes/README.md index 28bb1135d4..8d5ee5f13c 100644 --- a/examples/templates/kubernetes/README.md +++ b/examples/templates/kubernetes/README.md @@ -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. + + ## 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= -``` - -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. diff --git a/examples/templates/nomad-docker/README.md b/examples/templates/nomad-docker/README.md index f676ed3aac..b5ce534483 100644 --- a/examples/templates/nomad-docker/README.md +++ b/examples/templates/nomad-docker/README.md @@ -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. + + + +> **Note** +> This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case. ## Prerequisites diff --git a/scripts/examplegen/main.go b/scripts/examplegen/main.go index 5106bf0a50..1b59632662 100644 --- a/scripts/examplegen/main.go +++ b/scripts/examplegen/main.go @@ -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{