fix: include subdirectories in example templates (#1715)

.github/dependabot.yaml

@@ -55,7 +55,7 @@ updates:
           - version-update:semver-major
 
   - package-ecosystem: "terraform"
-    directory: "/examples"
+    directory: "/examples/templates"
     schedule:
       interval: "weekly"
       time: "06:00"

docs/about.md

@@ -48,7 +48,7 @@ layer of infrastructure control. This additional layer allows admins to:
 - Enable persistent workspaces, which are like local machines, but faster and
   hosted by a cloud service
 
-Coder includes [production-ready templates](../examples) for use with AWS EC2,
+Coder includes [production-ready templates](../examples/templates) for use with AWS EC2,
 Azure, Google Cloud, Kubernetes, and more.
 
 ## What Coder is *not*

docs/install.md

@@ -52,10 +52,13 @@ Coder](https://github.com/coder/coder/releases) installed.
    coder templates init
    ```
 
+   Choose the "Develop in Docker" example to generate a sample template in the
+   `docker` subdirectory.
+
 1. Navigate into the new directory and create a new template:
 
     ```console
-    cd examples/docker
+    cd docker
     coder templates create
     ```
 

docs/templates.md

@@ -9,7 +9,7 @@ to everybody. Users can also manually update their workspaces.
 
 ## Manage templates
 
-Coder provides production-ready [sample templates](../examples/), but you can
+Coder provides production-ready [sample templates](../examples/templates/), but you can
 modify the templates with Terraform.
 
 ```sh

docs/workspaces.md

@@ -58,7 +58,7 @@ resources](./templates.md#persistent-and-ephemeral-resources).
 
 > ⚠️ To avoid data loss, refer to your template documentation for information on
 > where to store files, install software, etc., so that they persist. Default
-> templates are documented in [../examples](../examples/).
+> templates are documented in [../examples/templates](../examples/templates/).
 >
 > You can use `coder show <workspace-name>` to see which resources are
 > persistent and which are ephemeral.

examples/examples.go

@@ -4,6 +4,8 @@ import (
 	"archive/tar"
 	"bytes"
 	"embed"
+	"io"
+	"io/fs"
 	"path"
 	"sync"
 
@@ -13,8 +15,7 @@ import (
 )
 
 var (
-	//go:embed */*.md
-	//go:embed */*.tf
+	//go:embed templates
 	files embed.FS
 
 	examples      = make([]Example, 0)
@@ -29,20 +30,30 @@ type Example struct {
 	Markdown    string `json:"markdown"`
 }
 
+const rootDir = "templates"
+
 // List returns all embedded examples.
 func List() ([]Example, error) {
 	var returnError error
 	parseExamples.Do(func() {
-		dirs, err := files.ReadDir(".")
+		files, err := fs.Sub(files, rootDir)
+		if err != nil {
+			returnError = xerrors.Errorf("get example fs: %w", err)
+		}
+
+		dirs, err := fs.ReadDir(files, ".")
 		if err != nil {
 			returnError = xerrors.Errorf("read dir: %w", err)
 			return
 		}
 
 		for _, dir := range dirs {
+			if !dir.IsDir() {
+				continue
+			}
 			exampleID := dir.Name()
 			// Each one of these is a example!
-			readme, err := files.ReadFile(path.Join(dir.Name(), "README.md"))
+			readme, err := fs.ReadFile(files, path.Join(dir.Name(), "README.md"))
 			if err != nil {
 				returnError = xerrors.Errorf("example %q does not contain README.md", exampleID)
 				return
@@ -110,54 +121,65 @@ func Archive(exampleID string) ([]byte, error) {
 			return nil, xerrors.Errorf("example with id %q not found", exampleID)
 		}
 
-		entries, err := files.ReadDir(exampleID)
+		exampleFiles, err := fs.Sub(files, path.Join(rootDir, exampleID))
 		if err != nil {
-			return nil, xerrors.Errorf("read dir: %w", err)
+			return nil, xerrors.Errorf("get example fs: %w", err)
 		}
 
 		var buffer bytes.Buffer
 		tarWriter := tar.NewWriter(&buffer)
 
-		for _, entry := range entries {
-			file, err := files.Open(path.Join(exampleID, entry.Name()))
+		err = fs.WalkDir(exampleFiles, ".", func(path string, entry fs.DirEntry, err error) error {
 			if err != nil {
-				return nil, xerrors.Errorf("open file: %w", err)
+				return err
 			}
 
-			info, err := file.Stat()
+			info, err := entry.Info()
 			if err != nil {
-				return nil, xerrors.Errorf("stat file: %w", err)
-			}
-
-			if info.IsDir() {
-				continue
-			}
-
-			data := make([]byte, info.Size())
-			_, err = file.Read(data)
-			if err != nil {
-				return nil, xerrors.Errorf("read data: %w", err)
+				return xerrors.Errorf("stat file: %w", err)
 			}
 
 			header, err := tar.FileInfoHeader(info, entry.Name())
 			if err != nil {
-				return nil, xerrors.Errorf("get file header: %w", err)
+				return xerrors.Errorf("get file header: %w", err)
 			}
 			header.Mode = 0644
 
-			err = tarWriter.WriteHeader(header)
-			if err != nil {
-				return nil, xerrors.Errorf("write file: %w", err)
-			}
+			if entry.IsDir() {
+				header.Name = path + "/"
 
-			_, err = tarWriter.Write(data)
-			if err != nil {
-				return nil, xerrors.Errorf("write: %w", err)
+				err = tarWriter.WriteHeader(header)
+				if err != nil {
+					return xerrors.Errorf("write file: %w", err)
+				}
+			} else {
+				header.Name = path
+
+				file, err := exampleFiles.Open(path)
+				if err != nil {
+					return xerrors.Errorf("open file %s: %w", path, err)
+				}
+				defer file.Close()
+
+				err = tarWriter.WriteHeader(header)
+				if err != nil {
+					return xerrors.Errorf("write file: %w", err)
+				}
+
+				_, err = io.Copy(tarWriter, file)
+				if err != nil {
+					return xerrors.Errorf("write: %w", err)
+				}
 			}
-		}
-		err = tarWriter.Flush()
+			return nil
+		})
 		if err != nil {
-			return nil, xerrors.Errorf("flush archive: %w", err)
+			return nil, xerrors.Errorf("walk example directory: %w", err)
+		}
+
+		err = tarWriter.Close()
+		if err != nil {
+			return nil, xerrors.Errorf("close archive: %w", err)
 		}
 
 		return buffer.Bytes(), nil

examples/examples_test.go

@@ -1,6 +1,10 @@
 package examples_test
 
 import (
+	"archive/tar"
+	"bytes"
+	"errors"
+	"io"
 	"testing"
 
 	"github.com/stretchr/testify/require"
@@ -17,3 +21,24 @@ func TestTemplate(t *testing.T) {
 	_, err = examples.Archive(list[0].ID)
 	require.NoError(t, err)
 }
+
+func TestSubdirs(t *testing.T) {
+	t.Parallel()
+	tarData, err := examples.Archive("docker-image-builds")
+	require.NoError(t, err)
+
+	tarReader := tar.NewReader(bytes.NewReader(tarData))
+	entryPaths := make(map[byte][]string)
+	for {
+		header, err := tarReader.Next()
+		if errors.Is(err, io.EOF) {
+			break
+		}
+		require.NoError(t, err)
+
+		entryPaths[header.Typeflag] = append(entryPaths[header.Typeflag], header.Name)
+	}
+
+	require.Subset(t, entryPaths[tar.TypeDir], []string{"./", "images/"})
+	require.Subset(t, entryPaths[tar.TypeReg], []string{"README.md", "main.tf", "images/base.Dockerfile"})
+}

examples/templates/README.md

@@ -10,6 +10,6 @@ Clone this repository to create a project from any example listed here:
 
 ```sh
 git clone https://github.com/coder/coder
-cd examples/aws-macos
+cd examples/templates/aws-macos
 coder templates create
 ```

examples/templates/kubernetes-multi-service/main.tf

@@ -41,7 +41,7 @@ variable "step3_certificate" {
   type        = string
   sensitive   = true
   description = <<-EOF
-  Use docs at https://github.com/coder/coder/tree/main/examples/kubernetes-multi-service#serviceaccount to create a ServiceAccount for Coder and grab values.
+  Use docs at https://github.com/coder/coder/tree/main/examples/templates/kubernetes-multi-service#serviceaccount to create a ServiceAccount for Coder and grab values.
 
   Enter CA certificate
 
@@ -53,7 +53,7 @@ variable "step4_token" {
   type        = string
   sensitive   = true
   description = <<-EOF
-  Enter token (refer to docs at https://github.com/coder/coder/tree/main/examples/kubernetes-multi-service#serviceaccount)
+  Enter token (refer to docs at https://github.com/coder/coder/tree/main/examples/templates/kubernetes-multi-service#serviceaccount)
 
   Leave blank if using ~/.kube/config (from step 1)
   EOF
@@ -63,7 +63,7 @@ variable "step5_coder_namespace" {
   type        = string
   sensitive   = true
   description = <<-EOF
-  Enter namespace (refer to docs at https://github.com/coder/coder/tree/main/examples/kubernetes-multi-service#serviceaccount)
+  Enter namespace (refer to docs at https://github.com/coder/coder/tree/main/examples/templates/kubernetes-multi-service#serviceaccount)
 
   Leave blank if using ~/.kube/config (from step 1)
   EOF