opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-24 15:04:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: reorganize template docs (#10297)

Browse Source 
* docs: rework our "templates" section

* wikistuff

* fix formatting

* add diagram

* reorganize some things

* docs: improve workspaces and templates doc (#9139)

* Reorg, updated/new screenshots, consistent terminology

* First pass

* Another pass

* Added integration section

* New outline for template pages, small updates

* Revised outline for templates, added tutorial

* First pass at tutorial

* Some feedback from Ben.

* Update docs/workspaces.md

Co-authored-by: Muhammad Atif Ali <matifali@live.com>

* Update docs/workspaces.md

Co-authored-by: Muhammad Atif Ali <matifali@live.com>

* Update docs/workspaces.md

Co-authored-by: Muhammad Atif Ali <matifali@live.com>

* Fixed typos

* Expanded tutorial

I have read the CLA Document and I hereby sign the CLA

* New screenshots, improved tutorial, revised anatomy

* Improved tutorial. Anatomy is now a guided tour.

* First pass at guided tour

* Updated authentication info

* Reorganized the guided tour

* Edited more template pages

* Update docs/templates/tour.md

Co-authored-by: Muhammad Atif Ali <matifali@live.com>

* Update docs/templates/tour.md

Co-authored-by: Muhammad Atif Ali <matifali@live.com>

* Update docs/templates/tour.md

Co-authored-by: Muhammad Atif Ali <matifali@live.com>

* Update docs/templates/tutorial.md

Co-authored-by: Muhammad Atif Ali <matifali@live.com>

* Update docs/templates/tour.md

Co-authored-by: Muhammad Atif Ali <matifali@live.com>

* Update docs/templates/tour.md

Co-authored-by: Muhammad Atif Ali <matifali@live.com>

* Update docs/templates/tour.md

Co-authored-by: Muhammad Atif Ali <matifali@live.com>

* Update docs/templates/tour.md

Co-authored-by: Muhammad Atif Ali <matifali@live.com>

* Update docs/templates/tour.md

Co-authored-by: Muhammad Atif Ali <matifali@live.com>

* Revised devcontainers and docker-in-workspaces

* Edited and added screenshots

* Prepared first draft, except docs/templates/open-in-coder.md

* Fix typo

* remove legacy parameters and migration guide

* Use coder templates create

* Added screenshot for workspace template variables

* Made it prettier

* Fixed minor typos and markdown problems

* edits to repairing workspaces

* fix broken links in product

* Added troubleshooting, minor corrections.

* fix terminal links

* fmt

---------

Co-authored-by: Muhammad Atif Ali <matifali@live.com>
Co-authored-by: Ben Potter <me@bpmct.net>
Co-authored-by: Atif Ali <atif@coder.com>

* make fmt

* fix merge conflict

* make fmt

* make gen

* update

* lint

* Discard changes to coderd/database/queries.sql.go

* Discard changes to cli/templates.go

* Discard changes to cli/templateversionarchive.go

* Discard changes to cli/templateversions.go

* Update docker-in-workspaces.md

* replace ```sh with ```shell

* open-in-coder

* fmt

* mention coder_metadata in icons.md

* resource_metadata

* use shell

* modules.md

* mention coder registry module

* workspace.md

* resource_metadata

* remove duplication

* address comments

* cleanup

* fmt

* fix broken links

* fix numbering

* mention module registry

* add example

* demote heading

* remove top level entry from manifest

* fmt

---------

Co-authored-by: Ben <me@bpmct.net>
Co-authored-by: Marc Paquette <22124737+marcpaq@users.noreply.github.com>
This commit is contained in:
Muhammad Atif Ali
2023-10-17 14:47:12 +00:00
committed by GitHub
co-authored by Muhammad Atif Ali Ben Potter Marc Paquette
parent b5e5b39de2
commit a49e6b88f9
56 changed files with 1438 additions and 1143 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/workspaces.md
+111 -68
View File
@@ -1,9 +1,25 @@
# Workspaces
Workspaces contain the IDEs, dependencies, and configuration information needed
for software development.
A workspace is the environment that a developer works in. Developers in a team
each work from their own workspace and can use [multiple IDEs](./ides.md).
## Create workspaces
A developer creates a workspace from a [shared template](./templates/index.md).
This lets an entire team work in environments that are identically configured
and provisioned with the same resources.
## Creating workspaces
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**.
![Creating a workspace in the UI](./images/creating-workspace-ui.png)
When you create a workspace, you will be prompted to give it a name. You might
also be prompted to set some parameters that the template provides.
You can manage your existing templates in the **Workspaces** tab.
You can also create a workspace from the command line:
Each Coder user has their own workspaces created from
[shared templates](./templates/index.md):
@@ -16,11 +32,72 @@ coder create --template="<templateName>" <workspaceName>
coder show <workspace-name>
```
## IDEs
## Workspace filtering
Coder [supports multiple IDEs](./ides.md) for use with your workspaces.
In the Coder UI, you can filter your workspaces using pre-defined filters or
Coder's filter query. For example, you can find the workspaces that you own or
that are currently running.
## Workspace lifecycle
The following filters are supported:
- `owner` - Represents the `username` of the owner. You can also use `me` as a
convenient alias for the logged-in user.
- `template` - Specifies the name of the template.
- `status` - Indicates the status of the workspace. For a list of supported
statuses, see
[WorkspaceStatus documentation](https://pkg.go.dev/github.com/coder/coder/codersdk#WorkspaceStatus).
## Starting and stopping workspaces
By default, you manually start and stop workspaces as you need. You can also
schedule a workspace to start and stop automatically.
To set a workspace's schedule, go to the workspace, then **Settings** >
**Schedule**.
![Scheduling UI](./images/schedule.png)
Coder might also stop a workspace automatically if there is a
[template update](./templates/index.md#Start/stop) available.
### Autostart and autostop
Use autostart to start a workspace at a specified time and which days of the
week. Also, you can choose your preferred timezone.
![Autostart UI](./images/autostart.png)
Use autostop to stop a workspace after a number of hours. Autostop won't stop a
workspace if you're still using it. It waits for another hour before checking
again. Coder checks for active connections in the IDE, SSH, Port Forwarding, and
coder_app.
![Autostop UI](./images/autostop.png)
### Max lifetime
Max lifetime is a template setting that determines the number of hours a
workspace will run before Coder automatically stops it, regardless of any active
connections. Use this setting to ensure that workspaces do not run in perpetuity
when connections are left open inadvertently.
## Updating workspaces
After updating the default version of the template that a workspace was created
from, you can update the workspace.
![Updating a workspace](./images/workspace-update.png)
If the workspace is running, Coder stops it, updates it, then starts the
workspace again.
On the command line:
```shell
coder update <workspace-name>
```
## Workspace resources
Workspaces in Coder are started and stopped, often based on whether there was
any activity or if there was a
@@ -33,53 +110,13 @@ though the exact behavior depends on the template. For more information, see
> ⚠️ To avoid data loss, refer to your template documentation for information on
> where to store files, install software, etc., so that they persist. Default
> templates are documented in
> [../examples/templates](https://github.com/coder/coder/tree/c6b1daabc5a7aa67bfbb6c89966d728919ba7f80/examples/templates).
> [../examples/templates](https://github.com/coder/coder/tree/main/examples/templates).
>
> You can use `coder show <workspace-name>` to see which resources are
> persistent and which are ephemeral.
When a workspace is deleted, all of the workspace's resources are deleted.
## Workspace scheduling
By default, workspaces are manually turned on/off by the user. However, a
schedule can be defined on a per-workspace basis to automate the workspace
start/stop.
![Scheduling UI](./images/schedule.png)
### Autostart
The autostart feature automates the workspace build at a user-specified time and
day(s) of the week. In addition, users can select their preferred timezone.
![Autostart UI](./images/autostart.png)
### Autostop
The autostop feature shuts off workspaces after given number of hours in the
"on" state. If Coder detects workspace connection activity, the autostop timer
is bumped up one hour. IDE, SSH, Port Forwarding, and coder_app activity trigger
this bump.
![autostop UI](./images/autostop.png)
### Max lifetime
Max lifetime is a template-level setting that determines the number of hours a
workspace can run before it is automatically shutdown, regardless of any active
connections. This setting ensures workspaces do not run in perpetuity when
connections are left open inadvertently.
## Updating workspaces
Use the following command to update a workspace to the latest template version.
The workspace will be stopped and started:
```shell
coder update <workspace-name>
```
## Repairing workspaces
Use the following command to re-enter template input variables in an existing
@@ -90,6 +127,33 @@ state is out of sync with the template.
coder update <your workspace name> --always-prompt
```
First, try re-entering parameters from a workspace. In the Coder UI, you can
filter your workspaces using pre-defined filters or employing the Coder's filter
query. Take a look at the following examples to understand how to use the
Coder's filter query:
- To find the workspaces that you own, use the filter `owner:me`.
- To find workspaces that are currently running, use the filter
`status:running`.
![Re-entering template variables](./images/template-variables.png)
You can also do this in the CLI with the following command:
```shell
coder update <your workspace name> --always-prompt
```
If that does not work, a Coder admin can manually push and pull the Terraform
state for a given workspace. This can lead to state corruption or deleted
resources if you do not know what you are doing.
```shell
coder state pull <username>/<workspace name>
# Make changes
coder state push <username>/<workspace name>
```
## Logging
Coder stores macOS and Linux logs at the following locations:
@@ -102,27 +166,6 @@ Coder stores macOS and Linux logs at the following locations:
> Note: Logs are truncated once they reach 5MB in size.
## Workspace filtering
In the Coder UI, you can filter your workspaces using pre-defined filters or
employing the Coder's filter query. Take a look at the following examples to
understand how to use the Coder's filter query:
- To find the workspaces that you own, use the filter `owner:me`.
- To find workspaces that are currently running, use the filter
`status:running`.
The following filters are supported:
- `owner` - Represents the `username` of the owner. You can also use `me` as a
convenient alias for the logged-in user.
- `template` - Specifies the name of the template.
- `status` - Indicates the status of the workspace. For a list of supported
statuses, please refer to the
[WorkspaceStatus documentation](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#WorkspaceStatus).
---
## Up next
- Learn about how to personalize your workspace with [Dotfiles](./dotfiles.md)