some reorg and writing

coder · matifali · May 22, 2024 · May 23, 2024 · May 23, 2024 · May 23, 2024
commit 90d92e1ae5b1b14c2b25311aab1d54d62e2ad195
diff --git a/docs/admin/templates/README.md b/docs/admin/templates/README.md
@@ -4,9 +4,11 @@ Templates define the underlying infrastructure that Coder workspaces run on. All
 
 ## Creating templates
 
-<tutorials filter="tag:creating-templates"></tutorials>
+The following are tutorials on creating templates in Coder for various platforms
 
-- From scratch
+<!-- TODO: Use the tutorials widget component -->
+
+- [From scratch](../../tutorials/template-from-scratch.md)
 - Kubernetes
 - GCP Compute Engine
 - AWS EC2
@@ -15,7 +17,9 @@ Templates define the underlying infrastructure that Coder workspaces run on. All
 
 ## Best practices
 
-- Image Management
+Learn about best practices running templates
+
+- [Image Management](../../tutorials/image-management.md)
 - Dev Container support
 - Protecting resources (user disks)
 - Manage templates with Ci/Cd pipelines

diff --git a/docs/admin/templates/best-practices.md b/docs/admin/templates/best-practices.md
@@ -0,0 +1,9 @@
+# Templates Best Practices
+
+<!-- TODO: use tutorial gallery -->
+
+## Image Management
+
+lorem ipsum
+
+- Guide: [Image Management](../../tutorials/image-management.md)
diff --git a/docs/admin/templates/template-permissions.md b/docs/admin/templates/template-permissions.md
@@ -0,0 +1,19 @@
+# Permissions
+
+![Template Permissions](../../images/templates/permissions.png)
+
+Permissions allow you to control who can use and modify the template. Both
+individual user and groups can be added to the access list for a template.
+Members can be assigned either a `Use` role, granting use of the template to
+create workspaces, or `Admin`, allowing a user or members of a group to control
+all aspects of the template. This offers a way to elevate the privileges of
+ordinary users for specific templates without granting them the site-wide role
+of `Template Admin`.
+
+By default the `Everyone` group is assigned to each template meaning any Coder
+user can use the template to create a workspace. To prevent this, disable the
+`Allow everyone to use the template` setting when creating a template.
+
+![Create Template Permissions](../../images/templates/create-template-permissions.png)
+
+Permissions is an enterprise-only feature.
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -213,6 +213,11 @@
               "description": "Learn how to create templates with Terraform",
               "path": "./admin/templates/creating-templates.md"
             },
+            {
+              "title": "Template Best Practices",
+              "description": "Learn best practices managing templates",
+              "path": "./admin/templates/best-practices.md"
+            },
             {
               "title": "Template Permissions",
               "description": "Learn how to create templates with Terraform",
@@ -283,9 +288,14 @@
           "path": "./tutorials/workspaces/README.md"
         },
         {
-          "title": "Writing Templates",
+          "title": "Write a Template from Scratch",
           "description": "Learn how to author Coder templates",
-          "path": "./tutorials/templates/README.md"
+          "path": "./tutorials/template-from-scratch.md"
+        },
+        {
+          "title": "Image Management",
+          "description": "Learn about image management with Coder",
+          "path": "./tutorials/image-management.md"
         }
       ]
     },

diff --git a/docs/tutorials/operating/README.md → docs/templates-old/tour.md b/docs/tutorials/operating/README.md → docs/templates-old/tour.md
diff --git a/docs/tutorials/image-management.md b/docs/tutorials/image-management.md
@@ -0,0 +1,73 @@
+# Image Management
+
+While Coder provides example
+[base container images](https://github.com/coder/enterprise-images) for
+workspaces, it's often best to create custom images that matches the needs of
+your users. This document serves a guide to operational maturity with some best
+practices around managing workspaces images for Coder.
+
+1. Create a minimal base image
+2. Create golden image(s) with standard tooling
+3. Allow developers to bring their own images and customizations with Dev
+   Containers
+
+> Note: An image is just one of the many properties defined within the template.
+> Templates can pull images from a public image registry (e.g. Docker Hub) or an
+> internal one., thanks to Terraform.
+
+## Create a minimal base image
+
+While you may not use this directly in Coder templates, it's useful to have a
+minimal base image is a small image that contains only the necessary
+dependencies to work in your network and work with Coder. Here are some things
+to consider:
+
+- `curl`, `wget`, or `busybox` is required to download and run
+  [the agent](https://github.com/coder/coder/blob/main/provisionersdk/scripts/bootstrap_linux.sh)
+- `git` is recommended so developers can clone repositories
+- If the Coder server is using a certificate from an internal certificate
+  authority (CA), you'll need to add or mount these into your image
+- Other generic utilities that will be required by all users, such as `ssh`,
+  `docker`, `bash`, `jq`, and/or internal tooling
+- Consider creating (and starting the container with) a non-root user
+
+> See Coder's
+> [example base image](https://github.com/coder/enterprise-images/tree/main/images/minimal)
+> for reference.
+
+## Create general-purpose golden image(s) with standard tooling
+
+It's often practical to have a few golden images that contain standard tooling
+for developers. These images should contain a number of languages (e.g. Python,
+Java, TypeScript), IDEs (VS Code, JetBrains, PyCharm), and other tools (e.g.
+`docker`). Unlike project-specific images (which are also important), general
+purpose images are great for:
+
+- **Scripting:** Developers may just want to hop in a Coder workspace to run
+  basic scripts or queries.
+- **Day 1 Onboarding:** New developers can quickly get started with a familiar
+  environment without having to browse through (or create) an image
+- **Basic Projects:** Developers can use these images for simple projects that
+  don't require any specific tooling outside of the standard libraries. As the
+  project gets more complex, its best to move to a project-specific image.
+- **"Golden Path" Projects:** If your developer platform offers specific tech
+  stacks and types of projects, the golden image can be a good starting point
+  for those projects.
+
+> This is often referred to as a "sandbox" or "kitchen sink" image. Since large
+> multi-purpose container images can quickly become difficult to maintain, it's
+> important to keep the number of general-purpose images to a minimum (2-3 in
+> most cases) with a well-defined scope.
+
+Examples:
+
+- [Universal Dev Containers Image](https://github.com/devcontainers/images/tree/main/src/universal)
+
+## Allow developers to bring their own images and customizations with Dev Containers
+
+While golden images are great for general use cases, developers will often need
+specific tooling for their projects. The [Dev Container](https://containers.dev)
+specification allows developers to define their projects dependencies within a
+`devcontainer.json` in their Git repository.
+
+- [Learn how to integrate Dev Containers with Coder](#TODO)
diff --git a/docs/tutorials/integrations/README.md b/docs/tutorials/integrations/README.md