From ba40049c4087d370fb08a0cccb3a9cd0105f3c67 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Tue, 27 May 2025 13:06:58 +0200
Subject: [PATCH 01/32] Quickstart

---
 docs/contributing/backend.md | 58 ++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 docs/contributing/backend.md

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
new file mode 100644
index 0000000000000..9b96e0748cacf
--- /dev/null
+++ b/docs/contributing/backend.md
@@ -0,0 +1,58 @@
+# Backend
+
+This guide is designed to support both Coder engineers and community contributors in understanding our backend systems and getting started with development.
+
+Coder’s backend powers the core infrastructure behind workspace provisioning, access control, and the overall developer experience. As the backbone of our platform, it plays a critical role in enabling reliable and scalable remote development environments.
+
+The purpose of this guide is to help you:
+
+* Understand how the various backend components fit together.
+
+* Navigate the codebase with confidence and adhere to established best practices.
+
+* Contribute meaningful changes - whether you're fixing bugs, implementing features, or reviewing code.
+
+By aligning on tools, workflows, and conventions, we reduce cognitive overhead, improve collaboration across teams, and accelerate our ability to deliver high-quality software.
+
+Need help or have questions? Join the conversation on our [Discord server](https://discord.com/invite/coder) — we’re always happy to support contributors.
+
+## Quickstart
+
+To get up and running with Coder's backend, make sure you have **Docker installed and running** on your system. Once that's in place, follow these steps:
+
+1. Clone the Coder repository and navigate into the project directory:
+
+```sh
+git clone https://github.com/coder/coder.git
+cd coder
+```
+
+2. Run the development script to spin up the local environment:
+
+```sh
+./scripts/develop.sh
+```
+
+This will start two processes:
+* http://localhost:3000 — the backend API server, used primarily for backend development.
+* http://localhost:8080 — the Node.js frontend dev server, useful if you're also touching frontend code.
+
+3. Verify Your Session
+
+Confirm that you're logged in by running:
+
+```sh
+./scripts/coder-dev.sh list
+```
+
+This should return an empty list of workspaces. If you encounter an error, review the output from the [develop.sh](https://github.com/coder/coder/blob/main/scripts/develop.sh) script for issues.
+
+4. Create a Quick Workspace
+
+A template named docker-amd64 (or docker-arm64 on ARM systems) is created automatically. To spin up a workspace quickly, use:
+
+```sh
+./scripts/coder-dev.sh create my-workspace -t docker-amd64
+```
+
+## Platform Architecture

From 2369345d97349e78a0564274bb8b2dfb8bd03554 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Tue, 27 May 2025 13:22:32 +0200
Subject: [PATCH 02/32] Platform Architecture

---
 docs/contributing/backend.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index 9b96e0748cacf..4732f8d870d4d 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -56,3 +56,12 @@ A template named docker-amd64 (or docker-arm64 on ARM systems) is created automa
 ```
 
 ## Platform Architecture
+
+To understand how the backend fits into the broader system, we recommend reviewing the following resources:
+* [General Concepts](../admin/infrastructure/validated-architectures.md#general-concepts): Essential concepts and language used to describe how Coder is structured and operated.
+
+* [Architecture](../admin/infrastructure/architecture.md): A high-level overview of the infrastructure layout, key services, and how components interact.
+
+These sections provide the necessary context for navigating and contributing to the backend effectively.
+
+## Tech Stack

From f3bca2a3b212458aed50998fac88d1e8ec71d40e Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Tue, 27 May 2025 13:53:50 +0200
Subject: [PATCH 03/32] Coder libraries

---
 docs/contributing/backend.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index 4732f8d870d4d..541299db12b93 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -65,3 +65,24 @@ To understand how the backend fits into the broader system, we recommend reviewi
 These sections provide the necessary context for navigating and contributing to the backend effectively.
 
 ## Tech Stack
+
+Coder's backend is built using a collection of robust, modern Go libraries and internal packages. Familiarity with these technologies will help you navigate the codebase and contribute effectively.
+
+### Core Libraries & Frameworks
+
+* [go-chi/chi](https://github.com/go-chi/chi): lightweight HTTP router for building RESTful APIs in Go
+* [golang-migrate/migrate](https://github.com/golang-migrate/migrate): manages database schema migrations across environments
+* [coder/terraform-config-inspect](https://github.com/coder/terraform-config-inspect) *(forked)*: used for parsing and analyzing Terraform configurations, forked to include [PR #74](https://github.com/hashicorp/terraform-config-inspect/pull/74)
+* [coder/pq](https://github.com/coder/pq) *(forked)*: PostgreSQL driver forked to support rotating authentication tokens via `driver.Connector`
+* [coder/tailscale](https://github.com/coder/tailscale) *(forked)*: enables secure, peer-to-peer connectivity, forked to apply internal patches pending upstreaming
+* [coder/wireguard-go](https://github.com/coder/wireguard-go) *(forked)*: WireGuard networking implementation, forked to fix a data race and adopt the latest gVisor changes
+* [coder/ssh](https://github.com/coder/ssh) *(forked)*: customized SSH server based on `gliderlabs/ssh`, forked to include Tailscale-specific patches and avoid complex subpath dependencies
+* [coder/bubbletea](https://github.com/coder/bubbletea) *(forked)*: terminal UI framework for CLI apps, forked to remove an `init()` function that interfered with web terminal output
+
+### Coder libraries
+
+* [coder/terraform-provider-coder](https://github.com/coder/terraform-provider-coder): official Terraform provider for managing Coder resources via infrastructure-as-code
+* [coder/websocket](https://github.com/coder/websocket): lightweight wrapper for real-time client-server communication
+* [coder/serpent](https://github.com/coder/serpent): manages background job orchestration, including workspace builds and audit logging
+* [coder/guts](https://github.com/coder/guts): shared internal utilities and logic
+* [coder/wgtunnel](https://github.com/coder/wgtunnel): custom tunneling layer for secure peer-to-peer workspace networking

From 2eb56dd5bd644c121c741d09b6708b9edc7d1a57 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Tue, 27 May 2025 13:58:25 +0200
Subject: [PATCH 04/32] fix libs

---
 docs/contributing/backend.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index 541299db12b93..d7ba300611c04 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -82,7 +82,7 @@ Coder's backend is built using a collection of robust, modern Go libraries and i
 ### Coder libraries
 
 * [coder/terraform-provider-coder](https://github.com/coder/terraform-provider-coder): official Terraform provider for managing Coder resources via infrastructure-as-code
-* [coder/websocket](https://github.com/coder/websocket): lightweight wrapper for real-time client-server communication
-* [coder/serpent](https://github.com/coder/serpent): manages background job orchestration, including workspace builds and audit logging
-* [coder/guts](https://github.com/coder/guts): shared internal utilities and logic
-* [coder/wgtunnel](https://github.com/coder/wgtunnel): custom tunneling layer for secure peer-to-peer workspace networking
+* [coder/websocket](https://github.com/coder/websocket): minimal WebSocket library for real-time communication
+* [coder/serpent](https://github.com/coder/serpent): CLI framework built on `cobra`, used for large, complex CLIs
+* [coder/guts](https://github.com/coder/guts): generates TypeScript types from Go for shared type definitions
+* [coder/wgtunnel](https://github.com/coder/wgtunnel): WireGuard tunnel server for secure backend networking

From 5d27d516f7d3a33acb1d95c1372f1bfe5008b47d Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Wed, 28 May 2025 11:14:13 +0200
Subject: [PATCH 05/32] Repository Structure WIP

---
 docs/contributing/backend.md | 30 ++++++++++++++++++++++++++++--
 1 file changed, 28 insertions(+), 2 deletions(-)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index d7ba300611c04..f00cdc3bd473c 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -7,9 +7,7 @@ Coder’s backend powers the core infrastructure behind workspace provisioning,
 The purpose of this guide is to help you:
 
 * Understand how the various backend components fit together.
-
 * Navigate the codebase with confidence and adhere to established best practices.
-
 * Contribute meaningful changes - whether you're fixing bugs, implementing features, or reviewing code.
 
 By aligning on tools, workflows, and conventions, we reduce cognitive overhead, improve collaboration across teams, and accelerate our ability to deliver high-quality software.
@@ -86,3 +84,31 @@ Coder's backend is built using a collection of robust, modern Go libraries and i
 * [coder/serpent](https://github.com/coder/serpent): CLI framework built on `cobra`, used for large, complex CLIs
 * [coder/guts](https://github.com/coder/guts): generates TypeScript types from Go for shared type definitions
 * [coder/wgtunnel](https://github.com/coder/wgtunnel): WireGuard tunnel server for secure backend networking
+
+## Repository Structure
+
+The Coder backend is organized into multiple packages and directories, each with a specific purpose. Here's a high-level overview of the most important ones:
+
+* [agent](https://github.com/coder/coder/tree/main/agent): core logic of a workspace agent, supports DevContainers, remote SSH, startup/shutdown script execution. Protobuf definitions for DRPC communication with `coderd` are kept in [proto](https://github.com/coder/coder/tree/main/agent/proto).
+* [cli](https://github.com/coder/coder/tree/main/cli): CLI interface for `coder` command built on [coder/serpent](https://github.com/coder/serpent). Input controls are defined in [cliui](https://github.com/coder/coder/tree/docs-backend-contrib-guide/cli/cliui), and [testdata](https://github.com/coder/coder/tree/docs-backend-contrib-guide/cli/testdata) contains golden files for common CLI calls
+* [cmd](https://github.com/coder/coder/tree/main/cmd): entry points for CLI and services, including `coderd`
+* [coderd](https://github.com/coder/coder/tree/main/coderd): the main API server implementation
+  * [audit](https://github.com/coder/coder/tree/main/coderd/audit): audit log logic, defines target resources, actions and extra fields
+  * [autobuild](https://github.com/coder/coder/tree/main/coderd/autobuild): core logic of the workspace autobuild executor, periodically evaluates workspaces for next transition actions
+  * `httpmw`: shared HTTP middleware
+  * `prebuilds`: prebuilt workspace logic
+  * `provisionerdserver`: interface to provisioner processes
+  * `rbac`: role-based access control
+  * `telemetry`: metrics and observability
+  * `tracing`: distributed tracing support
+  * `workspaceapps`: app lifecycle in workspaces
+  * `wsbuilder`: workspace build system
+* `database`: schema migrations and query logic
+* `dogfood`: internal testing and validation tools
+* `enterprise`: enterprise-only features and extensions
+* `nix`: Nix utility scripts and definitions
+* `provisioner`, `provisionerd`, `provisionersdk`: components for infrastructure provisioning
+* `pty`: terminal emulation for remote shells
+* `support`: shared internal helpers
+* `tailnet`: network stack and identity management
+* `vpn`: VPN and tunneling components

From 1b2eeaad8fe8490119151a3b9feba584a1c533c1 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Wed, 28 May 2025 14:05:07 +0200
Subject: [PATCH 06/32] Repository Structure WIP

---
 docs/contributing/backend.md | 39 ++++++++++++++++++++++++++----------
 1 file changed, 28 insertions(+), 11 deletions(-)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index f00cdc3bd473c..1210a0c750f84 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -56,7 +56,7 @@ A template named docker-amd64 (or docker-arm64 on ARM systems) is created automa
 ## Platform Architecture
 
 To understand how the backend fits into the broader system, we recommend reviewing the following resources:
-* [General Concepts](../admin/infrastructure/validated-architectures.md#general-concepts): Essential concepts and language used to describe how Coder is structured and operated.
+* [General Concepts](../admin/infrastructure/validated-architectures/index.md#general-concepts): Essential concepts and language used to describe how Coder is structured and operated.
 
 * [Architecture](../admin/infrastructure/architecture.md): A high-level overview of the infrastructure layout, key services, and how components interact.
 
@@ -92,20 +92,37 @@ The Coder backend is organized into multiple packages and directories, each with
 * [agent](https://github.com/coder/coder/tree/main/agent): core logic of a workspace agent, supports DevContainers, remote SSH, startup/shutdown script execution. Protobuf definitions for DRPC communication with `coderd` are kept in [proto](https://github.com/coder/coder/tree/main/agent/proto).
 * [cli](https://github.com/coder/coder/tree/main/cli): CLI interface for `coder` command built on [coder/serpent](https://github.com/coder/serpent). Input controls are defined in [cliui](https://github.com/coder/coder/tree/docs-backend-contrib-guide/cli/cliui), and [testdata](https://github.com/coder/coder/tree/docs-backend-contrib-guide/cli/testdata) contains golden files for common CLI calls
 * [cmd](https://github.com/coder/coder/tree/main/cmd): entry points for CLI and services, including `coderd`
-* [coderd](https://github.com/coder/coder/tree/main/coderd): the main API server implementation
+* [coderd](https://github.com/coder/coder/tree/main/coderd): the main API server implementation with [chi](https://github.com/go-chi/chi) endpoints
   * [audit](https://github.com/coder/coder/tree/main/coderd/audit): audit log logic, defines target resources, actions and extra fields
   * [autobuild](https://github.com/coder/coder/tree/main/coderd/autobuild): core logic of the workspace autobuild executor, periodically evaluates workspaces for next transition actions
-  * `httpmw`: shared HTTP middleware
-  * `prebuilds`: prebuilt workspace logic
-  * `provisionerdserver`: interface to provisioner processes
-  * `rbac`: role-based access control
-  * `telemetry`: metrics and observability
-  * `tracing`: distributed tracing support
-  * `workspaceapps`: app lifecycle in workspaces
-  * `wsbuilder`: workspace build system
-* `database`: schema migrations and query logic
+  * [httpmw](https://github.com/coder/coder/tree/main/coderd/httpmw): HTTP middlewares mainly used to extract parameters from HTTP requests (e.g. current user, template, workspace, OAuth2 account, etc.) and storing them in the request context
+  * [prebuilds](https://github.com/coder/coder/tree/main/coderd/prebuilds): common interfaces for prebuild workspaces, feature implementation is in [enterprise/prebuilds](https://github.com/coder/coder/tree/main/enterprise/coderd/prebuilds)
+  * [provisionerdserver](https://github.com/coder/coder/tree/main/coderd/provisionerdserver): DRPC server for [provisionerd](https://github.com/coder/coder/tree/main/provisionerd) instances, used to validate and extract Terraform data and resources, and store them in the database.
+  * [rbac](https://github.com/coder/coder/tree/main/coderd/rbac): RBAC engine for `coderd`, including authz layer, role definitions and custom roles. Built on top of [Open Policy Agent](https://github.com/open-policy-agent/opa) and Rego policies.
+  * [telemetry](https://github.com/coder/coder/tree/main/coderd/telemetry): records a snapshot with various workspace data for telemetry purposes. Once recorded the reporter sends it to the configured telemetry endpoint.
+  * [tracing](https://github.com/coder/coder/tree/main/coderd/tracing): extends telemetry with tracing data consistent with [OpenTelemetry specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md)
+  * [workspaceapps](https://github.com/coder/coder/tree/main/coderd/workspaceapps): core logic of a secure proxy to expose workspace apps deployed in a workspace
+  * [wsbuilder](https://github.com/coder/coder/tree/main/coderd/wsbuilder): wrapper for business logic of creating a workspace build. It encapsulates all database operations required to insert a build record in a transaction.
+* [database](https://github.com/coder/coder/tree/main/coderd/database): schema migrations, query logic, in-memory database, etc.
+  * [db2sdk](https://github.com/coder/coder/tree/main/coderd/database/db2sdk)
+  * [dbauthz](https://github.com/coder/coder/tree/main/coderd/database/dbauthz)
+  * [dbauthz](https://github.com/coder/coder/tree/main/coderd/database/dbauthz)
+  * [dbfake](https://github.com/coder/coder/tree/main/coderd/database/dbfake)
+  * [dbfake](https://github.com/coder/coder/tree/main/coderd/database/dbfake)
+  * [dbgen](https://github.com/coder/coder/tree/main/coderd/database/dbgen)
+  * [dbmem](https://github.com/coder/coder/tree/main/coderd/database/dbmem)
+  * [dbmetrics](https://github.com/coder/coder/tree/main/coderd/database/dbmetrics)
+  * [dbmetrics](https://github.com/coder/coder/tree/main/coderd/database/dbmetrics)
+  * [dbmock](https://github.com/coder/coder/tree/main/coderd/database/dbmock)
+  * [dbpurge](https://github.com/coder/coder/tree/main/coderd/database/dbpurge)
+  * [dbpurge](https://github.com/coder/coder/tree/main/coderd/database/dbpurge)
+  * [gen](https://github.com/coder/coder/tree/main/coderd/database/gen)
+  * [migrations](https://github.com/coder/coder/tree/main/coderd/database/migrations)
+  * [pubsub](https://github.com/coder/coder/tree/main/coderd/database/pubsub)
+  * [queries](https://github.com/coder/coder/tree/main/coderd/database/queries)
 * `dogfood`: internal testing and validation tools
 * `enterprise`: enterprise-only features and extensions
+TODO
 * `nix`: Nix utility scripts and definitions
 * `provisioner`, `provisionerd`, `provisionersdk`: components for infrastructure provisioning
 * `pty`: terminal emulation for remote shells

From a18e994b387130003b6ebdb574cc15346f53622b Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Wed, 28 May 2025 14:15:20 +0200
Subject: [PATCH 07/32] Repository Structure WIP

---
 docs/contributing/backend.md | 13 +++++--------
 1 file changed, 5 insertions(+), 8 deletions(-)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index 1210a0c750f84..e96e4cededa49 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -104,14 +104,11 @@ The Coder backend is organized into multiple packages and directories, each with
   * [workspaceapps](https://github.com/coder/coder/tree/main/coderd/workspaceapps): core logic of a secure proxy to expose workspace apps deployed in a workspace
   * [wsbuilder](https://github.com/coder/coder/tree/main/coderd/wsbuilder): wrapper for business logic of creating a workspace build. It encapsulates all database operations required to insert a build record in a transaction.
 * [database](https://github.com/coder/coder/tree/main/coderd/database): schema migrations, query logic, in-memory database, etc.
-  * [db2sdk](https://github.com/coder/coder/tree/main/coderd/database/db2sdk)
-  * [dbauthz](https://github.com/coder/coder/tree/main/coderd/database/dbauthz)
-  * [dbauthz](https://github.com/coder/coder/tree/main/coderd/database/dbauthz)
-  * [dbfake](https://github.com/coder/coder/tree/main/coderd/database/dbfake)
-  * [dbfake](https://github.com/coder/coder/tree/main/coderd/database/dbfake)
-  * [dbgen](https://github.com/coder/coder/tree/main/coderd/database/dbgen)
-  * [dbmem](https://github.com/coder/coder/tree/main/coderd/database/dbmem)
-  * [dbmetrics](https://github.com/coder/coder/tree/main/coderd/database/dbmetrics)
+  * [db2sdk](https://github.com/coder/coder/tree/main/coderd/database/db2sdk): translation between database structures and [codersdk](https://github.com/coder/coder/tree/main/coderd/codersdk) objects used by coderd API.
+  * [dbauthz](https://github.com/coder/coder/tree/main/coderd/database/dbauthz): AuthZ wrappers for database queries, ideally, every query should verify first if the accessor is eligible to see the query results.
+  * [dbfake](https://github.com/coder/coder/tree/main/coderd/database/dbfake): helper functions to quickly prepare the initial database state for testing purposes (e.g. create N healthy workspaces and templates), operates on higher level than [dbgen](https://github.com/coder/coder/tree/main/coderd/database/dbgen)
+  * [dbgen](https://github.com/coder/coder/tree/main/coderd/database/dbgen): helper functions to insert raw records to the database store, used for testing purposes
+  * [dbmem](https://github.com/coder/coder/tree/main/coderd/database/dbmem): in-memory implementation of the database store, ideally, every real query should have a complimentary Go implementation
   * [dbmetrics](https://github.com/coder/coder/tree/main/coderd/database/dbmetrics)
   * [dbmock](https://github.com/coder/coder/tree/main/coderd/database/dbmock)
   * [dbpurge](https://github.com/coder/coder/tree/main/coderd/database/dbpurge)

From fd4475354cecdaeb266c3aa3e4d7497e5564d597 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Wed, 28 May 2025 14:55:44 +0200
Subject: [PATCH 08/32] Repository Structure WIP

---
 docs/contributing/backend.md | 21 ++++++++++-----------
 1 file changed, 10 insertions(+), 11 deletions(-)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index e96e4cededa49..9db9645661dda 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -109,17 +109,16 @@ The Coder backend is organized into multiple packages and directories, each with
   * [dbfake](https://github.com/coder/coder/tree/main/coderd/database/dbfake): helper functions to quickly prepare the initial database state for testing purposes (e.g. create N healthy workspaces and templates), operates on higher level than [dbgen](https://github.com/coder/coder/tree/main/coderd/database/dbgen)
   * [dbgen](https://github.com/coder/coder/tree/main/coderd/database/dbgen): helper functions to insert raw records to the database store, used for testing purposes
   * [dbmem](https://github.com/coder/coder/tree/main/coderd/database/dbmem): in-memory implementation of the database store, ideally, every real query should have a complimentary Go implementation
-  * [dbmetrics](https://github.com/coder/coder/tree/main/coderd/database/dbmetrics)
-  * [dbmock](https://github.com/coder/coder/tree/main/coderd/database/dbmock)
-  * [dbpurge](https://github.com/coder/coder/tree/main/coderd/database/dbpurge)
-  * [dbpurge](https://github.com/coder/coder/tree/main/coderd/database/dbpurge)
-  * [gen](https://github.com/coder/coder/tree/main/coderd/database/gen)
-  * [migrations](https://github.com/coder/coder/tree/main/coderd/database/migrations)
-  * [pubsub](https://github.com/coder/coder/tree/main/coderd/database/pubsub)
-  * [queries](https://github.com/coder/coder/tree/main/coderd/database/queries)
-* `dogfood`: internal testing and validation tools
-* `enterprise`: enterprise-only features and extensions
-TODO
+  * [dbmock](https://github.com/coder/coder/tree/main/coderd/database/dbmock): a store wrapper for database queries, useful to verify if the function has been called, used for testing purposes
+  * [dbpurge](https://github.com/coder/coder/tree/main/coderd/database/dbpurge): simple wrapper for periodic database cleanup operations
+  * [migrations](https://github.com/coder/coder/tree/main/coderd/database/migrations): an ordered list of up/down database migrations, use `./create_migration.sh my_migration_name` to modify the database schema
+  * [pubsub](https://github.com/coder/coder/tree/main/coderd/database/pubsub): PubSub implementation using PostgreSQL and in-memory drop-in replacement
+  * [queries](https://github.com/coder/coder/tree/main/coderd/database/queries): contains SQL files with queries, `sqlc` compiles them to [Go functions](https://github.com/coder/coder/blob/docs-backend-contrib-guide/coderd/database/queries.sql.go)
+  * [sqlc.yaml](https://github.com/coder/coder/tree/main/coderd/database/sqlc.yaml): defines mappings between SQL types and custom Go structures
+* [dogfood](https://github.com/coder/coder/tree/main/dogfood): Terraform definition of the dogfood cluster deployment
+* [enterprise](https://github.com/coder/coder/tree/main/enterprise): enterprise-only features, notice similar file structure to repository root (`audit`, `cli`, `cmd`, `coderd`, etc.)
+  * [coderd](https://github.com/coder/coder/tree/main/enterprise/coderd)
+    * [prebuilds](https://github.com/coder/coder/tree/main/enterprise/coderd/prebuilds): core logic of prebuilt workspaces - reconciliation loop
 * `nix`: Nix utility scripts and definitions
 * `provisioner`, `provisionerd`, `provisionersdk`: components for infrastructure provisioning
 * `pty`: terminal emulation for remote shells

From 9bb61e4f70925cce8b4bd83ff499288075acca64 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Wed, 28 May 2025 15:13:33 +0200
Subject: [PATCH 09/32] Repository Structure WIP

---
 docs/contributing/backend.md | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index 9db9645661dda..edfc046d7ef8d 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -119,9 +119,10 @@ The Coder backend is organized into multiple packages and directories, each with
 * [enterprise](https://github.com/coder/coder/tree/main/enterprise): enterprise-only features, notice similar file structure to repository root (`audit`, `cli`, `cmd`, `coderd`, etc.)
   * [coderd](https://github.com/coder/coder/tree/main/enterprise/coderd)
     * [prebuilds](https://github.com/coder/coder/tree/main/enterprise/coderd/prebuilds): core logic of prebuilt workspaces - reconciliation loop
-* `nix`: Nix utility scripts and definitions
-* `provisioner`, `provisionerd`, `provisionersdk`: components for infrastructure provisioning
-* `pty`: terminal emulation for remote shells
-* `support`: shared internal helpers
-* `tailnet`: network stack and identity management
-* `vpn`: VPN and tunneling components
+* [provisioner](https://github.com/coder/coder/tree/main/provisioner):
+* [provisionerd](https://github.com/coder/coder/tree/main/provisionerd):
+* [provisionersdk](https://github.com/coder/coder/tree/main/provisionersdk):
+* [pty](https://github.com/coder/coder/tree/main/pty): terminal emulation for agent shell
+* [support](https://github.com/coder/coder/tree/main/support): compile a support bundle with diagnostics
+* [tailnet](https://github.com/coder/coder/tree/main/tailnet): core logic of Tailnet controller to maintain DERP maps, coordinate connections with agents and peers
+* [vpn](https://github.com/coder/coder/tree/main/vpn): Coder Desktop (VPN) and tunneling components

From 35a9865fa69e279f0f29a452f00e8016568e98c2 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Wed, 28 May 2025 15:31:54 +0200
Subject: [PATCH 10/32] Repository Structure

---
 docs/contributing/backend.md | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index edfc046d7ef8d..f739ac59c2bc0 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -119,9 +119,8 @@ The Coder backend is organized into multiple packages and directories, each with
 * [enterprise](https://github.com/coder/coder/tree/main/enterprise): enterprise-only features, notice similar file structure to repository root (`audit`, `cli`, `cmd`, `coderd`, etc.)
   * [coderd](https://github.com/coder/coder/tree/main/enterprise/coderd)
     * [prebuilds](https://github.com/coder/coder/tree/main/enterprise/coderd/prebuilds): core logic of prebuilt workspaces - reconciliation loop
-* [provisioner](https://github.com/coder/coder/tree/main/provisioner):
-* [provisionerd](https://github.com/coder/coder/tree/main/provisionerd):
-* [provisionersdk](https://github.com/coder/coder/tree/main/provisionersdk):
+* [provisioner](https://github.com/coder/coder/tree/main/provisioner): supported implementation of provisioners, Terraform and "echo" (for testing purposes)
+* [provisionerd](https://github.com/coder/coder/tree/main/provisionerd): core logic of provisioner runner to interact provisionerd server, depending on a job acquired it calls template import, dry run or a workspace build
 * [pty](https://github.com/coder/coder/tree/main/pty): terminal emulation for agent shell
 * [support](https://github.com/coder/coder/tree/main/support): compile a support bundle with diagnostics
 * [tailnet](https://github.com/coder/coder/tree/main/tailnet): core logic of Tailnet controller to maintain DERP maps, coordinate connections with agents and peers

From b73cc9e951e99a00a3145a313fdf703020d08d43 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Wed, 28 May 2025 15:42:08 +0200
Subject: [PATCH 11/32] quiz

---
 docs/contributing/backend.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index f739ac59c2bc0..a7d63e17752c4 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -125,3 +125,16 @@ The Coder backend is organized into multiple packages and directories, each with
 * [support](https://github.com/coder/coder/tree/main/support): compile a support bundle with diagnostics
 * [tailnet](https://github.com/coder/coder/tree/main/tailnet): core logic of Tailnet controller to maintain DERP maps, coordinate connections with agents and peers
 * [vpn](https://github.com/coder/coder/tree/main/vpn): Coder Desktop (VPN) and tunneling components
+
+## Testing
+
+TODO
+
+## Quiz
+
+Try to find answers to these questions before jumping into implementation work — having a solid understanding of how Coder works will save you time and help you contribute effectively.
+
+1. When you create a template, what does that do exactly?
+2. When you create a workspace, what exactly happens?
+3. How does the agent get the required information to run?
+4. How are provisioner jobs run?

From d372181f1a39f0a0aea5424fa859df33ef6c1309 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Wed, 28 May 2025 16:29:38 +0200
Subject: [PATCH 12/32] Testing WIP

---
 docs/contributing/backend.md | 37 +++++++++++++++++++++++++++++++++++-
 1 file changed, 36 insertions(+), 1 deletion(-)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index a7d63e17752c4..f58e9e6197c87 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -115,6 +115,7 @@ The Coder backend is organized into multiple packages and directories, each with
   * [pubsub](https://github.com/coder/coder/tree/main/coderd/database/pubsub): PubSub implementation using PostgreSQL and in-memory drop-in replacement
   * [queries](https://github.com/coder/coder/tree/main/coderd/database/queries): contains SQL files with queries, `sqlc` compiles them to [Go functions](https://github.com/coder/coder/blob/docs-backend-contrib-guide/coderd/database/queries.sql.go)
   * [sqlc.yaml](https://github.com/coder/coder/tree/main/coderd/database/sqlc.yaml): defines mappings between SQL types and custom Go structures
+* [codersdk](https://github.com/coder/coder/tree/main/codersdk): user-facing API entities used by CLI and site to communicate with `coderd` endpoints
 * [dogfood](https://github.com/coder/coder/tree/main/dogfood): Terraform definition of the dogfood cluster deployment
 * [enterprise](https://github.com/coder/coder/tree/main/enterprise): enterprise-only features, notice similar file structure to repository root (`audit`, `cli`, `cmd`, `coderd`, etc.)
   * [coderd](https://github.com/coder/coder/tree/main/enterprise/coderd)
@@ -128,7 +129,41 @@ The Coder backend is organized into multiple packages and directories, each with
 
 ## Testing
 
-TODO
+The Coder backend includes a rich suite of unit and end-to-end tests. A variety of helper utilities are used throughout the codebase to make testing easier, more consistent, and closer to real behavior.
+
+### `clitest`
+* Spawns an in-memory `serpent.Command` instance for unit testing
+* Configures an authorized `codersdk` client
+* Once a `serpent.Invocation` is created, tests can execute commands as if invoked by a real user
+
+### `ptytest`
+* `ptytest` attaches to a `serpent.Invocation` and simulates TTY input/output
+* `pty` provides matchers and "write" operations for interacting with pseudo-terminals
+
+### `coderdtest`
+* Provides shortcuts to spin up an in-memory `coderd` instance
+* Can start an embedded provisioner daemon
+* Supports multi-user testing via `CreateFirstUser` and `CreateAnotherUser`
+* Includes "busy wait" helpers like `AwaitTemplateVersionJobCompleted`
+
+### `testutil`
+
+General-purpose testing utilities, including:
+* `chan.go`: helpers for sending/receiving objects from channels (`TrySend`, `RequireReceive`, etc.)
+* `duration.go`: set timeouts for test execution
+* `eventually.go`: repeatedly poll for a condition using a ticker
+* `port.go`: select a free random port
+* `prometheus.go`: validate Prometheus metrics with expected values
+* `pty.go`: read output from a terminal until a condition is met
+
+### `dbtestutil`
+* Allows choosing between real and in-memory database backends for tests
+* `WillUsePostgres` is useful for skipping tests in CI environments that don't run Postgres
+
+### `quartz`
+* Provides a mockable clock or ticker interface
+* Allows manual time advancement
+* Useful for testing time-sensitive or timeout-related logic
 
 ## Quiz
 

From 5a7311ec30d7b846ca13c3beddd47af2451d91a1 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Wed, 28 May 2025 16:34:38 +0200
Subject: [PATCH 13/32] WIP

---
 docs/contributing/backend.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index f58e9e6197c87..3ef686ad9214e 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -131,7 +131,7 @@ The Coder backend is organized into multiple packages and directories, each with
 
 The Coder backend includes a rich suite of unit and end-to-end tests. A variety of helper utilities are used throughout the codebase to make testing easier, more consistent, and closer to real behavior.
 
-### `clitest`
+### [clitest](https://github.com/coder/coder/tree/main/clitest)
 * Spawns an in-memory `serpent.Command` instance for unit testing
 * Configures an authorized `codersdk` client
 * Once a `serpent.Invocation` is created, tests can execute commands as if invoked by a real user

From 3ee07474421b7ff17b9a928c4edd029bdc726b31 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Wed, 28 May 2025 16:36:02 +0200
Subject: [PATCH 14/32] WIP

---
 docs/contributing/backend.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index 3ef686ad9214e..6fa61261bafd9 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -136,11 +136,11 @@ The Coder backend includes a rich suite of unit and end-to-end tests. A variety
 * Configures an authorized `codersdk` client
 * Once a `serpent.Invocation` is created, tests can execute commands as if invoked by a real user
 
-### `ptytest`
+### [ptytest](https://github.com/coder/coder/tree/main/ptytest)
 * `ptytest` attaches to a `serpent.Invocation` and simulates TTY input/output
 * `pty` provides matchers and "write" operations for interacting with pseudo-terminals
 
-### `coderdtest`
+### [coderdtest](https://github.com/coder/coder/tree/main/coderd/coderdtest)
 * Provides shortcuts to spin up an in-memory `coderd` instance
 * Can start an embedded provisioner daemon
 * Supports multi-user testing via `CreateFirstUser` and `CreateAnotherUser`

From d8ff1231734da78bbd92b7c675754deadb6f9144 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Wed, 28 May 2025 16:39:00 +0200
Subject: [PATCH 15/32] WIP

---
 docs/contributing/backend.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index 6fa61261bafd9..c0feeb2c83bf1 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -131,12 +131,12 @@ The Coder backend is organized into multiple packages and directories, each with
 
 The Coder backend includes a rich suite of unit and end-to-end tests. A variety of helper utilities are used throughout the codebase to make testing easier, more consistent, and closer to real behavior.
 
-### [clitest](https://github.com/coder/coder/tree/main/clitest)
+### [clitest](https://github.com/coder/coder/tree/main/cli/clitest)
 * Spawns an in-memory `serpent.Command` instance for unit testing
 * Configures an authorized `codersdk` client
 * Once a `serpent.Invocation` is created, tests can execute commands as if invoked by a real user
 
-### [ptytest](https://github.com/coder/coder/tree/main/ptytest)
+### [ptytest](https://github.com/coder/coder/tree/main/pty/ptytest)
 * `ptytest` attaches to a `serpent.Invocation` and simulates TTY input/output
 * `pty` provides matchers and "write" operations for interacting with pseudo-terminals
 
@@ -145,9 +145,9 @@ The Coder backend includes a rich suite of unit and end-to-end tests. A variety
 * Can start an embedded provisioner daemon
 * Supports multi-user testing via `CreateFirstUser` and `CreateAnotherUser`
 * Includes "busy wait" helpers like `AwaitTemplateVersionJobCompleted`
+* [oidctest](https://github.com/coder/coder/tree/main/coderd/coderdtest/oidctest) can start a fake OIDC provider
 
-### `testutil`
-
+### [testutil](https://github.com/coder/coder/tree/main/testutil)
 General-purpose testing utilities, including:
 * `chan.go`: helpers for sending/receiving objects from channels (`TrySend`, `RequireReceive`, etc.)
 * `duration.go`: set timeouts for test execution
@@ -156,11 +156,11 @@ General-purpose testing utilities, including:
 * `prometheus.go`: validate Prometheus metrics with expected values
 * `pty.go`: read output from a terminal until a condition is met
 
-### `dbtestutil`
+### [dbtestutil](https://github.com/coder/coder/tree/main/coderd/database/dbtestutil)
 * Allows choosing between real and in-memory database backends for tests
 * `WillUsePostgres` is useful for skipping tests in CI environments that don't run Postgres
 
-### `quartz`
+### [quartz](https://github.com/coder/quartz/tree/main)
 * Provides a mockable clock or ticker interface
 * Allows manual time advancement
 * Useful for testing time-sensitive or timeout-related logic

From 2a9d702653f584b90d97d0a0dfe29024c914bb05 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Wed, 28 May 2025 16:40:57 +0200
Subject: [PATCH 16/32] WIP

---
 docs/contributing/backend.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index c0feeb2c83bf1..dd10a95ad79aa 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -148,13 +148,13 @@ The Coder backend includes a rich suite of unit and end-to-end tests. A variety
 * [oidctest](https://github.com/coder/coder/tree/main/coderd/coderdtest/oidctest) can start a fake OIDC provider
 
 ### [testutil](https://github.com/coder/coder/tree/main/testutil)
-General-purpose testing utilities, including:
-* `chan.go`: helpers for sending/receiving objects from channels (`TrySend`, `RequireReceive`, etc.)
-* `duration.go`: set timeouts for test execution
-* `eventually.go`: repeatedly poll for a condition using a ticker
-* `port.go`: select a free random port
-* `prometheus.go`: validate Prometheus metrics with expected values
-* `pty.go`: read output from a terminal until a condition is met
+* General-purpose testing utilities, including:
+  * [chan.go](https://github.com/coder/coder/blob/main/testutil/chan.go): helpers for sending/receiving objects from channels (`TrySend`, `RequireReceive`, etc.)
+  * [duration.go](https://github.com/coder/coder/blob/main/testutil/duration.go): set timeouts for test execution
+  * [eventually.go](https://github.com/coder/coder/blob/main/testutil/eventually.go): repeatedly poll for a condition using a ticker
+  * [port.go](https://github.com/coder/coder/blob/main/testutil/port.go): select a free random port
+  * [prometheus.go](https://github.com/coder/coder/blob/main/testutil/prometheus.go): validate Prometheus metrics with expected values
+  * [pty.go](https://github.com/coder/coder/blob/main/testutil/pty.go): read output from a terminal until a condition is met
 
 ### [dbtestutil](https://github.com/coder/coder/tree/main/coderd/database/dbtestutil)
 * Allows choosing between real and in-memory database backends for tests

From 619d31c1f3cee40a0cf03feb3b4e6b0f932526a1 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Wed, 28 May 2025 16:52:49 +0200
Subject: [PATCH 17/32] manifest.json

---
 docs/manifest.json | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/manifest.json b/docs/manifest.json
index 1ec955c6244cc..6499a2cbd7076 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -797,6 +797,12 @@
 					"path": "./contributing/documentation.md",
 					"icon_path": "./images/icons/document.svg"
 				},
+				{
+					"title": "Backend",
+					"description": "Our guide for backend development",
+					"path": "./contributing/backend.md",
+					"icon_path": "./images/icons/gear.svg"
+				},
 				{
 					"title": "Frontend",
 					"description": "Our guide for frontend development",

From 6d680eb4866176d502276cb8858cf9bb5568f52c Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Wed, 28 May 2025 16:56:07 +0200
Subject: [PATCH 18/32] fix link

---
 docs/contributing/backend.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index dd10a95ad79aa..39beb834a6be9 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -104,7 +104,7 @@ The Coder backend is organized into multiple packages and directories, each with
   * [workspaceapps](https://github.com/coder/coder/tree/main/coderd/workspaceapps): core logic of a secure proxy to expose workspace apps deployed in a workspace
   * [wsbuilder](https://github.com/coder/coder/tree/main/coderd/wsbuilder): wrapper for business logic of creating a workspace build. It encapsulates all database operations required to insert a build record in a transaction.
 * [database](https://github.com/coder/coder/tree/main/coderd/database): schema migrations, query logic, in-memory database, etc.
-  * [db2sdk](https://github.com/coder/coder/tree/main/coderd/database/db2sdk): translation between database structures and [codersdk](https://github.com/coder/coder/tree/main/coderd/codersdk) objects used by coderd API.
+  * [db2sdk](https://github.com/coder/coder/tree/main/coderd/database/db2sdk): translation between database structures and [codersdk](https://github.com/coder/coder/tree/main/codersdk) objects used by coderd API.
   * [dbauthz](https://github.com/coder/coder/tree/main/coderd/database/dbauthz): AuthZ wrappers for database queries, ideally, every query should verify first if the accessor is eligible to see the query results.
   * [dbfake](https://github.com/coder/coder/tree/main/coderd/database/dbfake): helper functions to quickly prepare the initial database state for testing purposes (e.g. create N healthy workspaces and templates), operates on higher level than [dbgen](https://github.com/coder/coder/tree/main/coderd/database/dbgen)
   * [dbgen](https://github.com/coder/coder/tree/main/coderd/database/dbgen): helper functions to insert raw records to the database store, used for testing purposes

From a4ce2c335f43a009524a7aac94eb72d8ee179691 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Wed, 28 May 2025 17:00:56 +0200
Subject: [PATCH 19/32] fix lint

---
 docs/contributing/backend.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index 39beb834a6be9..4523ac1ed769a 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -25,7 +25,7 @@ git clone https://github.com/coder/coder.git
 cd coder
 ```
 
-2. Run the development script to spin up the local environment:
+1. Run the development script to spin up the local environment:
 
 ```sh
 ./scripts/develop.sh
@@ -35,7 +35,7 @@ This will start two processes:
 * http://localhost:3000 — the backend API server, used primarily for backend development.
 * http://localhost:8080 — the Node.js frontend dev server, useful if you're also touching frontend code.
 
-3. Verify Your Session
+1. Verify Your Session
 
 Confirm that you're logged in by running:
 
@@ -45,7 +45,7 @@ Confirm that you're logged in by running:
 
 This should return an empty list of workspaces. If you encounter an error, review the output from the [develop.sh](https://github.com/coder/coder/blob/main/scripts/develop.sh) script for issues.
 
-4. Create a Quick Workspace
+1. Create a Quick Workspace
 
 A template named docker-amd64 (or docker-arm64 on ARM systems) is created automatically. To spin up a workspace quickly, use:
 

From 49311d050f26a77007a66371735d044ad5b0d135 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Wed, 28 May 2025 17:10:02 +0200
Subject: [PATCH 20/32] git apply

---
 docs/contributing/backend.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index 4523ac1ed769a..a25a59f1652d2 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -32,6 +32,7 @@ cd coder
 ```
 
 This will start two processes:
+
 * http://localhost:3000 — the backend API server, used primarily for backend development.
 * http://localhost:8080 — the Node.js frontend dev server, useful if you're also touching frontend code.
 
@@ -56,6 +57,7 @@ A template named docker-amd64 (or docker-arm64 on ARM systems) is created automa
 ## Platform Architecture
 
 To understand how the backend fits into the broader system, we recommend reviewing the following resources:
+
 * [General Concepts](../admin/infrastructure/validated-architectures/index.md#general-concepts): Essential concepts and language used to describe how Coder is structured and operated.
 
 * [Architecture](../admin/infrastructure/architecture.md): A high-level overview of the infrastructure layout, key services, and how components interact.
@@ -132,15 +134,18 @@ The Coder backend is organized into multiple packages and directories, each with
 The Coder backend includes a rich suite of unit and end-to-end tests. A variety of helper utilities are used throughout the codebase to make testing easier, more consistent, and closer to real behavior.
 
 ### [clitest](https://github.com/coder/coder/tree/main/cli/clitest)
+
 * Spawns an in-memory `serpent.Command` instance for unit testing
 * Configures an authorized `codersdk` client
 * Once a `serpent.Invocation` is created, tests can execute commands as if invoked by a real user
 
 ### [ptytest](https://github.com/coder/coder/tree/main/pty/ptytest)
+
 * `ptytest` attaches to a `serpent.Invocation` and simulates TTY input/output
 * `pty` provides matchers and "write" operations for interacting with pseudo-terminals
 
 ### [coderdtest](https://github.com/coder/coder/tree/main/coderd/coderdtest)
+
 * Provides shortcuts to spin up an in-memory `coderd` instance
 * Can start an embedded provisioner daemon
 * Supports multi-user testing via `CreateFirstUser` and `CreateAnotherUser`
@@ -148,6 +153,7 @@ The Coder backend includes a rich suite of unit and end-to-end tests. A variety
 * [oidctest](https://github.com/coder/coder/tree/main/coderd/coderdtest/oidctest) can start a fake OIDC provider
 
 ### [testutil](https://github.com/coder/coder/tree/main/testutil)
+
 * General-purpose testing utilities, including:
   * [chan.go](https://github.com/coder/coder/blob/main/testutil/chan.go): helpers for sending/receiving objects from channels (`TrySend`, `RequireReceive`, etc.)
   * [duration.go](https://github.com/coder/coder/blob/main/testutil/duration.go): set timeouts for test execution
@@ -157,10 +163,12 @@ The Coder backend includes a rich suite of unit and end-to-end tests. A variety
   * [pty.go](https://github.com/coder/coder/blob/main/testutil/pty.go): read output from a terminal until a condition is met
 
 ### [dbtestutil](https://github.com/coder/coder/tree/main/coderd/database/dbtestutil)
+
 * Allows choosing between real and in-memory database backends for tests
 * `WillUsePostgres` is useful for skipping tests in CI environments that don't run Postgres
 
 ### [quartz](https://github.com/coder/quartz/tree/main)
+
 * Provides a mockable clock or ticker interface
 * Allows manual time advancement
 * Useful for testing time-sensitive or timeout-related logic

From 253c4466549f93e595d03ebba234d0daf44e8bfc Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Thu, 29 May 2025 11:40:43 +0200
Subject: [PATCH 21/32] PR comments

---
 docs/contributing/backend.md | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index a25a59f1652d2..1b6453a567be7 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -16,7 +16,9 @@ Need help or have questions? Join the conversation on our [Discord server](https
 
 ## Quickstart
 
-To get up and running with Coder's backend, make sure you have **Docker installed and running** on your system. Once that's in place, follow these steps:
+To get started with Coder's backend, the easiest way to set up the required environment is to use the provided [Nix environment](https://github.com/coder/coder/tree/main/nix) or launch a local [DevContainer](https://github.com/coder/coder/tree/main/.devcontainer). Alternatively, ensure you have the following installed and running on your system: **Docker, Go, Node.js (with pnpm), and make**.
+
+ Once that's in place, follow these steps:
 
 1. Clone the Coder repository and navigate into the project directory:
 
@@ -33,8 +35,8 @@ cd coder
 
 This will start two processes:
 
-* http://localhost:3000 — the backend API server, used primarily for backend development.
-* http://localhost:8080 — the Node.js frontend dev server, useful if you're also touching frontend code.
+* http://localhost:3000 — the backend API server. Primarily used for backend development and also serves the *static* frontend build.
+* http://localhost:8080 — the Node.js frontend development server. Supports *hot reloading* and is useful if you're working on the frontend as well.
 
 1. Verify Your Session
 

From 18d51826a36123006175b0a6bedce637a0879e4d Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Thu, 29 May 2025 11:44:11 +0200
Subject: [PATCH 22/32] PR comments

---
 docs/contributing/backend.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index 1b6453a567be7..fe9c60b204918 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -38,6 +38,8 @@ This will start two processes:
 * http://localhost:3000 — the backend API server. Primarily used for backend development and also serves the *static* frontend build.
 * http://localhost:8080 — the Node.js frontend development server. Supports *hot reloading* and is useful if you're working on the frontend as well.
 
+Additionally, it starts a local PostgreSQL instance, creates both an admin and a member user account, and installs a default Docker-based template.
+
 1. Verify Your Session
 
 Confirm that you're logged in by running:

From 0fd7fc983cf0a398b91639567ac0f3809e9ac7fc Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Thu, 29 May 2025 11:45:00 +0200
Subject: [PATCH 23/32] PR comments

---
 docs/contributing/backend.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index fe9c60b204918..902254abd5d4a 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -10,8 +10,6 @@ The purpose of this guide is to help you:
 * Navigate the codebase with confidence and adhere to established best practices.
 * Contribute meaningful changes - whether you're fixing bugs, implementing features, or reviewing code.
 
-By aligning on tools, workflows, and conventions, we reduce cognitive overhead, improve collaboration across teams, and accelerate our ability to deliver high-quality software.
-
 Need help or have questions? Join the conversation on our [Discord server](https://discord.com/invite/coder) — we’re always happy to support contributors.
 
 ## Quickstart

From 7c644d8599e9022771a232a9aa5a88becf229b05 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Thu, 29 May 2025 13:05:54 +0200
Subject: [PATCH 24/32] PR comments

---
 docs/contributing/backend.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index 902254abd5d4a..0edf2c2ae2528 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -48,7 +48,9 @@ Confirm that you're logged in by running:
 
 This should return an empty list of workspaces. If you encounter an error, review the output from the [develop.sh](https://github.com/coder/coder/blob/main/scripts/develop.sh) script for issues.
 
-1. Create a Quick Workspace
+> `coder-dev.sh` is a helper script that behaves like the regular coder CLI, but uses the binary built from your local source and shares the same configuration directory set up by `develop.sh`. This ensures your local changes are reflected when testing.
+
+1. Create Your First Workspace
 
 A template named docker-amd64 (or docker-arm64 on ARM systems) is created automatically. To spin up a workspace quickly, use:
 

From 4a965053426e0bd22bb7e88421df21b934d085a4 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Thu, 29 May 2025 13:10:38 +0200
Subject: [PATCH 25/32] PR comments

---
 docs/contributing/backend.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index 0edf2c2ae2528..e7d1af92243cd 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -52,10 +52,10 @@ This should return an empty list of workspaces. If you encounter an error, revie
 
 1. Create Your First Workspace
 
-A template named docker-amd64 (or docker-arm64 on ARM systems) is created automatically. To spin up a workspace quickly, use:
+A template named `docker` is created automatically. To spin up a workspace quickly, use:
 
 ```sh
-./scripts/coder-dev.sh create my-workspace -t docker-amd64
+./scripts/coder-dev.sh create my-workspace -t docker
 ```
 
 ## Platform Architecture

From 08b85427ff1e517495679953edbc482c2b77d2af Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Thu, 29 May 2025 13:17:04 +0200
Subject: [PATCH 26/32] fix: dogfood

---
 dogfood/coder/guide.md | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/dogfood/coder/guide.md b/dogfood/coder/guide.md
index dbaa47ee85eed..43597379cb67a 100644
--- a/dogfood/coder/guide.md
+++ b/dogfood/coder/guide.md
@@ -57,11 +57,9 @@ The following explains how to do certain things related to dogfooding.
 5. Ensure that you’re logged in: `./scripts/coder-dev.sh list` — should return
     no workspace. If this returns an error, double-check the output of running
     `scripts/develop.sh`.
-6. A template named `docker-amd64` (or `docker-arm64` if you’re on ARM) will
-    have automatically been created for you. If you just want to create a
-    workspace quickly, you can run
-    `./scripts/coder-dev.sh create myworkspace -t docker-amd64` and this will
-    get you going quickly!
+6. A template named `docker` will have automatically been created for you. If you just
+    want to create a workspace quickly, you can run `./scripts/coder-dev.sh create myworkspace -t docker`
+	and this will get you going quickly!
 7. To create your own template, you can do:
     `./scripts/coder-dev.sh templates init` and choose your preferred option.
     For example, choosing “Develop in Docker” will create a new folder `docker`

From 4251ca876cd27f5f353ae7939751f751a435669a Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Fri, 30 May 2025 13:31:13 +0200
Subject: [PATCH 27/32] PR comments

---
 docs/CONTRIBUTING.md         | 105 +++++++++++++----------------------
 docs/contributing/backend.md |  46 ---------------
 2 files changed, 38 insertions(+), 113 deletions(-)

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index 61319d3f756b2..8639ea3d9ea11 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -4,8 +4,8 @@
 
 <div class="tabs">
 
-We recommend that you use [Nix](https://nix.dev/) package manager to
-[maintain dependency versions](https://nixos.org/guides/how-nix-works).
+To get started with Coder, the easiest way to set up the required environment is to use the provided [Nix environment](https://github.com/coder/coder/tree/main/nix).
+Learn more [how Nix works](https://nixos.org/guides/how-nix-works).
 
 ### Nix
 
@@ -56,37 +56,9 @@ We recommend that you use [Nix](https://nix.dev/) package manager to
 
 ### Without Nix
 
-Alternatively if you do not want to use Nix then you'll need to install the need
-the following tools by hand:
-
-- Go 1.18+
-  - on macOS, run `brew install go`
-- Node 14+
-  - on macOS, run `brew install node`
-- GNU Make 4.0+
-  - on macOS, run `brew install make`
-- [`shfmt`](https://github.com/mvdan/sh#shfmt)
-  - on macOS, run `brew install shfmt`
-- [`nfpm`](https://nfpm.goreleaser.com/install)
-  - on macOS, run `brew install goreleaser/tap/nfpm && brew install nfpm`
-- [`pg_dump`](https://stackoverflow.com/a/49689589)
-  - on macOS, run `brew install libpq zstd`
-  - on Linux, install [`zstd`](https://github.com/horta/zstd.install)
-- PostgreSQL 13 (optional if Docker is available)
-  - *Note*: If you are using Docker, you can skip this step
-  - on macOS, run `brew install postgresql@13` and `brew services start postgresql@13`
-  - To enable schema generation with non-containerized PostgreSQL, set the following environment variable:
-    - `export DB_DUMP_CONNECTION_URL="postgres://postgres@localhost:5432/postgres?password=postgres&sslmode=disable"`
-- `pkg-config`
-  - on macOS, run `brew install pkg-config`
-- `pixman`
-  - on macOS, run `brew install pixman`
-- `cairo`
-  - on macOS, run `brew install cairo`
-- `pango`
-  - on macOS, run `brew install pango`
-- `pandoc`
-  - on macOS, run `brew install pandocomatic`
+If you're not using the Nix environment, you can launch a local [DevContainer](https://github.com/coder/coder/tree/main/.devcontainer) to get a fully configured development environment.
+
+DevContainers are supported in tools like **VS Code** and **GitHub Codespaces**, and come preloaded with all required dependencies: Docker, Go, Node.js with `pnpm`, and `make`.
 
 </div>
 
@@ -101,19 +73,41 @@ Use the following `make` commands and scripts in development:
 
 ### Running Coder on development mode
 
-- Run `./scripts/develop.sh`
-- Access `http://localhost:8080`
-- The default user is `admin@coder.com` and the default password is
-  `SomeSecurePassword!`
+1. Run the development script to spin up the local environment:
+
+   ```sh
+   ./scripts/develop.sh
+   ```
+
+   This will start two processes:
+
+   * http://localhost:3000 — the backend API server. Primarily used for backend development and also serves the *static* frontend build.
+   * http://localhost:8080 — the Node.js frontend development server. Supports *hot reloading* and is useful if you're working on the frontend as well.
+
+   Additionally, it starts a local PostgreSQL instance, creates both an admin and a member user account, and installs a default Docker-based template.
+
+1. Verify Your Session
+
+   Confirm that you're logged in by running:
+
+   ```sh
+   ./scripts/coder-dev.sh list
+      ```
+
+   This should return an empty list of workspaces. If you encounter an error, review the output from the [develop.sh](https://github.com/coder/coder/blob/main/scripts/develop.sh) script for issues.
+
+   > `coder-dev.sh` is a helper script that behaves like the regular coder CLI, but uses the binary built from your local source and shares the same configuration directory set up by `develop.sh`. This ensures your local changes are reflected when testing.
 
-### Running Coder using docker-compose
+   > The default user is `admin@coder.com` and the default password is `SomeSecurePassword!`
 
-This mode is useful for testing HA or validating more complex setups.
 
-- Generate a new image from your HEAD: `make build/coder_$(./scripts/version.sh)_$(go env GOOS)_$(go env GOARCH).tag`
-  - This will output the name of the new image, e.g.: `ghcr.io/coder/coder:v2.19.0-devel-22fa71d15-amd64`
-- Inject this image into docker-compose: `CODER_VERSION=v2.19.0-devel-22fa71d15-amd64 docker-compose up` (*note the prefix `ghcr.io/coder/coder:` was removed*)
-- To use Docker, determine your host's `docker` group ID with `getent group docker | cut -d: -f3`, then update the value of `group_add` and uncomment
+1. Create Your First Workspace
+
+   A template named `docker` is created automatically. To spin up a workspace quickly, use:
+
+   ```sh
+   ./scripts/coder-dev.sh create my-workspace -t docker
+   ```
 
 ### Deploying a PR
 
@@ -226,32 +220,9 @@ This helps in naming the dump (e.g. `000069` above).
 
 ## Styling
 
-### Documentation
-
 Visit our [documentation style guide](./contributing/documentation.md).
 
-### Backend
-
-#### Use Go style
-
-Contributions must adhere to the guidelines outlined in
-[Effective Go](https://go.dev/doc/effective_go). We prefer linting rules over
-documenting styles (run ours with `make lint`); humans are error-prone!
-
-Read
-[Go's Code Review Comments Wiki](https://github.com/golang/go/wiki/CodeReviewComments)
-for information on common comments made during reviews of Go code.
-
-#### Avoid unused packages
-
-Coder writes packages that are used during implementation. It isn't easy to
-validate whether an abstraction is valid until it's checked against an
-implementation. This results in a larger changeset, but it provides reviewers
-with a holistic perspective regarding the contribution.
-
-### Frontend
-
-Our frontend guide can be found [here](./contributing/frontend.md).
+Frontend styling guide can be found [here](./contributing/frontend.md#styling).
 
 ## Reviews
 
diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index e7d1af92243cd..b26904711a9ff 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -12,52 +12,6 @@ The purpose of this guide is to help you:
 
 Need help or have questions? Join the conversation on our [Discord server](https://discord.com/invite/coder) — we’re always happy to support contributors.
 
-## Quickstart
-
-To get started with Coder's backend, the easiest way to set up the required environment is to use the provided [Nix environment](https://github.com/coder/coder/tree/main/nix) or launch a local [DevContainer](https://github.com/coder/coder/tree/main/.devcontainer). Alternatively, ensure you have the following installed and running on your system: **Docker, Go, Node.js (with pnpm), and make**.
-
- Once that's in place, follow these steps:
-
-1. Clone the Coder repository and navigate into the project directory:
-
-```sh
-git clone https://github.com/coder/coder.git
-cd coder
-```
-
-1. Run the development script to spin up the local environment:
-
-```sh
-./scripts/develop.sh
-```
-
-This will start two processes:
-
-* http://localhost:3000 — the backend API server. Primarily used for backend development and also serves the *static* frontend build.
-* http://localhost:8080 — the Node.js frontend development server. Supports *hot reloading* and is useful if you're working on the frontend as well.
-
-Additionally, it starts a local PostgreSQL instance, creates both an admin and a member user account, and installs a default Docker-based template.
-
-1. Verify Your Session
-
-Confirm that you're logged in by running:
-
-```sh
-./scripts/coder-dev.sh list
-```
-
-This should return an empty list of workspaces. If you encounter an error, review the output from the [develop.sh](https://github.com/coder/coder/blob/main/scripts/develop.sh) script for issues.
-
-> `coder-dev.sh` is a helper script that behaves like the regular coder CLI, but uses the binary built from your local source and shares the same configuration directory set up by `develop.sh`. This ensures your local changes are reflected when testing.
-
-1. Create Your First Workspace
-
-A template named `docker` is created automatically. To spin up a workspace quickly, use:
-
-```sh
-./scripts/coder-dev.sh create my-workspace -t docker
-```
-
 ## Platform Architecture
 
 To understand how the backend fits into the broader system, we recommend reviewing the following resources:

From 121e38a5019242fa5dce021776eab01dc0e2247b Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Fri, 30 May 2025 13:35:07 +0200
Subject: [PATCH 28/32] fix lint

---
 docs/CONTRIBUTING.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index 8639ea3d9ea11..5fd2ccdf3b561 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -97,7 +97,7 @@ Use the following `make` commands and scripts in development:
    This should return an empty list of workspaces. If you encounter an error, review the output from the [develop.sh](https://github.com/coder/coder/blob/main/scripts/develop.sh) script for issues.
 
    > `coder-dev.sh` is a helper script that behaves like the regular coder CLI, but uses the binary built from your local source and shares the same configuration directory set up by `develop.sh`. This ensures your local changes are reflected when testing.
-
+   >
    > The default user is `admin@coder.com` and the default password is `SomeSecurePassword!`
 
 

From b3274c88b5d9fd7d0012d5772ea7546b5f852db0 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Fri, 30 May 2025 13:41:12 +0200
Subject: [PATCH 29/32] fix lint

---
 docs/CONTRIBUTING.md | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index 5fd2ccdf3b561..f4a12243d2ea1 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -81,8 +81,8 @@ Use the following `make` commands and scripts in development:
 
    This will start two processes:
 
-   * http://localhost:3000 — the backend API server. Primarily used for backend development and also serves the *static* frontend build.
-   * http://localhost:8080 — the Node.js frontend development server. Supports *hot reloading* and is useful if you're working on the frontend as well.
+   - http://localhost:3000 — the backend API server. Primarily used for backend development and also serves the *static* frontend build.
+   - http://localhost:8080 — the Node.js frontend development server. Supports *hot reloading* and is useful if you're working on the frontend as well.
 
    Additionally, it starts a local PostgreSQL instance, creates both an admin and a member user account, and installs a default Docker-based template.
 
@@ -100,7 +100,6 @@ Use the following `make` commands and scripts in development:
    >
    > The default user is `admin@coder.com` and the default password is `SomeSecurePassword!`
 
-
 1. Create Your First Workspace
 
    A template named `docker` is created automatically. To spin up a workspace quickly, use:

From 25b9564323d8ef50647c6e67d55dd3f6f1a33d40 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Fri, 30 May 2025 13:55:14 +0200
Subject: [PATCH 30/32] move database to backend

---
 docs/CONTRIBUTING.md         | 76 -----------------------------------
 docs/contributing/backend.md | 78 ++++++++++++++++++++++++++++++++++++
 2 files changed, 78 insertions(+), 76 deletions(-)

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index f4a12243d2ea1..3b0d14cb659f2 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -141,82 +141,6 @@ Once the deployment is finished, a unique link and credentials will be posted in
 the [#pr-deployments](https://codercom.slack.com/archives/C05DNE982E8) Slack
 channel.
 
-### Adding database migrations and fixtures
-
-#### Database migrations
-
-Database migrations are managed with
-[`migrate`](https://github.com/golang-migrate/migrate).
-
-To add new migrations, use the following command:
-
-```shell
-./coderd/database/migrations/create_migration.sh my name
-/home/coder/src/coder/coderd/database/migrations/000070_my_name.up.sql
-/home/coder/src/coder/coderd/database/migrations/000070_my_name.down.sql
-```
-
-Then write queries into the generated `.up.sql` and `.down.sql` files and commit
-them into the repository. The down script should make a best-effort to retain as
-much data as possible.
-
-Run `make gen` to generate models.
-
-#### Database fixtures (for testing migrations)
-
-There are two types of fixtures that are used to test that migrations don't
-break existing Coder deployments:
-
-- Partial fixtures
-  [`migrations/testdata/fixtures`](../coderd/database/migrations/testdata/fixtures)
-- Full database dumps
-  [`migrations/testdata/full_dumps`](../coderd/database/migrations/testdata/full_dumps)
-
-Both types behave like database migrations (they also
-[`migrate`](https://github.com/golang-migrate/migrate)). Their behavior mirrors
-Coder migrations such that when migration number `000022` is applied, fixture
-`000022` is applied afterwards.
-
-Partial fixtures are used to conveniently add data to newly created tables so
-that we can ensure that this data is migrated without issue.
-
-Full database dumps are for testing the migration of fully-fledged Coder
-deployments. These are usually done for a specific version of Coder and are
-often fixed in time. A full database dump may be necessary when testing the
-migration of multiple features or complex configurations.
-
-To add a new partial fixture, run the following command:
-
-```shell
-./coderd/database/migrations/create_fixture.sh my fixture
-/home/coder/src/coder/coderd/database/migrations/testdata/fixtures/000070_my_fixture.up.sql
-```
-
-Then add some queries to insert data and commit the file to the repo. See
-[`000024_example.up.sql`](../coderd/database/migrations/testdata/fixtures/000024_example.up.sql)
-for an example.
-
-To create a full dump, run a fully fledged Coder deployment and use it to
-generate data in the database. Then shut down the deployment and take a snapshot
-of the database.
-
-```shell
-mkdir -p coderd/database/migrations/testdata/full_dumps/v0.12.2 && cd $_
-pg_dump "postgres://coder@localhost:..." -a --inserts >000069_dump_v0.12.2.up.sql
-```
-
-Make sure sensitive data in the dump is desensitized, for instance names,
-emails, OAuth tokens and other secrets. Then commit the dump to the project.
-
-To find out what the latest migration for a version of Coder is, use the
-following command:
-
-```shell
-git ls-files v0.12.2 -- coderd/database/migrations/*.up.sql
-```
-
-This helps in naming the dump (e.g. `000069` above).
-
 ## Styling
 
 Visit our [documentation style guide](./contributing/documentation.md).
diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index b26904711a9ff..de8e003074137 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -139,3 +139,81 @@ Try to find answers to these questions before jumping into implementation work 
 2. When you create a workspace, what exactly happens?
 3. How does the agent get the required information to run?
 4. How are provisioner jobs run?
+
+## Recipes
+
+### Adding database migrations and fixtures
+
+#### Database migrations
+
+Database migrations are managed with
+[`migrate`](https://github.com/golang-migrate/migrate).
+
+To add new migrations, use the following command:
+
+```shell
+./coderd/database/migrations/create_migration.sh my name
+/home/coder/src/coder/coderd/database/migrations/000070_my_name.up.sql
+/home/coder/src/coder/coderd/database/migrations/000070_my_name.down.sql
+```
+
+Then write queries into the generated `.up.sql` and `.down.sql` files and commit
+them into the repository. The down script should make a best-effort to retain as
+much data as possible.
+
+Run `make gen` to generate models.
+
+#### Database fixtures (for testing migrations)
+
+There are two types of fixtures that are used to test that migrations don't
+break existing Coder deployments:
+
+- Partial fixtures
+  [`migrations/testdata/fixtures`](../coderd/database/migrations/testdata/fixtures)
+- Full database dumps
+  [`migrations/testdata/full_dumps`](../coderd/database/migrations/testdata/full_dumps)
+
+Both types behave like database migrations (they also
+[`migrate`](https://github.com/golang-migrate/migrate)). Their behavior mirrors
+Coder migrations such that when migration number `000022` is applied, fixture
+`000022` is applied afterwards.
+
+Partial fixtures are used to conveniently add data to newly created tables so
+that we can ensure that this data is migrated without issue.
+
+Full database dumps are for testing the migration of fully-fledged Coder
+deployments. These are usually done for a specific version of Coder and are
+often fixed in time. A full database dump may be necessary when testing the
+migration of multiple features or complex configurations.
+
+To add a new partial fixture, run the following command:
+
+```shell
+./coderd/database/migrations/create_fixture.sh my fixture
+/home/coder/src/coder/coderd/database/migrations/testdata/fixtures/000070_my_fixture.up.sql
+```
+
+Then add some queries to insert data and commit the file to the repo. See
+[`000024_example.up.sql`](../coderd/database/migrations/testdata/fixtures/000024_example.up.sql)
+for an example.
+
+To create a full dump, run a fully fledged Coder deployment and use it to
+generate data in the database. Then shut down the deployment and take a snapshot
+of the database.
+
+```shell
+mkdir -p coderd/database/migrations/testdata/full_dumps/v0.12.2 && cd $_
+pg_dump "postgres://coder@localhost:..." -a --inserts >000069_dump_v0.12.2.up.sql
+```
+
+Make sure sensitive data in the dump is desensitized, for instance names,
+emails, OAuth tokens and other secrets. Then commit the dump to the project.
+
+To find out what the latest migration for a version of Coder is, use the
+following command:
+
+```shell
+git ls-files v0.12.2 -- coderd/database/migrations/*.up.sql
+```
+
+This helps in naming the dump (e.g. `000069` above).

From 90b719936e9d015423654c623e9884604deeaae2 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Fri, 30 May 2025 14:00:48 +0200
Subject: [PATCH 31/32] fix lint

---
 docs/contributing/backend.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index de8e003074137..adb6497a3c315 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -168,9 +168,9 @@ Run `make gen` to generate models.
 There are two types of fixtures that are used to test that migrations don't
 break existing Coder deployments:
 
-- Partial fixtures
+* Partial fixtures
   [`migrations/testdata/fixtures`](../coderd/database/migrations/testdata/fixtures)
-- Full database dumps
+* Full database dumps
   [`migrations/testdata/full_dumps`](../coderd/database/migrations/testdata/full_dumps)
 
 Both types behave like database migrations (they also

From 7f6517d405b9b4c85303917e805dc5807f1278e0 Mon Sep 17 00:00:00 2001
From: Marcin Tojek <marcin@coder.com>
Date: Fri, 30 May 2025 14:02:43 +0200
Subject: [PATCH 32/32] fix links

---
 docs/contributing/backend.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md
index adb6497a3c315..fd1a80dc6b73c 100644
--- a/docs/contributing/backend.md
+++ b/docs/contributing/backend.md
@@ -169,9 +169,9 @@ There are two types of fixtures that are used to test that migrations don't
 break existing Coder deployments:
 
 * Partial fixtures
-  [`migrations/testdata/fixtures`](../coderd/database/migrations/testdata/fixtures)
+  [`migrations/testdata/fixtures`](../../coderd/database/migrations/testdata/fixtures)
 * Full database dumps
-  [`migrations/testdata/full_dumps`](../coderd/database/migrations/testdata/full_dumps)
+  [`migrations/testdata/full_dumps`](../../coderd/database/migrations/testdata/full_dumps)
 
 Both types behave like database migrations (they also
 [`migrate`](https://github.com/golang-migrate/migrate)). Their behavior mirrors
@@ -194,7 +194,7 @@ To add a new partial fixture, run the following command:
 ```
 
 Then add some queries to insert data and commit the file to the repo. See
-[`000024_example.up.sql`](../coderd/database/migrations/testdata/fixtures/000024_example.up.sql)
+[`000024_example.up.sql`](../../coderd/database/migrations/testdata/fixtures/000024_example.up.sql)
 for an example.
 
 To create a full dump, run a fully fledged Coder deployment and use it to