diff --git a/docs/README.md b/docs/README.md
index 71fb99d1f50b1..1cf9b61679a4d 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -143,3 +143,4 @@ or [the v2 migration guide and FAQ](https://coder.com/docs/v1/guides/v2-faq).
- Learn about [Templates](./admin/templates/index.md)
- [Install Coder](./install/index.md)
+- Follow the [Quickstart guide](./tutorials/quickstart.md) to try Coder out for yourself.
diff --git a/docs/admin/templates/managing-templates/index.md b/docs/admin/templates/managing-templates/index.md
index 56e57239759e7..bee246b82f3d5 100644
--- a/docs/admin/templates/managing-templates/index.md
+++ b/docs/admin/templates/managing-templates/index.md
@@ -1,8 +1,8 @@
# Working with templates
-You create and edit Coder templates as [Terraform](../../../start/coder-tour.md)
-configuration files (`.tf`) and any supporting files, like a README or
-configuration files for other services.
+You create and edit Coder templates as
+[Terraform](../../../tutorials/quickstart.md) configuration files (`.tf`) and
+any supporting files, like a README or configuration files for other services.
## Who creates templates?
diff --git a/docs/images/screenshots/create-template.png b/docs/images/screenshots/create-template.png
new file mode 100644
index 0000000000000..e442a8557c42b
Binary files /dev/null and b/docs/images/screenshots/create-template.png differ
diff --git a/docs/images/screenshots/welcome-create-admin-user.png b/docs/images/screenshots/welcome-create-admin-user.png
new file mode 100644
index 0000000000000..2d4c0b9bb7835
Binary files /dev/null and b/docs/images/screenshots/welcome-create-admin-user.png differ
diff --git a/docs/images/screenshots/workspace-running-with-topbar.png b/docs/images/screenshots/workspace-running-with-topbar.png
new file mode 100644
index 0000000000000..ab3f6a78a9e6e
Binary files /dev/null and b/docs/images/screenshots/workspace-running-with-topbar.png differ
diff --git a/docs/install/index.md b/docs/install/index.md
index e63fda15eb385..2cf32f9fde85c 100644
--- a/docs/install/index.md
+++ b/docs/install/index.md
@@ -64,5 +64,5 @@ coder login https://coder.example.com
## Next steps
-- [Set up your first deployment](../start/coder-tour.md)
+- [Set up your first deployment](../tutorials/quickstart.md)
- [Expose your control plane to other users](../admin/setup/index.md)
diff --git a/docs/manifest.json b/docs/manifest.json
index a3ebdf9b98987..d6a0186b6af3d 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -8,9 +8,9 @@
"icon_path": "./images/icons/home.svg",
"children": [
{
- "title": "Tour Coder",
- "description": "Tour Coder by creating a deployment with Docker",
- "path": "./start/coder-tour.md"
+ "title": "Coder quickstart",
+ "description": "Try it out for yourself",
+ "path": "./tutorials/quickstart.md"
},
{
"title": "Screenshots",
@@ -634,6 +634,11 @@
"path": "./tutorials/index.md",
"icon_path": "./images/icons/generic.svg",
"children": [
+ {
+ "title": "Get started with Coder",
+ "description": "Learn how to install and run Coder quickly",
+ "path": "./tutorials/quickstart.md"
+ },
{
"title": "Write a Template from Scratch",
"description": "Learn how to author Coder templates",
diff --git a/docs/start/coder-tour.md b/docs/start/coder-tour.md
deleted file mode 100644
index bec0ccdece40b..0000000000000
--- a/docs/start/coder-tour.md
+++ /dev/null
@@ -1,187 +0,0 @@
-## Tour Coder and Set up your first deployment.
-
-For day-zero Coder users, we recommend following this guide to set up a local
-Coder deployment, create your first template, and connect to a workspace. This
-is completely free and leverages 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/index.md) and
-[templates](../admin/templates/index.md).
-
-Docker is not necessary for every Coder deployment and is only used here for
-simplicity.
-
-# Set up your Coder Deployment
-
-## 1. Install Docker
-
-First, install [Docker](https://docs.docker.com/engine/install/) locally.
-
-> If you already have the Coder binary installed, restart it after installing
-> Docker.
-
-## 2. Install Coder daemon
-
-
-
-## 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](../user-guides/workspace-access/vscode.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](../admin/templates/managing-templates/devcontainers.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](../admin/templates/managing-templates/change-management.md)
-through your own repo and continuous integration.
diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md
index 40d842685df44..b849120f8497e 100644
--- a/docs/tutorials/index.md
+++ b/docs/tutorials/index.md
@@ -6,5 +6,5 @@ Enterprise. These tutorials are hosted on our
request new topics to be covered.
- This page is rendered on https://coder.com/docs/guides. Refer to the other documents in the `guides/` directory for specific employee-written guides.
+ This page is rendered on . Refer to the other documents in the `docs/tutorials/` directory for specific employee-written guides.
diff --git a/docs/tutorials/quickstart.md b/docs/tutorials/quickstart.md
new file mode 100644
index 0000000000000..c5db4a7627848
--- /dev/null
+++ b/docs/tutorials/quickstart.md
@@ -0,0 +1,240 @@
+# Get started with Coder
+
+
+September 23, 2024
+
+---
+
+Follow the steps in this guide to install Coder locally or on a cloud-hosting
+provider, set up a workspace, and connect to it from VS Code.
+
+By the end of this guide, you'll have a remote development environment that you
+can connect to from any device anywhere, so you can work on the same files in a
+persistent environment from your main device, a tablet, or your phone.
+
+## Install and start Coder
+
+
+
+## Linux/macOS
+
+1. Install Docker:
+
+ ```bash
+ curl -sSL https://get.docker.com | sh
+ ```
+
+ For more details, visit:
+
+ - [Linux instructions](https://docs.docker.com/desktop/install/linux-install/)
+ - [Mac instructions](https://docs.docker.com/desktop/install/mac-install/)
+
+1. Assign your user to the Docker group:
+
+ ```shell
+ sudo usermod -aG docker $USER
+ ```
+
+1. Run `newgrp` to activate the groups changes:
+
+ ```shell
+ newgrp docker
+ ```
+
+ You might need to log out and back in or restart the machine for changes to
+ take effect.
+
+1. Install Coder:
+
+ ```shell
+ curl -L https://coder.com/install.sh | sh
+ ```
+
+ - For standalone binaries, system packages, or other alternate installation
+ methods, refer to the
+ [latest release on GitHub](https://github.com/coder/coder/releases/latest).
+
+1. Start Coder:
+
+ ```shell
+ coder server
+ ```
+
+## Windows
+
+> **Important:** If you plan to use the built-in PostgreSQL database, 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.
+
+1. [Install Docker](https://docs.docker.com/desktop/install/windows-install/).
+
+1. 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
+ ```
+
+1. Start Coder:
+
+ ```shell
+ coder server
+ ```
+
+
+
+## Configure Coder with a new Workspace
+
+1. If you're running Coder locally, go to .
+
+ - If you get a browser warning similar to `Secure Site Not Available`, you
+ can ignore the warning and continue to the setup page.
+
+ If your Coder server is on a network or cloud device, locate the message in
+ your terminal that reads,
+ `View the Web UI: https://..try.coder.app`. The server
+ begins to stream logs immediately and you might have to scroll up to find it.
+
+1. On the **Welcome to Coder** page, enter the information to create an admin
+ user, then select **Create account**.
+
+ _Welcome
+ to Coder - Create admin user_
+
+1. On the **Workspaces** page, select **Go to templates** to create a new
+ template.
+
+1. For this guide, use a Docker container. Locate **Docker Containers** and
+ select **Use template**.
+
+1. Give the template a **Name** that you'll recognize both in the Coder UI and
+ in command-line calls.
+
+ The rest of the template details are optional, but will be helpful when you
+ have more templates.
+
+ _Create
+ template_
+
+1. Select **Create template**.
+
+1. After the template is ready, select **Create Workspace**.
+
+1. Give the workspace a name and select **Create Workspace**.
+
+1. Coder starts your new workspace:
+
+ _Workspace
+ is running_
+
+1. Select **VS Code Desktop** to install the Coder extension and connect to your
+ Coder workspace.
+
+## Work on some code
+
+After VS Code loads the remote environment, you can select **Open Folder** to
+explore directories in the Docker container or work on something new.
+
+To clone an existing repository:
+
+1. Select **Clone Repository** and enter the repository URL.
+
+ For example, to clone the Coder repo, enter
+ `https://github.com/coder/coder.git`.
+
+ Learn more about how to find the repository URL in the
+ [GitHub documentation](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository).
+
+1. Choose the folder to which VS Code should clone the repo. It will be in its
+ own directory within this folder.
+
+ Note that you cannot create a new parent directory in this step.
+
+1. After VS Code completes the clone, select **Open** to open the directory.
+
+1. You are now using VS Code in your Coder environment!
+
+## What's next?
+
+Now that you have your own workspace, use the same template to set one up for a
+teammate.
+
+Go to **Templates** and select **Create Workspace** and continue from Step 7 in
+[Configure Coder with a new workspace](#configure-coder-with-a-new-workspace).
+
+After that, you can try to:
+
+- [Customize templates](../admin/templates/extending-templates/index.md)
+- [Enable Prometheus metrics](../admin/integrations/prometheus.md)
+- [Deploy to Google Cloud Platform (GCP)](../install/cloud/compute-engine.md)
+
+## Troubleshooting
+
+### Cannot connect to the Docker daemon
+
+> Error: Error pinging Docker server: Cannot connect to the Docker daemon at
+> unix:///var/run/docker.sock. Is the docker daemon running?
+
+1. Install Docker for your system:
+
+ ```shell
+ curl -sSL https://get.docker.com | sh
+ ```
+
+1. Set up the Docker daemon in rootless mode for your user to run Docker as a
+ non-privileged user:
+
+ ```shell
+ dockerd-rootless-setuptool.sh install
+ ```
+
+ Depending on your system's dependencies, you might need to run other commands
+ before you retry this step. Read the output of this command for further
+ instructions.
+
+1. Assign your user to the Docker group:
+
+ ```shell
+ sudo usermod -aG docker $USER
+ ```
+
+1. Confirm that the user has been added:
+
+ ```console
+ $ groups
+ docker sudo users
+ ```
+
+ - Ubuntu users might not see the group membership update. In that case, run
+ the following command or reboot the machine:
+
+ ```shell
+ newgrp docker
+ ```
+
+### Can't start Coder server: Address already in use
+
+```shell
+Encountered an error running "coder server", see "coder server --help" for more information
+error: configure http(s): listen tcp 127.0.0.1:3000: bind: address already in use
+```
+
+1. Stop the process:
+
+ ```shell
+ sudo systemctl stop coder
+ ```
+
+1. Start Coder:
+
+ ```shell
+ coder server
+ ```