synced/coder
1
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2025-07-21 01:28:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: restructure docs (#14421)

Browse Source 
Closes #13434 
Supersedes #14182

---------

Co-authored-by: Ethan <39577870+ethanndickson@users.noreply.github.com>
Co-authored-by: Ethan Dickson <ethan@coder.com>
Co-authored-by: Ben Potter <ben@coder.com>
Co-authored-by: Stephen Kirby <58410745+stirby@users.noreply.github.com>
Co-authored-by: Stephen Kirby <me@skirby.dev>
Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com>
This commit is contained in:
Muhammad Atif Ali
2024-10-05 08:52:04 -07:00
committed by GitHub
parent 288df75686
commit 419eba5fb6
298 changed files with 5009 additions and 3889 deletions
Download Patch File Download Diff File Expand all files Collapse all files

187
docs/start/coder-tour.md Normal file
View File

@ -0,0 +1,187 @@
## 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
<div class="tabs">
## 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
```
</div>
## 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.
![Coder login screen](../images/start/setup-page.png)
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**.
![Starter Templates UI](../images/start/starter-templates-annotated.png)
> 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**.
![Creating a template](../images/start/create-template.png)
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**.
![Template Preview](../images/start/template-preview.png)
In **New workspace**, fill in **Name** then scroll down to select **Create
Workspace**.
![Create Workspace](../images/start/create-workspace.png)
Coder starts your new workspace from your template.
After a few seconds, your workspace is ready to use.
![Workspace is ready](../images/start/workspace-ready.png)
## 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.
![Selecting the first template](../images/templates/select-template.png)
In the drop-down menu, select **Edit files**.
![Edit template files](../images/templates/edit-files.png)
Expand the **build** directory and select **Dockerfile**.
![Selecting source code](../images/templates/source-code.png)
Edit `build/Dockerfile` to replace `golang` with `python3`.
![Editing source code](../images/templates/edit-source-code.png)
Select **Build template** and wait for Coder to prepare the template for
workspaces.
![Building a template](../images/templates/build-template.png)
Select **Publish version**. In the **Publish new version** dialog, make sure
**Promote to default version** is checked then select **Publish**.
![Publish a template](../images/templates/publish.png)
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.

129
docs/start/first-template.md Normal file
View File

@ -0,0 +1,129 @@
# 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.
## Before you start
Use the [previous section](./local-deploy.md) of this guide to set up
[Docker](https://docs.docker.com/get-docker/) and [Coder](../install/cli.md) on
your local machine to continue.
## 1. Log in to Coder
In your web browser, go to your Coder dashboard using the URL provided during
setup to log in.
## 2. Choose a starter template
Select **Templates** to see the **Starter Templates**. Use the **Docker
Containers** template by pressing **Use Template**.
![Starter Templates UI](../images/start/starter-templates.png)
> You can also a find a comprehensive list of starter templates in **Templates**
> -> **Create Template** -> **Starter Templates**. s
## 3. Create your template
In **Create template**, fill in **Name** and **Display name**, then select
**Create template**.
![Creating a template](../images/start/create-template.png)
TODO:
- add CLI guide for making a new template
- refactor text below to be more beginner-friendly
<!-- ## 4. Create a workspace from your template
When the template is ready, select **Create Workspace**.
![Template Preview](../images/start/template-preview.png)
In **New workspace**, fill in **Name** then scroll down to select **Create
Workspace**.
![Create Workspace](../images/start/create-workspace.png)
Coder starts your new workspace from your template.
After a few seconds, your workspace is ready to use.
![Workspace is ready](../images/templates/workspace-ready.png)
## 5. Try out your new workspace
This starter template lets you connect to your workspace in a few ways:
- VS Code Desktop: Loads your workspace into
[VS Code Desktop](https://code.visualstudio.com/Download) installed on your
local computer.
- code-server: Opens [browser-based VS Code](../ides/web-ides.md) with your
workspace.
- Terminal: Opens a browser-based terminal with a shell in the workspace's
Docker instance.
- SSH: Use SSH to log in to the workspace from your local machine. If you
haven't already, you'll have to install Coder on your local machine to
configure your SSH client.
> **Tip**: You can edit the template to let developers connect to a workspace in
> [a few more ways](../ides.md).
When you're done, you can stop the workspace. -->
## 6. Modify your template
Now you can modify your template to suit your team's needs.
Let's replace the `golang` package in the Docker image with the `python3`
package. You can do this by editing the template's `Dockerfile` directly in your
web browser.
In the Coder dashboard, select **Templates** then your first template.
![Selecting the first template](../images/templates/select-template.png)
In the drop-down menu, select **Edit files**.
![Edit template files](../images/templates/edit-files.png)
Expand the **build** directory and select **Dockerfile**.
![Selecting source code](../images/templates/source-code.png)
Edit `build/Dockerfile` to replace `golang` with `python3`.
![Editing source code](../images/templates/edit-source-code.png)
Select **Build template** and wait for Coder to prepare the template for
workspaces.
![Building a template](../images/templates/build-template.png)
Select **Publish version**. In the **Publish new version** dialog, make sure
**Promote to active version** is checked then select **Publish**.
![Publish a template](../images/templates/publish.png)
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.
## Next steps
- [Setting up templates](../admin/templates/creating-templates.md)

66
docs/start/first-workspace.md Normal file
View File

@ -0,0 +1,66 @@
# Creating your first coder workspace
A workspace is the environment that a developer works in. Developers in a team
each work from their own workspace and can use
[multiple IDEs](../user-guides/workspace-access/index.md).
A developer creates a workspace from a
[shared template](../admin/templates/index.md). This lets an entire team work in
environments that are identically configured and provisioned with the same
resources.
## Before you begin
This guide will use the Docker template from the
[previous step](../tutorials/template-from-scratch.md) to create and connect to
a Coder workspace.
## 1. Create a workspace from your template through the GUI
You can create a workspace in the UI. Log in to your Coder instance, go to the
**Templates** tab, find the template you need, and select **Create Workspace**.
![Template Preview](../images/start/template-preview.png)
In **New workspace**, fill in **Name** then scroll down to select **Create
Workspace**.
![Create Workspace](../images/start/create-workspace.png)
Coder starts your new workspace from your template.
After a few seconds, your workspace is ready to use.
![Workspace is ready](../images/start/workspace-ready.png)
## 2. Try out your new workspace
The Docker starter template lets you connect to your workspace in a few ways:
- VS Code Desktop: Loads your workspace into
[VS Code Desktop](https://code.visualstudio.com/Download) installed on your
local computer.
- code-server: Opens
[browser-based VS Code](../user-guides/workspace-access/web-ides.md#code-server)
with your workspace.
- Terminal: Opens a browser-based terminal with a shell in the workspace's
Docker instance.
- JetBrains Gateway: Opens JetBrains IDEs via JetBrains Gateway.
- 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/extending-templates/web-ides.md).
## 3. Modify your workspace settings
Developers can modify attributes of their workspace including update policy,
scheduling, and parameters which define their development environment.
Once you're finished, you can stop your workspace.
## Next Steps
- Creating workspaces with the [CLI](../reference/cli/create.md)
- Creating workspaces with the [API](../reference/api/workspaces.md)

66
docs/start/local-deploy.md Normal file
View File

@ -0,0 +1,66 @@
## Setting up a Coder deployment
For day-zero Coder users, we recommend following this guide to set up a local
Coder deployment from our
[open source repository](https://github.com/coder/coder).
We'll use [Docker](https://docs.docker.com/engine) to manage the compute for a
slim deployment to experiment with [workspaces](../user-guides/index.md) and
[templates](../admin/templates/index.md).
Docker is not necessary for every Coder deployment and is only used here for
simplicity.
### Install Coder daemon
First, install [Docker](https://docs.docker.com/engine/install/) locally.
> If you already have the Coder binary installed, restart it after installing
> Docker.
<div class="tabs">
## 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
```
</div>
### Start the server
To start or restart the Coder deployment, use the following command:
```shell
coder server
```
The output will provide you with an access URL to create your first
administrator account.
![Coder login screen](../images/start/setup-page.png)
Once you've signed in, you'll be brought to an empty workspaces page, which
we'll soon populate with your first development environments.
### Next steps
TODO: Add link to next page.

59
docs/start/screenshots.md Normal file
View File

@ -0,0 +1,59 @@
# Screenshots
## Log in
![Install Coder in your cloud or air-gapped on-premises. Developers simply log in via their browser to access their Workspaces.](../images/screenshots/login.png)
Install Coder in your cloud or air-gapped on-premises. Developers simply log in
via their browser to access their Workspaces.
## Templates
![Developers provision their own ephemeral Workspaces in minutes using pre-defined Templates that include approved tooling and infrastructure.](../images/screenshots/templates_listing.png)
Developers provision their own ephemeral Workspaces in minutes using pre-defined
Templates that include approved tooling and infrastructure.
![Template administrators can either create a new Template from scratch or choose a Starter Template](../images/screenshots/starter_templates.png)
Template administrators can either create a new Template from scratch or choose
a Starter Template.
![Templates define the underlying infrastructure that Coder Workspaces run on.](../images/screenshots/terraform.png)
Template administrators build Templates using Terraform. Templates define the
underlying infrastructure that Coder Workspaces run on.
## Workspaces
![Developers create and delete their own workspaces. Coder administrators can easily enforce Workspace scheduling and autostop policies to ensure idle Workspaces don’t burn unnecessary cloud budget.](../images/screenshots/workspaces_listing.png)
Developers create and delete their own workspaces. Coder administrators can
easily enforce Workspace scheduling and autostop policies to ensure idle
Workspaces don’t burn unnecessary cloud budget.
![Developers launch their favorite web-based or desktop IDE, browse files, or access their Workspace’s Terminal.](../images/screenshots/workspace_launch.png)
Developers launch their favorite web-based or desktop IDE, browse files, or
access their Workspace’s Terminal.
## Administration
![Coder administrators can access Template usage insights to understand which Templates are most popular and how well they perform for developers.](../images/screenshots/templates_insights.png)
Coder administrators can access Template usage insights to understand which
Templates are most popular and how well they perform for developers.
![Coder administrators can control *every* aspect of their Coder deployment.](../images/screenshots/settings.png)
Coder administrators can control _every_ aspect of their Coder deployment.
![Coder administrators and auditor roles can review how users are interacting with their Coder Workspaces and Templates.](../images/screenshots/audit.png)
Coder administrators and auditor roles can review how users are interacting with
their Coder Workspaces and Templates.
![Coder administrators can monitor the health of their Coder deployment, including database latency, active provisioners, and more.](../images/screenshots/healthcheck.png)
Coder administrators can monitor the health of their Coder deployment, including
database latency, active provisioners, and more.

3
docs/start/why-coder.md Normal file
View File

@ -0,0 +1,3 @@
# Why use Coder
TODO: Make this page!