docs: explain using Artifactory as a template store (#9071)

docs/platforms/jfrog.md

@@ -5,7 +5,7 @@ Use Coder and JFrog together to secure your development environments without dis
 This guide will demonstrate how to use JFrog Artifactory as a package registry
 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).
+The full example template can be found [here](https://github.com/coder/coder/tree/main/examples/templates/jfrog/docker).
 
 ## Requirements
 
@@ -74,7 +74,7 @@ coder templates push --var 'jfrog_host=YYY.jfrog.io' --var 'artifactory_access_t
 we'll focus on its ability to configure package managers, as that's the relevant
 functionality for most developers.
 
-The generic method of installing the JFrog CLI is the following command:
+Most users should be able to install `jf` by running the following command:
 
 ```sh
 curl -fL https://install-cli.jfrog.io | sh
@@ -165,7 +165,7 @@ Default:                        true
 
 ## Installing the JFrog VS Code Extension
 
-You can install the JFrog VS Code extension into workspaces automatically
+You can install the JFrog VS Code extension into workspaces
 by inserting the following lines into your `startup_script`:
 
 ```sh
@@ -228,5 +228,6 @@ supported by Artifactory. See the [JFrog documentation](https://jfrog.com/help/r
 
 ## More reading
 
-- See the full example template [here](https://github.com/coder/coder/tree/main/examples/templates/jfrog-docker).
+- See the full example template [here](https://github.com/coder/coder/tree/main/examples/templates/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 [Artifactory modules](../templates/modules.md#artifactory) docs.

docs/templates/modules.md

@@ -87,3 +87,50 @@ coder:
       subPath: .git-credentials
       readOnly: true
 ```
+
+## Artifactory
+
+JFrog Artifactory can serve as a Terraform module registry, allowing you to simplify
+a Coder-stored template to a `module` block and input variables.
+
+With this approach, you can:
+
+- Easily share templates across multiple Coder instances
+- Store templates far larger than the 1MB limit of Coder's template storage
+- Apply JFrog platform security policies to your templates
+
+### Basic Scaffolding
+
+For example, a template with:
+
+```hcl
+module "frontend" {
+  source = "cdr.jfrog.io/tf__main/frontend/docker"
+}
+```
+
+References the `frontend` module in the `main` namespace of the `tf` repository.
+Remember to replace `cdr.jfrog.io` with your Artifactory instance URL.
+
+You can upload the underlying module to Artifactory with:
+
+```console
+# one-time setup commands
+# run this on the coder server (or external provisioners, if you have them)
+terraform login cdr.jfrog.io; jf tfc --global
+
+# jf tf p assumes the module name is the same as the current directory name.
+jf tf p --namespace=main --provider=docker --tag=v0.0.1
+```
+
+### Example template
+
+We have an example template [here](https://github.com/coder/coder/tree/main/examples/templates/jfrog/remote) that uses our [JFrog Docker](../platforms/jfrog.md) template
+as the underlying module.
+
+### Next up
+
+Learn more about
+
+- JFrog's Terraform Registry support [here](https://jfrog.com/help/r/jfrog-artifactory-documentation/terraform-registry).
+- Configuring the JFrog toolchain inside a workspace [here](../platforms/jfrog.md).

examples/templates/jfrog/docker/README.md

@@ -5,7 +5,7 @@ tags: [local, docker, jfrog]
 icon: /icon/docker.png
 ---
 
-# jfrog-docker
+# docker
 
 To get started, run `coder templates init`. When prompted, select this template.
 Follow the on-screen instructions to proceed.

examples/templates/jfrog/docker/main.tf

@@ -16,11 +16,9 @@ terraform {
 }
 
 locals {
-  # if the jfrog username is same as the coder username, you can use the following
-  # artifactory_username = data.coder_workspace.me.owner
-  # if the username is same as email, you can use the following
-  # artifactory_username = urlencode(data.coder_workspace.me.owner_email)
-  artifactory_username = data.coder_workspace.me.owner
+  # take care to use owner_email instead of owner because users can change
+  # their username.
+  artifactory_username = data.coder_workspace.me.owner_email
   artifactory_repository_keys = {
     "npm"    = "npm"
     "python" = "python"
@@ -55,7 +53,9 @@ provider "artifactory" {
 }
 
 resource "artifactory_scoped_token" "me" {
-  username = local.artifactory_username
+  # This is hacky, but on terraform plan the data source gives empty strings,
+  # which fails validation.
+  username = length(local.artifactory_username) > 0 ? local.artifactory_username : "plan"
 }
 
 resource "coder_agent" "main" {
@@ -125,13 +125,13 @@ resource "docker_volume" "home_volume" {
 resource "docker_image" "main" {
   name = "coder-${data.coder_workspace.me.id}"
   build {
-    context = "./build"
+    context = "${path.module}/build"
     build_args = {
       USER = local.workspace_user
     }
   }
   triggers = {
-    dir_sha1 = sha1(join("", [for f in fileset(path.module, "build/*") : filesha1(f)]))
+    dir_sha1 = sha1(join("", [for f in fileset(path.module, "build/*") : filesha1("${path.module}/${f}")]))
   }
 }
 

examples/templates/jfrog/remote/main.tf

@@ -0,0 +1,16 @@
+module "docker" {
+  source                   = "cdr.jfrog.io/tf__main/docker/docker"
+  jfrog_host               = var.jfrog_host
+  artifactory_access_token = var.artifactory_access_token
+}
+
+variable "jfrog_host" {
+  type        = string
+  description = "JFrog instance hostname. For example, 'YYY.jfrog.io'."
+}
+
+variable "artifactory_access_token" {
+  type        = string
+  description = "The admin-level access token to use for JFrog."
+}
+