-- -By default, the coder agent will configure native `git` authentication via the -`GIT_ASKPASS` environment variable. Meaning, with no additional configuration, -external authentication will work with native `git` commands. - -To check the auth token being used **from inside a running workspace**, run: - -```shell -# If the exit code is non-zero, then the user is not authenticated with the -# external provider. -coder external-auth access-token- This is the preferred authentication method. -
-
+
+## Community Edition
+
+
+
+## Enterprise
+
+
+
+## Multi-Region Enterprise
+
+
+
+
+
+## Primary components
+
+### coderd
+
+_coderd_ is the service created by running `coder server`. It is a thin API that
+connects workspaces, provisioners and users. _coderd_ stores its state in
+Postgres and is the only service that communicates with Postgres.
+
+It offers:
+
+- Dashboard (UI)
+- HTTP API
+- Dev URLs (HTTP reverse proxy to workspaces)
+- Workspace Web Applications (e.g for easy access to `code-server`)
+- Agent registration
+
+### provisionerd
+
+_provisionerd_ is the execution context for infrastructure modifying providers.
+At the moment, the only provider is Terraform (running `terraform`).
+
+By default, the Coder server runs multiple provisioner daemons.
+[External provisioners](../admin/provisioners.md) can be added for security or
+scalability purposes.
+
+### Workspaces
+
+At the highest level, a workspace is a set of cloud resources. These resources
+can be VMs, Kubernetes clusters, storage buckets, or whatever else Terraform
+lets you dream up.
+
+The resources that run the agent are described as _computational resources_,
+while those that don't are called _peripheral resources_.
+
+Each resource may also be _persistent_ or _ephemeral_ depending on whether
+they're destroyed on workspace stop.
+
+### Agents
+
+An agent is the Coder service that runs within a user's remote workspace. It
+provides a consistent interface for coderd and clients to communicate with
+workspaces regardless of operating system, architecture, or cloud.
+
+It offers the following services along with much more:
+
+- SSH
+- Port forwarding
+- Liveness checks
+- `startup_script` automation
+
+Templates are responsible for
+[creating and running agents](../templates/index.md#coder-agent) within
+workspaces.
+
+## Service Bundling
+
+While _coderd_ and Postgres can be orchestrated independently, our default
+installation paths bundle them all together into one system service. It's
+perfectly fine to run a production deployment this way, but there are certain
+situations that necessitate decomposition:
+
+- Reducing global client latency (distribute coderd and centralize database)
+- Achieving greater availability and efficiency (horizontally scale individual
+ services)
+
+## Data Layer
+
+### PostgreSQL (Recommended)
+
+While `coderd` runs a bundled version of PostgreSQL, we recommend running an
+external PostgreSQL 13+ database for production deployments.
+
+A managed PostgreSQL database, with daily backups, is recommended:
+
+- For AWS: Amazon RDS for PostgreSQL
+- For Azure: Azure Database for PostgreSQL
+- Flexible Server For GCP: Cloud SQL for PostgreSQL
+
+Learn more about database requirements:
+[Database Health](./health-check.md#database)
+
+### Git Providers (Recommended)
+
+Users will likely need to pull source code and other artifacts from a git
+provider. The Coder control plane and workspaces will need network connectivity
+to the git provider.
+
+- [GitHub](#TODO)
+- [GitHub Enterprise](#TODO)
+- [GitLab](#TODO)
+- [BitBucket](#TODO)
+- [BitBucket](#TODO)
+- [Other Providers](#TODO)
+
+### Artifact Manager (Optional)
+
+Workspaces and templates can pull artifacts from an artifact manager, such as
+JFrog Artifactory. This can be configured on the infrastructure level, or in
+some cases within Coder:
+
+- Tutorial: [JFrog Artifactory and Coder](#TODO)
+
+### Container Registry (Optional)
+
+If you prefer not to pull container images for the control plane (`coderd`,
+`provisionerd`) and workspaces from public container registry (Docker Hub,
+GitHub Container Registry) you can run your own container registry with Coder.
+
+To shorten the provisioning time, it is recommended to deploy registry mirrors
+in the same region as the workspace nodes.
diff --git a/docs/admin/scaling/scale-testing.md b/docs/admin/infrastructure/scale-testing.md
similarity index 93%
rename from docs/admin/scaling/scale-testing.md
rename to docs/admin/infrastructure/scale-testing.md
index f107dc7f7f071..e41ef86e5f40f 100644
--- a/docs/admin/scaling/scale-testing.md
+++ b/docs/admin/infrastructure/scale-testing.md
@@ -90,11 +90,11 @@ Database:
## Available reference architectures
-[Up to 1,000 users](../../architecture/1k-users.md)
+[Up to 1,000 users](./validated-architectures/1k-users.md)
-[Up to 2,000 users](../../architecture/2k-users.md)
+[Up to 2,000 users](./validated-architectures/2k-users.md)
-[Up to 3,000 users](../../architecture/3k-users.md)
+[Up to 3,000 users](./validated-architectures/3k-users.md)
## Hardware recommendation
@@ -112,13 +112,14 @@ on the workload size to ensure deployment stability.
#### CPU and memory usage
-Enabling [agent stats collection](../../cli.md#--prometheus-collect-agent-stats)
+Enabling
+[agent stats collection](../../reference/cli/README.md#--prometheus-collect-agent-stats)
(optional) may increase memory consumption.
Enabling direct connections between users and workspace agents (apps or SSH
traffic) can help prevent an increase in CPU usage. It is recommended to keep
-[this option enabled](../../cli.md#--disable-direct-connections) unless there
-are compelling reasons to disable it.
+[this option enabled](../../reference/cli/README.md#--disable-direct-connections)
+unless there are compelling reasons to disable it.
Inactive users do not consume Coder resources.
@@ -148,18 +149,19 @@ Terminal (bidirectional), and Workspace events/logs (unidirectional).
If the Coder deployment expects traffic from developers spread across the globe,
be aware that customer-facing latency might be higher because of the distance
between users and the load balancer. Fortunately, the latency can be improved
-with a deployment of Coder [workspace proxies](../workspace-proxies.md).
+with a deployment of Coder
+[workspace proxies](../networking/workspace-proxies.md).
**Node Autoscaling**
We recommend disabling the autoscaling for `coderd` nodes. Autoscaling can cause
interruptions for user connections, see
-[Autoscaling](scale-utility.md#autoscaling) for more details.
+[Autoscaling](./scale-utility.md#autoscaling) for more details.
### Control plane: Workspace Proxies
-When scaling [workspace proxies](../workspace-proxies.md), follow the same
-guidelines as for `coderd` above:
+When scaling [workspace proxies](../networking/workspace-proxies.md), follow the
+same guidelines as for `coderd` above:
- `1 vCPU x 2 GB memory` for every 250 users.
- Disable autoscaling.
diff --git a/docs/admin/scaling/scale-utility.md b/docs/admin/infrastructure/scale-utility.md
similarity index 95%
rename from docs/admin/scaling/scale-utility.md
rename to docs/admin/infrastructure/scale-utility.md
index 0cc0316193724..717688d03adda 100644
--- a/docs/admin/scaling/scale-utility.md
+++ b/docs/admin/infrastructure/scale-utility.md
@@ -6,15 +6,15 @@ infrastructure. For scale-testing Kubernetes clusters we recommend to install
and use the dedicated Coder template,
[scaletest-runner](https://github.com/coder/coder/tree/main/scaletest/templates/scaletest-runner).
-Learn more about [Coder’s architecture](../../architecture/architecture.md) and
-our [scale-testing methodology](scale-testing.md).
+Learn more about [Coder’s architecture](./architecture/architecture.md) and our
+[scale-testing methodology](./scale-testing.md).
## Recent scale tests
> Note: the below information is for reference purposes only, and are not
> intended to be used as guidelines for infrastructure sizing. Review the
-> [Reference Architectures](../../architecture/validated-arch.md#node-sizing)
-> for hardware sizing recommendations.
+> [Reference Architectures](./validated-architectures/README.md#node-sizing) for
+> hardware sizing recommendations.
| Environment | Coder CPU | Coder RAM | Coder Replicas | Database | Users | Concurrent builds | Concurrent connections (Terminal/SSH) | Coder Version | Last tested |
| ---------------- | --------- | --------- | -------------- | ----------------- | ----- | ----------------- | ------------------------------------- | ------------- | ------------ |
@@ -249,6 +249,7 @@ an annotation on the coderd deployment.
## Troubleshooting
If a load test fails or if you are experiencing performance issues during
-day-to-day use, you can leverage Coder's [Prometheus metrics](../prometheus.md)
-to identify bottlenecks during scale tests. Additionally, you can use your
-existing cloud monitoring stack to measure load, view server logs, etc.
+day-to-day use, you can leverage Coder's
+[Prometheus metrics](../integrations/prometheus.md) to identify bottlenecks
+during scale tests. Additionally, you can use your existing cloud monitoring
+stack to measure load, view server logs, etc.
diff --git a/docs/admin/infrastructure/validated-architectures/1k-users.md b/docs/admin/infrastructure/validated-architectures/1k-users.md
new file mode 100644
index 0000000000000..158eb10392e79
--- /dev/null
+++ b/docs/admin/infrastructure/validated-architectures/1k-users.md
@@ -0,0 +1,51 @@
+# Reference Architecture: up to 1,000 users
+
+The 1,000 users architecture is designed to cover a wide range of workflows.
+Examples of subjects that might utilize this architecture include medium-sized
+tech startups, educational units, or small to mid-sized enterprises.
+
+**Target load**: API: up to 180 RPS
+
+**High Availability**: non-essential for small deployments
+
+## Hardware recommendations
+
+### Coderd nodes
+
+| Users | Node capacity | Replicas | GCP | AWS | Azure |
+| ----------- | ------------------- | ------------------- | --------------- | ---------- | ----------------- |
+| Up to 1,000 | 2 vCPU, 8 GB memory | 1-2 / 1 coderd each | `n1-standard-2` | `t3.large` | `Standard_D2s_v3` |
+
+**Footnotes**:
+
+- For small deployments (ca. 100 users, 10 concurrent workspace builds), it is
+ acceptable to deploy provisioners on `coderd` nodes.
+
+### Provisioner nodes
+
+| Users | Node capacity | Replicas | GCP | AWS | Azure |
+| ----------- | -------------------- | ------------------------------ | ---------------- | ------------ | ----------------- |
+| Up to 1,000 | 8 vCPU, 32 GB memory | 2 nodes / 30 provisioners each | `t2d-standard-8` | `t3.2xlarge` | `Standard_D8s_v3` |
+
+**Footnotes**:
+
+- An external provisioner is deployed as Kubernetes pod.
+
+### Workspace nodes
+
+| Users | Node capacity | Replicas | GCP | AWS | Azure |
+| ----------- | -------------------- | ----------------------- | ---------------- | ------------ | ----------------- |
+| Up to 1,000 | 8 vCPU, 32 GB memory | 64 / 16 workspaces each | `t2d-standard-8` | `t3.2xlarge` | `Standard_D8s_v3` |
+
+**Footnotes**:
+
+- Assumed that a workspace user needs at minimum 2 GB memory to perform. We
+ recommend against over-provisioning memory for developer workloads, as this my
+ lead to OOMKiller invocations.
+- Maximum number of Kubernetes workspace pods per node: 256
+
+### Database nodes
+
+| Users | Node capacity | Replicas | Storage | GCP | AWS | Azure |
+| ----------- | ------------------- | -------- | ------- | ------------------ | ------------- | ----------------- |
+| Up to 1,000 | 2 vCPU, 8 GB memory | 1 | 512 GB | `db-custom-2-7680` | `db.t3.large` | `Standard_D2s_v3` |
diff --git a/docs/admin/infrastructure/validated-architectures/2k-users.md b/docs/admin/infrastructure/validated-architectures/2k-users.md
new file mode 100644
index 0000000000000..04ff5bf4ec19a
--- /dev/null
+++ b/docs/admin/infrastructure/validated-architectures/2k-users.md
@@ -0,0 +1,59 @@
+# Reference Architecture: up to 2,000 users
+
+In the 2,000 users architecture, there is a moderate increase in traffic,
+suggesting a growing user base or expanding operations. This setup is
+well-suited for mid-sized companies experiencing growth or for universities
+seeking to accommodate their expanding user populations.
+
+Users can be evenly distributed between 2 regions or be attached to different
+clusters.
+
+**Target load**: API: up to 300 RPS
+
+**High Availability**: The mode is _enabled_; multiple replicas provide higher
+deployment reliability under load.
+
+## Hardware recommendations
+
+### Coderd nodes
+
+| Users | Node capacity | Replicas | GCP | AWS | Azure |
+| ----------- | -------------------- | ----------------------- | --------------- | ----------- | ----------------- |
+| Up to 2,000 | 4 vCPU, 16 GB memory | 2 nodes / 1 coderd each | `n1-standard-4` | `t3.xlarge` | `Standard_D4s_v3` |
+
+### Provisioner nodes
+
+| Users | Node capacity | Replicas | GCP | AWS | Azure |
+| ----------- | -------------------- | ------------------------------ | ---------------- | ------------ | ----------------- |
+| Up to 2,000 | 8 vCPU, 32 GB memory | 4 nodes / 30 provisioners each | `t2d-standard-8` | `t3.2xlarge` | `Standard_D8s_v3` |
+
+**Footnotes**:
+
+- An external provisioner is deployed as Kubernetes pod.
+- It is not recommended to run provisioner daemons on `coderd` nodes.
+- Consider separating provisioners into different namespaces in favor of
+ zero-trust or multi-cloud deployments.
+
+### Workspace nodes
+
+| Users | Node capacity | Replicas | GCP | AWS | Azure |
+| ----------- | -------------------- | ------------------------ | ---------------- | ------------ | ----------------- |
+| Up to 2,000 | 8 vCPU, 32 GB memory | 128 / 16 workspaces each | `t2d-standard-8` | `t3.2xlarge` | `Standard_D8s_v3` |
+
+**Footnotes**:
+
+- Assumed that a workspace user needs 2 GB memory to perform
+- Maximum number of Kubernetes workspace pods per node: 256
+- Nodes can be distributed in 2 regions, not necessarily evenly split, depending
+ on developer team sizes
+
+### Database nodes
+
+| Users | Node capacity | Replicas | Storage | GCP | AWS | Azure |
+| ----------- | -------------------- | -------- | ------- | ------------------- | -------------- | ----------------- |
+| Up to 2,000 | 4 vCPU, 16 GB memory | 1 | 1 TB | `db-custom-4-15360` | `db.t3.xlarge` | `Standard_D4s_v3` |
+
+**Footnotes**:
+
+- Consider adding more replicas if the workspace activity is higher than 500
+ workspace builds per day or to achieve higher RPS.
diff --git a/docs/admin/infrastructure/validated-architectures/3k-users.md b/docs/admin/infrastructure/validated-architectures/3k-users.md
new file mode 100644
index 0000000000000..093ec21c5c52c
--- /dev/null
+++ b/docs/admin/infrastructure/validated-architectures/3k-users.md
@@ -0,0 +1,62 @@
+# Reference Architecture: up to 3,000 users
+
+The 3,000 users architecture targets large-scale enterprises, possibly with
+on-premises network and cloud deployments.
+
+**Target load**: API: up to 550 RPS
+
+**High Availability**: Typically, such scale requires a fully-managed HA
+PostgreSQL service, and all Coder observability features enabled for operational
+purposes.
+
+**Observability**: Deploy monitoring solutions to gather Prometheus metrics and
+visualize them with Grafana to gain detailed insights into infrastructure and
+application behavior. This allows operators to respond quickly to incidents and
+continuously improve the reliability and performance of the platform.
+
+## Hardware recommendations
+
+### Coderd nodes
+
+| Users | Node capacity | Replicas | GCP | AWS | Azure |
+| ----------- | -------------------- | ----------------- | --------------- | ----------- | ----------------- |
+| Up to 3,000 | 8 vCPU, 32 GB memory | 4 / 1 coderd each | `n1-standard-4` | `t3.xlarge` | `Standard_D4s_v3` |
+
+### Provisioner nodes
+
+| Users | Node capacity | Replicas | GCP | AWS | Azure |
+| ----------- | -------------------- | ------------------------ | ---------------- | ------------ | ----------------- |
+| Up to 3,000 | 8 vCPU, 32 GB memory | 8 / 30 provisioners each | `t2d-standard-8` | `t3.2xlarge` | `Standard_D8s_v3` |
+
+**Footnotes**:
+
+- An external provisioner is deployed as Kubernetes pod.
+- It is strongly discouraged to run provisioner daemons on `coderd` nodes at
+ this level of scale.
+- Separate provisioners into different namespaces in favor of zero-trust or
+ multi-cloud deployments.
+
+### Workspace nodes
+
+| Users | Node capacity | Replicas | GCP | AWS | Azure |
+| ----------- | -------------------- | ------------------------------ | ---------------- | ------------ | ----------------- |
+| Up to 3,000 | 8 vCPU, 32 GB memory | 256 nodes / 12 workspaces each | `t2d-standard-8` | `t3.2xlarge` | `Standard_D8s_v3` |
+
+**Footnotes**:
+
+- Assumed that a workspace user needs 2 GB memory to perform
+- Maximum number of Kubernetes workspace pods per node: 256
+- As workspace nodes can be distributed between regions, on-premises networks
+ and cloud areas, consider different namespaces in favor of zero-trust or
+ multi-cloud deployments.
+
+### Database nodes
+
+| Users | Node capacity | Replicas | Storage | GCP | AWS | Azure |
+| ----------- | -------------------- | -------- | ------- | ------------------- | --------------- | ----------------- |
+| Up to 3,000 | 8 vCPU, 32 GB memory | 2 | 1.5 TB | `db-custom-8-30720` | `db.t3.2xlarge` | `Standard_D8s_v3` |
+
+**Footnotes**:
+
+- Consider adding more replicas if the workspace activity is higher than 1500
+ workspace builds per day or to achieve higher RPS.
diff --git a/docs/admin/infrastructure/validated-architectures/README.md b/docs/admin/infrastructure/validated-architectures/README.md
new file mode 100644
index 0000000000000..ffb5a1e919ad7
--- /dev/null
+++ b/docs/admin/infrastructure/validated-architectures/README.md
@@ -0,0 +1,363 @@
+# Coder Validated Architecture
+
+Many customers operate Coder in complex organizational environments, consisting
+of multiple business units, agencies, and/or subsidiaries. This can lead to
+numerous Coder deployments, due to discrepancies in regulatory compliance, data
+sovereignty, and level of funding across groups. The Coder Validated
+Architecture (CVA) prescribes a Kubernetes-based deployment approach, enabling
+your organization to deploy a stable Coder instance that is easier to maintain
+and troubleshoot.
+
+The following sections will detail the components of the Coder Validated
+Architecture, provide guidance on how to configure and deploy these components,
+and offer insights into how to maintain and troubleshoot your Coder environment.
+
+- [General concepts](#general-concepts)
+- [Kubernetes Infrastructure](#kubernetes-infrastructure)
+- [PostgreSQL Database](#postgresql-database)
+- [Operational readiness](#operational-readiness)
+
+## Who is this document for?
+
+This guide targets the following personas. It assumes a basic understanding of
+cloud/on-premise computing, containerization, and the Coder platform.
+
+| Role | Description |
+| ------------------------- | ------------------------------------------------------------------------------ |
+| Platform Engineers | Responsible for deploying, operating the Coder deployment and infrastructure |
+| Enterprise Architects | Responsible for architecting Coder deployments to meet enterprise requirements |
+| Managed Service Providers | Entities that deploy and run Coder software as a service for customers |
+
+## CVA Guidance
+
+| CVA provides: | CVA does not provide: |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Single and multi-region K8s deployment options | Prescribing OS, or cloud vs. on-premise |
+| Reference architectures for up to 3,000 users | An approval of your architecture; the CVA solely provides recommendations and guidelines |
+| Best practices for building a Coder deployment | Recommendations for every possible deployment scenario |
+
+> For higher level design principles and architectural best practices, see
+> Coder's
+> [Well-Architected Framework](https://coder.com/blog/coder-well-architected-framework).
+
+## General concepts
+
+This section outlines core concepts and terminology essential for understanding
+Coder's architecture and deployment strategies.
+
+### Administrator
+
+An administrator is a user role within the Coder platform with elevated
+privileges. Admins have access to administrative functions such as user
+management, template definitions, insights, and deployment configuration.
+
+### Coder control plane
+
+Coder's control plane, also known as _coderd_, is the main service recommended
+for deployment with multiple replicas to ensure high availability. It provides
+an API for managing workspaces and templates, and serves the dashboard UI. In
+addition, each _coderd_ replica hosts 3 Terraform [provisioners](#provisioner)
+by default.
+
+### User
+
+A [user](../users.md) is an individual who utilizes the Coder platform to
+develop, test, and deploy applications using workspaces. Users can select
+available templates to provision workspaces. They interact with Coder using the
+web interface, the CLI tool, or directly calling API methods.
+
+### Workspace
+
+A [workspace](../../workspaces.md) refers to an isolated development environment
+where users can write, build, and run code. Workspaces are fully configurable
+and can be tailored to specific project requirements, providing developers with
+a consistent and efficient development environment. Workspaces can be
+autostarted and autostopped, enabling efficient resource management.
+
+Users can connect to workspaces using SSH or via workspace applications like
+`code-server`, facilitating collaboration and remote access. Additionally,
+workspaces can be parameterized, allowing users to customize settings and
+configurations based on their unique needs. Workspaces are instantiated using
+Coder templates and deployed on resources created by provisioners.
+
+### Template
+
+A [template](../../templates/index.md) in Coder is a predefined configuration
+for creating workspaces. Templates streamline the process of workspace creation
+by providing pre-configured settings, tooling, and dependencies. They are built
+by template administrators on top of Terraform, allowing for efficient
+management of infrastructure resources. Additionally, templates can utilize
+Coder modules to leverage existing features shared with other templates,
+enhancing flexibility and consistency across deployments. Templates describe
+provisioning rules for infrastructure resources offered by Terraform providers.
+
+### Workspace Proxy
+
+A [workspace proxy](../workspace-proxies.md) serves as a relay connection option
+for developers connecting to their workspace over SSH, a workspace app, or
+through port forwarding. It helps reduce network latency for geo-distributed
+teams by minimizing the distance network traffic needs to travel. Notably,
+workspace proxies do not handle dashboard connections or API calls.
+
+### Provisioner
+
+Provisioners in Coder execute Terraform during workspace and template builds.
+While the platform includes built-in provisioner daemons by default, there are
+advantages to employing external provisioners. These external daemons provide
+secure build environments and reduce server load, improving performance and
+scalability. Each provisioner can handle a single concurrent workspace build,
+allowing for efficient resource allocation and workload management.
+
+### Registry
+
+The [Coder Registry](https://registry.coder.com) is a platform where you can
+find starter templates and _Modules_ for various cloud services and platforms.
+
+Templates help create self-service development environments using
+Terraform-defined infrastructure, while _Modules_ simplify template creation by
+providing common features like workspace applications, third-party integrations,
+or helper scripts.
+
+Please note that the Registry is a hosted service and isn't available for
+offline use.
+
+## Kubernetes Infrastructure
+
+Kubernetes is the recommended, and supported platform for deploying Coder in the
+enterprise. It is the hosting platform of choice for a large majority of Coder's
+Fortune 500 customers, and it is the platform in which we build and test against
+here at Coder.
+
+### General recommendations
+
+In general, it is recommended to deploy Coder into its own respective cluster,
+separate from production applications. Keep in mind that Coder runs development
+workloads, so the cluster should be deployed as such, without production-level
+configurations.
+
+### Compute
+
+Deploy your Kubernetes cluster with two node groups, one for Coder's control
+plane, and another for user workspaces (if you intend on leveraging K8s for
+end-user compute).
+
+#### Control plane nodes
+
+The Coder control plane node group must be static, to prevent scale down events
+from dropping pods, and thus dropping user connections to the dashboard UI and
+their workspaces.
+
+Coder's Helm Chart supports
+[defining nodeSelectors, affinities, and tolerations](https://github.com/coder/coder/blob/e96652ebbcdd7554977594286b32015115c3f5b6/helm/coder/values.yaml#L221-L249)
+to schedule the control plane pods on the appropriate node group.
+
+#### Workspace nodes
+
+Coder workspaces can be deployed either as Pods or Deployments in Kubernetes.
+See our
+[example Kubernetes workspace template](https://github.com/coder/coder/tree/main/examples/templates/kubernetes).
+Configure the workspace node group to be auto-scaling, to dynamically allocate
+compute as users start/stop workspaces at the beginning and end of their day.
+Set nodeSelectors, affinities, and tolerations in Coder templates to assign
+workspaces to the given node group:
+
+```hcl
+resource "kubernetes_deployment" "coder" {
+ spec {
+ template {
+ metadata {
+ labels = {
+ app = "coder-workspace"
+ }
+ }
+
+ spec {
+ affinity {
+ pod_anti_affinity {
+ preferred_during_scheduling_ignored_during_execution {
+ weight = 1
+ pod_affinity_term {
+ label_selector {
+ match_expressions {
+ key = "app.kubernetes.io/instance"
+ operator = "In"
+ values = ["coder-workspace"]
+ }
+ }
+ topology_key = # add your node group label here
+ }
+ }
+ }
+ }
+
+ tolerations {
+ # Add your tolerations here
+ }
+
+ node_selector {
+ # Add your node selectors here
+ }
+
+ container {
+ image = "coder-workspace:latest"
+ name = "dev"
+ }
+ }
+ }
+ }
+}
+```
+
+#### Node sizing
+
+For sizing recommendations, see the below reference architectures:
+
+- [Up to 1,000 users](1k-users.md)
+
+- [Up to 2,000 users](2k-users.md)
+
+- [Up to 3,000 users](3k-users.md)
+
+### Networking
+
+It is likely your enterprise deploys Kubernetes clusters with various networking
+restrictions. With this in mind, Coder requires the following connectivity:
+
+- Egress from workspace compute to the Coder control plane pods
+- Egress from control plane pods to Coder's PostgreSQL database
+- Egress from control plane pods to git and package repositories
+- Ingress from user devices to the control plane Load Balancer or Ingress
+ controller
+
+We recommend configuring your network policies in accordance with the above.
+Note that Coder workspaces do not require any ports to be open.
+
+### Storage
+
+If running Coder workspaces as Kubernetes Pods or Deployments, you will need to
+assign persistent storage. We recommend leveraging a
+[supported Container Storage Interface (CSI) driver](https://kubernetes-csi.github.io/docs/drivers.html)
+in your cluster, with Dynamic Provisioning and read/write, to provide on-demand
+storage to end-user workspaces.
+
+The following Kubernetes volume types have been validated by Coder internally,
+and/or by our customers:
+
+- [PersistentVolumeClaim](https://kubernetes.io/docs/concepts/storage/volumes/#persistentvolumeclaim)
+- [NFS](https://kubernetes.io/docs/concepts/storage/volumes/#nfs)
+- [subPath](https://kubernetes.io/docs/concepts/storage/volumes/#using-subpath)
+- [cephfs](https://kubernetes.io/docs/concepts/storage/volumes/#cephfs)
+
+Our
+[example Kubernetes workspace template](https://github.com/coder/coder/blob/5b9a65e5c137232351381fc337d9784bc9aeecfc/examples/templates/kubernetes/main.tf#L191-L219)
+provisions a PersistentVolumeClaim block storage device, attached to the
+Deployment.
+
+It is not recommended to mount volumes from the host node(s) into workspaces,
+for security and reliability purposes. The below volume types are _not_
+recommended for use with Coder:
+
+- [Local](https://kubernetes.io/docs/concepts/storage/volumes/#local)
+- [hostPath](https://kubernetes.io/docs/concepts/storage/volumes/#hostpath)
+
+Not that Coder's control plane filesystem is ephemeral, so no persistent storage
+is required.
+
+## PostgreSQL database
+
+Coder requires access to an external PostgreSQL database to store user data,
+workspace state, template files, and more. Depending on the scale of the
+user-base, workspace activity, and High Availability requirements, the amount of
+CPU and memory resources required by Coder's database may differ.
+
+### Disaster recovery
+
+Prepare internal scripts for dumping and restoring your database. We recommend
+scheduling regular database backups, especially before upgrading Coder to a new
+release. Coder does not support downgrades without initially restoring the
+database to the prior version.
+
+### Performance efficiency
+
+We highly recommend deploying the PostgreSQL instance in the same region (and if
+possible, same availability zone) as the Coder server to optimize for low
+latency connections. We recommend keeping latency under 10ms between the Coder
+server and database.
+
+When determining scaling requirements, take into account the following
+considerations:
+
+- `2 vCPU x 8 GB RAM x 512 GB storage`: A baseline for database requirements for
+ Coder deployment with less than 1000 users, and low activity level (30% active
+ users). This capacity should be sufficient to support 100 external
+ provisioners.
+- Storage size depends on user activity, workspace builds, log verbosity,
+ overhead on database encryption, etc.
+- Allocate two additional CPU core to the database instance for every 1000
+ active users.
+- Enable High Availability mode for database engine for large scale deployments.
+
+If you enable [database encryption](../encryption.md) in Coder, consider
+allocating an additional CPU core to every `coderd` replica.
+
+#### Resource utilization guidelines
+
+Below are general recommendations for sizing your PostgreSQL instance:
+
+- Increase number of vCPU if CPU utilization or database latency is high.
+- Allocate extra memory if database performance is poor, CPU utilization is low,
+ and memory utilization is high.
+- Utilize faster disk options (higher IOPS) such as SSDs or NVMe drives for
+ optimal performance enhancement and possibly reduce database load.
+
+## Operational readiness
+
+Operational readiness in Coder is about ensuring that everything is set up
+correctly before launching a platform into production. It involves making sure
+that the service is reliable, secure, and easily scales accordingly to user-base
+needs. Operational readiness is crucial because it helps prevent issues that
+could affect workspace users experience once the platform is live.
+
+### Helm Chart Configuration
+
+1. Reference our [Helm chart values file](../../../helm/coder/values.yaml) and
+ identify the required values for deployment.
+1. Create a `values.yaml` and add it to your version control system.
+1. Determine the necessary environment variables. Here is the
+ [full list of supported server environment variables](../../cli/server.md).
+1. Follow our documented
+ [steps for installing Coder via Helm](../../install/kubernetes.md).
+
+### Template configuration
+
+1. Establish dedicated accounts for users with the _Template Administrator_
+ role.
+1. Maintain Coder templates using
+ [version control](../../templates/change-management.md).
+1. Consider implementing a GitOps workflow to automatically push new template
+ versions into Coder from git. For example, on Github, you can use the
+ [Update Coder Template](https://github.com/marketplace/actions/update-coder-template)
+ action.
+1. Evaluate enabling
+ [automatic template updates](../../templates/general-settings.md#require-automatic-updates-enterprise)
+ upon workspace startup.
+
+### Observability
+
+1. Enable the Prometheus endpoint (environment variable:
+ `CODER_PROMETHEUS_ENABLE`).
+1. Deploy the
+ [Coder Observability bundle](https://github.com/coder/observability) to
+ leverage pre-configured dashboards, alerts, and runbooks for monitoring
+ Coder. This includes integrations between Prometheus, Grafana, Loki, and
+ Alertmanager.
+1. Review the [Prometheus response](../prometheus.md) and set up alarms on
+ selected metrics.
+
+### User support
+
+1. Incorporate [support links](../appearance.md#support-links) into internal
+ documentation accessible from the user context menu. Ensure that hyperlinks
+ are valid and lead to up-to-date materials.
+1. Encourage the use of `coder support bundle` to allow workspace users to
+ generate and provide network-related diagnostic data.
diff --git a/docs/admin/integrations/README.md b/docs/admin/integrations/README.md
new file mode 100644
index 0000000000000..5b0e3e2bbb136
--- /dev/null
+++ b/docs/admin/integrations/README.md
@@ -0,0 +1,23 @@
+# Integrations
+
+Coder is highly extensible and is not limited to the platforms outlined in these
+docs. The control plane can be provisioned on any VM or container compute, and
+workspaces can include any Terraform resource. See our
+[architecture diagram](../infrastructure/architecture.md) for more details.
+
+You can host your deployment on almost any infrastructure. To learn how, read our [installation guides](../../install/README.md).
+
+- -| Username | Groups | Effective Budget | -| -------- | ----------------- | ---------------- | -| jill | Frontend, Backend | 30 | -| jack | Backend, Data | 50 | -| sam | Data | 30 | -| alex | Frontend | 10 | - -By default, groups are assumed to have a default allowance of 0. - -## Quota Enforcement - -Coder enforces Quota on workspace start and stop operations. The workspace build -process dynamically calculates costs, so quota violation fails builds as opposed -to failing the build-triggering operation. For example, the Workspace Create -Form will never get held up by quota enforcement. - - - -## Up next - -- [Enterprise](../enterprise.md) -- [Configuring](./configure.md) diff --git a/docs/admin/rbac.md b/docs/admin/rbac.md deleted file mode 100644 index 554650ea675b8..0000000000000 --- a/docs/admin/rbac.md +++ /dev/null @@ -1,22 +0,0 @@ -# Role Based Access Control (RBAC) - -Use RBAC to define which users and [groups](./groups.md) can use specific -templates in Coder. These can be defined in Coder or -[synced from your identity provider](./auth.md) - - - -The "Everyone" group makes a template accessible to all users. This can be -removed to make a template private. - -## Permissions - -You can set the following permissions: - -- **Admin**: Read, use, edit, push, and delete -- **View**: Read, use - -## Enabling this feature - -This feature is only available with an enterprise license. -[Learn more](../enterprise.md) diff --git a/docs/admin/security/README.md b/docs/admin/security/README.md new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/docs/admin/audit-logs.md b/docs/admin/security/audit-logs.md similarity index 99% rename from docs/admin/audit-logs.md rename to docs/admin/security/audit-logs.md index 564a4f8594a0e..6747703989abc 100644 --- a/docs/admin/audit-logs.md +++ b/docs/admin/security/audit-logs.md @@ -6,7 +6,7 @@ Audit Logs allows **Auditors** to monitor user operations in their deployment. We track the following resources: - + | Resource | | | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -30,7 +30,7 @@ We track the following resources: | WorkspaceBuild
start, stop |
| Field | Tracked |
|---|---|
| build_number | false |
| created_at | false |
| daily_cost | false |
| deadline | false |
| id | false |
| initiator_by_avatar_url | false |
| initiator_by_username | false |
| initiator_id | false |
| job_id | false |
| max_deadline | false |
| provisioner_state | false |
| reason | false |
| template_version_id | true |
| transition | false |
| updated_at | false |
| workspace_id | false |
|
| Field | Tracked |
|---|---|
| created_at | true |
| deleted | false |
| derp_enabled | true |
| derp_only | true |
| display_name | true |
| icon | true |
| id | true |
| name | true |
| region_id | true |
| token_hashed_secret | true |
| updated_at | false |
| url | true |
| version | true |
| wildcard_hostname | true |
+This article explains how to use secrets in a workspace. To authenticate the +workspace provisioner, see this. ++ +Coder is open-minded about how you get your secrets into your workspaces. + +## Wait a minute... + +Your first stab at secrets with Coder should be your local method. You can do +everything you can locally and more with your Coder workspace, so whatever +workflow and tools you already use to manage secrets may be brought over. + +Often, this workflow is simply: + +1. Give your users their secrets in advance +1. Your users write them to a persistent file after they've built their + workspace + +[Template parameters](./templates/parameters.md) are a dangerous way to accept +secrets. We show parameters in cleartext around the product. Assume anyone with +view access to a workspace can also see its parameters. + +## SSH Keys + +Coder generates SSH key pairs for each user. This can be used as an +authentication mechanism for git providers or other tools. Within workspaces, +git will attempt to use this key within workspaces via the `$GIT_SSH_COMMAND` +environment variable. + +Users can view their public key in their account settings: + + + +> Note: SSH keys are never stored in Coder workspaces, and are fetched only when +> SSH is invoked. The keys are held in-memory and never written to disk. + +## Dynamic Secrets + +Dynamic secrets are attached to the workspace lifecycle and automatically +injected into the workspace. With a little bit of up front template work, they +make life simpler for both the end user and the security team. + +This method is limited to +[services with Terraform providers](https://registry.terraform.io/browse/providers), +which excludes obscure API providers. + +Dynamic secrets can be implemented in your template code like so: + +```hcl +resource "twilio_iam_api_key" "api_key" { + account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" + friendly_name = "Test API Key" +} + +resource "coder_agent" "main" { + # ... + env = { + # Let users access the secret via $TWILIO_API_SECRET + TWILIO_API_SECRET = "${twilio_iam_api_key.api_key.secret}" + } +} +``` + +A catch-all variation of this approach is dynamically provisioning a cloud +service account (e.g +[GCP](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/google_service_account_key#private_key)) +for each workspace and then making the relevant secrets available via the +cloud's secret management system. + +## Displaying Secrets + +While you can inject secrets into the workspace via environment variables, you +can also show them in the Workspace UI with +[`coder_metadata`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/metadata). + + + +Can be produced with + +```hcl +resource "twilio_iam_api_key" "api_key" { + account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" + friendly_name = "Test API Key" +} + + +resource "coder_metadata" "twilio_key" { + resource_id = twilio_iam_api_key.api_key.id + item { + key = "secret" + value = twilio_iam_api_key.api_key.secret + sensitive = true + } +} +``` + +## Secrets Management + +For more advanced secrets management, you can use a secrets management tool to +store and retrieve secrets in your workspace. For example, you can use +[HashiCorp Vault](https://www.vaultproject.io/) to inject secrets into your +workspace. + +Refer to our [HashiCorp Vault Integration](./integrations/vault.md) guide for +more information on how to integrate HashiCorp Vault with Coder. diff --git a/docs/admin/telemetry.md b/docs/admin/telemetry.md deleted file mode 100644 index 29ea709f31b11..0000000000000 --- a/docs/admin/telemetry.md +++ /dev/null @@ -1,44 +0,0 @@ -# Telemetry - -
-TL;DR: disable telemetry by setting CODER_TELEMETRY=false.
-
-
-Coder collects telemetry from all installations by default. We believe our users
-should have the right to know what we collect, why we collect it, and how we use
-the data.
-
-## What we collect
-
-You can find a full list of the data we collect in our source code
-[here](https://github.com/coder/coder/blob/main/coderd/telemetry/telemetry.go).
-In particular, look at the struct types such as `Template` or `Workspace`.
-
-As a rule, we **do not collect** the following types of information:
-
-- Any data that could make your installation less secure
-- Any data that could identify individual users
-
-For example, we do not collect parameters, environment variables, or user email
-addresses.
-
-## Why we collect
-
-Telemetry helps us understand which features are most valuable, what use cases
-to focus on, and which bugs to fix first.
-
-Most cloud-based software products collect far more data than we do. They often
-offer little transparency and configurability. It's hard to imagine our favorite
-SaaS products existing without their creators having a detailed understanding of
-user interactions. We want to wield some of that product development power to
-build self-hosted, open-source software.
-
-## Security
-
-In the event we discover a critical security issue with Coder, we will use
-telemetry to identify affected installations and notify their administrators.
-
-## Toggling
-
-You can turn telemetry on or off using either the `CODER_TELEMETRY=[true|false]`
-environment variable or the `--telemetry=[true|false]` command-line flag.
diff --git a/docs/admin/templates/README.md b/docs/admin/templates/README.md
new file mode 100644
index 0000000000000..406c2438ae9a1
--- /dev/null
+++ b/docs/admin/templates/README.md
@@ -0,0 +1,41 @@
+# Template
+
+Templates are written in [Terraform](https://developer.hashicorp.com/terraform/intro) and define the underlying infrastructure that all Coder workspaces run on.
+
+
+
+The "Starter Templates" page within the Coder dashboard.
+
+## Learn the concepts
+
+While templates are written in standard Terraform, it's important to learn the Coder-specific concepts behind templates. The best way to learn the concepts is by
+[creating a basic template from scratch](../../tutorials/template-from-scratch.md).
+
+
+
+## Starter templates
+
+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).
+
+## Extending templates
+
+It's often necessary to extend the template to make it generally useful to end users. Common modifications are:
+
+- Your image(s) (e.g. a Docker image with languages and tools installed). Docs: [Image management](./extending-templates/image-management.md).
+- Additional parameters (e.g. disk size, instance type, or region). Docs: [Template parameters](./extending-templates/parameters.md).
+- Additional IDEs (e.g. JetBrains) or features (e.g. dotfiles, RDP). Docs: [Adding IDEs and features](./extending-templates/ides/README.md).
+
+Learn more about the various ways you can [extend your templates](./extending-templates.md).
+
+## Best Practices
+
+We recommend starting with a universal template that can be used for basic tasks. As your Coder deployment grows, you can create more templates to meet the needs of different teams.
+
+- [Image management](../../tutorials/image-management.md): Learn how to create and publish images for use within Coder workspaces & templates.
+- [Dev Container support](#): Enable dev containers to allow teams to bring their own tools into Coder workspaces.
+- [Template hardening](./): Configure your template to prevent certain resources from being destroyed (e.g. user disks).
+- [Manage templates with Ci/Cd pipelines](#): Learn how to source control your templates and use GitOps to ensure template changes are reviewed and tested.
+
+## Template permissions & policies (enterprise)
+
+TODO
diff --git a/docs/admin/templates/creating-templates.md b/docs/admin/templates/creating-templates.md
new file mode 100644
index 0000000000000..f24aaaf111a29
--- /dev/null
+++ b/docs/admin/templates/creating-templates.md
@@ -0,0 +1,134 @@
+# Creating Templates
+
+Users with the `Template Administrator` role or above can create templates
+within Coder.
+
+## From a starter template
+
+In most cases, it is best to start with a starter template.
+
+
+
+### Web UI
+
+After navigating to the Templates page in the Coder dashboard, choose
+`Create Template > Choose a starter template`.
+
+
+
+From there, select a starter template for desired underlying infrastructure for
+workspaces.
+
+
+
+Give your template a name, description, and icon and press `Create template`.
+
+
+
+> **⚠️ Note**: If template creation fails, Coder is likely not authorized to
+> deploy infrastructure in the given location. Learn how to configure
+> [provisioner authentication](#TODO).
+
+### CLI
+
+You can the [Coder CLI](../../install/cli.md) to manage templates for Coder.
+After [logging in](#TODO) to your deployment, create a folder to store your
+templates:
+
+```sh
+# This snippet applies to macOS and Linux only
+mkdir $HOME/coder-templates
+cd $HOME/coder-templates
+```
+
+Use the [`templates init`](../../reference/cli/templates_init.md) command to
+pull a starter template:
+
+```sh
+coder templates init
+```
+
+After pulling the template to your local machine (e.g. `aws-linux`), you can
+rename it:
+
+```sh
+# This snippet applies to macOS and Linux only
+mv aws-linux universal-template
+cd universal-template
+```
+
+Next, push it to Coder with the
+[`templates push`](../../reference/cli/templates_push.md) command:
+
+```sh
+coder templates push
+```
+
+> ⚠️ Note: If `template push` fails, Coder is likely not authorized to deploy
+> infrastructure in the given location. Learn how to configure
+> [provisioner authentication](#TODO).
+
+You can edit the metadata of the template such as the display name with the
+[`templates edit`](../../reference/cli/templates_edit.md) command:
+
+```sh
+coder templates edit universal-template \
+ --display-name "Universal Template" \
+ --description "Virtual machine configured with Java, Python, Typescript, IntelliJ IDEA, and Ruby. Use this for starter projects. " \
+ --icon "/emojis/2b50.png"
+```
+
+### CI/CD
+
+Follow the [change management](./managing-templates/change-management.md) guide to manage templates via GitOps.
+
+
+
+## From an existing template
+
+You can duplicate an existing template in your Coder deployment. This will copy
+the template code and metadata, allowing you to make changes without affecting
+the original template.
+
+
+
+### Web UI
+
+After navigating to the page for a template, use the dropdown menu on the right
+to `Duplicate`.
+
+
+
+Give the new template a name, icon, and description.
+
+
+
+Press `Create template`. After the build, you will be taken to the new template
+page.
+
+
+
+### CLI
+
+
+
+## From scratch (advanced)
+
+There may be cases where you want to create a template from scratch. You can use
+[any Terraform provider](https://registry.terraform.com) with Coder to create
+templates for additional clouds (e.g. Hetzner, Alibaba) or orchestrators
+(VMware, Proxmox) that we do not provide example templates for.
+
+Refer to the following resources:
+
+- [Tutorial: Create a template from scratch](../../tutorials/template-from-scratch.md)
+- [Extending templates](./editing-templates.md): Features and concepts around
+ templates (agents, parameters, variables, etc)
+- [Coder Registry](https://registry.coder.com/templates): Official and community
+ templates for Coder
+- [Coder Terraform Provider Reference](https://registry.terraform.io/providers/coder/coder)
+
+## Next steps
+
+- [Extending templates](#TODO)
+- [TODO](#TODO)
diff --git a/docs/admin/templates/extending-templates/README.md b/docs/admin/templates/extending-templates/README.md
new file mode 100644
index 0000000000000..322c6a6030317
--- /dev/null
+++ b/docs/admin/templates/extending-templates/README.md
@@ -0,0 +1,60 @@
+# Extending templates
+
+
+
+There are a variety of Coder-native features to extend the configuration of your development environments. Many of the following features are defined in your templates using the [Coder Terraform provider](https://registry.terraform.io/providers/coder/coder/latest/docs). The provider docs will provide code examples for usage; alternatively, you can view our [example templates](https://github.com/coder/coder/tree/main/examples/templates) to get started.
+
+## Workspace agents
+
+For users to connect to a workspace, the template must include a [`coder_agent`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent). The associated agent will facilitate [workspace connections](../../../user-guides/workspace-access/README.md) via SSH, port forwarding, and IDEs. The agent may also display real-time [workspace metadata](./agent-metadata.md) like resource usage.
+
+```hcl
+resource "coder_agent" "dev" {
+ os = "linux"
+ arch = "amd64"
+ dir = "/workspace"
+ display_apps {
+ vscode = true
+ }
+}
+```
+
+You can also leverage [resource metadata](./resource-metadata.md) to display static resource information from your template.
+
+Templates must include some computational resource to start the agent. All processes on the workspace are then spawned from the agent. It also provides all information displayed in the dashboard's workspace view.
+
+
+
+Multiple agents may be used in a single template or even a single resource. Each agent may have it's own apps, startup script, and metadata. This can be used to associate multiple containers or VMs with a workspace.
+
+## Resource persistence
+
+The resources you define in a template may be _ephemeral_ or _persistent_. Persistent resources stay provisioned when workspaces are stopped, where as ephemeral resources are destroyed and recreated on restart. All resources are destroyed when a workspace is deleted.
+
+> You can read more about how resource behavior and workspace state in the [workspace lifecycle documentation](../../workspaces/lifecycle.md).
+
+Template resources follow the [behavior of Terraform resources](https://developer.hashicorp.com/terraform/language/resources/behavior#how-terraform-applies-a-configuration) and can be further configured using the [lifecycle argument](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle).
+
+A common configuration is a template whose only persistent resource is the home directory. This allows the developer to retain their work while ensuring the rest of their environment is consistently up-to-date on each workspace restart.
+
+When a workspace is deleted, the Coder server essentially runs a
+[terraform destroy](https://www.terraform.io/cli/commands/destroy) to remove all
+resources associated with the workspace.
+
+> Terraform's
+> [prevent-destroy](https://www.terraform.io/language/meta-arguments/lifecycle#prevent_destroy)
+> and
+> [ignore-changes](https://www.terraform.io/language/meta-arguments/lifecycle#ignore_changes)
+> meta-arguments can be used to prevent accidental data loss.
+
+## Coder apps
+
+Additional IDEs, documentation, or services can be associated to your workspace using the [`coder_app`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app) resource.
+
+
+
+Note that some apps are associated to the agent by default as [`display_apps`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#nested-schema-for-display_apps) and can be hidden directly in the [`coder_agent`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent) resource. You can arrange the display orientation of Coder apps in your template using [resource ordering](./resource-ordering.md).
+
+Check out our [module registry](https://registry.coder.com/modules) for additional Coder apps from the team and our OSS community.
+
+++ +By default, the coder agent will configure native `git` authentication via the +`GIT_ASKPASS` environment variable. Meaning, with no additional configuration, +external authentication will work with native `git` commands. + +To check the auth token being used **from inside a running workspace**, run: + +```shell +# If the exit code is non-zero, then the user is not authenticated with the +# external provider. +coder external-auth access-token+ This is the preferred authentication method. +
+
type metadata.
@@ -107,5 +107,5 @@ how to use the builtin icons [here](./icons.md).
## Up next
-- [Secrets](../secrets.md)
+- [Secrets](../../security/secrets.md)
- [Agent metadata](./agent-metadata.md)
diff --git a/docs/templates/resource-ordering.md b/docs/admin/templates/extending-templates/resource-ordering.md
similarity index 100%
rename from docs/templates/resource-ordering.md
rename to docs/admin/templates/extending-templates/resource-ordering.md
diff --git a/docs/templates/variables.md b/docs/admin/templates/extending-templates/variables.md
similarity index 100%
rename from docs/templates/variables.md
rename to docs/admin/templates/extending-templates/variables.md
diff --git a/docs/ides/web-ides.md b/docs/admin/templates/extending-templates/web-ides.md
similarity index 85%
rename from docs/ides/web-ides.md
rename to docs/admin/templates/extending-templates/web-ides.md
index 89a6b4ca26e79..2db879ab9b402 100644
--- a/docs/ides/web-ides.md
+++ b/docs/admin/templates/extending-templates/web-ides.md
@@ -1,16 +1,5 @@
# Web IDEs
-By default, Coder workspaces allow connections via:
-
-- Web terminal
-- SSH (plus any [SSH-compatible IDE](../ides.md))
-
-It's common to also let developers to connect via web IDEs for uses cases like
-zero trust networks, data science, contractors, and infrequent code
-contributors.
-
-
-
In Coder, web IDEs are defined as
[coder_app](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app)
resources in the template. With our generic model, any web application can be
@@ -34,33 +23,6 @@ resource "coder_app" "portainer" {
}
```
-## External URLs
-
-Any URL external to the Coder deployment is accessible as a `coder_app`. e.g.,
-Dropbox, Slack, Discord, GitHub
-
-```hcl
-resource "coder_app" "pubslack" {
- agent_id = coder_agent.coder.id
- display_name = "Coder Public Slack"
- slug = "pubslack"
- url = "https://coder-com.slack.com/"
- icon = "/icon/slack.svg"
- external = true
-}
-
-resource "coder_app" "discord" {
- agent_id = coder_agent.coder.id
- display_name = "Coder Discord"
- slug = "discord"
- url = "https://discord.com/invite/coder"
- icon = "/icon/discord.svg"
- external = true
-}
-```
-
-
-
## code-server
[code-server](https://github.com/coder/coder) is our supported method of running
@@ -223,17 +185,24 @@ resource "coder_app" "jupyter" {
}
```
+Or Alternatively, you can use the Jypyter Lab module from the Coder registry:
+
+```tf
+module "jupyter" {
+ source = "registry.coder.com/modules/jupyter-lab/coder"
+ version = "1.0.0"
+ agent_id = coder_agent.main.id
+}
+```
+
If you cannot enable a
[wildcard subdomain](https://coder.com/docs/admin/configure#wildcard-access-url),
you can configure the template to run Jupyter on a path. There is however
-[security risk](https://coder.com/docs/cli/server#--dangerous-allow-path-app-sharing)
+[security risk](https://coder.com/docs/reference/cli/server#--dangerous-allow-path-app-sharing)
running an app on a path and the template code is more complicated with coder
value substitution to recreate the path structure.
-[This](https://github.com/sharkymark/v2-templates/tree/main/src/pod-with-jupyter-path)
-is a community template example.
-
-
+
## RStudio
@@ -252,7 +221,6 @@ resource "coder_agent" "coder" {
EOT
}
-# rstudio
resource "coder_app" "rstudio" {
agent_id = coder_agent.coder.id
slug = "rstudio"
@@ -274,14 +242,14 @@ If you cannot enable a
[wildcard subdomain](https://coder.com/docs/admin/configure#wildcard-access-url),
you can configure the template to run RStudio on a path using an NGINX reverse
proxy in the template. There is however
-[security risk](https://coder.com/docs/cli/server#--dangerous-allow-path-app-sharing)
+[security risk](https://coder.com/docs/reference/cli/server#--dangerous-allow-path-app-sharing)
running an app on a path and the template code is more complicated with coder
value substitution to recreate the path structure.
[This](https://github.com/sempie/coder-templates/tree/main/rstudio) is a
community template example.
-
+
## Airflow
@@ -318,10 +286,25 @@ resource "coder_app" "airflow" {
}
```
-
+or use the [Airflow module](https://registry.coder.com/modules/apache-airflow)
+from the Coder registry:
+
+```tf
+module "airflow" {
+ source = "registry.coder.com/modules/airflow/coder"
+ version = "1.0.13"
+ agent_id = coder_agent.main.id
+}
+```
+
+
## File Browser
+To access the contents of a workspace directory in a browser, you can use File
+Browser. File Browser is a lightweight file manager that allows you to view and
+manipulate files in a web browser.
+
Show and manipulate the contents of the `/home/coder` directory in a browser.
```hcl
@@ -355,6 +338,18 @@ resource "coder_app" "filebrowser" {
}
```
+Or alternatively, you can use the
+[`filebrowser`](https://registry.coder.com/modules/filebrowser) module from the
+Coder registry:
+
+```tf
+module "filebrowser" {
+ source = "registry.coder.com/modules/filebrowser/coder"
+ version = "1.0.8"
+ agent_id = coder_agent.main.id
+}
+```
+
## SSH Fallback
diff --git a/docs/templates/creating.md b/docs/admin/templates/managing-templates/README.md
similarity index 65%
rename from docs/templates/creating.md
rename to docs/admin/templates/managing-templates/README.md
index 4818ae989aa83..77fe2d94ea844 100644
--- a/docs/templates/creating.md
+++ b/docs/admin/templates/managing-templates/README.md
@@ -7,10 +7,9 @@ other services.
## Who creates templates?
The [Template Admin](../admin/users.md) role (and above) can create templates.
-End users, like developers, create workspaces from them.
-
-Templates can also be [managed with git](./change-management.md), allowing any
-developer to propose changes to a template.
+End users, like developers, create workspaces from them. Templates can also be
+[managed with git](./change-management.md), allowing any developer to propose
+changes to a template.
You can give different users and groups access to templates with
[role-based access control](../admin/rbac.md).
@@ -23,9 +22,9 @@ 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!
-
+
-If you prefer to use Coder on the [command line](../cli.md), use
+If you prefer to use Coder on the [command line](../../reference/cli/README.md),
`coder templates init`.
> Coder starter templates are also available on our
@@ -42,7 +41,7 @@ by our users
Our starter templates are meant to be modified for your use cases. You can edit
any template's files directly in the Coder dashboard.
-
+
If you'd prefer to use the CLI, use `coder templates pull`, edit the template
files, then `coder templates push`.
@@ -57,7 +56,18 @@ When you publish a new version, developers are notified to get the latest
infrastructure, software, or security patches. Learn more about
[change management](./change-management.md).
-
+
+
+### Template update policies (enterprise)
+
+Enterprise template admins may want workspaces to always remain on the latest
+version of their parent template. To do so, enable **Template Update Policies**
+in the template's general settings. All non-admin users of the template will be
+forced to update their workspaces before starting them once the setting is
+applied. Workspaces which leverage autostart or start-on-connect will be
+automatically updated on the next startup.
+
+
## Delete templates
@@ -68,7 +78,7 @@ template must not have any running workspaces associated to it.
In the UI, navigate to the template you want to delete, and select the dropdown
in the right-hand corner of the page to delete the template.
-
+
Using the CLI, login to Coder and run the following command to delete a
template:
@@ -77,18 +87,10 @@ template:
coder templates delete -- -To upgrade your Coder server, simply reinstall Coder using your original method -of [install](../install). - -## Via install.sh - -If you installed Coder using the `install.sh` script, re-run the below command -on the host: - -```shell -curl -L https://coder.com/install.sh | sh -``` - -The script will unpack the new `coder` binary version over the one currently -installed. Next, you can restart Coder with the following commands (if running -it as a system service): - -```shell -systemctl daemon-reload -systemctl restart coder -``` - -## Via docker-compose - -If you installed using `docker-compose`, run the below command to upgrade the -Coder container: - -```shell -docker-compose pull coder && docker-compose up -d coder -``` - -## Via Kubernetes - -See -[Upgrading Coder via Helm](../install/kubernetes.md#upgrading-coder-via-helm). - -## Via Windows - -Download the latest Windows installer or binary from -[GitHub releases](https://github.com/coder/coder/releases/latest), or upgrade -from Winget. - -```pwsh -winget install Coder.Coder -``` - -## Up Next - -- [Learn how to enable Enterprise features](../enterprise.md). diff --git a/docs/admin/users.md b/docs/admin/users/README.md similarity index 72% rename from docs/admin/users.md rename to docs/admin/users/README.md index 02832a7e22320..308b2b6aca430 100644 --- a/docs/admin/users.md +++ b/docs/admin/users/README.md @@ -1,38 +1,25 @@ # Users -This article walks you through the user roles available in Coder and creating -and managing users. +By default, Coder is accessible via password authentication. For production deployments, we recommend using an SSO authentication provider with multi-factor authentication (MFA). It is your responsibility to ensure the auth provider enforces MFA correctly. + +## Configuring SSO + +- [OpenID Connect](./auth.md#openid-connect) (e.g. Okta, KeyCloak, PingFederate, Azure AD) +- [GitHub](./auth.md#github) (or GitHub Enterprise) + +## Groups + +Multiple users can be organized into logical groups to control which templates they can use. While groups can be manually created in Coder, we recommend syncing them from your identity provider. + +- [Learn more about Groups](./groups.md) +- [Group & Role Sync](./group-role-sync.md) ## Roles -Coder offers these user roles in the community edition: - -| | Auditor | User Admin | Template Admin | Owner | -| ----------------------------------------------------- | ------- | ---------- | -------------- | ----- | -| Add and remove Users | | ✅ | | ✅ | -| Manage groups (enterprise) | | ✅ | | ✅ | -| Change User roles | | | | ✅ | -| Manage **ALL** Templates | | | ✅ | ✅ | -| View **ALL** Workspaces | | | ✅ | ✅ | -| Update and delete **ALL** Workspaces | | | | ✅ | -| Run [external provisioners](./provisioners.md) | | | ✅ | ✅ | -| Execute and use **ALL** Workspaces | | | | ✅ | -| View all user operation [Audit Logs](./audit-logs.md) | ✅ | | | ✅ | - -A user may have one or more roles. All users have an implicit Member role that -may use personal workspaces. - -## Security notes - -A malicious Template Admin could write a template that executes commands on the -host (or `coder server` container), which potentially escalates their privileges -or shuts down the Coder server. To avoid this, run -[external provisioners](./provisioners.md). - -In low-trust environments, we do not recommend giving users direct access to -edit templates. Instead, use -[CI/CD pipelines to update templates](../templates/change-management.md) with -proper security scans and code reviews in place. +Roles determine which actions users can take within the platform. Typically, most developers in your organization have the `Member` role, allowing them to create workspaces. Other roles have administrative capabilities such as auditing, managing users, and managing templates. + +- [Learn more about Roles](./roles.md) +- [Group & Role Sync](./group-role-sync.md) ## User status diff --git a/docs/admin/users/github-auth.md b/docs/admin/users/github-auth.md new file mode 100644 index 0000000000000..155b6a3b4ed8d --- /dev/null +++ b/docs/admin/users/github-auth.md @@ -0,0 +1,84 @@ +## GitHub + +### Step 1: Configure the OAuth application in GitHub + +First, +[register a GitHub OAuth app](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/). +GitHub will ask you for the following Coder parameters: + +- **Homepage URL**: Set to your Coder deployments + [`CODER_ACCESS_URL`](../cli/server.md#--access-url) (e.g. + `https://coder.domain.com`) +- **User Authorization Callback URL**: Set to `https://coder.domain.com` + +> Note: If you want to allow multiple coder deployments hosted on subdomains +> e.g. coder1.domain.com, coder2.domain.com, to be able to authenticate with the +> same GitHub OAuth app, then you can set **User Authorization Callback URL** to +> the `https://domain.com` + +Note the Client ID and Client Secret generated by GitHub. You will use these +values in the next step. + +Coder will need permission to access user email addresses. Find the "Account +Permissions" settings for your app and select "read-only" for "Email addresses". + +### Step 2: Configure Coder with the OAuth credentials + +Navigate to your Coder host and run the following command to start up the Coder +server: + +```shell +coder server --oauth2-github-allow-signups=true --oauth2-github-allowed-orgs="your-org" --oauth2-github-client-id="8d1...e05" --oauth2-github-client-secret="57ebc9...02c24c" +``` + +> For GitHub Enterprise support, specify the +> `--oauth2-github-enterprise-base-url` flag. + +Alternatively, if you are running Coder as a system service, you can achieve the +same result as the command above by adding the following environment variables +to the `/etc/coder.d/coder.env` file: + +```env +CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true +CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org" +CODER_OAUTH2_GITHUB_CLIENT_ID="8d1...e05" +CODER_OAUTH2_GITHUB_CLIENT_SECRET="57ebc9...02c24c" +``` + +**Note:** To allow everyone to signup using GitHub, set: + +```env +CODER_OAUTH2_GITHUB_ALLOW_EVERYONE=true +``` + +Once complete, run `sudo service coder restart` to reboot Coder. + +If deploying Coder via Helm, you can set the above environment variables in the +`values.yaml` file as such: + +```yaml +coder: + env: + - name: CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS + value: "true" + - name: CODER_OAUTH2_GITHUB_CLIENT_ID + value: "533...des" + - name: CODER_OAUTH2_GITHUB_CLIENT_SECRET + value: "G0CSP...7qSM" + # If setting allowed orgs, comment out CODER_OAUTH2_GITHUB_ALLOW_EVERYONE and its value + - name: CODER_OAUTH2_GITHUB_ALLOWED_ORGS + value: "your-org" + # If allowing everyone, comment out CODER_OAUTH2_GITHUB_ALLOWED_ORGS and it's value + #- name: CODER_OAUTH2_GITHUB_ALLOW_EVERYONE + # value: "true" +``` + +To upgrade Coder, run: + +```shell +helm upgrade- Prior to upgrading a production Coder deployment, take a database snapshot since - Coder does not support rollbacks. -
-
+
+## CLI
+
+```sh
+coder users create \
+ --email="coder-bot@coder.com" \
+ --username="coder-bot" \
+ --login-type="none \
+```
+
+## UI
+
+Navigate to the `Users` > `Create user` in the topbar
+
+
+
+
+
+To make API or CLI requests on behalf of the headless user, learn how to
+[generate API tokens on behalf of a user](./sessions-tokens.md#generate-a-long-lived-api-token-on-behalf-of-another-user).
diff --git a/docs/admin/auth.md b/docs/admin/users/oidc-auth.md
similarity index 81%
rename from docs/admin/auth.md
rename to docs/admin/users/oidc-auth.md
index c0ac87c6511f2..812491de50886 100644
--- a/docs/admin/auth.md
+++ b/docs/admin/users/oidc-auth.md
@@ -1,101 +1,4 @@
-# Authentication
-
-.
-
-By default, Coder is accessible via password authentication. Coder does not
-recommend using password authentication in production, and recommends using an
-authentication provider with properly configured multi-factor authentication
-(MFA). It is your responsibility to ensure the auth provider enforces MFA
-correctly.
-
-The following steps explain how to set up GitHub OAuth or OpenID Connect.
-
-## GitHub
-
-### Step 1: Configure the OAuth application in GitHub
-
-First,
-[register a GitHub OAuth app](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/).
-GitHub will ask you for the following Coder parameters:
-
-- **Homepage URL**: Set to your Coder deployments
- [`CODER_ACCESS_URL`](../cli/server.md#--access-url) (e.g.
- `https://coder.domain.com`)
-- **User Authorization Callback URL**: Set to `https://coder.domain.com`
-
-> Note: If you want to allow multiple coder deployments hosted on subdomains
-> e.g. coder1.domain.com, coder2.domain.com, to be able to authenticate with the
-> same GitHub OAuth app, then you can set **User Authorization Callback URL** to
-> the `https://domain.com`
-
-Note the Client ID and Client Secret generated by GitHub. You will use these
-values in the next step.
-
-Coder will need permission to access user email addresses. Find the "Account
-Permissions" settings for your app and select "read-only" for "Email addresses".
-
-### Step 2: Configure Coder with the OAuth credentials
-
-Navigate to your Coder host and run the following command to start up the Coder
-server:
-
-```shell
-coder server --oauth2-github-allow-signups=true --oauth2-github-allowed-orgs="your-org" --oauth2-github-client-id="8d1...e05" --oauth2-github-client-secret="57ebc9...02c24c"
-```
-
-> For GitHub Enterprise support, specify the
-> `--oauth2-github-enterprise-base-url` flag.
-
-Alternatively, if you are running Coder as a system service, you can achieve the
-same result as the command above by adding the following environment variables
-to the `/etc/coder.d/coder.env` file:
-
-```env
-CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true
-CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org"
-CODER_OAUTH2_GITHUB_CLIENT_ID="8d1...e05"
-CODER_OAUTH2_GITHUB_CLIENT_SECRET="57ebc9...02c24c"
-```
-
-**Note:** To allow everyone to signup using GitHub, set:
-
-```env
-CODER_OAUTH2_GITHUB_ALLOW_EVERYONE=true
-```
-
-Once complete, run `sudo service coder restart` to reboot Coder.
-
-If deploying Coder via Helm, you can set the above environment variables in the
-`values.yaml` file as such:
-
-```yaml
-coder:
- env:
- - name: CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS
- value: "true"
- - name: CODER_OAUTH2_GITHUB_CLIENT_ID
- value: "533...des"
- - name: CODER_OAUTH2_GITHUB_CLIENT_SECRET
- value: "G0CSP...7qSM"
- # If setting allowed orgs, comment out CODER_OAUTH2_GITHUB_ALLOW_EVERYONE and its value
- - name: CODER_OAUTH2_GITHUB_ALLOWED_ORGS
- value: "your-org"
- # If allowing everyone, comment out CODER_OAUTH2_GITHUB_ALLOWED_ORGS and it's value
- #- name: CODER_OAUTH2_GITHUB_ALLOW_EVERYONE
- # value: "true"
-```
-
-To upgrade Coder, run:
-
-```shell
-helm upgrade
+
+#### UI
+
+Visit your account settings in the top right of the dashboard or by navigating
+to `https://coder.example.com/settings/account`
+
+Navigate to the tokens page in the sidebar and create a new token:
+
+
+
+#### CLI
+
+Use the following command:
+
+```sh
+coder tokens create --name=my-token --lifetime=720h
+```
+
+See the help docs for [`coder tokens create`](../../reference/cli/tokens_create)
+for more info.
+
+
+
+### Generate a long-lived API token on behalf of another user
+
+Today, you must use the REST API to generate a token on behalf of another user.
+You must have the `Owner` role to do this. Use our API reference for more
+information:
+[Create token API key](https://coder.com/docs/reference/api/users#create-token-api-key)
+
+### Set max token length
+
+You can use the
+[`CODER_MAX_TOKEN_LIFETIME`](https://coder.com/docs/reference/cli/server#--max-token-lifetime)
+server flag to set the maximum duration for long-lived tokens in your
+deployment.
diff --git a/docs/admin/workspaces/README.md b/docs/admin/workspaces/README.md
new file mode 100644
index 0000000000000..28d29319b09c1
--- /dev/null
+++ b/docs/admin/workspaces/README.md
@@ -0,0 +1,85 @@
+# Administering workspaces
+
+
+
+Coder manages Workspaces, which are user-facing virtualized development environments. Each workspace is defined by a [template](../templates/README.md), owned by a single user, and can be individually modified with parameters and scheduling.
+
+Coder allows workspaces to be hosted on either VMs or containers and is not opinionated on which compute you choose to maximize flexibility.
+
+
+
+> If you are an end-user of Coder looking to learn more about how to use and manage the workspaces you own, see our [user guides](../../user-guides/README.md).
+
+## Viewing and Filtering workspaces
+
+Admins have visibility for every workspace in a deployment under the **Workspaces** tab. The name, associated template, and status are shown for each workspace.
+
+
+
+You can filter these workspaces using pre-defined filters or
+Coder's filter query. For example, you can find the workspaces that you own or
+that are currently running.
+
+The following filters are supported:
+
+- `owner` - Represents the `username` of the owner. You can also use `me` as a
+ convenient alias for the logged-in user.
+- `template` - Specifies the name of the template.
+- `status` - Indicates the status of the workspace. For a list of supported
+ statuses, see
+ [WorkspaceStatus documentation](https://pkg.go.dev/github.com/coder/coder/codersdk#WorkspaceStatus).
+
+## Updating workspaces
+
+After updating the default version of the template that a workspace was created
+from, you can update the workspace.
+
+
+
+
+
+If the workspace is running, Coder stops it, updates it, then starts the workspace again.
+
+### Updating via the CLI
+
+Update a workspace through the command line:
+
+```shell
+coder update
## Linux/macOS
@@ -42,15 +38,11 @@ package manager to install Coder:
winget install Coder.Coder
```
-## Other
-
-
To start the Coder server:
-```sh
+````sh
coder server
```
@@ -60,7 +52,7 @@ To log in to an existing Coder deployment:
```sh
coder login https://coder.example.com
-```
+````
## Next up
diff --git a/docs/install/cloud/README.md b/docs/install/cloud/README.md
new file mode 100644
index 0000000000000..0721a89197ea8
--- /dev/null
+++ b/docs/install/cloud/README.md
@@ -0,0 +1,35 @@
+# Cloud Platforms
+
+We provide install guides and example templates for deploying Coder to your cloud of choice.
+
+
+
+## AWS
+
+We publish an EC2 image with Coder pre-installed. Follow the tutorial here:
+
+- [Install Coder on AWS EC2](./ec2.md)
+
+Alternatively, install the [CLI binary](../cli.md) on any Linux machine or follow our [Kubernetes](../kubernetes.md) documentation to install Coder on an existing EKS cluster.
+
+## GCP
+
+We publish a GCP Marketplace listing with Coder pre-installed. Follow the tutorial here:
+
+- [Install Coder on GCP Compute Engine](./compute-engine.md)
+
+Alternatively, install the [CLI binary](../cli.md) on any Linux machine or follow our [Kubernetes](../kubernetes.md) documentation to install Coder on an existing GKE cluster.
+
+## Azure
+
+Use the following guide to run Coder on an Azure VM:
+
+- [Install Coder on an Azure VM](./azure-vm.md)
+
+Alternatively, install the [CLI binary](../cli.md) on any Linux machine or follow our [Kubernetes](../kubernetes.md) documentation to install Coder on an existing GKE cluster.
+
+## Other
+
+Is your cloud missing? Check [unofficial](../other/README.md) install methods or install the [standalone binary](../cli.md).
+
+
diff --git a/docs/platforms/azure.md b/docs/install/cloud/azure-vm.md
similarity index 88%
rename from docs/platforms/azure.md
rename to docs/install/cloud/azure-vm.md
index df5bb64a5b5fb..751d204b321b4 100644
--- a/docs/platforms/azure.md
+++ b/docs/install/cloud/azure-vm.md
@@ -12,7 +12,7 @@ This guide assumes you have full administrator privileges on Azure.
From the Azure Portal, navigate to the Virtual Machines Dashboard. Click Create,
and select creating a new Azure Virtual machine .
-
+
This will bring you to the `Create a virtual machine` page. Select the
subscription group of your choice, or create one if necessary.
@@ -22,14 +22,14 @@ of your choice. Change the region to something more appropriate for your current
location. For this tutorial, we will use the base selection of the Ubuntu Gen2
Image and keep the rest of the base settings for this image the same.
-
+
-
+
Up next, under `Inbound port rules` modify the Select `inbound ports` to also
take in `HTTPS` and `HTTP`.
-
+
The set up for the image is complete at this stage. Click `Review and Create` -
review the information and click `Create`. A popup will appear asking you to
@@ -37,11 +37,11 @@ download the key pair for the server. Click
`Download private key and create resource` and place it into a folder of your
choice on your local system.
-
+
Click `Return to create a virtual machine`. Your VM will start up!
-
+
Click `Go to resource` in the virtual machine and copy the public IP address.
You will need it to SSH into the virtual machine via your local machine.
@@ -100,12 +100,12 @@ First, run `coder template init` to create your first template. You’ll be give
a list of possible templates to use. This tutorial will show you how to set up
your Coder instance to create a Linux based machine on Azure.
-
+
Press `enter` to select `Develop in Linux on Azure` template. This will return
the following:
-
+
To get started using the Azure template, install the Azure CLI by following the
instructions
@@ -133,9 +133,3 @@ coder templates push
Congrats! You can now navigate to your Coder dashboard and use this Linux on
Azure template to create a new workspace!
-
-## Next Steps
-
-- [Port-forward](../networking/port-forwarding.md)
-- [Learn more about template configuration](../templates/index.md)
-- [Configure more IDEs](../ides/web-ides.md)
diff --git a/docs/platforms/gcp.md b/docs/install/cloud/compute-engine.md
similarity index 91%
rename from docs/platforms/gcp.md
rename to docs/install/cloud/compute-engine.md
index c8c4203314c77..5c1997a21f110 100644
--- a/docs/platforms/gcp.md
+++ b/docs/install/cloud/compute-engine.md
@@ -14,7 +14,7 @@ We publish an Ubuntu 22.04 VM image with Coder and Docker pre-installed. Search
for `Coder v2` in the GCP Marketplace or
[use direct link](https://console.cloud.google.com/marketplace/product/coder-enterprise-market-public/coder-v2).
-
+
Be sure to keep the default firewall options checked so you can connect over
HTTP, HTTPS, and SSH.
@@ -31,18 +31,18 @@ Your browser does not support the video tag.
Be sure to add a keypair so that you can connect over SSH to further
-[configure Coder](../admin/configure.md).
+[configure Coder](../../admin/configure.md).
After launching the instance, wait 30 seconds and navigate to the public IPv4
address. You should be redirected to a public tunnel URL.
-
+
That's all! Use the UI to create your first user, template, and workspace. We
recommend starting with a Docker template since the instance has Docker
pre-installed.
-
+
## Configuring Coder server
diff --git a/docs/install/cloud/ec2.md b/docs/install/cloud/ec2.md
new file mode 100644
index 0000000000000..f9bdf9ff30e36
--- /dev/null
+++ b/docs/install/cloud/ec2.md
@@ -0,0 +1,90 @@
+# Amazon Web Services
+
+This guide is designed to get you up and running with a Coder proof-of-concept
+VM on AWS EC2 using a [Coder-provided AMI](https://github.com/coder/packages).
+If you are familiar with EC2 however, you can use our
+[install script](../cli.md) to run Coder on any popular Linux distribution.
+
+## Requirements
+
+This guide assumes your AWS account has `AmazonEC2FullAccess` permissions.
+
+## Launch a Coder instance from the from AWS Marketplace
+
+We publish an Ubuntu 22.04 AMI with Coder and Docker pre-installed. Search for
+`Coder` in the EC2 "Launch an Instance" screen or
+[launch directly from the marketplace](https://aws.amazon.com/marketplace/pp/prodview-5gxjyur2vc7rg).
+
+
+
+Be sure to keep the default firewall (SecurityGroup) options checked so you can
+connect over HTTP, HTTPS, and SSH.
+
+
+
+We recommend keeping the default instance type (`t2.xlarge`, 4 cores and 16 GB
+memory) if you plan on provisioning Docker containers as workspaces on this EC2
+instance. Keep in mind this platforms is intended for proof-of-concept
+deployments and you should adjust your infrastructure when preparing for
+production use. See: [Scaling Coder](../../admin/scale.md)
+
+Be sure to add a keypair so that you can connect over SSH to further
+[configure Coder](../../admin/configure.md).
+
+After launching the instance, wait 30 seconds and navigate to the public IPv4
+address. You should be redirected to a public tunnel URL.
+
+
+
+That's all! Use the UI to create your first user, template, and workspace. We
+recommend starting with a Docker template since the instance has Docker
+pre-installed.
+
+
+
+## Configuring Coder server
+
+Coder is primarily configured by server-side flags and environment variables.
+Given you created or added key-pairs when launching the instance, you can
+[configure your Coder deployment](../../admin/configure.md) by logging in via
+SSH or using the console:
+
+
+
+```sh
+ssh ubuntu@
+
-## docker run
+## Install Coder via `docker run`
-**Built-in database (quick)**
+### Built-in database (quick)
For proof-of-concept deployments, you can run a complete Coder instance with the
following command.
@@ -29,7 +33,7 @@ docker run --rm -it \
ghcr.io/coder/coder:latest
```
-**External database**
+### External database (recommended)
For production deployments, we recommend using an external PostgreSQL database
(version 13 or higher). Set `CODER_ACCESS_URL` to the external URL that users
@@ -45,7 +49,7 @@ docker run --rm -it \
ghcr.io/coder/coder:latest
```
-## docker compose
+## Install Coder via `docker compose`
Coder's publishes a
[docker-compose example](https://github.com/coder/coder/blob/main/docker-compose.yaml)
@@ -67,31 +71,14 @@ which includes an PostgreSQL container and volume.
4. Start Coder with `docker compose up`
-5. Visit the web ui via the configured url.
+5. Visit the web UI via the configured url.
6. Follow the on-screen instructions log in and create your first template and
workspace
-
-
Coder configuration is defined via environment variables. Learn more about
Coder's [configuration options](../admin/configure.md).
-> **Note:** In order to use cloud-based templates (e.g. Kubernetes, AWS), you
-> must have an external URL that users and workspaces will use to connect to
-> Coder.
->
-> > For proof-of-concept deployments, you can use
-> > [Coder's tunnel](../admin/configure.md#tunnel).
-> >
-> > For production deployments, we recommend setting an
-> > [access URL](../admin/configure.md#access-url)
-
-> **Note:** Coder runs as a non-root user, we use `--group-add` to ensure Coder
-> has permissions to manage Docker via `docker.sock`. If the host systems
-> `/var/run/docker.sock` is not group writeable or does not belong to the
-> `docker` group, the above may not work as-is.
-
## Troubleshooting
### Docker-based workspace is stuck in "Connecting..."
@@ -105,7 +92,17 @@ more steps.
See Docker's official documentation to
[Manage Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user)
-## Next steps
+### I cannot add Docker templates
+
+Coder runs as a non-root user, we use `--group-add` to ensure Coder has
+permissions to manage Docker via `docker.sock`. If the host systems
+`/var/run/docker.sock` is not group writeable or does not belong to the `docker`
+group, the above may not work as-is.
+
+### I cannot add cloud-based templates
-- [Configuring Coder](../admin/configure.md)
-- [Templates](../templates/index.md)
+In order to use cloud-based templates (e.g. Kubernetes, AWS), you must have an
+external URL that users and workspaces will use to connect to Coder. For
+proof-of-concept deployments, you can use
+[Coder's tunnel](../admin/configure.md#tunnel). For production deployments, we
+recommend setting an [access URL](../admin/configure.md#access-url)
diff --git a/docs/install/kubernetes.md b/docs/install/kubernetes.md
index 72d8d43061e65..b28738015ec73 100644
--- a/docs/install/kubernetes.md
+++ b/docs/install/kubernetes.md
@@ -1,164 +1,159 @@
+# Install Coder on Kubernetes
+
+You can install Coder on Kubernetes using Helm. We run on most Kubernetes
+distributions, including [OpenShift](./other/openshift.md).
+
## Requirements
-Before proceeding, please ensure that you have a Kubernetes cluster running K8s
-1.19+ and have Helm 3.5+ installed.
-
-You'll also want to install the
-[latest version of Coder](https://github.com/coder/coder/releases/latest)
-locally in order to log in and manage templates.
-
-> Coder supports two release channels: mainline for the true latest version of
-> Coder, and stable for large enterprise deployments. Before installing your
-> control plane via Helm, please read the [Releases](./releases.md) document to
-> identify the best-suited release for your team, then specify the version using
-> Helm's `--version` flag.
-
-> The version flags for both stable and mainline are automatically filled in
-> this page.
-
-> If you need help setting up k8s, we have a
-> [repo with Terraform configuration](https://github.com/ElliotG/coder-oss-tf)
-> to provision Coder on Google GKE, Azure AKS, AWS EKS, DigitalOcean DOKS,
-> IBMCloud K8s, OVHCloud K8s, and Scaleway K8s Kapsule.
-
-## Install Coder with Helm
-
-1. Create a namespace for Coder, such as `coder`:
-
- ```console
- kubectl create namespace coder
- ```
-
-1. Create a PostgreSQL deployment. Coder does not manage a database server for
- you.
-
- If you're in a public cloud such as
- [Google Cloud](https://cloud.google.com/sql/docs/postgres/),
- [AWS](https://aws.amazon.com/rds/postgresql/),
- [Azure](https://docs.microsoft.com/en-us/azure/postgresql/), or
- [DigitalOcean](https://www.digitalocean.com/products/managed-databases-postgresql),
- you can use the managed PostgreSQL offerings they provide. Make sure that the
- PostgreSQL service is running and accessible from your cluster. It should be
- in the same network, same project, etc.
-
- You can install Postgres manually on your cluster using the
- [Bitnami PostgreSQL Helm chart](https://github.com/bitnami/charts/tree/master/bitnami/postgresql#readme).
- There are some
- [helpful guides](https://phoenixnap.com/kb/postgresql-kubernetes) on the
- internet that explain sensible configurations for this chart. Example:
-
- ```console
- # Install PostgreSQL
- helm repo add bitnami https://charts.bitnami.com/bitnami
- helm install coder-db bitnami/postgresql \
- --namespace coder \
- --set auth.username=coder \
- --set auth.password=coder \
- --set auth.database=coder \
- --set persistence.size=10Gi
- ```
-
- The cluster-internal DB URL for the above database is:
-
- ```shell
- postgres://coder:coder@coder-db-postgresql.coder.svc.cluster.local:5432/coder?sslmode=disable
- ```
-
- > Ensure you set up periodic backups so you don't lose data.
-
- You can use [Postgres operator](https://github.com/zalando/postgres-operator)
- to manage PostgreSQL deployments on your Kubernetes cluster.
-
-1. Create a secret with the database URL:
-
- ```shell
- # Uses Bitnami PostgreSQL example. If you have another database,
- # change to the proper URL.
- kubectl create secret generic coder-db-url -n coder \
- --from-literal=url="postgres://coder:coder@coder-db-postgresql.coder.svc.cluster.local:5432/coder?sslmode=disable"
- ```
-
-1. Add the Coder Helm repo:
-
- ```shell
- helm repo add coder-v2 https://helm.coder.com/v2
- ```
-
-1. Create a `values.yaml` with the configuration settings you'd like for your
- deployment. For example:
-
- ```yaml
- coder:
- # You can specify any environment variables you'd like to pass to Coder
- # here. Coder consumes environment variables listed in
- # `coder server --help`, and these environment variables are also passed
- # to the workspace provisioner (so you can consume them in your Terraform
- # templates for auth keys etc.).
- #
- # Please keep in mind that you should not set `CODER_HTTP_ADDRESS`,
- # `CODER_TLS_ENABLE`, `CODER_TLS_CERT_FILE` or `CODER_TLS_KEY_FILE` as
- # they are already set by the Helm chart and will cause conflicts.
- env:
- - name: CODER_PG_CONNECTION_URL
- valueFrom:
- secretKeyRef:
- # You'll need to create a secret called coder-db-url with your
- # Postgres connection URL like:
- # postgres://coder:password@postgres:5432/coder?sslmode=disable
- name: coder-db-url
- key: url
-
- # (Optional) For production deployments the access URL should be set.
- # If you're just trying Coder, access the dashboard via the service IP.
- - name: CODER_ACCESS_URL
- value: "https://coder.example.com"
-
- #tls:
- # secretNames:
- # - my-tls-secret-name
- ```
-
- > You can view our
- > [Helm README](https://github.com/coder/coder/blob/main/helm#readme) for
- > details on the values that are available, or you can view the
- > [values.yaml](https://github.com/coder/coder/blob/main/helm/coder/values.yaml)
- > file directly.
-
-1. Run the following command to install the chart in your cluster.
-
- For the **mainline** Coder release:
+- Kubernetes cluster running K8s 1.19+
+- [Helm](https://helm.sh/docs/intro/install/) 3.5+ installed on your local
+ machine
+
+## 1. Create a namespace
+
+Create a namespace for the Coder control plane. In this tutorial, we'll call it
+`coder`.
+
+```sh
+kubectl create namespace coder
+```
+
+## 2. Create a PostgreSQL instance
+
+Coder does not manage a database server for you. This is required for storing
+data about your Coder deployment and resources.
+
+### Managed PostgreSQL (recommended)
+
+If you're in a public cloud such as
+[Google Cloud](https://cloud.google.com/sql/docs/postgres/),
+[AWS](https://aws.amazon.com/rds/postgresql/),
+[Azure](https://docs.microsoft.com/en-us/azure/postgresql/), or
+[DigitalOcean](https://www.digitalocean.com/products/managed-databases-postgresql),
+you can use the managed PostgreSQL offerings they provide. Make sure that the
+PostgreSQL service is running and accessible from your cluster. It should be in
+the same network, same project, etc.
+
+### In-Cluster PostgreSQL (for proof of concepts)
+
+You can install Postgres manually on your cluster using the
+[Bitnami PostgreSQL Helm chart](https://github.com/bitnami/charts/tree/master/bitnami/postgresql#readme).
+There are some [helpful guides](https://phoenixnap.com/kb/postgresql-kubernetes)
+on the internet that explain sensible configurations for this chart. Example:
+
+```console
+# Install PostgreSQL
+helm repo add bitnami https://charts.bitnami.com/bitnami
+helm install coder-db bitnami/postgresql \
+ --namespace coder \
+ --set auth.username=coder \
+ --set auth.password=coder \
+ --set auth.database=coder \
+ --set persistence.size=10Gi
+```
+
+The cluster-internal DB URL for the above database is:
+
+```shell
+postgres://coder:coder@coder-db-postgresql.coder.svc.cluster.local:5432/coder?sslmode=disable
+```
+
+You can optionally use the
+[Postgres operator](https://github.com/zalando/postgres-operator) to manage
+PostgreSQL deployments on your Kubernetes cluster.
+
+## 3. Create the PostgreSQL secret
+
+Create a secret with the PostgreSQL database URL string. In the case of the
+self-managed PostgreSQL, the address will be:
+
+```sh
+kubectl create secret generic coder-db-url -n coder \
+ --from-literal=url="postgres://coder:coder@coder-db-postgresql.coder.svc.cluster.local:5432/coder?sslmode=disable"
+```
+
+## 4. Install Coder with Helm
+
+```shell
+helm repo add coder-v2 https://helm.coder.com/v2
+```
+
+Create a `values.yaml` with the configuration settings you'd like for your
+deployment. For example:
+
+```yaml
+coder:
+ # You can specify any environment variables you'd like to pass to Coder
+ # here. Coder consumes environment variables listed in
+ # `coder server --help`, and these environment variables are also passed
+ # to the workspace provisioner (so you can consume them in your Terraform
+ # templates for auth keys etc.).
+ #
+ # Please keep in mind that you should not set `CODER_HTTP_ADDRESS`,
+ # `CODER_TLS_ENABLE`, `CODER_TLS_CERT_FILE` or `CODER_TLS_KEY_FILE` as
+ # they are already set by the Helm chart and will cause conflicts.
+ env:
+ - name: CODER_PG_CONNECTION_URL
+ valueFrom:
+ secretKeyRef:
+ # You'll need to create a secret called coder-db-url with your
+ # Postgres connection URL like:
+ # postgres://coder:password@postgres:5432/coder?sslmode=disable
+ name: coder-db-url
+ key: url
+
+ # (Optional) For production deployments the access URL should be set.
+ # If you're just trying Coder, access the dashboard via the service IP.
+ - name: CODER_ACCESS_URL
+ value: "https://coder.example.com"
+
+ #tls:
+ # secretNames:
+ # - my-tls-secret-name
+```
+
+> You can view our
+> [Helm README](https://github.com/coder/coder/blob/main/helm#readme) for
+> details on the values that are available, or you can view the
+> [values.yaml](https://github.com/coder/coder/blob/main/helm/coder/values.yaml)
+> file directly.
+
+We support two release channels: mainline and stable - read the
+[Releases](./releases.md) page to learn more about which best suits your team.
+
+For the **mainline** Coder release:
- ```shell
- helm install coder coder-v2/coder \
- --namespace coder \
- --values values.yaml \
- --version 2.14.0
- ```
+```shell
+helm install coder coder-v2/coder \
+ --namespace coder \
+ --values values.yaml \
+ --version 2.14.0
+```
- For the **stable** Coder release:
+For the **stable** Coder release:
- ```shell
- helm install coder coder-v2/coder \
- --namespace coder \
- --values values.yaml \
- --version 2.13.4
- ```
+```shell
+helm install coder coder-v2/coder \
+ --namespace coder \
+ --values values.yaml \
+ --version 2.13.4
+```
- You can watch Coder start up by running `kubectl get pods -n coder`. Once
- Coder has started, the `coder-*` pods should enter the `Running` state.
+You can watch Coder start up by running `kubectl get pods -n coder`. Once Coder
+has started, the `coder-*` pods should enter the `Running` state.
-1. Log in to Coder
+## 5. Log in to Coder 🎉
- Use `kubectl get svc -n coder` to get the IP address of the LoadBalancer.
- Visit this in the browser to set up your first account.
+Use `kubectl get svc -n coder` to get the IP address of the LoadBalancer. Visit
+this in the browser to set up your first account.
- If you do not have a domain, you should set `CODER_ACCESS_URL` to this URL in
- the Helm chart and upgrade Coder (see below). This allows workspaces to
- connect to the proper Coder URL.
+If you do not have a domain, you should set `CODER_ACCESS_URL` to this URL in
+the Helm chart and upgrade Coder (see below). This allows workspaces to connect
+to the proper Coder URL.
## Upgrading Coder via Helm
@@ -294,8 +289,3 @@ Coder's LoadBalancer (`kubectl get svc -n coder`).
See [troubleshooting templates](../templates/index.md#troubleshooting-templates)
for more steps.
-
-## Next steps
-
-- [Configuring Coder](../admin/configure.md)
-- [Templates](../templates/index.md)
diff --git a/docs/install/openshift.md b/docs/install/openshift.md
index cb8bb779ea3f4..57ca8b8a86a63 100644
--- a/docs/install/openshift.md
+++ b/docs/install/openshift.md
@@ -1,13 +1,9 @@
## Requirements
-Before proceeding, please ensure that you have an OpenShift cluster running K8s
-1.19+ (OpenShift 4.7+) and have Helm 3.5+ installed. In addition, you'll need to
-install the OpenShift CLI (`oc`) to authenticate to your cluster and create
-OpenShift resources.
-
-You'll also want to install the
-[latest version of Coder](https://github.com/coder/coder/releases/latest)
-locally in order to log in and manage templates.
+- OpenShift cluster running K8s 1.19+ (OpenShift 4.7+)
+- Helm 3.5+ installed
+- OpenShift CLI (`oc`) installed
+- [Coder CLI](./cli.md) installed
## Install Coder with OpenShift
diff --git a/docs/install/other/README.md b/docs/install/other/README.md
new file mode 100644
index 0000000000000..b3bc83345cb37
--- /dev/null
+++ b/docs/install/other/README.md
@@ -0,0 +1,16 @@
+# Alternate install methods
+
+Coder has a number of alternate unofficial install methods. Contributions are welcome!
+
+| Platform Name | Status | Documentation |
+| --------------------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------- |
+| AWS EC2 | Official | [Guide: AWS](https://coder.com/docs/platforms/aws) |
+| Google Compute Engine | Official | [Guide: Google Compute Engine](https://coder.com/docs/platforms/gcp) |
+| Azure AKS | Unofficial | [GitHub: coder-aks](https://github.com/ericpaulsen/coder-aks) |
+| Terraform (GKE, AKS, LKE, DOKS, IBMCloud K8s, OVHCloud K8s, Scaleway K8s Kapsule) | Unofficial | [GitHub: coder-oss-terraform](https://github.com/ElliotG/coder-oss-tf) |
+| Fly.io | Unofficial | [Blog: Run Coder on Fly.io](https://coder.com/blog/remote-developer-environments-on-fly-io) |
+| Garden.io | Unofficial | [GitHub: garden-coder-example](https://github.com/garden-io/garden-coder-example) |
+| Railway.app | Unofficial | [Blog: Run Coder on Railway.app](https://coder.com/blog/deploy-coder-on-railway-app) |
+| Heroku | Unofficial | [Docs: Deploy Coder on Heroku](https://github.com/coder/packages/blob/main/heroku/README.md) |
+| Render | Unofficial | [Docs: Deploy Coder on Render](https://github.com/coder/packages/blob/main/render/README.md) |
+| Snapcraft | Unofficial | [Get it from the Snap Store](https://snapcraft.io/coder) |
diff --git a/docs/install/other/openshift.md b/docs/install/other/openshift.md
new file mode 100644
index 0000000000000..e69de29bb2d1d
diff --git a/docs/manifest.json b/docs/manifest.json
index 4b686ed9598b6..5564aff7bc543 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -3,1171 +3,1059 @@
"routes": [
{
"title": "About",
- "description": "About Coder",
+ "description": "Landing Page",
"path": "./README.md",
- "icon_path": "./images/icons/home.svg",
- "children": [
- {
- "title": "Screenshots",
- "description": "Browse screenshots of the Coder platform",
- "path": "./about/screenshots.md"
- }
- ]
+ "icon_path": "./images/icons/home.svg"
},
{
- "title": "Architecture",
- "description": "Learn about validated and reference architectures for Coder",
- "path": "./architecture/architecture.md",
- "icon_path": "./images/icons/container.svg",
+ "title": "Getting Started",
+ "description": "Tour Coder by setting up your first deployment",
+ "path": "./start/README.md",
+ "icon_path": "./images/icons/star.svg",
"children": [
{
- "title": "Validated Architecture",
- "path": "./architecture/validated-arch.md"
- },
- {
- "title": "Up to 1,000 users",
- "path": "./architecture/1k-users.md"
+ "title": "Tour Coder",
+ "description": "Tour Coder by creating a deployment with Docker",
+ "path": "./start/coder-tour.md"
},
{
- "title": "Up to 2,000 users",
- "path": "./architecture/2k-users.md"
- },
- {
- "title": "Up to 3,000 users",
- "path": "./architecture/3k-users.md"
+ "title": "Screenshots",
+ "description": "View screenshots of the Coder platform",
+ "path": "./start/screenshots.md"
}
]
},
{
- "title": "Installation",
- "description": "How to install and deploy Coder",
- "path": "./install/index.md",
+ "title": "Install",
+ "description": "Installing Coder",
+ "path": "./install/README.md",
"icon_path": "./images/icons/download.svg",
"children": [
{
- "title": "Kubernetes",
- "description": "Install Coder with Kubernetes via Helm",
- "path": "./install/kubernetes.md"
+ "title": "Coder CLI",
+ "description": "Install the standalone binary",
+ "path": "./install/cli.md"
},
{
"title": "Docker",
- "description": "Install Coder with Docker / docker-compose",
+ "description": "Install Coder using Docker",
"path": "./install/docker.md"
},
+ {
+ "title": "Kubernetes",
+ "description": "Install Coder on Kubernetes",
+ "path": "./install/kubernetes.md"
+ },
{
"title": "OpenShift",
"description": "Install Coder on OpenShift",
"path": "./install/openshift.md"
},
{
- "title": "Offline deployments",
- "description": "Run Coder in offline / air-gapped environments",
- "path": "./install/offline.md"
- },
- {
- "title": "External database",
- "description": "Use external PostgreSQL database",
- "path": "./install/database.md"
- },
- {
- "title": "Uninstall",
- "description": "Learn how to uninstall Coder",
- "path": "./install/uninstall.md"
- },
- {
- "title": "1-click install",
- "description": "Install Coder on a cloud provider with a single click",
- "path": "./install/1-click.md"
+ "title": "Cloud Providers",
+ "description": "Install Coder on cloud providers",
+ "path": "./install/cloud/README.md",
+ "children": [
+ {
+ "title": "AWS EC2",
+ "description": "Install Coder on AWS EC2",
+ "path": "./install/cloud/ec2.md"
+ },
+ {
+ "title": "GCP Compute Engine",
+ "description": "Install Coder on GCP Compute Engine",
+ "path": "./install/cloud/compute-engine.md"
+ },
+ {
+ "title": "Azure VM",
+ "description": "Install Coder on an Azure VM",
+ "path": "./install/cloud/azure-vm.md"
+ }
+ ]
},
{
- "title": "Releases",
- "description": "Coder Release Channels and Cadence",
- "path": "./install/releases.md"
+ "title": "Unofficial Install Methods",
+ "description": "Other installation methods",
+ "path": "./install/other/README.md"
}
]
},
{
- "title": "Platforms",
- "description": "Platform-specific guides using Coder",
- "path": "./platforms/README.md",
- "icon_path": "./images/icons/star.svg",
+ "title": "User Guides",
+ "description": "Guides for end-users of Coder",
+ "path": "./user-guides/README.md",
+ "icon_path": "./images/icons/users.svg",
"children": [
{
- "title": "AWS",
- "description": "Set up Coder on an AWS EC2 VM",
- "path": "./platforms/aws.md",
- "icon_path": "./images/aws.svg"
- },
- {
- "title": "Azure",
- "description": "Set up Coder on an Azure VM",
- "path": "./platforms/azure.md",
- "icon_path": "./images/azure.svg"
- },
- {
- "title": "Docker",
- "description": "Set up Coder with Docker",
- "path": "./platforms/docker.md",
- "icon_path": "./images/icons/docker.svg"
- },
- {
- "title": "GCP",
- "description": "Set up Coder on a GCP Compute Engine VM",
- "path": "./platforms/gcp.md",
- "icon_path": "./images/google-cloud.svg"
- },
- {
- "title": "Kubernetes",
- "description": "Set up Coder on Kubernetes",
- "path": "./platforms/kubernetes/index.md",
+ "title": "Access Workspaces",
+ "description": "Connect to your Coder workspaces",
+ "path": "./user-guides/workspace-access/README.md",
"children": [
{
- "title": "Additional clusters",
- "description": "Deploy workspaces on additional Kubernetes clusters",
- "path": "./platforms/kubernetes/additional-clusters.md"
+ "title": "Visual Studio Code",
+ "description": "Use VSCode with Coder in the desktop or browser",
+ "path": "./user-guides/workspace-access/vscode.md"
},
{
- "title": "Deployment logs",
- "description": "Stream K8s event logs on workspace startup",
- "path": "./platforms/kubernetes/deployment-logs.md"
+ "title": "JetBrains IDEs",
+ "description": "Use JetBrains IDEs with Gateway",
+ "path": "./user-guides/workspace-access/jetbrains.md"
+ },
+ {
+ "title": "Remote desktop",
+ "description": "Use RDP in Coder",
+ "path": "./user-guides/workspace-access/remote-desktops.md"
+ },
+ {
+ "title": "Emacs TRAMP",
+ "description": "Use Emacs TRAMP in Coder",
+ "path": "./user-guides/workspace-access/emacs-tramp.md"
+ },
+ {
+ "title": "Port Forwarding",
+ "description": "Access ports on your workspace",
+ "path": "./user-guides/workspace-access/port-forwarding.md"
+ },
+ {
+ "title": "Filebrowser",
+ "description": "Access your workspace files",
+ "path": "./user-guides/workspace-access/filebrowser.md"
}
]
},
{
- "title": "Other platforms",
- "description": "Set up Coder on an another provider",
- "path": "./platforms/other.md"
+ "title": "Workspace Scheduling",
+ "description": "Cost control with workspace schedules",
+ "path": "./user-guides/workspace-scheduling.md"
+ },
+ {
+ "title": "Dotfiles",
+ "description": "Personalize your environment with dotfiles",
+ "path": "./user-guides/workspace-dotfiles.md"
}
]
},
{
- "title": "Templates",
- "description": "Templates define the infrastructure for workspaces",
- "path": "./templates/index.md",
- "icon_path": "./images/icons/picture.svg",
+ "title": "Administration",
+ "description": "Guides for template and deployment administrators",
+ "path": "./admin/README.md",
+ "icon_path": "./images/icons/wrench.svg",
"children": [
{
- "title": "Working with templates",
- "description": "Creating, editing, and updating templates",
- "path": "./templates/creating.md"
- },
- {
- "title": "Your first template",
- "description": "A tutorial for creating and editing your first template",
- "path": "./templates/tutorial.md"
+ "title": "Control Plane Configuration",
+ "description": "Configure user access to your control plane.",
+ "path": "./admin/configure.md"
},
{
- "title": "Guided tour",
- "description": "Create a template from scratch",
- "path": "./templates/tour.md"
+ "title": "Infrastructure",
+ "description": "How to integrate Coder with your organization's compute",
+ "path": "./admin/infrastructure/README.md",
+ "children": [
+ {
+ "title": "Architecture",
+ "description": "Learn about Coder's architecture",
+ "path": "./admin/infrastructure/architecture.md"
+ },
+ {
+ "title": "Validated Architectures",
+ "description": "Architectures for large Coder deployments",
+ "path": "./admin/infrastructure/validated-architectures/README.md",
+ "children": [
+ {
+ "title": "Up to 1,000 Users",
+ "path": "./admin/infrastructure/validated-architectures/1k-users.md"
+ },
+ {
+ "title": "Up to 2,000 Users",
+ "path": "./admin/infrastructure/validated-architectures/2k-users.md"
+ },
+ {
+ "title": "Up to 3,000 Users",
+ "path": "./admin/infrastructure/validated-architectures/3k-users.md"
+ }
+ ]
+ },
+ {
+ "title": "Scale Testing",
+ "description": "Ensure your deployment can handle your organization's needs",
+ "path": "./admin/infrastructure/scale-testing.md"
+ },
+ {
+ "title": "Scaling Utilities",
+ "description": "Tools to help you scale your deployment",
+ "path": "./admin/infrastructure/scale-utility.md"
+ }
+ ]
},
{
- "title": "Setting up templates",
- "description": "Best practices for writing templates",
- "path": "./templates/best-practices.md",
+ "title": "Users",
+ "description": "Learn how to manage and audit users",
+ "path": "./admin/users/README.md",
"children": [
{
- "title": "Template Dependencies",
- "description": "Manage dependencies of your templates",
- "path": "./templates/dependencies.md",
- "icon_path": "./images/icons/dependency.svg"
+ "title": "OIDC Authentication",
+ "path": "./admin/users/oidc-auth.md"
+ },
+ {
+ "title": "GitHub Authentication",
+ "path": "./admin/users/github-auth.md"
},
{
- "title": "Change management",
- "description": "Versioning templates with git and CI",
- "path": "./templates/change-management.md",
- "icon_path": "./images/icons/git.svg"
+ "title": "Password Authentication",
+ "path": "./admin/users/password-auth.md"
},
{
- "title": "Provider authentication",
- "description": "Authenticate the provisioner",
- "path": "./templates/authentication.md",
- "icon_path": "./images/icons/key.svg"
+ "title": "Headless Authentication",
+ "path": "./admin/users/headless-auth.md"
},
{
- "title": "Resource persistence",
- "description": "How resource persistence works in Coder",
- "path": "./templates/resource-persistence.md",
- "icon_path": "./images/icons/infinity.svg"
+ "title": "Groups \u0026 Roles",
+ "path": "./admin/users/groups-roles.md"
},
{
- "title": "Terraform modules",
- "description": "Reuse code across Coder templates",
- "path": "./templates/modules.md"
+ "title": "Organizations",
+ "path": "./admin/users/organizations.md",
+ "state": "enterprise"
+ },
+ {
+ "title": "Sessions \u0026 API Tokens",
+ "path": "./admin/users/sessions-tokens.md"
}
]
},
{
- "title": "Customizing templates",
- "description": "Give information and options to workspace users",
- "path": "./templates/customizing.md",
+ "title": "Templates",
+ "description": "Learn how to author and maintain Coder templates",
+ "path": "./admin/templates/README.md",
"children": [
{
- "title": "Agent metadata",
- "description": "Show operational metrics in the workspace",
- "path": "./templates/agent-metadata.md"
+ "title": "Creating Templates",
+ "description": "Learn how to create templates with Terraform",
+ "path": "./admin/templates/creating-templates.md"
+ },
+ {
+ "title": "Managing Templates",
+ "description": "Learn how to manage templates and best practices",
+ "path": "./admin/templates/managing-templates/README.md",
+ "children": [
+ {
+ "title": "Image Management",
+ "description": "Learn about template image management",
+ "path": "./admin/templates/managing-templates/image-management.md"
+ },
+ {
+ "title": "Change Management",
+ "description": "Learn about template change management and versioning",
+ "path": "./admin/templates/managing-templates/change-management.md"
+ },
+ {
+ "title": "Devcontainers",
+ "description": "Learn about using devcontainers in templates",
+ "path": "./admin/templates/managing-templates/devcontainers.md"
+ }
+ ]
},
{
- "title": "Resource metadata",
- "description": "Show information in the workspace about template resources",
- "path": "./templates/resource-metadata.md"
+ "title": "Extending Templates",
+ "description": "Learn best practices in extending templates",
+ "path": "./admin/templates/extending-templates/README.md",
+ "children": [
+ {
+ "title": "Agent Metadata",
+ "description": "Retrieve real-time stats from the workspace agent",
+ "path": "./admin/templates/extending-templates/agent-metadata.md"
+ },
+ {
+ "title": "Build Parameters",
+ "description": "Use parameters to customize workspaces at build",
+ "path": "./admin/templates/extending-templates/parameters.md"
+ },
+ {
+ "title": "Icons",
+ "description": "Customize your template with built-in icons",
+ "path": "./admin/templates/extending-templates/icons.md"
+ },
+ {
+ "title": "Resource Metadata",
+ "description": "Display resource state in the workspace dashboard",
+ "path": "./admin/templates/extending-templates/resource-metadata.md"
+ },
+ {
+ "title": "Resource Ordering",
+ "description": "Design the UI of workspaces in Terraform",
+ "path": "./admin/templates/extending-templates/resource-ordering.md"
+ },
+ {
+ "title": "Terraform Variables",
+ "description": "Use variables to manage template state",
+ "path": "./admin/templates/extending-templates/variables.md"
+ },
+ {
+ "title": "Terraform Modules",
+ "description": "Reuse terraform code across templates",
+ "path": "./admin/templates/extending-templates/modules.md"
+ },
+ {
+ "title": "Web IDEs and Coder Apps",
+ "description": "Add and configure Web IDEs in your templates as coder apps",
+ "path": "./admin/templates/extending-templates/web-ides.md"
+ }
+ ]
},
{
- "title": "UI Resource Ordering",
- "description": "Learn how to manage the order of Terraform resources in UI",
- "path": "./templates/resource-ordering.md"
+ "title": "Permissions \u0026 Policies",
+ "description": "Learn how to create templates with Terraform",
+ "path": "./admin/templates/template-permissions.md"
}
]
},
{
- "title": "Parameters",
- "description": "Prompt the user for additional information about a workspace",
- "path": "./templates/parameters.md"
- },
- {
- "title": "Variables",
- "description": "Prompt the template administrator for additional information about a template",
- "path": "./templates/variables.md"
- },
- {
- "title": "Workspace Tags",
- "description": "Control provisioning using Workspace Tags and Parameters",
- "path": "./templates/workspace-tags.md"
+ "title": "Provisioners",
+ "description": "Learn how to run external provisioners with Coder",
+ "path": "./admin/provisioners.md"
},
{
- "title": "Administering templates",
- "description": "Configuration settings for template admins",
- "path": "./templates/configuration.md",
+ "title": "Integrations",
+ "description": "Use integrations to extend Coder",
+ "path": "./admin/integrations/README.md",
"children": [
{
- "title": "General settings",
- "description": "Configure name, display info, and update polices",
- "path": "./templates/general-settings.md"
+ "title": "Prometheus",
+ "description": "Collect deployment metrics with Prometheus",
+ "path": "./admin/integrations/prometheus.md"
+ },
+ {
+ "title": "Kubernetes Logging",
+ "description": "Stream K8s event logs on workspace startup",
+ "path": "./admin/integrations/kubernetes-logs.md"
+ },
+ {
+ "title": "Additional Kubernetes Clusters",
+ "description": "Deploy workspaces on additional Kubernetes clusters",
+ "path": "./admin/integrations/multiple-kube-clusters.md"
+ },
+ {
+ "title": "JFrog Artifactory",
+ "description": "Integrate Coder with JFrog Artifactory",
+ "path": "./admin/integrations/jfrog-artifactory.md"
+ },
+ {
+ "title": "JFrog Xray",
+ "description": "Integrate Coder with JFrog Xray",
+ "path": "./admin/integrations/jfrog-xray.md"
},
{
- "title": "Permissions",
- "description": "Configure who can access a template",
- "path": "./templates/permissions.md"
+ "title": "Island Secure Browser",
+ "description": "Integrate Coder with Island's Secure Browser",
+ "path": "./admin/integrations/island.md"
},
{
- "title": "Workspace Scheduling",
- "description": "Configure when workspaces start, stop, and delete",
- "path": "./templates/schedule.md"
+ "title": "Hashicorp Vault",
+ "description": "Integrate Coder with Hashicorp Vault",
+ "path": "./admin/integrations/vault.md"
}
]
},
{
- "title": "Open in Coder",
- "description": "Add an \"Open in Coder\" button to your repos",
- "path": "./templates/open-in-coder.md",
- "icon_path": "./images/icons/key.svg"
- },
- {
- "title": "Docker in workspaces",
- "description": "Use Docker inside containerized templates",
- "path": "./templates/docker-in-workspaces.md",
- "icon_path": "./images/icons/docker.svg"
- },
- {
- "title": "Dev Containers",
- "description": "Use Dev Containers in workspaces",
- "path": "./templates/dev-containers.md",
- "state": "alpha"
- },
- {
- "title": "Troubleshooting templates",
- "description": "Fix common template problems",
- "path": "./templates/troubleshooting.md"
- },
- {
- "title": "Process Logging",
- "description": "Audit commands in workspaces with exectrace",
- "path": "./templates/process-logging.md",
- "state": "enterprise"
- },
- {
- "title": "Icons",
- "description": "Coder includes icons for popular cloud providers and programming languages for you to use",
- "path": "./templates/icons.md"
- }
- ]
- },
- {
- "title": "Workspaces",
- "description": "Learn about Coder workspaces.",
- "path": "./workspaces.md",
- "icon_path": "./images/icons/layers.svg"
- },
- {
- "title": "IDEs",
- "description": "Learn how to use your IDE of choice with Coder",
- "path": "./ides.md",
- "icon_path": "./images/icons/code.svg",
- "children": [
- {
- "title": "Web IDEs",
- "description": "Learn how to configure web IDEs in your templates",
- "path": "./ides/web-ides.md"
- },
- {
- "title": "JetBrains Gateway",
- "description": "Learn how to configure JetBrains Gateway for your workspaces",
- "path": "./ides/gateway.md"
- },
- {
- "title": "JetBrains Fleet",
- "description": "Learn how to configure JetBrains Fleet for your workspaces",
- "path": "./ides/fleet.md"
- },
- {
- "title": "Emacs",
- "description": "Learn how to configure Emacs with TRAMP in Coder",
- "path": "./ides/emacs-tramp.md"
- },
- {
- "title": "Remote Desktops",
- "description": "Learn how to use Remote Desktops with Coder",
- "path": "./ides/remote-desktops.md"
- }
- ]
- },
- {
- "title": "Networking",
- "description": "Learn about networking in Coder",
- "path": "./networking/index.md",
- "icon_path": "./images/icons/networking.svg",
- "children": [
- {
- "title": "Port Forwarding",
- "description": "Learn how to forward ports in Coder",
- "path": "./networking/port-forwarding.md"
- },
- {
- "title": "STUN and NAT",
- "description": "Learn how Coder establishes direct connections",
- "path": "./networking/stun.md"
- }
- ]
- },
- {
- "title": "Dotfiles",
- "description": "Learn how to personalize your workspace",
- "path": "./dotfiles.md",
- "icon_path": "./images/icons/art-pad.svg"
- },
- {
- "title": "Secrets",
- "description": "Learn how to use secrets in your workspace",
- "path": "./secrets.md",
- "icon_path": "./images/icons/secrets.svg"
- },
- {
- "title": "Administration",
- "description": "How to install and deploy Coder",
- "path": "./admin/README.md",
- "icon_path": "./images/icons/wrench.svg",
- "children": [
- {
- "title": "Authentication",
- "description": "Learn how to set up authentication using GitHub or OpenID Connect",
- "path": "./admin/auth.md",
- "icon_path": "./images/icons/key.svg"
- },
- {
- "title": "Users",
- "description": "Learn about user roles available in Coder and how to create and manage users",
- "path": "./admin/users.md",
- "icon_path": "./images/icons/users.svg"
- },
- {
- "title": "Groups",
- "description": "Learn how to manage user groups",
- "path": "./admin/groups.md",
- "icon_path": "./images/icons/group.svg",
- "state": "enterprise"
- },
- {
- "title": "RBAC",
- "description": "Learn how to use the role based access control",
- "path": "./admin/rbac.md",
- "icon_path": "./images/icons/rbac.svg",
- "state": "enterprise"
- },
- {
- "title": "Configuration",
- "description": "Learn how to configure Coder",
- "path": "./admin/configure.md",
- "icon_path": "./images/icons/toggle_on.svg"
- },
- {
- "title": "External Auth",
- "description": "Learn how connect Coder with external auth providers",
- "path": "./admin/external-auth.md",
- "icon_path": "./images/icons/git.svg"
- },
- {
- "title": "Upgrading",
- "description": "Learn how to upgrade Coder",
- "path": "./admin/upgrade.md",
- "icon_path": "./images/icons/upgrade.svg"
- },
- {
- "title": "Automation",
- "description": "Learn how to automate Coder with the CLI and API",
- "path": "./admin/automation.md",
- "icon_path": "./images/icons/plug.svg"
- },
- {
- "title": "Scaling Coder",
- "description": "Learn how to use load testing tools",
- "path": "./admin/scaling/scale-testing.md",
- "icon_path": "./images/icons/scale.svg",
+ "title": "Workspaces",
+ "description": "Learn how to manage \u0026 audit workspaces",
+ "path": "./admin/workspaces/README.md",
"children": [
{
- "title": "Scaling Utility",
- "path": "./admin/scaling/scale-utility.md"
+ "title": "Workspace Tags",
+ "description": "Control provisioning using Workspace Tags and Parameters",
+ "path": "./admin/workspaces/workspace-tags.md"
+ },
+ {
+ "title": "Workspace Lifecycle",
+ "description": "Understand the lifecycle of a workspace",
+ "path": "./admin/workspaces/lifecycle.md"
}
]
},
{
- "title": "External Provisioners",
- "description": "Run provisioners isolated from the Coder server",
- "path": "./admin/provisioners.md",
- "icon_path": "./images/icons/queue.svg",
- "state": "enterprise"
- },
- {
- "title": "Workspace Proxies",
- "description": "Run geo distributed workspace proxies",
- "path": "./admin/workspace-proxies.md",
- "icon_path": "./images/icons/networking.svg",
- "state": "enterprise"
- },
- {
- "title": "Application Logs",
- "description": "Learn how to use Application Logs in your Coder deployment",
- "path": "./admin/app-logs.md",
- "icon_path": "./images/icons/notes.svg"
- },
- {
- "title": "Audit Logs",
- "description": "Learn how to use Audit Logs in your Coder deployment",
- "path": "./admin/audit-logs.md",
- "icon_path": "./images/icons/radar.svg",
- "state": "enterprise"
- },
- {
- "title": "Quotas",
- "description": "Learn how to use Workspace Quotas in Coder",
- "path": "./admin/quotas.md",
- "icon_path": "./images/icons/dollar.svg",
- "state": "enterprise"
- },
- {
- "title": "High Availability",
- "description": "Learn how to configure Coder for High Availability",
- "path": "./admin/high-availability.md",
- "icon_path": "./images/icons/hydra.svg",
- "state": "enterprise"
- },
- {
- "title": "Prometheus",
- "description": "Learn how to collect Prometheus metrics",
- "path": "./admin/prometheus.md",
- "icon_path": "./images/icons/speed.svg"
- },
- {
- "title": "Appearance",
- "description": "Learn how to configure the appearance of Coder",
- "path": "./admin/appearance.md",
- "icon_path": "./images/icons/info.svg",
- "state": "enterprise"
- },
- {
- "title": "Telemetry",
- "description": "Learn what usage telemetry Coder collects",
- "path": "./admin/telemetry.md",
- "icon_path": "./images/icons/science.svg"
- },
- {
- "title": "Database Encryption",
- "description": "Learn how to encrypt sensitive data at rest in Coder",
- "path": "./admin/encryption.md",
- "icon_path": "./images/icons/lock.svg",
- "state": "enterprise"
- },
- {
- "title": "Deployment Health",
- "description": "Learn how to monitor the health of your Coder deployment",
- "path": "./admin/healthcheck.md",
- "icon_path": "./images/icons/health.svg"
- }
- ]
- },
- {
- "title": "Enterprise",
- "description": "Learn how to enable Enterprise features",
- "path": "./enterprise.md",
- "icon_path": "./images/icons/group.svg"
- },
- {
- "title": "Contributing",
- "description": "Learn how to contribute to Coder",
- "path": "./CONTRIBUTING.md",
- "icon_path": "./images/icons/contributing.svg",
- "children": [
- {
- "title": "Code of Conduct",
- "description": "See the code of conduct for contributing to Coder",
- "path": "./contributing/CODE_OF_CONDUCT.md"
- },
- {
- "title": "Feature stages",
- "description": "Policies for Alpha and Experimental features.",
- "path": "./contributing/feature-stages.md"
+ "title": "Networking",
+ "description": "Understand Coder's networking layer",
+ "path": "./admin/networking/README.md",
+ "children": [
+ {
+ "title": "Port Forwarding",
+ "description": "Learn how to forward ports in Coder",
+ "path": "./admin/networking/port-forwarding.md"
+ },
+ {
+ "title": "STUN and NAT",
+ "description": "Learn how to forward ports in Coder",
+ "path": "./admin/networking/stun.md"
+ }
+ ]
},
{
- "title": "Documentation",
- "description": "Our style guide for use when authoring documentation",
- "path": "./contributing/documentation.md"
+ "title": "Monitoring",
+ "description": "Configure security policy and audit your deployment",
+ "path": "./admin/monitoring/README.md",
+ "children": [
+ {
+ "title": "Logs",
+ "description": "Learn about Coder's logs",
+ "path": "./admin/monitoring/logs.md"
+ },
+ {
+ "title": "Metrics",
+ "description": "Learn about Coder's logs",
+ "path": "./admin/monitoring/metrics.md"
+ },
+ {
+ "title": "Health Check",
+ "description": "Learn about Coder's automated health checks",
+ "path": "./admin/monitoring/health-check.md"
+ }
+ ]
},
{
"title": "Security",
- "description": "How to report vulnerabilities in Coder",
- "path": "./contributing/SECURITY.md"
- },
- {
- "title": "Frontend",
- "description": "Our guide for frontend development",
- "path": "./contributing/frontend.md"
+ "description": "Configure security policy and audit your deployment",
+ "path": "./admin/security/README.md",
+ "children": [
+ {
+ "title": "Audit Logs",
+ "description": "Audit actions taken inside Coder",
+ "path": "./admin/security/audit-logs.md"
+ },
+ {
+ "title": "Secrets",
+ "description": "Use sensitive variables in your workspaces",
+ "path": "./admin/security/secrets.md"
+ }
+ ]
}
]
},
{
- "title": "API",
- "description": "Learn how to use Coderd API",
- "path": "./api/index.md",
- "icon_path": "./images/icons/api.svg",
+ "title": "Tutorials",
+ "description": "Coder knowledgebase for administrating your deployment",
+ "path": "./tutorials/README.md",
+ "icon_path": "./images/icons/generic.svg",
"children": [
{
- "title": "General",
- "path": "./api/general.md"
- },
- {
- "title": "Agents",
- "path": "./api/agents.md"
- },
- {
- "title": "Applications",
- "path": "./api/applications.md"
- },
- {
- "title": "Audit",
- "path": "./api/audit.md"
- },
- {
- "title": "Authentication",
- "path": "./api/authentication.md"
- },
- {
- "title": "Authorization",
- "path": "./api/authorization.md"
- },
- {
- "title": "Builds",
- "path": "./api/builds.md"
- },
- {
- "title": "Debug",
- "path": "./api/debug.md"
+ "title": "Write a Template from Scratch",
+ "description": "Learn how to author Coder templates",
+ "path": "./tutorials/template-from-scratch.md"
},
{
- "title": "Enterprise",
- "path": "./api/enterprise.md"
+ "title": "Image Management",
+ "description": "Learn about image management with Coder",
+ "path": "./tutorials/image-management.md"
},
{
- "title": "Files",
- "path": "./api/files.md"
- },
- {
- "title": "Git",
- "path": "./api/git.md"
- },
- {
- "title": "Insights",
- "path": "./api/insights.md"
+ "title": "Generate a Support Bundle",
+ "description": "Generate and upload a Support Bundle to Coder Support",
+ "path": "./tutorials/support-bundle.md"
},
{
- "title": "Members",
- "path": "./api/members.md"
+ "title": "Configuring Okta",
+ "description": "Custom claims/scopes with Okta for group/role sync",
+ "path": "./tutorials/configuring-okta.md"
},
{
- "title": "Notifications",
- "path": "./api/notifications.md"
+ "title": "Google to AWS Federation",
+ "description": "Federating a Google Cloud service account to AWS",
+ "path": "./tutorials/gcp-to-aws.md"
},
{
- "title": "Organizations",
- "path": "./api/organizations.md"
+ "title": "JFrog Artifactory Integration",
+ "description": "Integrate Coder with JFrog Artifactory",
+ "path": "./tutorials/artifactory-integration.md"
},
{
- "title": "PortSharing",
- "path": "./api/portsharing.md"
+ "title": "Island Secure Browser Integration",
+ "description": "Integrate Coder with Island's Secure Browser",
+ "path": "./tutorials/island-integration.md"
},
{
- "title": "Schemas",
- "path": "./api/schemas.md"
+ "title": "Template ImagePullSecrets",
+ "description": "Creating ImagePullSecrets for private registries",
+ "path": "./tutorials/image-pull-secret.md"
},
{
- "title": "Templates",
- "path": "./api/templates.md"
+ "title": "Postgres SSL",
+ "description": "Configure Coder to connect to Postgres over SSL",
+ "path": "./tutorials/postgres-ssl.md"
},
{
- "title": "Users",
- "path": "./api/users.md"
+ "title": "Azure Federation",
+ "description": "Federating Coder to Azure",
+ "path": "./tutorials/azure-federation.md"
},
{
- "title": "WorkspaceProxies",
- "path": "./api/workspaceproxies.md"
+ "title": "Scanning Workspaces with JFrog Xray",
+ "description": "Integrate Coder with JFrog Xray",
+ "path": "./tutorials/xray-integration.md"
},
{
- "title": "Workspaces",
- "path": "./api/workspaces.md"
+ "title": "FAQs",
+ "description": "Miscellaneous FAQs from our community",
+ "path": "./tutorials/faqs.md"
}
]
},
{
- "title": "Command Line",
- "description": "Learn how to use Coder CLI",
- "path": "./cli.md",
- "icon_path": "./images/icons/terminal.svg",
+ "title": "Reference",
+ "description": "Reference",
+ "path": "./reference/README.md",
+ "icon_path": "./images/icons/notes.svg",
"children": [
{
- "title": "autoupdate",
- "description": "Toggle auto-update policy for a workspace",
- "path": "cli/autoupdate.md"
- },
- {
- "title": "coder",
- "path": "cli.md"
- },
- {
- "title": "config-ssh",
- "description": "Add an SSH Host entry for your workspaces \"ssh coder.workspace\"",
- "path": "cli/config-ssh.md"
- },
- {
- "title": "create",
- "description": "Create a workspace",
- "path": "cli/create.md"
- },
- {
- "title": "delete",
- "description": "Delete a workspace",
- "path": "cli/delete.md"
- },
- {
- "title": "dotfiles",
- "description": "Personalize your workspace by applying a canonical dotfiles repository",
- "path": "cli/dotfiles.md"
- },
- {
- "title": "external-auth",
- "description": "Manage external authentication",
- "path": "cli/external-auth.md"
- },
- {
- "title": "external-auth access-token",
- "description": "Print auth for an external provider",
- "path": "cli/external-auth_access-token.md"
- },
- {
- "title": "favorite",
- "description": "Add a workspace to your favorites",
- "path": "cli/favorite.md"
- },
- {
- "title": "features",
- "description": "List Enterprise features",
- "path": "cli/features.md"
- },
- {
- "title": "features list",
- "path": "cli/features_list.md"
- },
- {
- "title": "groups",
- "description": "Manage groups",
- "path": "cli/groups.md"
- },
- {
- "title": "groups create",
- "description": "Create a user group",
- "path": "cli/groups_create.md"
- },
- {
- "title": "groups delete",
- "description": "Delete a user group",
- "path": "cli/groups_delete.md"
- },
- {
- "title": "groups edit",
- "description": "Edit a user group",
- "path": "cli/groups_edit.md"
- },
- {
- "title": "groups list",
- "description": "List user groups",
- "path": "cli/groups_list.md"
- },
- {
- "title": "licenses",
- "description": "Add, delete, and list licenses",
- "path": "cli/licenses.md"
- },
- {
- "title": "licenses add",
- "description": "Add license to Coder deployment",
- "path": "cli/licenses_add.md"
- },
- {
- "title": "licenses delete",
- "description": "Delete license by ID",
- "path": "cli/licenses_delete.md"
- },
- {
- "title": "licenses list",
- "description": "List licenses (including expired)",
- "path": "cli/licenses_list.md"
- },
- {
- "title": "list",
- "description": "List workspaces",
- "path": "cli/list.md"
- },
- {
- "title": "login",
- "description": "Authenticate with Coder deployment",
- "path": "cli/login.md"
- },
- {
- "title": "logout",
- "description": "Unauthenticate your local session",
- "path": "cli/logout.md"
- },
- {
- "title": "netcheck",
- "description": "Print network debug information for DERP and STUN",
- "path": "cli/netcheck.md"
- },
- {
- "title": "notifications",
- "description": "Manage Coder notifications",
- "path": "cli/notifications.md"
- },
- {
- "title": "notifications pause",
- "description": "Pause notifications",
- "path": "cli/notifications_pause.md"
- },
- {
- "title": "notifications resume",
- "description": "Resume notifications",
- "path": "cli/notifications_resume.md"
- },
- {
- "title": "open",
- "description": "Open a workspace",
- "path": "cli/open.md"
- },
- {
- "title": "open vscode",
- "description": "Open a workspace in VS Code Desktop",
- "path": "cli/open_vscode.md"
- },
- {
- "title": "ping",
- "description": "Ping a workspace",
- "path": "cli/ping.md"
- },
- {
- "title": "port-forward",
- "description": "Forward ports from a workspace to the local machine. For reverse port forwarding, use \"coder ssh -R\".",
- "path": "cli/port-forward.md"
- },
- {
- "title": "provisionerd",
- "description": "Manage provisioner daemons",
- "path": "cli/provisionerd.md"
- },
- {
- "title": "provisionerd start",
- "description": "Run a provisioner daemon",
- "path": "cli/provisionerd_start.md"
- },
- {
- "title": "publickey",
- "description": "Output your Coder public key used for Git operations",
- "path": "cli/publickey.md"
- },
- {
- "title": "rename",
- "description": "Rename a workspace",
- "path": "cli/rename.md"
- },
- {
- "title": "reset-password",
- "description": "Directly connect to the database to reset a user's password",
- "path": "cli/reset-password.md"
- },
- {
- "title": "restart",
- "description": "Restart a workspace",
- "path": "cli/restart.md"
- },
- {
- "title": "schedule",
- "description": "Schedule automated start and stop times for workspaces",
- "path": "cli/schedule.md"
- },
- {
- "title": "schedule override-stop",
- "description": "Override the stop time of a currently running workspace instance.",
- "path": "cli/schedule_override-stop.md"
- },
- {
- "title": "schedule show",
- "description": "Show workspace schedules",
- "path": "cli/schedule_show.md"
- },
- {
- "title": "schedule start",
- "description": "Edit workspace start schedule",
- "path": "cli/schedule_start.md"
- },
- {
- "title": "schedule stop",
- "description": "Edit workspace stop schedule",
- "path": "cli/schedule_stop.md"
- },
- {
- "title": "server",
- "description": "Start a Coder server",
- "path": "cli/server.md"
- },
- {
- "title": "server create-admin-user",
- "description": "Create a new admin user with the given username, email and password and adds it to every organization.",
- "path": "cli/server_create-admin-user.md"
- },
- {
- "title": "server dbcrypt",
- "description": "Manage database encryption.",
- "path": "cli/server_dbcrypt.md"
- },
- {
- "title": "server dbcrypt decrypt",
- "description": "Decrypt a previously encrypted database.",
- "path": "cli/server_dbcrypt_decrypt.md"
- },
- {
- "title": "server dbcrypt delete",
- "description": "Delete all encrypted data from the database. THIS IS A DESTRUCTIVE OPERATION.",
- "path": "cli/server_dbcrypt_delete.md"
- },
- {
- "title": "server dbcrypt rotate",
- "description": "Rotate database encryption keys.",
- "path": "cli/server_dbcrypt_rotate.md"
- },
- {
- "title": "server postgres-builtin-serve",
- "description": "Run the built-in PostgreSQL deployment.",
- "path": "cli/server_postgres-builtin-serve.md"
- },
- {
- "title": "server postgres-builtin-url",
- "description": "Output the connection URL for the built-in PostgreSQL deployment.",
- "path": "cli/server_postgres-builtin-url.md"
- },
- {
- "title": "show",
- "description": "Display details of a workspace's resources and agents",
- "path": "cli/show.md"
- },
- {
- "title": "speedtest",
- "description": "Run upload and download tests from your machine to a workspace",
- "path": "cli/speedtest.md"
- },
- {
- "title": "ssh",
- "description": "Start a shell into a workspace",
- "path": "cli/ssh.md"
- },
- {
- "title": "start",
- "description": "Start a workspace",
- "path": "cli/start.md"
- },
- {
- "title": "stat",
- "description": "Show resource usage for the current workspace.",
- "path": "cli/stat.md"
- },
- {
- "title": "stat cpu",
- "description": "Show CPU usage, in cores.",
- "path": "cli/stat_cpu.md"
- },
- {
- "title": "stat disk",
- "description": "Show disk usage, in gigabytes.",
- "path": "cli/stat_disk.md"
- },
- {
- "title": "stat mem",
- "description": "Show memory usage, in gigabytes.",
- "path": "cli/stat_mem.md"
- },
- {
- "title": "state",
- "description": "Manually manage Terraform state to fix broken workspaces",
- "path": "cli/state.md"
- },
- {
- "title": "state pull",
- "description": "Pull a Terraform state file from a workspace.",
- "path": "cli/state_pull.md"
- },
- {
- "title": "state push",
- "description": "Push a Terraform state file to a workspace.",
- "path": "cli/state_push.md"
- },
- {
- "title": "stop",
- "description": "Stop a workspace",
- "path": "cli/stop.md"
- },
- {
- "title": "support",
- "description": "Commands for troubleshooting issues with a Coder deployment.",
- "path": "cli/support.md"
- },
- {
- "title": "support bundle",
- "description": "Generate a support bundle to troubleshoot issues connecting to a workspace.",
- "path": "cli/support_bundle.md"
- },
- {
- "title": "templates",
- "description": "Manage templates",
- "path": "cli/templates.md"
- },
- {
- "title": "templates archive",
- "description": "Archive unused or failed template versions from a given template(s)",
- "path": "cli/templates_archive.md"
- },
- {
- "title": "templates create",
- "description": "DEPRECATED: Create a template from the current directory or as specified by flag",
- "path": "cli/templates_create.md"
- },
- {
- "title": "templates delete",
- "description": "Delete templates",
- "path": "cli/templates_delete.md"
- },
- {
- "title": "templates edit",
- "description": "Edit the metadata of a template by name.",
- "path": "cli/templates_edit.md"
- },
- {
- "title": "templates init",
- "description": "Get started with a templated template.",
- "path": "cli/templates_init.md"
- },
- {
- "title": "templates list",
- "description": "List all the templates available for the organization",
- "path": "cli/templates_list.md"
- },
- {
- "title": "templates pull",
- "description": "Download the active, latest, or specified version of a template to a path.",
- "path": "cli/templates_pull.md"
- },
- {
- "title": "templates push",
- "description": "Create or update a template from the current directory or as specified by flag",
- "path": "cli/templates_push.md"
- },
- {
- "title": "templates versions",
- "description": "Manage different versions of the specified template",
- "path": "cli/templates_versions.md"
- },
- {
- "title": "templates versions archive",
- "description": "Archive a template version(s).",
- "path": "cli/templates_versions_archive.md"
- },
- {
- "title": "templates versions list",
- "description": "List all the versions of the specified template",
- "path": "cli/templates_versions_list.md"
- },
- {
- "title": "templates versions unarchive",
- "description": "Unarchive a template version(s).",
- "path": "cli/templates_versions_unarchive.md"
- },
- {
- "title": "tokens",
- "description": "Manage personal access tokens",
- "path": "cli/tokens.md"
- },
- {
- "title": "tokens create",
- "description": "Create a token",
- "path": "cli/tokens_create.md"
- },
- {
- "title": "tokens list",
- "description": "List tokens",
- "path": "cli/tokens_list.md"
- },
- {
- "title": "tokens remove",
- "description": "Delete a token",
- "path": "cli/tokens_remove.md"
- },
- {
- "title": "unfavorite",
- "description": "Remove a workspace from your favorites",
- "path": "cli/unfavorite.md"
- },
- {
- "title": "update",
- "description": "Will update and start a given workspace if it is out of date",
- "path": "cli/update.md"
- },
- {
- "title": "users",
- "description": "Manage users",
- "path": "cli/users.md"
- },
- {
- "title": "users activate",
- "description": "Update a user's status to 'active'. Active users can fully interact with the platform",
- "path": "cli/users_activate.md"
- },
- {
- "title": "users create",
- "path": "cli/users_create.md"
- },
- {
- "title": "users delete",
- "description": "Delete a user by username or user_id.",
- "path": "cli/users_delete.md"
- },
- {
- "title": "users list",
- "path": "cli/users_list.md"
- },
- {
- "title": "users show",
- "description": "Show a single user. Use 'me' to indicate the currently authenticated user.",
- "path": "cli/users_show.md"
- },
- {
- "title": "users suspend",
- "description": "Update a user's status to 'suspended'. A suspended user cannot log into the platform",
- "path": "cli/users_suspend.md"
- },
- {
- "title": "version",
- "description": "Show coder version",
- "path": "cli/version.md"
- },
- {
- "title": "whoami",
- "description": "Fetch authenticated user info for Coder deployment",
- "path": "cli/whoami.md"
- }
- ]
- },
- {
- "title": "Security",
- "description": "Security advisories",
- "path": "./security/index.md",
- "icon_path": "./images/icons/security.svg",
- "children": [
- {
- "title": "API tokens of deleted users not invalidated",
- "description": "Fixed in v0.23.0 (Apr 25, 2023)",
- "path": "./security/0001_user_apikeys_invalidation.md"
- }
- ]
- },
- {
- "title": "FAQs",
- "description": "Frequently asked questions",
- "path": "./faqs.md",
- "icon_path": "./images/icons/info.svg"
- },
- {
- "title": "Guides",
- "description": "Employee-authored tutorials",
- "path": "./guides/index.md",
- "icon_path": "./images/icons/notes.svg",
- "children": [
- {
- "title": "Generate a Support Bundle",
- "description": "Generate and upload a Support Bundle to Coder Support",
- "path": "./guides/support-bundle.md"
- },
- {
- "title": "Configuring Okta",
- "description": "Custom claims/scopes with Okta for group/role sync",
- "path": "./guides/configuring-okta.md"
- },
- {
- "title": "Google to AWS Federation",
- "description": "Federating a Google Cloud service account to AWS",
- "path": "./guides/gcp-to-aws.md"
- },
- {
- "title": "JFrog Artifactory Integration",
- "description": "Integrate Coder with JFrog Artifactory",
- "path": "./guides/artifactory-integration.md"
- },
- {
- "title": "Island Enterprise Browser Integration",
- "description": "Integrate Coder with Island's Enterprise Browser",
- "path": "./guides/island-integration.md"
- },
- {
- "title": "Template ImagePullSecrets",
- "description": "Creating ImagePullSecrets for private registries",
- "path": "./guides/image-pull-secret.md"
- },
- {
- "title": "Postgres SSL",
- "description": "Configure Coder to connect to Postgres over SSL",
- "path": "./guides/postgres-ssl.md"
- },
- {
- "title": "Azure Federation",
- "description": "Federating Coder to Azure",
- "path": "./guides/azure-federation.md"
+ "title": "REST API",
+ "description": "Learn how to use Coderd API",
+ "path": "./reference/api/README.md",
+ "icon_path": "./images/icons/api.svg",
+ "children": [
+ {
+ "title": "General",
+ "path": "./reference/api/general.md"
+ },
+ {
+ "title": "Agents",
+ "path": "./reference/api/agents.md"
+ },
+ {
+ "title": "Applications",
+ "path": "./reference/api/applications.md"
+ },
+ {
+ "title": "Audit",
+ "path": "./reference/api/audit.md"
+ },
+ {
+ "title": "Authentication",
+ "path": "./reference/api/authentication.md"
+ },
+ {
+ "title": "Authorization",
+ "path": "./reference/api/authorization.md"
+ },
+ {
+ "title": "Builds",
+ "path": "./reference/api/builds.md"
+ },
+ {
+ "title": "Debug",
+ "path": "./reference/api/debug.md"
+ },
+ {
+ "title": "Enterprise",
+ "path": "./reference/api/enterprise.md"
+ },
+ {
+ "title": "Files",
+ "path": "./reference/api/files.md"
+ },
+ {
+ "title": "Git",
+ "path": "./reference/api/git.md"
+ },
+ {
+ "title": "Insights",
+ "path": "./reference/api/insights.md"
+ },
+ {
+ "title": "Members",
+ "path": "./reference/api/members.md"
+ },
+ {
+ "title": "Organizations",
+ "path": "./reference/api/organizations.md"
+ },
+ {
+ "title": "PortSharing",
+ "path": "./reference/api/portsharing.md"
+ },
+ {
+ "title": "Schemas",
+ "path": "./reference/api/schemas.md"
+ },
+ {
+ "title": "Templates",
+ "path": "./reference/api/templates.md"
+ },
+ {
+ "title": "Users",
+ "path": "./reference/api/users.md"
+ },
+ {
+ "title": "WorkspaceProxies",
+ "path": "./reference/api/workspaceproxies.md"
+ },
+ {
+ "title": "Workspaces",
+ "path": "./reference/api/workspaces.md"
+ }
+ ]
},
{
- "title": "Scanning Coder Workspaces with JFrog Xray",
- "description": "Integrate Coder with JFrog Xray",
- "path": "./guides/xray-integration.md"
+ "title": "Command Line",
+ "description": "Learn how to use Coder CLI",
+ "path": "./reference/cli/README.md",
+ "icon_path": "./images/icons/terminal.svg",
+ "children": [
+ {
+ "title": "autoupdate",
+ "description": "Toggle auto-update policy for a workspace",
+ "path": "reference/cli/autoupdate.md"
+ },
+ {
+ "title": "coder",
+ "path": "reference/cli/README.md"
+ },
+ {
+ "title": "config-ssh",
+ "description": "Add an SSH Host entry for your workspaces \"ssh coder.workspace\"",
+ "path": "reference/cli/config-ssh.md"
+ },
+ {
+ "title": "create",
+ "description": "Create a workspace",
+ "path": "reference/cli/create.md"
+ },
+ {
+ "title": "delete",
+ "description": "Delete a workspace",
+ "path": "reference/cli/delete.md"
+ },
+ {
+ "title": "dotfiles",
+ "description": "Personalize your workspace by applying a canonical dotfiles repository",
+ "path": "reference/cli/dotfiles.md"
+ },
+ {
+ "title": "external-auth",
+ "description": "Manage external authentication",
+ "path": "reference/cli/external-auth.md"
+ },
+ {
+ "title": "external-auth access-token",
+ "description": "Print auth for an external provider",
+ "path": "reference/cli/external-auth_access-token.md"
+ },
+ {
+ "title": "favorite",
+ "description": "Add a workspace to your favorites",
+ "path": "reference/cli/favorite.md"
+ },
+ {
+ "title": "features",
+ "description": "List Enterprise features",
+ "path": "reference/cli/features.md"
+ },
+ {
+ "title": "features list",
+ "path": "reference/cli/features_list.md"
+ },
+ {
+ "title": "groups",
+ "description": "Manage groups",
+ "path": "reference/cli/groups.md"
+ },
+ {
+ "title": "groups create",
+ "description": "Create a user group",
+ "path": "reference/cli/groups_create.md"
+ },
+ {
+ "title": "groups delete",
+ "description": "Delete a user group",
+ "path": "reference/cli/groups_delete.md"
+ },
+ {
+ "title": "groups edit",
+ "description": "Edit a user group",
+ "path": "reference/cli/groups_edit.md"
+ },
+ {
+ "title": "groups list",
+ "description": "List user groups",
+ "path": "reference/cli/groups_list.md"
+ },
+ {
+ "title": "licenses",
+ "description": "Add, delete, and list licenses",
+ "path": "reference/cli/licenses.md"
+ },
+ {
+ "title": "licenses add",
+ "description": "Add license to Coder deployment",
+ "path": "reference/cli/licenses_add.md"
+ },
+ {
+ "title": "licenses delete",
+ "description": "Delete license by ID",
+ "path": "reference/cli/licenses_delete.md"
+ },
+ {
+ "title": "licenses list",
+ "description": "List licenses (including expired)",
+ "path": "reference/cli/licenses_list.md"
+ },
+ {
+ "title": "list",
+ "description": "List workspaces",
+ "path": "reference/cli/list.md"
+ },
+ {
+ "title": "login",
+ "description": "Authenticate with Coder deployment",
+ "path": "reference/cli/login.md"
+ },
+ {
+ "title": "logout",
+ "description": "Unauthenticate your local session",
+ "path": "reference/cli/logout.md"
+ },
+ {
+ "title": "netcheck",
+ "description": "Print network debug information for DERP and STUN",
+ "path": "reference/cli/netcheck.md"
+ },
+ {
+ "title": "notifications",
+ "description": "Manage Coder notifications",
+ "path": "reference/cli/notifications.md"
+ },
+ {
+ "title": "notifications pause",
+ "description": "Pause notifications",
+ "path": "reference/cli/notifications_pause.md"
+ },
+ {
+ "title": "notifications resume",
+ "description": "Resume notifications",
+ "path": "reference/cli/notifications_resume.md"
+ },
+ {
+ "title": "open",
+ "description": "Open a workspace",
+ "path": "reference/cli/open.md"
+ },
+ {
+ "title": "open vscode",
+ "description": "Open a workspace in VS Code Desktop",
+ "path": "reference/cli/open_vscode.md"
+ },
+ {
+ "title": "ping",
+ "description": "Ping a workspace",
+ "path": "reference/cli/ping.md"
+ },
+ {
+ "title": "port-forward",
+ "description": "Forward ports from a workspace to the local machine. For reverse port forwarding, use \"coder ssh -R\".",
+ "path": "reference/cli/port-forward.md"
+ },
+ {
+ "title": "provisionerd",
+ "description": "Manage provisioner daemons",
+ "path": "reference/cli/provisionerd.md"
+ },
+ {
+ "title": "provisionerd start",
+ "description": "Run a provisioner daemon",
+ "path": "reference/cli/provisionerd_start.md"
+ },
+ {
+ "title": "publickey",
+ "description": "Output your Coder public key used for Git operations",
+ "path": "reference/cli/publickey.md"
+ },
+ {
+ "title": "rename",
+ "description": "Rename a workspace",
+ "path": "reference/cli/rename.md"
+ },
+ {
+ "title": "reset-password",
+ "description": "Directly connect to the database to reset a user's password",
+ "path": "reference/cli/reset-password.md"
+ },
+ {
+ "title": "restart",
+ "description": "Restart a workspace",
+ "path": "reference/cli/restart.md"
+ },
+ {
+ "title": "schedule",
+ "description": "Schedule automated start and stop times for workspaces",
+ "path": "reference/cli/schedule.md"
+ },
+ {
+ "title": "schedule override-stop",
+ "description": "Override the stop time of a currently running workspace instance.",
+ "path": "reference/cli/schedule_override-stop.md"
+ },
+ {
+ "title": "schedule show",
+ "description": "Show workspace schedules",
+ "path": "reference/cli/schedule_show.md"
+ },
+ {
+ "title": "schedule start",
+ "description": "Edit workspace start schedule",
+ "path": "reference/cli/schedule_start.md"
+ },
+ {
+ "title": "schedule stop",
+ "description": "Edit workspace stop schedule",
+ "path": "reference/cli/schedule_stop.md"
+ },
+ {
+ "title": "server",
+ "description": "Start a Coder server",
+ "path": "reference/cli/server.md"
+ },
+ {
+ "title": "server create-admin-user",
+ "description": "Create a new admin user with the given username, email and password and adds it to every organization.",
+ "path": "reference/cli/server_create-admin-user.md"
+ },
+ {
+ "title": "server dbcrypt",
+ "description": "Manage database encryption.",
+ "path": "reference/cli/server_dbcrypt.md"
+ },
+ {
+ "title": "server dbcrypt decrypt",
+ "description": "Decrypt a previously encrypted database.",
+ "path": "reference/cli/server_dbcrypt_decrypt.md"
+ },
+ {
+ "title": "server dbcrypt delete",
+ "description": "Delete all encrypted data from the database. THIS IS A DESTRUCTIVE OPERATION.",
+ "path": "reference/cli/server_dbcrypt_delete.md"
+ },
+ {
+ "title": "server dbcrypt rotate",
+ "description": "Rotate database encryption keys.",
+ "path": "reference/cli/server_dbcrypt_rotate.md"
+ },
+ {
+ "title": "server postgres-builtin-serve",
+ "description": "Run the built-in PostgreSQL deployment.",
+ "path": "reference/cli/server_postgres-builtin-serve.md"
+ },
+ {
+ "title": "server postgres-builtin-url",
+ "description": "Output the connection URL for the built-in PostgreSQL deployment.",
+ "path": "reference/cli/server_postgres-builtin-url.md"
+ },
+ {
+ "title": "show",
+ "description": "Display details of a workspace's resources and agents",
+ "path": "reference/cli/show.md"
+ },
+ {
+ "title": "speedtest",
+ "description": "Run upload and download tests from your machine to a workspace",
+ "path": "reference/cli/speedtest.md"
+ },
+ {
+ "title": "ssh",
+ "description": "Start a shell into a workspace",
+ "path": "reference/cli/ssh.md"
+ },
+ {
+ "title": "start",
+ "description": "Start a workspace",
+ "path": "reference/cli/start.md"
+ },
+ {
+ "title": "stat",
+ "description": "Show resource usage for the current workspace.",
+ "path": "reference/cli/stat.md"
+ },
+ {
+ "title": "stat cpu",
+ "description": "Show CPU usage, in cores.",
+ "path": "reference/cli/stat_cpu.md"
+ },
+ {
+ "title": "stat disk",
+ "description": "Show disk usage, in gigabytes.",
+ "path": "reference/cli/stat_disk.md"
+ },
+ {
+ "title": "stat mem",
+ "description": "Show memory usage, in gigabytes.",
+ "path": "reference/cli/stat_mem.md"
+ },
+ {
+ "title": "state",
+ "description": "Manually manage Terraform state to fix broken workspaces",
+ "path": "reference/cli/state.md"
+ },
+ {
+ "title": "state pull",
+ "description": "Pull a Terraform state file from a workspace.",
+ "path": "reference/cli/state_pull.md"
+ },
+ {
+ "title": "state push",
+ "description": "Push a Terraform state file to a workspace.",
+ "path": "reference/cli/state_push.md"
+ },
+ {
+ "title": "stop",
+ "description": "Stop a workspace",
+ "path": "reference/cli/stop.md"
+ },
+ {
+ "title": "support",
+ "description": "Commands for troubleshooting issues with a Coder deployment.",
+ "path": "reference/cli/support.md"
+ },
+ {
+ "title": "support bundle",
+ "description": "Generate a support bundle to troubleshoot issues connecting to a workspace.",
+ "path": "reference/cli/support_bundle.md"
+ },
+ {
+ "title": "templates",
+ "description": "Manage templates",
+ "path": "reference/cli/templates.md"
+ },
+ {
+ "title": "templates archive",
+ "description": "Archive unused or failed template versions from a given template(s)",
+ "path": "reference/cli/templates_archive.md"
+ },
+ {
+ "title": "templates create",
+ "description": "DEPRECATED: Create a template from the current directory or as specified by flag",
+ "path": "reference/cli/templates_create.md"
+ },
+ {
+ "title": "templates delete",
+ "description": "Delete templates",
+ "path": "reference/cli/templates_delete.md"
+ },
+ {
+ "title": "templates edit",
+ "description": "Edit the metadata of a template by name.",
+ "path": "reference/cli/templates_edit.md"
+ },
+ {
+ "title": "templates init",
+ "description": "Get started with a templated template.",
+ "path": "reference/cli/templates_init.md"
+ },
+ {
+ "title": "templates list",
+ "description": "List all the templates available for the organization",
+ "path": "reference/cli/templates_list.md"
+ },
+ {
+ "title": "templates pull",
+ "description": "Download the active, latest, or specified version of a template to a path.",
+ "path": "reference/cli/templates_pull.md"
+ },
+ {
+ "title": "templates push",
+ "description": "Create or update a template from the current directory or as specified by flag",
+ "path": "reference/cli/templates_push.md"
+ },
+ {
+ "title": "templates versions",
+ "description": "Manage different versions of the specified template",
+ "path": "reference/cli/templates_versions.md"
+ },
+ {
+ "title": "templates versions archive",
+ "description": "Archive a template version(s).",
+ "path": "reference/cli/templates_versions_archive.md"
+ },
+ {
+ "title": "templates versions list",
+ "description": "List all the versions of the specified template",
+ "path": "reference/cli/templates_versions_list.md"
+ },
+ {
+ "title": "templates versions unarchive",
+ "description": "Unarchive a template version(s).",
+ "path": "reference/cli/templates_versions_unarchive.md"
+ },
+ {
+ "title": "tokens",
+ "description": "Manage personal access tokens",
+ "path": "reference/cli/tokens.md"
+ },
+ {
+ "title": "tokens create",
+ "description": "Create a token",
+ "path": "reference/cli/tokens_create.md"
+ },
+ {
+ "title": "tokens list",
+ "description": "List tokens",
+ "path": "reference/cli/tokens_list.md"
+ },
+ {
+ "title": "tokens remove",
+ "description": "Delete a token",
+ "path": "reference/cli/tokens_remove.md"
+ },
+ {
+ "title": "unfavorite",
+ "description": "Remove a workspace from your favorites",
+ "path": "reference/cli/unfavorite.md"
+ },
+ {
+ "title": "update",
+ "description": "Will update and start a given workspace if it is out of date",
+ "path": "reference/cli/update.md"
+ },
+ {
+ "title": "users",
+ "description": "Manage users",
+ "path": "reference/cli/users.md"
+ },
+ {
+ "title": "users activate",
+ "description": "Update a user's status to 'active'. Active users can fully interact with the platform",
+ "path": "reference/cli/users_activate.md"
+ },
+ {
+ "title": "users create",
+ "path": "reference/cli/users_create.md"
+ },
+ {
+ "title": "users delete",
+ "description": "Delete a user by username or user_id.",
+ "path": "reference/cli/users_delete.md"
+ },
+ {
+ "title": "users list",
+ "path": "reference/cli/users_list.md"
+ },
+ {
+ "title": "users show",
+ "description": "Show a single user. Use 'me' to indicate the currently authenticated user.",
+ "path": "reference/cli/users_show.md"
+ },
+ {
+ "title": "users suspend",
+ "description": "Update a user's status to 'suspended'. A suspended user cannot log into the platform",
+ "path": "reference/cli/users_suspend.md"
+ },
+ {
+ "title": "version",
+ "description": "Show coder version",
+ "path": "reference/cli/version.md"
+ },
+ {
+ "title": "whoami",
+ "description": "Fetch authenticated user info for Coder deployment",
+ "path": "reference/cli/whoami.md"
+ }
+ ]
}
]
}
diff --git a/docs/manifest.old.json b/docs/manifest.old.json
new file mode 100644
index 0000000000000..6df5f622f2dae
--- /dev/null
+++ b/docs/manifest.old.json
@@ -0,0 +1,1126 @@
+{
+ "versions": ["main"],
+ "routes": [
+ {
+ "title": "About",
+ "description": "About Coder",
+ "path": "./README.md",
+ "icon_path": "./images/icons/home.svg",
+ "children": [
+ {
+ "title": "Architecture",
+ "description": "Learn how Coder works",
+ "path": "./about/architecture.md",
+ "icon_path": "./images/icons/protractor.svg"
+ }
+ ]
+ },
+ {
+ "title": "Installation",
+ "description": "How to install and deploy Coder",
+ "path": "./install/index.md",
+ "icon_path": "./images/icons/download.svg",
+ "children": [
+ {
+ "title": "Kubernetes",
+ "description": "Install Coder with Kubernetes via Helm",
+ "path": "./install/kubernetes.md"
+ },
+ {
+ "title": "Docker",
+ "description": "Install Coder with Docker / docker-compose",
+ "path": "./install/docker.md"
+ },
+ {
+ "title": "OpenShift",
+ "description": "Install Coder on OpenShift",
+ "path": "./install/openshift.md"
+ },
+ {
+ "title": "Offline deployments",
+ "description": "Run Coder in offline / air-gapped environments",
+ "path": "./install/offline.md"
+ },
+ {
+ "title": "External database",
+ "description": "Use external PostgreSQL database",
+ "path": "./install/database.md"
+ },
+ {
+ "title": "Uninstall",
+ "description": "Learn how to uninstall Coder",
+ "path": "./install/uninstall.md"
+ },
+ {
+ "title": "1-click install",
+ "description": "Install Coder on a cloud provider with a single click",
+ "path": "./install/1-click.md"
+ },
+ {
+ "title": "Releases",
+ "description": "Coder Release Channels and Cadence",
+ "path": "./install/releases.md"
+ }
+ ]
+ },
+ {
+ "title": "Platforms",
+ "description": "Platform-specific guides using Coder",
+ "path": "./platforms/README.md",
+ "icon_path": "./images/icons/star.svg",
+ "children": [
+ {
+ "title": "AWS",
+ "description": "Set up Coder on an AWS EC2 VM",
+ "path": "./platforms/aws.md",
+ "icon_path": "./images/aws.svg"
+ },
+ {
+ "title": "Azure",
+ "description": "Set up Coder on an Azure VM",
+ "path": "./platforms/azure.md",
+ "icon_path": "./images/azure.svg"
+ },
+ {
+ "title": "Docker",
+ "description": "Set up Coder with Docker",
+ "path": "./platforms/docker.md",
+ "icon_path": "./images/icons/docker.svg"
+ },
+ {
+ "title": "GCP",
+ "description": "Set up Coder on a GCP Compute Engine VM",
+ "path": "./platforms/gcp.md",
+ "icon_path": "./images/google-cloud.svg"
+ },
+ {
+ "title": "Kubernetes",
+ "description": "Set up Coder on Kubernetes",
+ "path": "./platforms/kubernetes/index.md",
+ "children": [
+ {
+ "title": "Additional clusters",
+ "description": "Deploy workspaces on additional Kubernetes clusters",
+ "path": "./platforms/kubernetes/additional-clusters.md"
+ },
+ {
+ "title": "Deployment logs",
+ "description": "Stream K8s event logs on workspace startup",
+ "path": "./platforms/kubernetes/deployment-logs.md"
+ }
+ ]
+ },
+ {
+ "title": "Other platforms",
+ "description": "Set up Coder on an another provider",
+ "path": "./platforms/other.md"
+ }
+ ]
+ },
+ {
+ "title": "Templates",
+ "description": "Templates define the infrastructure for workspaces",
+ "path": "./templates/index.md",
+ "icon_path": "./images/icons/picture.svg",
+ "children": [
+ {
+ "title": "Working with templates",
+ "description": "Creating, editing, and updating templates",
+ "path": "./templates/creating.md"
+ },
+ {
+ "title": "Your first template",
+ "description": "A tutorial for creating and editing your first template",
+ "path": "./templates/tutorial.md"
+ },
+ {
+ "title": "Guided tour",
+ "description": "Create a template from scratch",
+ "path": "./templates/tour.md"
+ },
+ {
+ "title": "Setting up templates",
+ "description": "Best practices for writing templates",
+ "path": "./templates/best-practices.md",
+ "children": [
+ {
+ "title": "Change management",
+ "description": "Versioning templates with git and CI",
+ "path": "./templates/change-management.md",
+ "icon_path": "./images/icons/git.svg"
+ },
+ {
+ "title": "Provider authentication",
+ "description": "Authenticate the provisioner",
+ "path": "./templates/authentication.md",
+ "icon_path": "./images/icons/key.svg"
+ },
+ {
+ "title": "Resource persistence",
+ "description": "How resource persistence works in Coder",
+ "path": "./templates/resource-persistence.md",
+ "icon_path": "./images/icons/infinity.svg"
+ },
+ {
+ "title": "Terraform modules",
+ "description": "Reuse code across Coder templates",
+ "path": "./templates/modules.md"
+ }
+ ]
+ },
+ {
+ "title": "Customizing templates",
+ "description": "Give information and options to workspace users",
+ "path": "./templates/customizing.md",
+ "children": [
+ {
+ "title": "Agent metadata",
+ "description": "Show operational metrics in the workspace",
+ "path": "./templates/agent-metadata.md"
+ },
+ {
+ "title": "Resource metadata",
+ "description": "Show information in the workspace about template resources",
+ "path": "./templates/resource-metadata.md"
+ },
+ {
+ "title": "UI Resource Ordering",
+ "description": "Learn how to manage the order of Terraform resources in UI",
+ "path": "./templates/resource-ordering.md"
+ }
+ ]
+ },
+ {
+ "title": "Parameters",
+ "description": "Prompt the user for additional information about a workspace",
+ "path": "./templates/parameters.md"
+ },
+ {
+ "title": "Variables",
+ "description": "Prompt the template administrator for additional information about a template",
+ "path": "./templates/variables.md"
+ },
+ {
+ "title": "Administering templates",
+ "description": "Configuration settings for template admins",
+ "path": "./templates/configuration.md",
+ "children": [
+ {
+ "title": "General settings",
+ "description": "Configure name, display info, and update polices",
+ "path": "./templates/general-settings.md"
+ },
+ {
+ "title": "Permissions",
+ "description": "Configure who can access a template",
+ "path": "./templates/permissions.md"
+ },
+ {
+ "title": "Workspace Scheduling",
+ "description": "Configure when workspaces start, stop, and delete",
+ "path": "./templates/schedule.md"
+ }
+ ]
+ },
+ {
+ "title": "Open in Coder",
+ "description": "Add an \"Open in Coder\" button to your repos",
+ "path": "./templates/open-in-coder.md",
+ "icon_path": "./images/icons/key.svg"
+ },
+ {
+ "title": "Docker in workspaces",
+ "description": "Use Docker inside containerized templates",
+ "path": "./templates/docker-in-workspaces.md",
+ "icon_path": "./images/icons/docker.svg"
+ },
+ {
+ "title": "Dev Containers",
+ "description": "Use Dev Containers in workspaces",
+ "path": "./templates/dev-containers.md",
+ "state": "alpha"
+ },
+ {
+ "title": "Troubleshooting templates",
+ "description": "Fix common template problems",
+ "path": "./templates/troubleshooting.md"
+ },
+ {
+ "title": "Process Logging",
+ "description": "Audit commands in workspaces with exectrace",
+ "path": "./templates/process-logging.md",
+ "state": "enterprise"
+ },
+ {
+ "title": "Icons",
+ "description": "Coder includes icons for popular cloud providers and programming languages for you to use",
+ "path": "./templates/icons.md"
+ }
+ ]
+ },
+ {
+ "title": "Workspaces",
+ "description": "Learn about Coder workspaces.",
+ "path": "./workspaces.md",
+ "icon_path": "./images/icons/layers.svg"
+ },
+ {
+ "title": "IDEs",
+ "description": "Learn how to use your IDE of choice with Coder",
+ "path": "./ides.md",
+ "icon_path": "./images/icons/code.svg",
+ "children": [
+ {
+ "title": "Web IDEs",
+ "description": "Learn how to configure web IDEs in your templates",
+ "path": "./ides/web-ides.md"
+ },
+ {
+ "title": "JetBrains Gateway",
+ "description": "Learn how to configure JetBrains Gateway for your workspaces",
+ "path": "./ides/gateway.md"
+ },
+ {
+ "title": "Emacs",
+ "description": "Learn how to configure Emacs with TRAMP in Coder",
+ "path": "./ides/emacs-tramp.md"
+ },
+ {
+ "title": "Remote Desktops",
+ "description": "Learn how to use Remote Desktops with Coder",
+ "path": "./ides/remote-desktops.md"
+ }
+ ]
+ },
+ {
+ "title": "Networking",
+ "description": "Learn about networking in Coder",
+ "path": "./networking/index.md",
+ "icon_path": "./images/icons/networking.svg",
+ "children": [
+ {
+ "title": "Port Forwarding",
+ "description": "Learn how to forward ports in Coder",
+ "path": "./networking/port-forwarding.md"
+ },
+ {
+ "title": "STUN and NAT",
+ "description": "Learn how Coder establishes direct connections",
+ "path": "./networking/stun.md"
+ }
+ ]
+ },
+ {
+ "title": "Dotfiles",
+ "description": "Learn how to personalize your workspace",
+ "path": "./dotfiles.md",
+ "icon_path": "./images/icons/art-pad.svg"
+ },
+ {
+ "title": "Secrets",
+ "description": "Learn how to use secrets in your workspace",
+ "path": "./secrets.md",
+ "icon_path": "./images/icons/secrets.svg"
+ },
+ {
+ "title": "Administration",
+ "description": "How to install and deploy Coder",
+ "path": "./admin/README.md",
+ "icon_path": "./images/icons/wrench.svg",
+ "children": [
+ {
+ "title": "Authentication",
+ "description": "Learn how to set up authentication using GitHub or OpenID Connect",
+ "path": "./admin/auth.md",
+ "icon_path": "./images/icons/key.svg"
+ },
+ {
+ "title": "Users",
+ "description": "Learn about user roles available in Coder and how to create and manage users",
+ "path": "./admin/users.md",
+ "icon_path": "./images/icons/users.svg"
+ },
+ {
+ "title": "Groups",
+ "description": "Learn how to manage user groups",
+ "path": "./admin/groups.md",
+ "icon_path": "./images/icons/group.svg",
+ "state": "enterprise"
+ },
+ {
+ "title": "RBAC",
+ "description": "Learn how to use the role based access control",
+ "path": "./admin/rbac.md",
+ "icon_path": "./images/icons/rbac.svg",
+ "state": "enterprise"
+ },
+ {
+ "title": "Configuration",
+ "description": "Learn how to configure Coder",
+ "path": "./admin/configure.md",
+ "icon_path": "./images/icons/toggle_on.svg"
+ },
+ {
+ "title": "External Auth",
+ "description": "Learn how connect Coder with external auth providers",
+ "path": "./admin/external-auth.md",
+ "icon_path": "./images/icons/git.svg"
+ },
+ {
+ "title": "Upgrading",
+ "description": "Learn how to upgrade Coder",
+ "path": "./admin/upgrade.md",
+ "icon_path": "./images/icons/upgrade.svg"
+ },
+ {
+ "title": "Automation",
+ "description": "Learn how to automate Coder with the CLI and API",
+ "path": "./admin/automation.md",
+ "icon_path": "./images/icons/plug.svg"
+ },
+ {
+ "title": "Scaling Coder",
+ "description": "Learn how to use load testing tools",
+ "path": "./admin/scale.md",
+ "icon_path": "./images/icons/scale.svg"
+ },
+ {
+ "title": "Reference Architectures",
+ "description": "Learn about reference architectures for Coder",
+ "path": "./admin/architectures/index.md",
+ "icon_path": "./images/icons/scale.svg",
+ "children": [
+ {
+ "title": "Up to 1,000 users",
+ "path": "./admin/architectures/1k-users.md"
+ },
+ {
+ "title": "Up to 2,000 users",
+ "path": "./admin/architectures/2k-users.md"
+ },
+ {
+ "title": "Up to 3,000 users",
+ "path": "./admin/architectures/3k-users.md"
+ }
+ ]
+ },
+ {
+ "title": "External Provisioners",
+ "description": "Run provisioners isolated from the Coder server",
+ "path": "./admin/provisioners.md",
+ "icon_path": "./images/icons/queue.svg",
+ "state": "enterprise"
+ },
+ {
+ "title": "Workspace Proxies",
+ "description": "Run geo distributed workspace proxies",
+ "path": "./admin/workspace-proxies.md",
+ "icon_path": "./images/icons/networking.svg",
+ "state": "enterprise"
+ },
+ {
+ "title": "Application Logs",
+ "description": "Learn how to use Application Logs in your Coder deployment",
+ "path": "./admin/app-logs.md",
+ "icon_path": "./images/icons/notes.svg"
+ },
+ {
+ "title": "Audit Logs",
+ "description": "Learn how to use Audit Logs in your Coder deployment",
+ "path": "./admin/audit-logs.md",
+ "icon_path": "./images/icons/radar.svg",
+ "state": "enterprise"
+ },
+ {
+ "title": "Quotas",
+ "description": "Learn how to use Workspace Quotas in Coder",
+ "path": "./admin/quotas.md",
+ "icon_path": "./images/icons/dollar.svg",
+ "state": "enterprise"
+ },
+ {
+ "title": "High Availability",
+ "description": "Learn how to configure Coder for High Availability",
+ "path": "./admin/high-availability.md",
+ "icon_path": "./images/icons/hydra.svg",
+ "state": "enterprise"
+ },
+ {
+ "title": "Prometheus",
+ "description": "Learn how to collect Prometheus metrics",
+ "path": "./admin/prometheus.md",
+ "icon_path": "./images/icons/speed.svg"
+ },
+ {
+ "title": "Appearance",
+ "description": "Learn how to configure the appearance of Coder",
+ "path": "./admin/appearance.md",
+ "icon_path": "./images/icons/info.svg",
+ "state": "enterprise"
+ },
+ {
+ "title": "Telemetry",
+ "description": "Learn what usage telemetry Coder collects",
+ "path": "./admin/telemetry.md",
+ "icon_path": "./images/icons/science.svg"
+ },
+ {
+ "title": "Database Encryption",
+ "description": "Learn how to encrypt sensitive data at rest in Coder",
+ "path": "./admin/encryption.md",
+ "icon_path": "./images/icons/lock.svg",
+ "state": "enterprise"
+ },
+ {
+ "title": "Deployment Health",
+ "description": "Learn how to monitor the health of your Coder deployment",
+ "path": "./admin/healthcheck.md",
+ "icon_path": "./images/icons/health.svg"
+ }
+ ]
+ },
+ {
+ "title": "Enterprise",
+ "description": "Learn how to enable Enterprise features",
+ "path": "./enterprise.md",
+ "icon_path": "./images/icons/group.svg"
+ },
+ {
+ "title": "Contributing",
+ "description": "Learn how to contribute to Coder",
+ "path": "./CONTRIBUTING.md",
+ "icon_path": "./images/icons/contributing.svg",
+ "children": [
+ {
+ "title": "Code of Conduct",
+ "description": "See the code of conduct for contributing to Coder",
+ "path": "./contributing/CODE_OF_CONDUCT.md"
+ },
+ {
+ "title": "Feature stages",
+ "description": "Policies for Alpha and Experimental features.",
+ "path": "./contributing/feature-stages.md"
+ },
+ {
+ "title": "Documentation",
+ "description": "Our style guide for use when authoring documentation",
+ "path": "./contributing/documentation.md"
+ },
+ {
+ "title": "Security",
+ "description": "How to report vulnerabilities in Coder",
+ "path": "./contributing/SECURITY.md"
+ },
+ {
+ "title": "Frontend",
+ "description": "Our guide for frontend development",
+ "path": "./contributing/frontend.md"
+ }
+ ]
+ },
+ {
+ "title": "REST API",
+ "description": "Learn how to use Coderd API",
+ "path": "./api/index.md",
+ "icon_path": "./images/icons/api.svg",
+ "children": [
+ {
+ "title": "General",
+ "path": "./api/general.md"
+ },
+ {
+ "title": "Agents",
+ "path": "./api/agents.md"
+ },
+ {
+ "title": "Applications",
+ "path": "./api/applications.md"
+ },
+ {
+ "title": "Audit",
+ "path": "./api/audit.md"
+ },
+ {
+ "title": "Authentication",
+ "path": "./api/authentication.md"
+ },
+ {
+ "title": "Authorization",
+ "path": "./api/authorization.md"
+ },
+ {
+ "title": "Builds",
+ "path": "./api/builds.md"
+ },
+ {
+ "title": "Debug",
+ "path": "./api/debug.md"
+ },
+ {
+ "title": "Enterprise",
+ "path": "./api/enterprise.md"
+ },
+ {
+ "title": "Files",
+ "path": "./api/files.md"
+ },
+ {
+ "title": "Git",
+ "path": "./api/git.md"
+ },
+ {
+ "title": "Insights",
+ "path": "./api/insights.md"
+ },
+ {
+ "title": "Members",
+ "path": "./api/members.md"
+ },
+ {
+ "title": "Organizations",
+ "path": "./api/organizations.md"
+ },
+ {
+ "title": "PortSharing",
+ "path": "./api/portsharing.md"
+ },
+ {
+ "title": "Schemas",
+ "path": "./api/schemas.md"
+ },
+ {
+ "title": "Templates",
+ "path": "./api/templates.md"
+ },
+ {
+ "title": "Users",
+ "path": "./api/users.md"
+ },
+ {
+ "title": "WorkspaceProxies",
+ "path": "./api/workspaceproxies.md"
+ },
+ {
+ "title": "Workspaces",
+ "path": "./api/workspaces.md"
+ }
+ ]
+ },
+ {
+ "title": "Command Line",
+ "description": "Learn how to use Coder CLI",
+ "path": "./cli.md",
+ "icon_path": "./images/icons/terminal.svg",
+ "children": [
+ {
+ "title": "autoupdate",
+ "description": "Toggle auto-update policy for a workspace",
+ "path": "cli/autoupdate.md"
+ },
+ {
+ "title": "coder",
+ "path": "cli.md"
+ },
+ {
+ "title": "config-ssh",
+ "description": "Add an SSH Host entry for your workspaces \"ssh coder.workspace\"",
+ "path": "cli/config-ssh.md"
+ },
+ {
+ "title": "create",
+ "description": "Create a workspace",
+ "path": "cli/create.md"
+ },
+ {
+ "title": "delete",
+ "description": "Delete a workspace",
+ "path": "cli/delete.md"
+ },
+ {
+ "title": "dotfiles",
+ "description": "Personalize your workspace by applying a canonical dotfiles repository",
+ "path": "cli/dotfiles.md"
+ },
+ {
+ "title": "external-auth",
+ "description": "Manage external authentication",
+ "path": "cli/external-auth.md"
+ },
+ {
+ "title": "external-auth access-token",
+ "description": "Print auth for an external provider",
+ "path": "cli/external-auth_access-token.md"
+ },
+ {
+ "title": "favorite",
+ "description": "Add a workspace to your favorites",
+ "path": "cli/favorite.md"
+ },
+ {
+ "title": "features",
+ "description": "List Enterprise features",
+ "path": "cli/features.md"
+ },
+ {
+ "title": "features list",
+ "path": "cli/features_list.md"
+ },
+ {
+ "title": "groups",
+ "description": "Manage groups",
+ "path": "cli/groups.md"
+ },
+ {
+ "title": "groups create",
+ "description": "Create a user group",
+ "path": "cli/groups_create.md"
+ },
+ {
+ "title": "groups delete",
+ "description": "Delete a user group",
+ "path": "cli/groups_delete.md"
+ },
+ {
+ "title": "groups edit",
+ "description": "Edit a user group",
+ "path": "cli/groups_edit.md"
+ },
+ {
+ "title": "groups list",
+ "description": "List user groups",
+ "path": "cli/groups_list.md"
+ },
+ {
+ "title": "licenses",
+ "description": "Add, delete, and list licenses",
+ "path": "cli/licenses.md"
+ },
+ {
+ "title": "licenses add",
+ "description": "Add license to Coder deployment",
+ "path": "cli/licenses_add.md"
+ },
+ {
+ "title": "licenses delete",
+ "description": "Delete license by ID",
+ "path": "cli/licenses_delete.md"
+ },
+ {
+ "title": "licenses list",
+ "description": "List licenses (including expired)",
+ "path": "cli/licenses_list.md"
+ },
+ {
+ "title": "list",
+ "description": "List workspaces",
+ "path": "cli/list.md"
+ },
+ {
+ "title": "login",
+ "description": "Authenticate with Coder deployment",
+ "path": "cli/login.md"
+ },
+ {
+ "title": "logout",
+ "description": "Unauthenticate your local session",
+ "path": "cli/logout.md"
+ },
+ {
+ "title": "netcheck",
+ "description": "Print network debug information for DERP and STUN",
+ "path": "cli/netcheck.md"
+ },
+ {
+ "title": "open",
+ "description": "Open a workspace",
+ "path": "cli/open.md"
+ },
+ {
+ "title": "open vscode",
+ "description": "Open a workspace in VS Code Desktop",
+ "path": "cli/open_vscode.md"
+ },
+ {
+ "title": "ping",
+ "description": "Ping a workspace",
+ "path": "cli/ping.md"
+ },
+ {
+ "title": "port-forward",
+ "description": "Forward ports from a workspace to the local machine. For reverse port forwarding, use \"coder ssh -R\".",
+ "path": "cli/port-forward.md"
+ },
+ {
+ "title": "provisionerd",
+ "description": "Manage provisioner daemons",
+ "path": "cli/provisionerd.md"
+ },
+ {
+ "title": "provisionerd start",
+ "description": "Run a provisioner daemon",
+ "path": "cli/provisionerd_start.md"
+ },
+ {
+ "title": "publickey",
+ "description": "Output your Coder public key used for Git operations",
+ "path": "cli/publickey.md"
+ },
+ {
+ "title": "rename",
+ "description": "Rename a workspace",
+ "path": "cli/rename.md"
+ },
+ {
+ "title": "reset-password",
+ "description": "Directly connect to the database to reset a user's password",
+ "path": "cli/reset-password.md"
+ },
+ {
+ "title": "restart",
+ "description": "Restart a workspace",
+ "path": "cli/restart.md"
+ },
+ {
+ "title": "schedule",
+ "description": "Schedule automated start and stop times for workspaces",
+ "path": "cli/schedule.md"
+ },
+ {
+ "title": "schedule override-stop",
+ "description": "Override the stop time of a currently running workspace instance.",
+ "path": "cli/schedule_override-stop.md"
+ },
+ {
+ "title": "schedule show",
+ "description": "Show workspace schedules",
+ "path": "cli/schedule_show.md"
+ },
+ {
+ "title": "schedule start",
+ "description": "Edit workspace start schedule",
+ "path": "cli/schedule_start.md"
+ },
+ {
+ "title": "schedule stop",
+ "description": "Edit workspace stop schedule",
+ "path": "cli/schedule_stop.md"
+ },
+ {
+ "title": "server",
+ "description": "Start a Coder server",
+ "path": "cli/server.md"
+ },
+ {
+ "title": "server create-admin-user",
+ "description": "Create a new admin user with the given username, email and password and adds it to every organization.",
+ "path": "cli/server_create-admin-user.md"
+ },
+ {
+ "title": "server dbcrypt",
+ "description": "Manage database encryption.",
+ "path": "cli/server_dbcrypt.md"
+ },
+ {
+ "title": "server dbcrypt decrypt",
+ "description": "Decrypt a previously encrypted database.",
+ "path": "cli/server_dbcrypt_decrypt.md"
+ },
+ {
+ "title": "server dbcrypt delete",
+ "description": "Delete all encrypted data from the database. THIS IS A DESTRUCTIVE OPERATION.",
+ "path": "cli/server_dbcrypt_delete.md"
+ },
+ {
+ "title": "server dbcrypt rotate",
+ "description": "Rotate database encryption keys.",
+ "path": "cli/server_dbcrypt_rotate.md"
+ },
+ {
+ "title": "server postgres-builtin-serve",
+ "description": "Run the built-in PostgreSQL deployment.",
+ "path": "cli/server_postgres-builtin-serve.md"
+ },
+ {
+ "title": "server postgres-builtin-url",
+ "description": "Output the connection URL for the built-in PostgreSQL deployment.",
+ "path": "cli/server_postgres-builtin-url.md"
+ },
+ {
+ "title": "show",
+ "description": "Display details of a workspace's resources and agents",
+ "path": "cli/show.md"
+ },
+ {
+ "title": "speedtest",
+ "description": "Run upload and download tests from your machine to a workspace",
+ "path": "cli/speedtest.md"
+ },
+ {
+ "title": "ssh",
+ "description": "Start a shell into a workspace",
+ "path": "cli/ssh.md"
+ },
+ {
+ "title": "start",
+ "description": "Start a workspace",
+ "path": "cli/start.md"
+ },
+ {
+ "title": "stat",
+ "description": "Show resource usage for the current workspace.",
+ "path": "cli/stat.md"
+ },
+ {
+ "title": "stat cpu",
+ "description": "Show CPU usage, in cores.",
+ "path": "cli/stat_cpu.md"
+ },
+ {
+ "title": "stat disk",
+ "description": "Show disk usage, in gigabytes.",
+ "path": "cli/stat_disk.md"
+ },
+ {
+ "title": "stat mem",
+ "description": "Show memory usage, in gigabytes.",
+ "path": "cli/stat_mem.md"
+ },
+ {
+ "title": "state",
+ "description": "Manually manage Terraform state to fix broken workspaces",
+ "path": "cli/state.md"
+ },
+ {
+ "title": "state pull",
+ "description": "Pull a Terraform state file from a workspace.",
+ "path": "cli/state_pull.md"
+ },
+ {
+ "title": "state push",
+ "description": "Push a Terraform state file to a workspace.",
+ "path": "cli/state_push.md"
+ },
+ {
+ "title": "stop",
+ "description": "Stop a workspace",
+ "path": "cli/stop.md"
+ },
+ {
+ "title": "support",
+ "description": "Commands for troubleshooting issues with a Coder deployment.",
+ "path": "cli/support.md"
+ },
+ {
+ "title": "support bundle",
+ "description": "Generate a support bundle to troubleshoot issues connecting to a workspace.",
+ "path": "cli/support_bundle.md"
+ },
+ {
+ "title": "templates",
+ "description": "Manage templates",
+ "path": "cli/templates.md"
+ },
+ {
+ "title": "templates archive",
+ "description": "Archive unused or failed template versions from a given template(s)",
+ "path": "cli/templates_archive.md"
+ },
+ {
+ "title": "templates create",
+ "description": "DEPRECATED: Create a template from the current directory or as specified by flag",
+ "path": "cli/templates_create.md"
+ },
+ {
+ "title": "templates delete",
+ "description": "Delete templates",
+ "path": "cli/templates_delete.md"
+ },
+ {
+ "title": "templates edit",
+ "description": "Edit the metadata of a template by name.",
+ "path": "cli/templates_edit.md"
+ },
+ {
+ "title": "templates init",
+ "description": "Get started with a templated template.",
+ "path": "cli/templates_init.md"
+ },
+ {
+ "title": "templates list",
+ "description": "List all the templates available for the organization",
+ "path": "cli/templates_list.md"
+ },
+ {
+ "title": "templates pull",
+ "description": "Download the active, latest, or specified version of a template to a path.",
+ "path": "cli/templates_pull.md"
+ },
+ {
+ "title": "templates push",
+ "description": "Create or update a template from the current directory or as specified by flag",
+ "path": "cli/templates_push.md"
+ },
+ {
+ "title": "templates versions",
+ "description": "Manage different versions of the specified template",
+ "path": "cli/templates_versions.md"
+ },
+ {
+ "title": "templates versions archive",
+ "description": "Archive a template version(s).",
+ "path": "cli/templates_versions_archive.md"
+ },
+ {
+ "title": "templates versions list",
+ "description": "List all the versions of the specified template",
+ "path": "cli/templates_versions_list.md"
+ },
+ {
+ "title": "templates versions unarchive",
+ "description": "Unarchive a template version(s).",
+ "path": "cli/templates_versions_unarchive.md"
+ },
+ {
+ "title": "tokens",
+ "description": "Manage personal access tokens",
+ "path": "cli/tokens.md"
+ },
+ {
+ "title": "tokens create",
+ "description": "Create a token",
+ "path": "cli/tokens_create.md"
+ },
+ {
+ "title": "tokens list",
+ "description": "List tokens",
+ "path": "cli/tokens_list.md"
+ },
+ {
+ "title": "tokens remove",
+ "description": "Delete a token",
+ "path": "cli/tokens_remove.md"
+ },
+ {
+ "title": "unfavorite",
+ "description": "Remove a workspace from your favorites",
+ "path": "cli/unfavorite.md"
+ },
+ {
+ "title": "update",
+ "description": "Will update and start a given workspace if it is out of date",
+ "path": "cli/update.md"
+ },
+ {
+ "title": "users",
+ "description": "Manage users",
+ "path": "cli/users.md"
+ },
+ {
+ "title": "users activate",
+ "description": "Update a user's status to 'active'. Active users can fully interact with the platform",
+ "path": "cli/users_activate.md"
+ },
+ {
+ "title": "users create",
+ "path": "cli/users_create.md"
+ },
+ {
+ "title": "users delete",
+ "description": "Delete a user by username or user_id.",
+ "path": "cli/users_delete.md"
+ },
+ {
+ "title": "users list",
+ "path": "cli/users_list.md"
+ },
+ {
+ "title": "users show",
+ "description": "Show a single user. Use 'me' to indicate the currently authenticated user.",
+ "path": "cli/users_show.md"
+ },
+ {
+ "title": "users suspend",
+ "description": "Update a user's status to 'suspended'. A suspended user cannot log into the platform",
+ "path": "cli/users_suspend.md"
+ },
+ {
+ "title": "version",
+ "description": "Show coder version",
+ "path": "cli/version.md"
+ }
+ ]
+ },
+ {
+ "title": "Security",
+ "description": "Security advisories",
+ "path": "./security/index.md",
+ "icon_path": "./images/icons/security.svg",
+ "children": [
+ {
+ "title": "API tokens of deleted users not invalidated",
+ "description": "Fixed in v0.23.0 (Apr 25, 2023)",
+ "path": "./security/0001_user_apikeys_invalidation.md"
+ }
+ ]
+ },
+ {
+ "title": "FAQs",
+ "description": "Frequently asked questions",
+ "path": "./faqs.md",
+ "icon_path": "./images/icons/info.svg"
+ },
+ {
+ "title": "Guides",
+ "description": "Employee-authored tutorials",
+ "path": "./guides/index.md",
+ "icon_path": "./images/icons/notes.svg",
+ "children": [
+ {
+ "title": "Generate a Support Bundle",
+ "description": "Generate and upload a Support Bundle to Coder Support",
+ "path": "./guides/support-bundle.md"
+ },
+ {
+ "title": "Configuring Okta",
+ "description": "Custom claims/scopes with Okta for group/role sync",
+ "path": "./guides/configuring-okta.md"
+ },
+ {
+ "title": "Google to AWS Federation",
+ "description": "Federating a Google Cloud service account to AWS",
+ "path": "./guides/gcp-to-aws.md"
+ },
+ {
+ "title": "JFrog Artifactory Integration",
+ "description": "Integrate Coder with JFrog Artifactory",
+ "path": "./guides/artifactory-integration.md"
+ },
+ {
+ "title": "Island Secure Browser Integration",
+ "description": "Integrate Coder with Island's Secure Browser",
+ "path": "./guides/island-integration.md"
+ },
+ {
+ "title": "Template ImagePullSecrets",
+ "description": "Creating ImagePullSecrets for private registries",
+ "path": "./guides/image-pull-secret.md"
+ },
+ {
+ "title": "Postgres SSL",
+ "description": "Configure Coder to connect to Postgres over SSL",
+ "path": "./guides/postgres-ssl.md"
+ },
+ {
+ "title": "Azure Federation",
+ "description": "Federating Coder to Azure",
+ "path": "./guides/azure-federation.md"
+ },
+ {
+ "title": "Scanning Coder Workspaces with JFrog Xray",
+ "description": "Integrate Coder with JFrog Xray",
+ "path": "./guides/xray-integration.md"
+ }
+ ]
+ }
+ ]
+}
diff --git a/docs/platforms/aws.md b/docs/platforms/aws.md
index 83e0c6c2aa642..e69de29bb2d1d 100644
--- a/docs/platforms/aws.md
+++ b/docs/platforms/aws.md
@@ -1,89 +0,0 @@
-# Amazon Web Services
-
-This guide is designed to get you up and running with a Coder proof-of-concept
-VM on AWS EC2 using a [Coder-provided AMI](https://github.com/coder/packages).
-If you are familiar with EC2 however, you can use our
-[install script](../install/index.md#install-coder) to run Coder on any popular
-Linux distribution.
-
-## Requirements
-
-This guide assumes your AWS account has `AmazonEC2FullAccess` permissions.
-
-## Launch a Coder instance from the from AWS Marketplace
-
-We publish an Ubuntu 22.04 AMI with Coder and Docker pre-installed. Search for
-`Coder` in the EC2 "Launch an Instance" screen or
-[launch directly from the marketplace](https://aws.amazon.com/marketplace/pp/prodview-5gxjyur2vc7rg).
-
-
-
-Be sure to keep the default firewall (SecurityGroup) options checked so you can
-connect over HTTP, HTTPS, and SSH.
-
-
-
-We recommend keeping the default instance type (`t2.xlarge`, 4 cores and 16 GB
-memory) if you plan on provisioning Docker containers as workspaces on this EC2
-instance. Keep in mind this platforms is intended for proof-of-concept
-deployments and you should adjust your infrastructure when preparing for
-production use. See: [Scaling Coder](../admin/scaling/scale-testing.md)
-
-Be sure to add a keypair so that you can connect over SSH to further
-[configure Coder](../admin/configure.md).
-
-After launching the instance, wait 30 seconds and navigate to the public IPv4
-address. You should be redirected to a public tunnel URL.
-
-
-
-That's all! Use the UI to create your first user, template, and workspace. We
-recommend starting with a Docker template since the instance has Docker
-pre-installed.
-
-
-
-## Configuring Coder server
-
-Coder is primarily configured by server-side flags and environment variables.
-Given you created or added key-pairs when launching the instance, you can
-[configure your Coder deployment](../admin/configure.md) by logging in via SSH
-or using the console:
-
-```shell
-ssh ubuntu@string |
| Environment | $CODER_SESSION_TOKEN |
-Specify an authentication token. For security reasons setting
-CODER_SESSION_TOKEN is preferred.
+Specify an authentication token. For security reasons setting CODER_SESSION_TOKEN is preferred.
### --no-version-warning
@@ -120,8 +119,7 @@ Suppress warnings about unlicensed features.
| Type | string-array |
| Environment | $CODER_HEADER |
-Additional HTTP headers added to all requests. Provide as key=value. Can be
-specified multiple times.
+Additional HTTP headers added to all requests. Provide as key=value. Can be specified multiple times.
### --header-command
@@ -130,8 +128,7 @@ specified multiple times.
| Type | string |
| Environment | $CODER_HEADER_COMMAND |
-An external command that outputs additional HTTP headers added to all requests.
-The command must output each header as `key=value` on its own line.
+An external command that outputs additional HTTP headers added to all requests. The command must output each header as `key=value` on its own line.
### -v, --verbose
@@ -158,10 +155,7 @@ Disable direct (P2P) connections to workspaces.
| Type | bool |
| Environment | $CODER_DISABLE_NETWORK_TELEMETRY |
-Disable network telemetry. Network telemetry is collected when connecting to
-workspaces using the CLI, and is forwarded to the server. If telemetry is also
-enabled on the server, it may be sent to Coder. Network telemetry is used to
-measure network quality and detect regressions.
+Disable network telemetry. Network telemetry is collected when connecting to workspaces using the CLI, and is forwarded to the server. If telemetry is also enabled on the server, it may be sent to Coder. Network telemetry is used to measure network quality and detect regressions.
### --global-config
diff --git a/docs/cli/autoupdate.md b/docs/reference/cli/autoupdate.md
similarity index 100%
rename from docs/cli/autoupdate.md
rename to docs/reference/cli/autoupdate.md
diff --git a/docs/cli/config-ssh.md b/docs/reference/cli/config-ssh.md
similarity index 100%
rename from docs/cli/config-ssh.md
rename to docs/reference/cli/config-ssh.md
diff --git a/docs/cli/create.md b/docs/reference/cli/create.md
similarity index 100%
rename from docs/cli/create.md
rename to docs/reference/cli/create.md
diff --git a/docs/cli/delete.md b/docs/reference/cli/delete.md
similarity index 100%
rename from docs/cli/delete.md
rename to docs/reference/cli/delete.md
diff --git a/docs/cli/dotfiles.md b/docs/reference/cli/dotfiles.md
similarity index 100%
rename from docs/cli/dotfiles.md
rename to docs/reference/cli/dotfiles.md
diff --git a/docs/cli/external-auth.md b/docs/reference/cli/external-auth.md
similarity index 100%
rename from docs/cli/external-auth.md
rename to docs/reference/cli/external-auth.md
diff --git a/docs/cli/external-auth_access-token.md b/docs/reference/cli/external-auth_access-token.md
similarity index 100%
rename from docs/cli/external-auth_access-token.md
rename to docs/reference/cli/external-auth_access-token.md
diff --git a/docs/cli/favorite.md b/docs/reference/cli/favorite.md
similarity index 100%
rename from docs/cli/favorite.md
rename to docs/reference/cli/favorite.md
diff --git a/docs/cli/features.md b/docs/reference/cli/features.md
similarity index 100%
rename from docs/cli/features.md
rename to docs/reference/cli/features.md
diff --git a/docs/cli/features_list.md b/docs/reference/cli/features_list.md
similarity index 100%
rename from docs/cli/features_list.md
rename to docs/reference/cli/features_list.md
diff --git a/docs/cli/groups.md b/docs/reference/cli/groups.md
similarity index 100%
rename from docs/cli/groups.md
rename to docs/reference/cli/groups.md
diff --git a/docs/cli/groups_create.md b/docs/reference/cli/groups_create.md
similarity index 100%
rename from docs/cli/groups_create.md
rename to docs/reference/cli/groups_create.md
diff --git a/docs/cli/groups_delete.md b/docs/reference/cli/groups_delete.md
similarity index 100%
rename from docs/cli/groups_delete.md
rename to docs/reference/cli/groups_delete.md
diff --git a/docs/cli/groups_edit.md b/docs/reference/cli/groups_edit.md
similarity index 100%
rename from docs/cli/groups_edit.md
rename to docs/reference/cli/groups_edit.md
diff --git a/docs/cli/groups_list.md b/docs/reference/cli/groups_list.md
similarity index 100%
rename from docs/cli/groups_list.md
rename to docs/reference/cli/groups_list.md
diff --git a/docs/cli/licenses.md b/docs/reference/cli/licenses.md
similarity index 100%
rename from docs/cli/licenses.md
rename to docs/reference/cli/licenses.md
diff --git a/docs/cli/licenses_add.md b/docs/reference/cli/licenses_add.md
similarity index 100%
rename from docs/cli/licenses_add.md
rename to docs/reference/cli/licenses_add.md
diff --git a/docs/cli/licenses_delete.md b/docs/reference/cli/licenses_delete.md
similarity index 100%
rename from docs/cli/licenses_delete.md
rename to docs/reference/cli/licenses_delete.md
diff --git a/docs/cli/licenses_list.md b/docs/reference/cli/licenses_list.md
similarity index 100%
rename from docs/cli/licenses_list.md
rename to docs/reference/cli/licenses_list.md
diff --git a/docs/cli/list.md b/docs/reference/cli/list.md
similarity index 100%
rename from docs/cli/list.md
rename to docs/reference/cli/list.md
diff --git a/docs/cli/login.md b/docs/reference/cli/login.md
similarity index 100%
rename from docs/cli/login.md
rename to docs/reference/cli/login.md
diff --git a/docs/cli/logout.md b/docs/reference/cli/logout.md
similarity index 100%
rename from docs/cli/logout.md
rename to docs/reference/cli/logout.md
diff --git a/docs/cli/netcheck.md b/docs/reference/cli/netcheck.md
similarity index 100%
rename from docs/cli/netcheck.md
rename to docs/reference/cli/netcheck.md
diff --git a/docs/cli/notifications.md b/docs/reference/cli/notifications.md
similarity index 100%
rename from docs/cli/notifications.md
rename to docs/reference/cli/notifications.md
diff --git a/docs/cli/notifications_pause.md b/docs/reference/cli/notifications_pause.md
similarity index 100%
rename from docs/cli/notifications_pause.md
rename to docs/reference/cli/notifications_pause.md
diff --git a/docs/cli/notifications_resume.md b/docs/reference/cli/notifications_resume.md
similarity index 100%
rename from docs/cli/notifications_resume.md
rename to docs/reference/cli/notifications_resume.md
diff --git a/docs/cli/open.md b/docs/reference/cli/open.md
similarity index 100%
rename from docs/cli/open.md
rename to docs/reference/cli/open.md
diff --git a/docs/cli/open_vscode.md b/docs/reference/cli/open_vscode.md
similarity index 100%
rename from docs/cli/open_vscode.md
rename to docs/reference/cli/open_vscode.md
diff --git a/docs/cli/ping.md b/docs/reference/cli/ping.md
similarity index 100%
rename from docs/cli/ping.md
rename to docs/reference/cli/ping.md
diff --git a/docs/cli/port-forward.md b/docs/reference/cli/port-forward.md
similarity index 100%
rename from docs/cli/port-forward.md
rename to docs/reference/cli/port-forward.md
diff --git a/docs/cli/provisionerd.md b/docs/reference/cli/provisionerd.md
similarity index 100%
rename from docs/cli/provisionerd.md
rename to docs/reference/cli/provisionerd.md
diff --git a/docs/cli/provisionerd_start.md b/docs/reference/cli/provisionerd_start.md
similarity index 100%
rename from docs/cli/provisionerd_start.md
rename to docs/reference/cli/provisionerd_start.md
diff --git a/docs/cli/publickey.md b/docs/reference/cli/publickey.md
similarity index 100%
rename from docs/cli/publickey.md
rename to docs/reference/cli/publickey.md
diff --git a/docs/cli/rename.md b/docs/reference/cli/rename.md
similarity index 100%
rename from docs/cli/rename.md
rename to docs/reference/cli/rename.md
diff --git a/docs/cli/reset-password.md b/docs/reference/cli/reset-password.md
similarity index 100%
rename from docs/cli/reset-password.md
rename to docs/reference/cli/reset-password.md
diff --git a/docs/cli/restart.md b/docs/reference/cli/restart.md
similarity index 100%
rename from docs/cli/restart.md
rename to docs/reference/cli/restart.md
diff --git a/docs/cli/schedule.md b/docs/reference/cli/schedule.md
similarity index 100%
rename from docs/cli/schedule.md
rename to docs/reference/cli/schedule.md
diff --git a/docs/cli/schedule_override-stop.md b/docs/reference/cli/schedule_override-stop.md
similarity index 100%
rename from docs/cli/schedule_override-stop.md
rename to docs/reference/cli/schedule_override-stop.md
diff --git a/docs/cli/schedule_show.md b/docs/reference/cli/schedule_show.md
similarity index 100%
rename from docs/cli/schedule_show.md
rename to docs/reference/cli/schedule_show.md
diff --git a/docs/cli/schedule_start.md b/docs/reference/cli/schedule_start.md
similarity index 100%
rename from docs/cli/schedule_start.md
rename to docs/reference/cli/schedule_start.md
diff --git a/docs/cli/schedule_stop.md b/docs/reference/cli/schedule_stop.md
similarity index 100%
rename from docs/cli/schedule_stop.md
rename to docs/reference/cli/schedule_stop.md
diff --git a/docs/cli/server.md b/docs/reference/cli/server.md
similarity index 100%
rename from docs/cli/server.md
rename to docs/reference/cli/server.md
diff --git a/docs/cli/server_create-admin-user.md b/docs/reference/cli/server_create-admin-user.md
similarity index 100%
rename from docs/cli/server_create-admin-user.md
rename to docs/reference/cli/server_create-admin-user.md
diff --git a/docs/cli/server_dbcrypt.md b/docs/reference/cli/server_dbcrypt.md
similarity index 100%
rename from docs/cli/server_dbcrypt.md
rename to docs/reference/cli/server_dbcrypt.md
diff --git a/docs/cli/server_dbcrypt_decrypt.md b/docs/reference/cli/server_dbcrypt_decrypt.md
similarity index 100%
rename from docs/cli/server_dbcrypt_decrypt.md
rename to docs/reference/cli/server_dbcrypt_decrypt.md
diff --git a/docs/cli/server_dbcrypt_delete.md b/docs/reference/cli/server_dbcrypt_delete.md
similarity index 100%
rename from docs/cli/server_dbcrypt_delete.md
rename to docs/reference/cli/server_dbcrypt_delete.md
diff --git a/docs/cli/server_dbcrypt_rotate.md b/docs/reference/cli/server_dbcrypt_rotate.md
similarity index 100%
rename from docs/cli/server_dbcrypt_rotate.md
rename to docs/reference/cli/server_dbcrypt_rotate.md
diff --git a/docs/cli/server_postgres-builtin-serve.md b/docs/reference/cli/server_postgres-builtin-serve.md
similarity index 100%
rename from docs/cli/server_postgres-builtin-serve.md
rename to docs/reference/cli/server_postgres-builtin-serve.md
diff --git a/docs/cli/server_postgres-builtin-url.md b/docs/reference/cli/server_postgres-builtin-url.md
similarity index 100%
rename from docs/cli/server_postgres-builtin-url.md
rename to docs/reference/cli/server_postgres-builtin-url.md
diff --git a/docs/cli/show.md b/docs/reference/cli/show.md
similarity index 100%
rename from docs/cli/show.md
rename to docs/reference/cli/show.md
diff --git a/docs/cli/speedtest.md b/docs/reference/cli/speedtest.md
similarity index 100%
rename from docs/cli/speedtest.md
rename to docs/reference/cli/speedtest.md
diff --git a/docs/cli/ssh.md b/docs/reference/cli/ssh.md
similarity index 100%
rename from docs/cli/ssh.md
rename to docs/reference/cli/ssh.md
diff --git a/docs/cli/start.md b/docs/reference/cli/start.md
similarity index 100%
rename from docs/cli/start.md
rename to docs/reference/cli/start.md
diff --git a/docs/cli/stat.md b/docs/reference/cli/stat.md
similarity index 100%
rename from docs/cli/stat.md
rename to docs/reference/cli/stat.md
diff --git a/docs/cli/stat_cpu.md b/docs/reference/cli/stat_cpu.md
similarity index 100%
rename from docs/cli/stat_cpu.md
rename to docs/reference/cli/stat_cpu.md
diff --git a/docs/cli/stat_disk.md b/docs/reference/cli/stat_disk.md
similarity index 100%
rename from docs/cli/stat_disk.md
rename to docs/reference/cli/stat_disk.md
diff --git a/docs/cli/stat_mem.md b/docs/reference/cli/stat_mem.md
similarity index 100%
rename from docs/cli/stat_mem.md
rename to docs/reference/cli/stat_mem.md
diff --git a/docs/cli/state.md b/docs/reference/cli/state.md
similarity index 100%
rename from docs/cli/state.md
rename to docs/reference/cli/state.md
diff --git a/docs/cli/state_pull.md b/docs/reference/cli/state_pull.md
similarity index 100%
rename from docs/cli/state_pull.md
rename to docs/reference/cli/state_pull.md
diff --git a/docs/cli/state_push.md b/docs/reference/cli/state_push.md
similarity index 100%
rename from docs/cli/state_push.md
rename to docs/reference/cli/state_push.md
diff --git a/docs/cli/stop.md b/docs/reference/cli/stop.md
similarity index 100%
rename from docs/cli/stop.md
rename to docs/reference/cli/stop.md
diff --git a/docs/cli/support.md b/docs/reference/cli/support.md
similarity index 100%
rename from docs/cli/support.md
rename to docs/reference/cli/support.md
diff --git a/docs/cli/support_bundle.md b/docs/reference/cli/support_bundle.md
similarity index 100%
rename from docs/cli/support_bundle.md
rename to docs/reference/cli/support_bundle.md
diff --git a/docs/cli/templates.md b/docs/reference/cli/templates.md
similarity index 100%
rename from docs/cli/templates.md
rename to docs/reference/cli/templates.md
diff --git a/docs/cli/templates_archive.md b/docs/reference/cli/templates_archive.md
similarity index 100%
rename from docs/cli/templates_archive.md
rename to docs/reference/cli/templates_archive.md
diff --git a/docs/cli/templates_create.md b/docs/reference/cli/templates_create.md
similarity index 100%
rename from docs/cli/templates_create.md
rename to docs/reference/cli/templates_create.md
diff --git a/docs/cli/templates_delete.md b/docs/reference/cli/templates_delete.md
similarity index 100%
rename from docs/cli/templates_delete.md
rename to docs/reference/cli/templates_delete.md
diff --git a/docs/cli/templates_edit.md b/docs/reference/cli/templates_edit.md
similarity index 100%
rename from docs/cli/templates_edit.md
rename to docs/reference/cli/templates_edit.md
diff --git a/docs/cli/templates_init.md b/docs/reference/cli/templates_init.md
similarity index 100%
rename from docs/cli/templates_init.md
rename to docs/reference/cli/templates_init.md
diff --git a/docs/cli/templates_list.md b/docs/reference/cli/templates_list.md
similarity index 100%
rename from docs/cli/templates_list.md
rename to docs/reference/cli/templates_list.md
diff --git a/docs/cli/templates_pull.md b/docs/reference/cli/templates_pull.md
similarity index 100%
rename from docs/cli/templates_pull.md
rename to docs/reference/cli/templates_pull.md
diff --git a/docs/cli/templates_push.md b/docs/reference/cli/templates_push.md
similarity index 100%
rename from docs/cli/templates_push.md
rename to docs/reference/cli/templates_push.md
diff --git a/docs/cli/templates_versions.md b/docs/reference/cli/templates_versions.md
similarity index 100%
rename from docs/cli/templates_versions.md
rename to docs/reference/cli/templates_versions.md
diff --git a/docs/cli/templates_versions_archive.md b/docs/reference/cli/templates_versions_archive.md
similarity index 100%
rename from docs/cli/templates_versions_archive.md
rename to docs/reference/cli/templates_versions_archive.md
diff --git a/docs/cli/templates_versions_list.md b/docs/reference/cli/templates_versions_list.md
similarity index 100%
rename from docs/cli/templates_versions_list.md
rename to docs/reference/cli/templates_versions_list.md
diff --git a/docs/cli/templates_versions_unarchive.md b/docs/reference/cli/templates_versions_unarchive.md
similarity index 100%
rename from docs/cli/templates_versions_unarchive.md
rename to docs/reference/cli/templates_versions_unarchive.md
diff --git a/docs/cli/tokens.md b/docs/reference/cli/tokens.md
similarity index 100%
rename from docs/cli/tokens.md
rename to docs/reference/cli/tokens.md
diff --git a/docs/cli/tokens_create.md b/docs/reference/cli/tokens_create.md
similarity index 100%
rename from docs/cli/tokens_create.md
rename to docs/reference/cli/tokens_create.md
diff --git a/docs/cli/tokens_list.md b/docs/reference/cli/tokens_list.md
similarity index 100%
rename from docs/cli/tokens_list.md
rename to docs/reference/cli/tokens_list.md
diff --git a/docs/cli/tokens_remove.md b/docs/reference/cli/tokens_remove.md
similarity index 100%
rename from docs/cli/tokens_remove.md
rename to docs/reference/cli/tokens_remove.md
diff --git a/docs/cli/unfavorite.md b/docs/reference/cli/unfavorite.md
similarity index 100%
rename from docs/cli/unfavorite.md
rename to docs/reference/cli/unfavorite.md
diff --git a/docs/cli/update.md b/docs/reference/cli/update.md
similarity index 100%
rename from docs/cli/update.md
rename to docs/reference/cli/update.md
diff --git a/docs/cli/users.md b/docs/reference/cli/users.md
similarity index 100%
rename from docs/cli/users.md
rename to docs/reference/cli/users.md
diff --git a/docs/cli/users_activate.md b/docs/reference/cli/users_activate.md
similarity index 100%
rename from docs/cli/users_activate.md
rename to docs/reference/cli/users_activate.md
diff --git a/docs/cli/users_create.md b/docs/reference/cli/users_create.md
similarity index 100%
rename from docs/cli/users_create.md
rename to docs/reference/cli/users_create.md
diff --git a/docs/cli/users_delete.md b/docs/reference/cli/users_delete.md
similarity index 100%
rename from docs/cli/users_delete.md
rename to docs/reference/cli/users_delete.md
diff --git a/docs/cli/users_list.md b/docs/reference/cli/users_list.md
similarity index 100%
rename from docs/cli/users_list.md
rename to docs/reference/cli/users_list.md
diff --git a/docs/cli/users_show.md b/docs/reference/cli/users_show.md
similarity index 100%
rename from docs/cli/users_show.md
rename to docs/reference/cli/users_show.md
diff --git a/docs/cli/users_suspend.md b/docs/reference/cli/users_suspend.md
similarity index 100%
rename from docs/cli/users_suspend.md
rename to docs/reference/cli/users_suspend.md
diff --git a/docs/cli/version.md b/docs/reference/cli/version.md
similarity index 100%
rename from docs/cli/version.md
rename to docs/reference/cli/version.md
diff --git a/docs/cli/whoami.md b/docs/reference/cli/whoami.md
similarity index 100%
rename from docs/cli/whoami.md
rename to docs/reference/cli/whoami.md
diff --git a/docs/start/README.md b/docs/start/README.md
new file mode 100644
index 0000000000000..a833100756b92
--- /dev/null
+++ b/docs/start/README.md
@@ -0,0 +1,108 @@
+# About Coder
+
+Coder is an open-source platform for creating and managing developer workspaces
+on your preferred clouds and servers.
+
+
+ 
+
++ +## How it works + +Coder workspaces are represented with Terraform, but no Terraform knowledge is +required to get started. We have a database of pre-made templates built into the +product. + ++ If you are a Coder v1 customer, view the docs or the sunset plans. +
+
+ 
+
+ 
+
+
+## Linux/macOS
+
+Our install script is the fastest way to install Coder on Linux/macOS:
+
+```sh
+curl -L https://coder.com/install.sh | sh
+```
+
+## Windows
+
+> **Important:** If you plan to use the built-in PostgreSQL database, you will
+> need to ensure that the
+> [Visual C++ Runtime](https://learn.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist#latest-microsoft-visual-c-redistributable-version)
+> is installed.
+
+You can use the
+[`winget`](https://learn.microsoft.com/en-us/windows/package-manager/winget/#use-winget)
+package manager to install Coder:
+
+```powershell
+winget install Coder.Coder
+```
+
+
+
+## 3. Start the server
+
+To start or restart the Coder deployment, use the following command:
+
+```shell
+coder server
+```
+
+The output will provide you with a URL to access your deployment, where you'll
+create your first administrator account.
+
+
+
+Once you've signed in, you'll be brought to an empty workspaces page, which
+we'll soon populate with your first development environments.
+
+### More information on the Coder Server
+
+# Create 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
+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.
+
+## 1. Choose a starter template
+
+Select **Templates** to see the **Starter Templates**. Use the **Docker
+Containers** template by pressing **Use Template**.
+
+
+
+> You can also a find a comprehensive list of starter templates in **Templates**
+> -> **Create Template** -> **Starter Templates**.
+
+## 2. Create your template
+
+In **Create template**, fill in **Name** and **Display name**, then select
+**Create template**.
+
+
+
+TODO:
+
+- add CLI guide for making a new template
+- refactor text below to be more beginner-friendly
+
+# Create a workspace
+
+## 1. Create a workspace from your template
+
+When the template is ready, select **Create Workspace**.
+
+
+
+In **New workspace**, fill in **Name** then scroll down to select **Create
+Workspace**.
+
+
+
+Coder starts your new workspace from your template.
+
+After a few seconds, your workspace is ready to use.
+
+
+
+## 4. Try out your new workspace
+
+This starter 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
+ local computer.
+- code-server: Opens [browser-based VS Code](../ides/web-ides.md) with your
+ workspace.
+- Terminal: Opens a browser-based terminal with a shell in the workspace's
+ Docker instance.
+- SSH: Use SSH to log in to the workspace from your local machine. If you
+ haven't already, you'll have to install Coder on your local machine to
+ configure your SSH client.
+
+> **Tip**: You can edit the template to let developers connect to a workspace in
+> [a few more ways](../ides.md).
+
+When you're done, you can stop the workspace.
+
+## 6. Modify your template
+
+Now you can modify your template to suit your team's needs.
+
+Let's replace the `golang` package in the Docker image with the `python3`
+package. You can do this by editing the template's `Dockerfile` directly in your
+web browser.
+
+In the Coder dashboard, select **Templates** then your first template.
+
+
+
+In the drop-down menu, select **Edit files**.
+
+
+
+Expand the **build** directory and select **Dockerfile**.
+
+
+
+Edit `build/Dockerfile` to replace `golang` with `python3`.
+
+
+
+Select **Build template** and wait for Coder to prepare the template for
+workspaces.
+
+
+
+Select **Publish version**. In the **Publish new version** dialog, make sure
+**Promote to default version** is checked then select **Publish**.
+
+
+
+Now when developers create a new workspace from this template, they can use
+Python 3 instead of Go.
+
+For developers with workspaces that were created with a previous version of your
+template, Coder will notify them that there's a new version of the template.
+
+You can also handle [change management](./change-management.md) through your own
+repo and continuous integration.
diff --git a/docs/templates/tutorial.md b/docs/start/first-template.md
similarity index 77%
rename from docs/templates/tutorial.md
rename to docs/start/first-template.md
index 7063b7b288e7d..ca062aa18052c 100644
--- a/docs/templates/tutorial.md
+++ b/docs/start/first-template.md
@@ -12,48 +12,47 @@ template.
## Before you start
-You'll need a computer or cloud computing instance with both
+Use the [previous section](./local-deploy.md) of this guide to set up
[Docker](https://docs.docker.com/get-docker/) and [Coder](../install/index.md)
-installed on it.
-
-> When setting up your computer or computing instance, make sure to install
-> Docker first, then Coder.
+on your local machine to continue.
## 1. Log in to Coder
-In your web browser, go to your Coder dashboard to log in.
+In your web browser, go to your Coder dashboard using the URL provided during
+setup to log in.
## 2. Choose a starter template
-Select **Templates** > **Starter Templates**.
-
-
+Select **Templates** to see the **Starter Templates**. Use the **Docker
+Containers** template by pressing **Use Template**.
-In **Filter**, select **Docker** then select **Develop in Docker**.
+
-
+> You can also a find a comprehensive list of starter templates in **Templates**
+> -> **Create Template** -> **Starter Templates**. s
-Select **Use template**.
+## 3. Create your template
-
+In **Create template**, fill in **Name** and **Display name**, then select
+**Create template**.
-## 3. Create your template
+
-In **Create template**, fill in **Name** and **Display name**,then scroll down
-and select **Create template**.
+TODO:
-
+- add CLI guide for making a new template
+- refactor text below to be more beginner-friendly
-## 4. Create a workspace from your template
+
## 6. Modify your template
diff --git a/docs/start/first-workspace.md b/docs/start/first-workspace.md
new file mode 100644
index 0000000000000..09ef7aa73168f
--- /dev/null
+++ b/docs/start/first-workspace.md
@@ -0,0 +1,67 @@
+# Creating your first coder workspace
+
+A workspace is the environment that a developer works in. Developers in a team
+each work from their own workspace and can use [multiple IDEs](../ides.md).
+
+A developer creates a workspace from a
+[shared template](../tutorials/templates/README.md). This lets an entire team
+work in environments that are identically configured and provisioned with the
+same resources.
+
+## Before you begin
+
+This guide will use the Docker template from the
+[previous step](./first-template.md) to create and connect to a Coder workspace.
+
+## 1. Create a workspace from your template through the GUI
+
+You can create a workspace in the UI. Log in to your Coder instance, go to the
+**Templates** tab, find the template you need, and select **Create Workspace**.
+
+
+
+In **New workspace**, fill in **Name** then scroll down to select **Create
+Workspace**.
+
+
+
+Coder starts your new workspace from your template.
+
+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:
+
+- VS Code Desktop: Loads your workspace into
+ [VS Code Desktop](https://code.visualstudio.com/Download) installed on your
+ local computer.
+- code-server: Opens [browser-based VS Code](../ides/web-ides.md) with your
+ workspace.
+- Terminal: Opens a browser-based terminal with a shell in the workspace's
+ Docker instance.
+- SSH: Use SSH to log in to the workspace from your local machine. If you
+ haven't already, you'll have to install Coder on your local machine to
+ configure your SSH client.
+
+> **Tip**: You can edit the template to let developers connect to a workspace in
+> [a few more ways](../ides.md).
+
+## 3. Modify your workspace settings
+
+Developers can modify attributes of their workspace including update policy,
+scheduling, and parameters which define their development environment.
+
+Once you're finished, you can stop your workspace.
+
+
+
+## Read more on using workspaces
+
+- Creating workspaces with the CLI
+- Creating worksapces with the API
+-
+
+## Next Steps
diff --git a/docs/start/local-deploy.md b/docs/start/local-deploy.md
new file mode 100644
index 0000000000000..b373eb8c06a49
--- /dev/null
+++ b/docs/start/local-deploy.md
@@ -0,0 +1,66 @@
+## Setting up a Coder deployment
+
+For day-zero Coder users, we recommend following this guide to set up a local
+Coder deployment from our
+[open source repository](https://github.com/coder/coder).
+
+We'll use [Docker](https://docs.docker.com/engine) to manage the compute for a
+slim deployment to experiment with [workspaces](../user-guides/README.md) and
+[templates](../admin/templates/README.md).
+
+Docker is not necessary for every Coder deployment and is only used here for
+simplicity.
+
+### Install Coder daemon
+
+First, install [Docker](https://docs.docker.com/engine/install/) locally.
+
+> If you already have the Coder binary installed, restart it after installing
+> Docker.
+
+
+
+## Linux/macOS
+
+Our install script is the fastest way to install Coder on Linux/macOS:
+
+```sh
+curl -L https://coder.com/install.sh | sh
+```
+
+## Windows
+
+> **Important:** If you plan to use the built-in PostgreSQL database, you will
+> need to ensure that the
+> [Visual C++ Runtime](https://learn.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist#latest-microsoft-visual-c-redistributable-version)
+> is installed.
+
+You can use the
+[`winget`](https://learn.microsoft.com/en-us/windows/package-manager/winget/#use-winget)
+package manager to install Coder:
+
+```powershell
+winget install Coder.Coder
+```
+
+
+
+### Start the server
+
+To start or restart the Coder deployment, use the following command:
+
+```shell
+coder server
+```
+
+The output will provide you with an access URL to create your first
+administrator account.
+
+
+
+Once you've signed in, you'll be brought to an empty workspaces page, which
+we'll soon populate with your first development environments.
+
+### Next steps
+
+TODO: Add link to next page.
diff --git a/docs/about/screenshots.md b/docs/start/screenshots.md
similarity index 100%
rename from docs/about/screenshots.md
rename to docs/start/screenshots.md
diff --git a/docs/start/why-coder.md b/docs/start/why-coder.md
new file mode 100644
index 0000000000000..94dd8e58b6216
--- /dev/null
+++ b/docs/start/why-coder.md
@@ -0,0 +1,3 @@
+# Why use Coder
+
+TODO: Make this page!
diff --git a/docs/templates/README.md b/docs/templates/README.md
deleted file mode 100644
index 253f58848f00b..0000000000000
--- a/docs/templates/README.md
+++ /dev/null
@@ -1,422 +0,0 @@
-# Templates
-
-Templates are written in [Terraform](https://www.terraform.io/) and describe the
-infrastructure for workspaces (e.g., docker_container, aws_instance,
-kubernetes_pod).
-
-In most cases, a small group of users (team leads or Coder administrators) [have permissions](../admin/users.md#roles) to create and manage templates. Then, other
-users provision their [workspaces](../workspaces.md) from templates using the UI
-or CLI.
-
-## Get the CLI
-
-The CLI and the server are the same binary. We did this to encourage virality so
-individuals can start their own Coder deployments.
-
-From your local machine, download the CLI for your operating system from the
-[releases](https://github.com/coder/coder/releases/latest) or run:
-
-```shell
-curl -fsSL https://coder.com/install.sh | sh
-```
-
-To see the sub-commands for managing templates, run:
-
-```shell
-coder templates --help
-```
-
-## Login to your Coder Deployment
-
-Before you can create templates, you must first login to your Coder deployment
-with the CLI.
-
-```shell
-coder login https://coder.example.com # aka the URL to your coder instance
-```
-
-This will open a browser and ask you to authenticate to your Coder deployment,
-returning an API Key.
-
-> Make a note of the API Key. You can re-use the API Key in future CLI logins or
-> sessions.
-
-```shell
-coder --token -- -The Coder server's -[provisioner](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/provisioner) -process needs to authenticate with other provider APIs to provision workspaces. -There are two approaches to do this: - -- Pass credentials to the provisioner as parameters. -- Preferred: Execute the Coder server in an environment that is authenticated - with the provider. - -We encourage the latter approach where supported: - -- Simplifies the template. -- Keeps provider credentials out of Coder's database, making it a less valuable - target for attackers. -- Compatible with agent-based authentication schemes, which handle credential - rotation or ensure the credentials are not written to disk. - -Generally, you can set up an environment to provide credentials to Coder in -these ways: - -- A well-known location on disk. For example, `~/.aws/credentials` for AWS on - POSIX systems. -- Environment variables. - -It is usually sufficient to authenticate using the CLI or SDK for the provider -before running Coder, but check the Terraform provider's documentation for -details. - -These platforms have Terraform providers that support authenticated -environments: - -- [Google Cloud](https://registry.terraform.io/providers/hashicorp/google/latest/docs) -- [Amazon Web Services](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) -- [Microsoft Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs) -- [Kubernetes](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs) - -Other providers might also support authenticated environments. Check the -[documentation of the Terraform provider](https://registry.terraform.io/browse/providers) -for details. diff --git a/docs/templates/best-practices.md b/docs/templates/best-practices.md deleted file mode 100644 index 71aed19447d39..0000000000000 --- a/docs/templates/best-practices.md +++ /dev/null @@ -1,7 +0,0 @@ -# Template best practices - -We recommend a few ways to manage workspace resources, authentication, and -versioning. - -- Do not store secrets in templates. Assume every user has cleartext access - to every template. -
-
+
+ M Atif Ali
+ 
+
+
+January 24, 2024
+
+---
+
+Use Coder and JFrog Artifactory together to secure your development environments
+without disturbing your developers' existing workflows.
+
+This guide will demonstrate how to use JFrog Artifactory as a package registry
+within a workspace.
+
+## Requirements
+
+- A JFrog Artifactory instance
+- 1:1 mapping of users in Coder to users in Artifactory by email address or
+ username
+- Repositories configured in Artifactory for each package manager you want to
+ use
+
+## Provisioner Authentication
+
+The most straight-forward way to authenticate your template with Artifactory is
+by using our official Coder [modules](https://registry.coder.com). We publish
+two type of modules that automate the JFrog Artifactory and Coder integration.
+
+1. [JFrog-OAuth](https://registry.coder.com/modules/jfrog-oauth)
+2. [JFrog-Token](https://registry.coder.com/modules/jfrog-token)
+
+### JFrog-OAuth
+
+This module is usable by JFrog self-hosted (on-premises) Artifactory as it
+requires configuring a custom integration. This integration benefits from
+Coder's [external-auth](https://coder.com/docs/admin/external-auth) feature and
+allows each user to authenticate with Artifactory using an OAuth flow and issues
+user-scoped tokens to each user.
+
+To set this up, follow these steps:
+
+1. Modify your Helm chart `values.yaml` for JFrog Artifactory to add,
+
+```yaml
+artifactory:
+ enabled: true
+ frontend:
+ extraEnvironmentVariables:
+ - name: JF_FRONTEND_FEATURETOGGLER_ACCESSINTEGRATION
+ value: "true"
+ access:
+ accessConfig:
+ integrations-enabled: true
+ integration-templates:
+ - id: "1"
+ name: "CODER"
+ redirect-uri: "https://CODER_URL/external-auth/jfrog/callback"
+ scope: "applied-permissions/user"
+```
+
+> Note Replace `CODER_URL` with your Coder deployment URL, e.g.,
+>
+
++The admin-level access token is used to provision user tokens and is never exposed to +developers or stored in workspaces. ++ +If you do not want to use the official modules, you can check example template +that uses Docker as the underlying compute +[here](https://github.com/coder/coder/tree/main/examples/jfrog/docker). The same +concepts apply to all compute types. + +## Offline Deployments + +See the [offline deployments](../templates/modules.md#offline-installations) +section for instructions on how to use coder-modules in an offline environment +with Artifactory. + +## More reading + +- See the full example template + [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 + [Artifactory modules](../templates/modules.md#artifactory) docs. diff --git a/docs/guides/azure-federation.md b/docs/tutorials/azure-federation.md similarity index 100% rename from docs/guides/azure-federation.md rename to docs/tutorials/azure-federation.md diff --git a/docs/guides/configuring-okta.md b/docs/tutorials/configuring-okta.md similarity index 100% rename from docs/guides/configuring-okta.md rename to docs/tutorials/configuring-okta.md diff --git a/docs/guides/example-guide.md b/docs/tutorials/example-guide.md similarity index 100% rename from docs/guides/example-guide.md rename to docs/tutorials/example-guide.md diff --git a/docs/tutorials/faqs.md b/docs/tutorials/faqs.md new file mode 100644 index 0000000000000..f4df0dbe65611 --- /dev/null +++ b/docs/tutorials/faqs.md @@ -0,0 +1,541 @@ +# FAQs + +Frequently asked questions on Coder OSS and Enterprise deployments. These FAQs +come from our community and enterprise customers, feel free to +[contribute to this page](https://github.com/coder/coder/edit/main/docs/faqs.md). + +For other community resources, see our +[Github discussions](https://github.com/coder/coder/discussions), or join our +[Discord server](https://discord.gg/coder). + +### How do I add an enterprise license? + +Visit https://coder.com/trial or contact +[sales@coder.com](mailto:sales@coder.com?subject=License) to get a v2 enterprise +trial key. + +You can add a license through the UI or CLI. + +In the UI, click the Deployment tab -> Licenses and upload the `jwt` license +file. + +> To add the license with the CLI, first +> [install the Coder CLI](./install/index.md#install-script) and server to the +> latest release. + +If the license is a text string: + +```sh +coder licenses add -l 1f5...765 +``` + +If the license is in a file: + +```sh +coder licenses add -f
+ 
-