Files
coder/docs/install/cloud/azure-vm.md
T
Nick Vigilante 7846490770 docs: reconcile H1/label mismatches into front-matter titles (Phase 3) (#28036)
## Summary

**Batch B of Phase 3** of the H1 → front-matter migration (`DOCS-484`;
parent `DOCS-477`), the editorial follow-up to Batch A (#28030). For the
**124** hand-authored pages whose leading body H1 differed from the
manifest nav label, this promotes the richer body H1 to the front-matter
**page title** and drops the duplicate H1, while keeping the short
manifest **label** as the sidebar entry.

Policy agreed with the docs owner:
- Short sidebar labels win. Duplicate sidebar labels are acceptable.
- Identical **page titles** across two pages are not. On a collision,
rename the non-generated page's title.

## Page-title collisions resolved

Promoting the H1 created 4 page-title collisions; each is disambiguated
by renaming the non-generated / secondary page (sidebar labels left
unchanged):

| page | sidebar label | body H1 | → page title |
|------|---------------|---------|--------------|
| `install/index.md` | Install | Installing Coder | **Install Coder in
your infrastructure** |
| `install/cli.md` | Coder CLI | Installing Coder | **Install the Coder
CLI** |
| `ai-gateway/clients/jetbrains.md` | JetBrains | JetBrains IDEs |
**JetBrains** |
| `workspace-access/web-ides.md` | Web IDEs and Coder Apps | Web IDEs |
Web IDEs *(kept — primary user guide)* |
| `extending-templates/web-ides.md` | Web IDEs and Coder Apps | Web IDEs
| **Web IDEs in templates** |
| `workspace-management.md` | Workspace Management | Workspaces |
**Manage workspaces** *(vs generated `api/workspaces.md`)* |

These titles are the only non-mechanical editorial calls in this PR.

## Deliberately excluded: generated pages

`admin/security/audit-logs.md` and
`admin/setup/configuration-reference.md` are `make gen` outputs
(`auditdocgen` / `configdocgen`) that Phase 2 did **not** update, so a
hand-added title would be reverted on the next generation. They're
excluded here and need their generators taught to emit front matter
first (Phase 2 pattern), tracked as `DOCS-631`. Batch A (#28030) had the
same issue for three other generated pages; it has been corrected there
too.

## Verification

AI was the primary author of this PR (see disclosure below); per the [AI
Contribution
Guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING)
here is the manual verification.

- Promote = set front-matter `title` to the body H1 (or the
disambiguated title above) and remove that one duplicate H1. No other
body prose is reflowed.
- Every added front-matter block parses as YAML; all files pass `pnpm
check-docs` (markdownlint-cli2 + table formatter): `Summary: 0
error(s)`.
- Removing the H1 orphaned one in-page fragment (`[MCP](#mcp)` in
`ai-gateway/mcp.md`), now repointed. A cross-file fragment audit into
the retitled pages found no real breakage.


Anchor-change note

Unlike Batch A (title unchanged, a rendered no-op), Batch B changes each
page's effective title from the manifest label to the body H1, so the
rendered H1 **anchor slug changes**. An audit of cross-file
`.md#fragment` links into these pages surfaced no links that break as a
result (the only hits were false positives against a still-present `##
TLS & Reverse Proxy` heading). Same-file fragments are enforced by
markdownlint MD051, which is green.

## Title casing (follow-up, DOCS-742)

A follow-up commit puts the promoted titles into sentence case and
removes leading gerunds (for example, `Managing workspace schedules` →
`Manage workspace schedules`): 57 of the 120 titles changed, the other
63 were already compliant. Proper nouns and branded names (Coder
Validated Architecture, JetBrains, File Browser, Dev Containers,
Island), acronyms (API, CLI, IDE, MCP, OIDC, URL, UI, CI/CD), the
Premium license tier, and maturity labels (Beta, Experimental) are
preserved. The four `Nk-users` pages become `Reference architecture: up
to N users` (lowercase, matching the CVA landing page's own usage); the
CVA landing page keeps its branded title. `pnpm check-docs`: `Summary: 0
error(s)`.

Linear: DOCS-484, DOCS-742

> This PR was created with AI assistance (Coder Agents).
2026-09-08 16:34:00 +00:00

4.8 KiB
Raw Blame History

title
title
Microsoft Azure

This guide shows you how to set up the Coder server on Azure which will provision Azure-hosted Linux workspaces.

Requirements

This guide assumes you have full administrator privileges on Azure.

Create An Azure VM

From the Azure Portal, navigate to the Virtual Machines Dashboard. Select Create to create a new Azure virtual machine.

Azure VM creation page

This will bring you to the Create a virtual machine page. Select the subscription group of your choice, or create one if necessary.

Next, name the VM something relevant to this project using the naming convention 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.

Azure VM instance details Azure VM size selection

Up next, under Inbound port rules modify the Select inbound ports to also take in HTTPS and HTTP.

Azure VM inbound port rules

The set up for the image is complete at this stage. Select Review and Create, review the information, and select Create. A popup will appear asking you to download the key pair for the server. Select Download private key and create resource and place it into a folder of your choice on your local system.

Azure VM key pair generation

Select Return to create a virtual machine. Your VM will start up.

Azure VM deployment complete

Select 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.

Follow these instructions to SSH into the virtual machine. Once on the VM, you can run and install Coder using your method of choice. For the fastest install, we recommend running Coder as a system service.

Install Coder

For this instance, we will run Coder as a system service, however you can run Coder a multitude of different ways. You can learn more about those here.

In the Azure VM instance, run the following command to install Coder

curl -fsSL https://coder.com/install.sh | sh

Run Coder

Run the following command to start Coder as a system level service:

sudo systemctl enable --now coder

The following command will get you information about the Coder launch service

journalctl -u coder.service -b

This will return a series of logs related to running Coder as a system service. Embedded in the logs is the Coder Access URL.

Copy the URL and run the following command to create the first user, either on your local machine or in the instance terminal.

coder login <url***.try.coder.app>

Fill out the prompts. Be sure to save use email and password as these are your admin username and password.

You can now access Coder on your local machine with the relevant ***.try.coder.app URL and logging in with the username and password.

Creating and Uploading Your First Template

First, run coder template init to create your first template. You’ll be given 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.

Coder CLI template init

Press enter to select Develop in Linux on Azure template. This will return the following:

Coder CLI template init

To get started using the Azure template, install the Azure CLI by following the instructions here. Run az login and follow the instructions to configure the Azure command line.

Coder is running as a system service, which creates the system user coder for handling processes. The Coder user will require access to the Azure credentials to initialize the template.

Run the following commands to copy the Azure credentials and give the coder user access to them:

sudo cp -r ~/.azure /home/coder/.azure
sudo chown -R coder:coder /home/coder/.azure/

Navigate to the ./azure-linux folder where you created your template and run the following command to put the template on your Coder instance.

coder templates push

Congrats! You can now navigate to your Coder dashboard and use this Linux on Azure template to create a new workspace!