diff --git a/docs/about/screenshots.md b/docs/about/screenshots.md index dff7ea75946d8..d0a0591c81958 100644 --- a/docs/about/screenshots.md +++ b/docs/about/screenshots.md @@ -14,10 +14,11 @@ via their browser to access their Workspaces. Developers provision their own ephemeral Workspaces in minutes using pre-defined Templates that include approved tooling and infrastructure. -![Template administrators can either create a new Template from scratch or choose a Starter Template](../images/screenshots/starter-templates.png) +![Template administrators create templates using the template builder, which guides them through selecting base infrastructure and adding modules.](../images/templatebuilder_01_bases.png) -Template administrators can either create a new Template from scratch or choose -a Starter Template. +Template administrators create templates using the template builder, which +guides them through selecting base infrastructure and adding modules. Templates +can also be created from scratch or uploaded directly. ![Templates define the underlying infrastructure that Coder Workspaces run on.](../images/screenshots/terraform.png) diff --git a/docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md b/docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md index 326e0857b2676..07f98a8117d7c 100644 --- a/docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md +++ b/docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md @@ -14,22 +14,11 @@ choose a template from the ## Dashboard -1. In the Coder dashboard, select **Templates** then **Create Template**. -1. Use a - [starter template](../../../../../examples/templates) - or create a new template: - - - Starter template: - - 1. Select **Choose a starter template**. - 1. Choose a template from the list or select **Devcontainer** from the - sidebar to display only dev container-compatible templates. - 1. Select **Use template**, enter the details, then select **Create - template**. - - - To create a new template, select **From scratch** and enter the templates - details, then select **Create template**. - +1. In the Coder dashboard, select **Templates** > **New Template**. + The template builder opens. +1. The template builder does not currently include dev-container-compatible base templates. + Select **Upload an existing template** at the bottom of the page to upload your Terraform files directly. +1. Upload your `.zip` or `.tar.gz` file, enter the details, then select **Create template**. 1. Edit the template files to fit your deployment. ## CLI diff --git a/docs/admin/templates/creating-templates.md b/docs/admin/templates/creating-templates.md index 6387cc0368c35..9b10855787228 100644 --- a/docs/admin/templates/creating-templates.md +++ b/docs/admin/templates/creating-templates.md @@ -9,28 +9,93 @@ In most cases, it is best to start with a starter template.
-### Web UI +### Template builder + +The template builder is the recommended way to create templates in Coder. It +guides you through selecting a base infrastructure template, adding modules +(IDEs, tools, integrations), and configuring your template, all without writing +Terraform. + +The template builder is enabled by default. When you select **New Template** on +the **Templates** page, the builder opens automatically. + +The builder guides you through up to five steps: + +1. **Select base infrastructure**: Choose a starter template for your target + platform (e.g. Docker, AWS EC2, Kubernetes). Each base template provides a + working foundation with the Coder agent pre-configured. + + ![Select a base infrastructure template in the template builder](../../images/templatebuilder_01_bases.png) + +1. **Base template parameters** *(optional)*: If the selected base template + declares configurable variables, you can supply values for them here. + If the base template has no parameters, this step is skipped automatically. + +1. **Select modules**: Pick from a curated list of + [registry modules](https://registry.coder.com) to add IDEs, AI agents, + source control integrations, and other tools. Modules are grouped by + category and filtered for compatibility with the selected base template's + operating system. You can select multiple modules. -After navigating to the Templates page in the Coder dashboard, choose -`Create Template > Choose a starter template`. + ![Select modules to add to your template](../../images/templatebuilder_02_modules.png) -![Create a template](../../images/admin/templates/create-template.png) +1. **Module settings** *(optional)*: Configure variables for the modules you + selected. Required variables without defaults must be filled in before you + can proceed. Modules that require secrets (such as API keys) display a + notice that developers will be prompted for the value at workspace creation + time. -From there, select a starter template for desired underlying infrastructure for -workspaces. + ![Configure module settings](../../images/templatebuilder_03_module_customization.png) -![Starter templates](../../images/admin/templates/starter-templates.png) +1. **Template customizations**: Set the template's display name, description, + icon, and organization, then select **Create Template**. -Give your template a name, description, and icon and press `Create template`. + ![Set template display name, description, and other metadata](../../images/templatebuilder_04_customizations.png) -![Name and icon](../../images/admin/templates/import-template.png) +After you select **Create Template**, Coder composes the Terraform +configuration server-side, validates it with `terraform init` and +`terraform validate`, and creates the template. The generated template is +standard Terraform HCL that you can edit later through the dashboard or CLI. -If template creation fails, it's likely that Coder is not authorized to deploy infrastructure in the given location. -Learn how to configure [provisioner authentication](./extending-templates/provider-authentication.md). +> [!NOTE] +> The template builder requires outbound access to `registry.coder.com` so +> that `terraform init` can resolve module sources. For air-gapped or +> restricted-egress deployments, visit +> [Air-gapped deployments](../../install/airgap.md#template-builder). + +If you select modules that are known to conflict with each other, the builder +displays a warning. Module conflicts do not block template creation, but you +should review the warning before proceeding. + +#### Disabling the template builder + +Operators can disable the template builder by setting the +`CODER_DISABLE_TEMPLATE_BUILDER` environment variable or the +`--disable-template-builder` server flag. When disabled, the **New Template** +button links to the starter templates page instead, and the +`/api/v2/templatebuilder/*` endpoints return 404. + +Deployments using a self-hosted module registry mirror can set +`CODER_TEMPLATE_BUILDER_REGISTRY_URL` to point generated module source paths at +the mirror instead of `registry.coder.com`. + +#### Alternative creation methods + +The template builder's first step also links to alternative creation paths: + +- **Upload an existing template**: Upload a `.tar.gz` or `.zip` of Terraform + files you have authored locally. +- **Start from scratch**: Follow the + [template from scratch tutorial](../../tutorials/template-from-scratch.md) to + write Terraform by hand. +- **Browse community templates**: Browse the + [Coder Registry](https://registry.coder.com/templates) for community and + official templates. ### CLI -You can the [Coder CLI](../../install/cli.md) to manage templates for Coder. +You can use the [Coder CLI](../../install/cli.md) to manage templates for Coder. + After [logging in](../../reference/cli/login.md) to your deployment, create a folder to store your templates: @@ -63,8 +128,9 @@ Next, push it to Coder with the coder templates push ``` -If `template push` fails, it's likely that Coder is not authorized to deploy infrastructure in the given location. -Learn how to configure [provisioner authentication](../provisioners/index.md). +If `templates push` fails, it is likely that Coder is not authorized to deploy +infrastructure in the given location. Learn how to configure +[provisioner authentication](../provisioners/index.md). You can edit the metadata of the template such as the display name with the [`templates edit`](../../reference/cli/templates_edit.md) command: @@ -85,7 +151,7 @@ to manage templates via GitOps. ## From an existing template -You can duplicate an existing template in your Coder deployment. This will copy +You can duplicate an existing template in your Coder deployment. This copies the template code and metadata, allowing you to make changes without affecting the original template. diff --git a/docs/admin/templates/index.md b/docs/admin/templates/index.md index 138bfdbb98dce..0aec788a545f0 100644 --- a/docs/admin/templates/index.md +++ b/docs/admin/templates/index.md @@ -4,9 +4,10 @@ Templates are written in [Terraform](https://developer.hashicorp.com/terraform/intro) and define the underlying infrastructure that all Coder workspaces run on. -![Starter templates](../../images/admin/templates/starter-templates.png) - -The "Starter Templates" page within the Coder dashboard. +The [template builder](./creating-templates.md#template-builder) is +the recommended way to create templates. It guides you through selecting base +infrastructure, adding modules, and configuring your template without writing +Terraform. ## Learn the concepts @@ -18,12 +19,14 @@ If you are unfamiliar with Terraform, see [Hashicorp's Tutorials](https://developer.hashicorp.com/terraform/tutorials) for common cloud providers. -## Starter templates +## Create a template -After learning the basics, use starter templates to import a template with -sensible defaults for popular platforms (e.g. AWS, Kubernetes, Docker, etc). -Docs: -[Create a template from a starter template](./creating-templates.md#from-a-starter-template). +The fastest way to get started is with the +[template builder](./creating-templates.md#template-builder), which +composes a working template from a base infrastructure template and optional +registry modules. Starter templates for popular platforms (AWS, Kubernetes, +Docker, and others) are available as base templates in the builder, or through +the [CLI](./creating-templates.md#cli). ## Extending templates diff --git a/docs/admin/templates/managing-templates/index.md b/docs/admin/templates/managing-templates/index.md index d4fcb8fbc0a63..63549f3251dd7 100644 --- a/docs/admin/templates/managing-templates/index.md +++ b/docs/admin/templates/managing-templates/index.md @@ -14,18 +14,21 @@ any developer to propose changes to a template. You can give different users and groups access to templates with [role-based access control](../template-permissions.md). -## Starter templates +## Creating templates -We provide starter templates for common cloud providers, like AWS, and -orchestrators, like Kubernetes. From there, you can modify them to use your own -images, VPC, cloud credentials, and so on. Coder supports all Terraform -resources and properties, so fear not if your favorite cloud provider isn't -here! +The [template builder](../creating-templates.md#template-builder) is +the recommended way to create templates. It guides you through selecting a base +infrastructure template, adding modules (IDEs, tools, integrations), and +configuring template settings without writing Terraform. -![Starter templates](../../../images/start/starter-templates.png) +Starter templates for common cloud providers (AWS, Azure) and orchestrators +(Kubernetes, Docker) are available as base templates within the builder. You can +modify the generated template to use your own images, VPC, cloud credentials, +and so on. Coder supports all Terraform resources and properties. If you prefer to use Coder on the -[command line](../../../reference/cli/index.md), `coder templates init`. +[command line](../../../reference/cli/index.md), use `coder templates init` to +pull a starter template, then `coder templates push` to upload it. Coder starter templates are also available on our [GitHub repo](../../../../examples/templates). @@ -38,7 +41,7 @@ by our users ## Editing templates -Our starter templates are meant to be modified for your use cases. You can edit +Our templates are meant to be modified for your use cases. You can edit any template's files directly in the Coder dashboard. ![Editing a template](../../../images/templates/choosing-edit-template.gif) diff --git a/docs/get-started/index.md b/docs/get-started/index.md index 48fb949c041f2..f5b3848707c78 100644 --- a/docs/get-started/index.md +++ b/docs/get-started/index.md @@ -215,34 +215,43 @@ lines of output, so you might have to scroll up to find it. > [!TIP] > If you use an AI coding assistant, the [coder-templates](https://github.com/coder/registry/blob/main/.agents/skills/coder-templates/SKILL.md) agent skill can guide you through creating and customizing templates with best practices built-in. -Templates define what's in your development environment. The following is a basic example: +Templates define what's in your development environment. The template builder +guides you through creating one without writing any Terraform. -1. Select **Templates** → **New Template**. +1. Select **Templates** > **New Template**. The template builder opens. -2. Select the **Coder Quickstart** template from the list of starter templates. +1. Select the **Docker** base template from the list. - **Note:** running this template requires Docker to be running in the background, so make sure Docker is running! + > [!NOTE] + > This template requires Docker to be running in the background, so make sure Docker is running. -3. Name your template. - The **Display name** and **Description** are pre-filled from the starter template, so you can keep the defaults or replace them: - - **Name**: `quickstart` - - **Display name**: `Coder Quickstart` - - **Description**: `Get started with Coder by picking your languages, editors, and a repo` +1. Skip or configure any base template parameters, then select modules to add + IDEs and tools to your template. For example, add **code-server** to get + VS Code in the browser. You can skip module selection for now and add + modules later. -4. Select **Save**. +1. On the final step, name your template: + - **Name**: `my-docker-template` + - **Display name** and **Description**: fill in as you like. - ![Create template](../images/screenshots/create-quickstart-template.png) +1. Select **Create Template**. Coder composes and validates the Terraform + configuration, then creates your template. + + ![Template builder base selection step](../images/templatebuilder_01_bases.png) **What just happened?** -You defined a template, a reusable blueprint for dev environments, in your Coder deployment. -It's now stored in your organization's template list, where you and any teammates in the same organization can create workspaces from it. +The template builder selected a base infrastructure template, composed it with +any modules you chose, and generated a valid Terraform configuration. Coder +validated the configuration server-side, then created a reusable template in +your organization's template list. You and any teammates in the same +organization can now create workspaces from it.
What happens under the hood? A Coder template is a [Terraform](https://developer.hashicorp.com/terraform/intro) configuration, and Coder is built on top of Terraform. When you create a workspace from this template, a Coder [provisioner](../admin/infrastructure/architecture.md#provisionerd) runs a Terraform job from the template's configuration to build your environment. -For the Coder Quickstart template, that job starts a Docker container, connects the Coder agent, and runs a startup script that installs the programming languages and editors you choose in the next step. +For the Docker base template, that job starts a Docker container with the Coder agent pre-configured, along with any modules you selected. To learn how Coder uses Terraform to provision and run workspaces, refer to the [architecture overview](../admin/infrastructure/architecture.md). @@ -254,19 +263,15 @@ Now it's time to launch a workspace. 1. After the template is ready, select **+ Create Workspace**. -2. Give the workspace a name. If you need a suggestion for a workspace, you can select the automatically generated name next to the **Need a suggestion?** label. - -3. In this window are [parameters](../admin/templates/extending-templates/parameters.md) that customize the workspace's behavior. Set the following based on your needs: - - - **Programming Languages**: the languages to pre-install in your workspace. You can use more than one if you want. - - **IDEs & Editors**: the IDEs and editors you want to configure for quick access once the workspace is running. You can choose more than one if you want. - - **Git Repository (Optional)**: the Git repository you want to clone into your workspace. Leave this field blank to skip it. - - **Note:** If you use any of the JetBrains IDEs as your preferred IDE (such as PyCharm, GoLand, or RustRover), select **JetBrains IDEs** as the value. A new parameter will appear, with which you can choose your preferred JetBrains IDE. +1. Give the workspace a name. If you need a suggestion, you can select the + automatically generated name next to the **Need a suggestion?** label. - ![Workspace creation screen](../images/screenshots/create-workspace.png)_Workspace creation screen_ +1. If the template has any + [parameters](../admin/templates/extending-templates/parameters.md), fill + them in. Parameters vary by template and the modules you selected in the + builder. -4. Launch your workspace by selecting **Create workspace**. +1. Select **Create workspace**. After a short wait (10-15 seconds on most modern computers), Coder will start your new workspace: @@ -275,7 +280,7 @@ After a short wait (10-15 seconds on most modern computers), Coder will start yo ## Step 6: Connect your IDE Each button in the workspace view is a different **agent app**. -The buttons you see reflect the editors you selected in the **IDEs & Editors** parameter in [Step 5](#step-5-launch-your-workspace). +The buttons in the UI reflect the modules you added in the template builder (such as code-server, Claude Code, or any of the JetBrains editors). Select your preferred IDE from the list of agent apps. This guide uses **VS Code Desktop**, which opens the workspace in the VS Code installed on your local machine, using the Coder extension. diff --git a/docs/images/admin/templates/create-template.png b/docs/images/admin/templates/create-template.png deleted file mode 100644 index d9cbd8ff615d8..0000000000000 Binary files a/docs/images/admin/templates/create-template.png and /dev/null differ diff --git a/docs/images/admin/templates/import-template.png b/docs/images/admin/templates/import-template.png deleted file mode 100644 index 3378709562592..0000000000000 Binary files a/docs/images/admin/templates/import-template.png and /dev/null differ diff --git a/docs/images/admin/templates/starter-templates.png b/docs/images/admin/templates/starter-templates.png deleted file mode 100644 index 02bbe2c9ca3e9..0000000000000 Binary files a/docs/images/admin/templates/starter-templates.png and /dev/null differ diff --git a/docs/images/screenshots/create-quickstart-template.png b/docs/images/screenshots/create-quickstart-template.png deleted file mode 100644 index ced09ecd599d8..0000000000000 Binary files a/docs/images/screenshots/create-quickstart-template.png and /dev/null differ diff --git a/docs/images/screenshots/starter-templates.png b/docs/images/screenshots/starter-templates.png deleted file mode 100644 index 51ac42c4bce5f..0000000000000 Binary files a/docs/images/screenshots/starter-templates.png and /dev/null differ diff --git a/docs/images/start/create-template.png b/docs/images/start/create-template.png deleted file mode 100644 index 4e078a0c5a451..0000000000000 Binary files a/docs/images/start/create-template.png and /dev/null differ diff --git a/docs/images/start/starter-templates.png b/docs/images/start/starter-templates.png deleted file mode 100644 index 2fb98b37e0011..0000000000000 Binary files a/docs/images/start/starter-templates.png and /dev/null differ diff --git a/docs/images/templatebuilder_01_bases.png b/docs/images/templatebuilder_01_bases.png new file mode 100644 index 0000000000000..a6afd078f77b2 Binary files /dev/null and b/docs/images/templatebuilder_01_bases.png differ diff --git a/docs/images/templatebuilder_02_modules.png b/docs/images/templatebuilder_02_modules.png new file mode 100644 index 0000000000000..7fbe68f2d3e64 Binary files /dev/null and b/docs/images/templatebuilder_02_modules.png differ diff --git a/docs/images/templatebuilder_03_module_customization.png b/docs/images/templatebuilder_03_module_customization.png new file mode 100644 index 0000000000000..cc05734f6f522 Binary files /dev/null and b/docs/images/templatebuilder_03_module_customization.png differ diff --git a/docs/images/templatebuilder_04_customizations.png b/docs/images/templatebuilder_04_customizations.png new file mode 100644 index 0000000000000..3542ac5574999 Binary files /dev/null and b/docs/images/templatebuilder_04_customizations.png differ diff --git a/docs/install/airgap.md b/docs/install/airgap.md index c1963fba5398e..244978d7d1593 100644 --- a/docs/install/airgap.md +++ b/docs/install/airgap.md @@ -234,6 +234,31 @@ server, as demonstrated in the example below: With these steps, you'll have the Coder documentation hosted on your server and accessible for your team to use. +## Template builder + +The template builder requires outbound access to `registry.coder.com` for +`terraform init` to resolve module sources at template composition time. + +For fully air-gapped deployments, disable the template builder: + +```sh +CODER_DISABLE_TEMPLATE_BUILDER=true +``` + +When the builder is disabled, template creation falls back to the standard +upload and CLI workflows. The **New Template** button on the **Templates** page +links to the starter templates page instead of the builder. + +For deployments using a self-hosted module registry mirror, set the registry URL +instead of disabling the builder: + +```sh +CODER_TEMPLATE_BUILDER_REGISTRY_URL=registry.internal.example.com +``` + +This makes the builder generate module source paths pointing at your mirror +rather than `registry.coder.com`. + ## Coder Modules To use Coder modules in offline installations, you can either: diff --git a/docs/start/first-template.md b/docs/start/first-template.md index ba7a2a802cfb9..1936c27cd92f3 100644 --- a/docs/start/first-template.md +++ b/docs/start/first-template.md @@ -1,14 +1,14 @@ # Your first template -A common way to create a template is to begin with a starter template then -modify it for your needs. Coder makes this easy with starter templates for -popular development targets like Docker, Kubernetes, Azure, and so on. Once your -template is up and running, you can edit it in the Coder dashboard. Coder even +The fastest way to create a template is with the template builder. The builder +guides you through selecting base infrastructure, adding modules for IDEs and +tools, and configuring your template, all without writing Terraform. Once your +template is up and running, you can edit it in the Coder dashboard. Coder handles versioning for you so you can publish official updates or revert to previous versions. -In this tutorial, you'll create your first template from the Docker starter -template. +In this tutorial, you'll create your first template from the Docker base +template using the template builder. ## Before you start @@ -21,65 +21,35 @@ your local machine to continue. In your web browser, go to your Coder dashboard using the URL provided during setup to log in. -## 2. Choose a starter template +## 2. Open the template builder -Select **Templates** to see the **Starter Templates**. Use the **Docker -Containers** template by pressing **Use Template**. +Select **Templates** then **New Template**. The template builder opens and +displays a list of base infrastructure templates. -![Starter Templates UI](../images/start/starter-templates.png) +![Template builder base selection](../images/templatebuilder_01_bases.png) -You can also a find a comprehensive list of starter templates in **Templates** --> **Create Template** -> **Starter Templates**. s +## 3. Select a base template -## 3. Create your template +Select the **Docker Containers** base template. This provides a working +Docker-based workspace with the Coder agent pre-configured. -In **Create template**, fill in **Name** and **Display name**, then select -**Create template**. +## 4. Add modules (optional) -![Creating a template](../images/start/create-template.png) +The builder shows a list of available modules grouped by category. You can add +IDEs like **code-server** (VS Code in the browser) or tools like **git-clone**. +For your first template, you can skip this step and add modules later. -TODO: +![Template builder module selection](../images/templatebuilder_02_modules.png) -- add CLI guide for making a new template -- refactor text below to be more beginner-friendly +Select **Continue** to proceed. - +![Template builder customizations](../images/templatebuilder_04_customizations.png) ## 6. Modify your template diff --git a/docs/start/first-workspace.md b/docs/start/first-workspace.md index f4aec315be6b5..2de5accd875c3 100644 --- a/docs/start/first-workspace.md +++ b/docs/start/first-workspace.md @@ -35,7 +35,7 @@ After a few seconds, your workspace is ready to use. ## 2. Try out your new workspace -The Docker starter template lets you connect to your workspace in a few ways: +The Docker template lets you connect to your workspace in a few ways: - VS Code Desktop: Loads your workspace into [VS Code Desktop](https://code.visualstudio.com/Download) installed on your diff --git a/docs/tutorials/template-from-scratch.md b/docs/tutorials/template-from-scratch.md index 3abfdbf940c10..e30f1d7bfdaff 100644 --- a/docs/tutorials/template-from-scratch.md +++ b/docs/tutorials/template-from-scratch.md @@ -1,5 +1,11 @@ # Write a template from scratch +> [!TIP] +> If you want to create a template without writing Terraform, use the +> [template builder](../admin/templates/creating-templates.md#template-builder) +> instead. The builder guides you through selecting base infrastructure and +> adding modules through a visual interface. + A template is a common configuration that you use to deploy workspaces. This tutorial teaches you how to create a template that provisions a workspace @@ -373,7 +379,7 @@ through the CLI, or through the Coder dashboard: #### CLI -1. Run `coder templates create` from the directory with your template files: +1. Run `coder templates push` from the directory with your template files: ```console $ pwd