mirror of https://github.com/coder/coder.git
docs: make it clear the CLI must be downloaded to use templates (#5373)
This commit is contained in:
parent
4fc4c01cea
commit
8df02f42c0
|
@ -66,7 +66,7 @@ curl -L https://coder.com/install.sh | sh -s -- --help
|
|||
|
||||
Once installed, you can start a production deployment<sup>1</sup> with a single command:
|
||||
|
||||
```sh
|
||||
```console
|
||||
# Automatically sets up an external access URL on *.try.coder.app
|
||||
coder server
|
||||
|
||||
|
|
|
@ -6,7 +6,7 @@ We recommend automating Coder deployments through the CLI. Examples include [upd
|
|||
|
||||
Long-lived tokens can be generated to perform actions on behalf of your user account:
|
||||
|
||||
```sh
|
||||
```console
|
||||
coder tokens create
|
||||
```
|
||||
|
||||
|
@ -15,7 +15,7 @@ coder tokens create
|
|||
You can use tokens with the CLI by setting the `--token` CLI flag or the `CODER_SESSION_TOKEN`
|
||||
environment variable.
|
||||
|
||||
```sh
|
||||
```console
|
||||
export CODER_URL=https://coder.example.com
|
||||
export CODER_SESSION_TOKEN=*****
|
||||
coder workspaces ls
|
||||
|
@ -25,7 +25,7 @@ coder workspaces ls
|
|||
|
||||
You can use tokens with the Coder's REST API using the `Coder-Session-Token` HTTP header.
|
||||
|
||||
```sh
|
||||
```console
|
||||
curl 'https://dev.coder.com/api/v2/workspaces' \
|
||||
-H 'Coder-Session-Token: *****'
|
||||
```
|
||||
|
|
|
@ -40,7 +40,7 @@ downloaded from Maven (https://repo1.maven.org/maven2) and store all data in the
|
|||
If you are using the built-in PostgreSQL deployment and need to use `psql` (aka
|
||||
the PostgreSQL interactive terminal), output the connection URL with the following command:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ coder server postgres-builtin-url
|
||||
$ psql "postgres://coder@localhost:49627/coder?sslmode=disable&password=feU...yI1"
|
||||
```
|
||||
|
@ -50,7 +50,7 @@ $ psql "postgres://coder@localhost:49627/coder?sslmode=disable&password=feU...yI
|
|||
If you've installed Coder via a [system package](../install/packages.md) Coder, you can
|
||||
configure the server by setting the following variables in `/etc/coder.d/coder.env`:
|
||||
|
||||
```sh
|
||||
```console
|
||||
# String. Specifies the external URL (HTTP/S) to access Coder.
|
||||
CODER_ACCESS_URL=https://coder.example.com
|
||||
|
||||
|
@ -78,7 +78,7 @@ CODER_TLS_KEY_FILE=
|
|||
|
||||
To run Coder as a system service on the host:
|
||||
|
||||
```sh
|
||||
```console
|
||||
# Use systemd to start Coder now and on reboot
|
||||
sudo systemctl enable --now coder
|
||||
|
||||
|
@ -88,7 +88,7 @@ journalctl -u coder.service -b
|
|||
|
||||
To restart Coder after applying system changes:
|
||||
|
||||
```sh
|
||||
```console
|
||||
sudo systemctl restart coder
|
||||
```
|
||||
|
||||
|
|
|
@ -24,7 +24,7 @@ Example callback URL: `https://coder.example.com/gitauth/primary-github/callback
|
|||
|
||||
Set the following environment variables to [configure the Coder server](./configure.md):
|
||||
|
||||
```sh
|
||||
```console
|
||||
CODER_GITAUTH_0_ID="primary-github"
|
||||
CODER_GITAUTH_0_TYPE=github|gitlab|azure-devops|bitbucket
|
||||
CODER_GITAUTH_0_CLIENT_ID=xxxxxx
|
||||
|
@ -36,7 +36,7 @@ CODER_GITAUTH_0_CLIENT_SECRET=xxxxxxx
|
|||
Custom authentication and token URLs should be
|
||||
used for self-managed Git provider deployments.
|
||||
|
||||
```sh
|
||||
```console
|
||||
CODER_GITAUTH_0_AUTH_URL="https://github.example.com/oauth/authorize"
|
||||
CODER_GITAUTH_0_TOKEN_URL="https://github.example.com/oauth/token"
|
||||
```
|
||||
|
@ -45,7 +45,7 @@ CODER_GITAUTH_0_TOKEN_URL="https://github.example.com/oauth/token"
|
|||
|
||||
Optionally, you can request custom scopes:
|
||||
|
||||
```sh
|
||||
```console
|
||||
CODER_GITAUTH_0_SCOPES="repo:read repo:write write:gpg_key"
|
||||
```
|
||||
|
||||
|
@ -55,7 +55,7 @@ Multiple providers are an Enterprise feature. [Learn more](../enterprise.md).
|
|||
|
||||
A custom regex can be used to match a specific repository or organization to limit auth scope. Here's a sample config:
|
||||
|
||||
```sh
|
||||
```console
|
||||
# Provider 1) github.com
|
||||
CODER_GITAUTH_0_ID=primary-github
|
||||
CODER_GITAUTH_0_TYPE=github
|
||||
|
@ -75,6 +75,6 @@ CODER_GITAUTH_1_TOKEN_URL="https://github.example.com/oauth/token"
|
|||
|
||||
To support regex matching for paths (e.g. github.com/orgname), youll need to add this to the [Coder agent startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script):
|
||||
|
||||
```sh
|
||||
```console
|
||||
git config --global credential.useHttpPath true
|
||||
```
|
||||
|
|
|
@ -12,7 +12,7 @@ The Prometheus endpoint address is `http://localhost:2112/` by default. You can
|
|||
|
||||
If `coder server --prometheus-enable` is started locally, you can preview the metrics endpoint in your browser or by using curl: <!-- markdown-link-check-disable -->http://localhost:2112/<!-- markdown-link-check-enable -->.
|
||||
|
||||
```shell
|
||||
```console
|
||||
$ curl http://localhost:2112/
|
||||
# HELP coderd_api_active_users_duration_hour The number of users that have been active within the last hour.
|
||||
# TYPE coderd_api_active_users_duration_hour gauge
|
||||
|
|
|
@ -38,7 +38,7 @@ resource "coder_app" "portainer" {
|
|||
|
||||
[code-server](https://github.com/coder/coder) is our supported method of running VS Code in the web browser. A simple way to install code-server in Linux/macOS workspaces is via the Coder agent in your template:
|
||||
|
||||
```sh
|
||||
```console
|
||||
# edit your template
|
||||
cd your-template/
|
||||
vim main.tf
|
||||
|
|
|
@ -4,7 +4,7 @@ Coder publishes self-contained .zip and .tar.gz archives in [GitHub releases](ht
|
|||
|
||||
1. Unzip the folder you just downloaded, and move the `coder` executable to a location that's on your `PATH`
|
||||
|
||||
```sh
|
||||
```console
|
||||
# ex. macOS and Linux
|
||||
mv coder /usr/local/bin
|
||||
```
|
||||
|
@ -13,7 +13,7 @@ Coder publishes self-contained .zip and .tar.gz archives in [GitHub releases](ht
|
|||
|
||||
1. Start a Coder server
|
||||
|
||||
```sh
|
||||
```console
|
||||
# Automatically sets up an external access URL on *.try.coder.app
|
||||
coder server
|
||||
|
||||
|
|
|
@ -22,7 +22,7 @@ CREATE DATABASE coder;
|
|||
Coder configuration is defined via [environment variables](../admin/configure.md).
|
||||
The database client requires the connection string provided via the `CODER_PG_CONNECTION_URL` variable.
|
||||
|
||||
```sh
|
||||
```console
|
||||
export CODER_PG_CONNECTION_URL="postgres://coder:secret42@localhost/coder?sslmode=disable"
|
||||
```
|
||||
|
||||
|
@ -49,7 +49,7 @@ Once the schema is created, you can list all schemas with `\dn`:
|
|||
|
||||
In this case the database client requires the modified connection string:
|
||||
|
||||
```sh
|
||||
```console
|
||||
export CODER_PG_CONNECTION_URL="postgres://coder:secret42@localhost/coder?sslmode=disable&search_path=myschema"
|
||||
```
|
||||
|
||||
|
@ -77,7 +77,7 @@ ALTER ROLE coder SET search_path = myschema;
|
|||
Please make sure that the schema selected in the connection string `...&search_path=myschema` exists
|
||||
and the role has granted permissions to access it. The schema should be present on this listing:
|
||||
|
||||
```sh
|
||||
```console
|
||||
psql -U coder -c '\dn'
|
||||
```
|
||||
|
||||
|
|
|
@ -9,7 +9,7 @@ Docker is required. See the [official installation documentation](https://docs.d
|
|||
For proof-of-concept deployments, you can run a complete Coder instance with
|
||||
the following command:
|
||||
|
||||
```sh
|
||||
```console
|
||||
export CODER_DATA=$HOME/.config/coderv2-docker
|
||||
export DOCKER_GROUP=$(getent group docker | cut -d: -f3)
|
||||
mkdir -p $CODER_DATA
|
||||
|
@ -34,7 +34,7 @@ For production deployments, we recommend using an external PostgreSQL database
|
|||
(version 13 or higher). Set `ACCESS_URL` to the external URL that users and
|
||||
workspaces will use to connect to Coder.
|
||||
|
||||
```sh
|
||||
```console
|
||||
docker run --rm -it \
|
||||
-e CODER_ACCESS_URL="https://coder.example.com" \
|
||||
-e CODER_PG_CONNECTION_URL="postgresql://username:password@database/coder" \
|
||||
|
@ -64,7 +64,7 @@ an PostgreSQL container and volume.
|
|||
|
||||
For proof-of-concept deployments, you can use [Coder's tunnel](../admin/configure.md#tunnel):
|
||||
|
||||
```sh
|
||||
```console
|
||||
cd coder
|
||||
|
||||
docker-compose up
|
||||
|
@ -72,7 +72,7 @@ an PostgreSQL container and volume.
|
|||
|
||||
For production deployments, we recommend setting an [access URL](../admin/configure.md#access-url):
|
||||
|
||||
```sh
|
||||
```console
|
||||
cd coder
|
||||
|
||||
CODER_ACCESS_URL=https://coder.example.com docker-compose up
|
||||
|
|
|
@ -34,7 +34,7 @@ to log in and manage templates.
|
|||
[helpful guides](https://phoenixnap.com/kb/postgresql-kubernetes) on the
|
||||
internet that explain sensible configurations for this chart. Example:
|
||||
|
||||
```sh
|
||||
```console
|
||||
# Install PostgreSQL
|
||||
helm repo add bitnami https://charts.bitnami.com/bitnami
|
||||
helm install coder-db bitnami/postgresql \
|
||||
|
@ -65,7 +65,7 @@ to log in and manage templates.
|
|||
|
||||
1. Create a secret with the database URL:
|
||||
|
||||
```sh
|
||||
```console
|
||||
# Uses Bitnami PostgreSQL example. If you have another database,
|
||||
# change to the proper URL.
|
||||
kubectl create secret generic coder-db-url -n coder \
|
||||
|
@ -120,7 +120,7 @@ to log in and manage templates.
|
|||
|
||||
1. Run the following command to install the chart in your cluster.
|
||||
|
||||
```sh
|
||||
```console
|
||||
helm install coder coder-v2/coder \
|
||||
--namespace coder \
|
||||
--values values.yaml
|
||||
|
@ -143,7 +143,7 @@ to log in and manage templates.
|
|||
To upgrade Coder in the future or change values,
|
||||
you can run the following command:
|
||||
|
||||
```sh
|
||||
```console
|
||||
helm repo update
|
||||
helm upgrade coder coder-v2/coder \
|
||||
--namespace coder \
|
||||
|
|
|
@ -105,13 +105,13 @@ Follow our [docker-compose](./docker.md#run-coder-with-docker-compose) documenta
|
|||
|
||||
First, make a create an empty plugins directory:
|
||||
|
||||
```sh
|
||||
```console
|
||||
mkdir $HOME/plugins
|
||||
```
|
||||
|
||||
Next, add a volume mount to docker-compose.yaml:
|
||||
|
||||
```sh
|
||||
```console
|
||||
vim docker-compose.yaml
|
||||
```
|
||||
|
||||
|
|
|
@ -6,7 +6,7 @@
|
|||
|
||||
1. Run Coder as a system service.
|
||||
|
||||
```sh
|
||||
```console
|
||||
# Optional) Set up an access URL
|
||||
sudo vim /etc/coder.d/coder.env
|
||||
|
||||
|
@ -23,7 +23,7 @@
|
|||
|
||||
1. Visit the Coder URL in the logs to set up your first account, or use the CLI:
|
||||
|
||||
```sh
|
||||
```console
|
||||
coder login <access-url>
|
||||
```
|
||||
|
||||
|
@ -31,7 +31,7 @@
|
|||
|
||||
After updating Coder or applying configuration changes, restart the server:
|
||||
|
||||
```sh
|
||||
```console
|
||||
sudo systemctl restart coder
|
||||
```
|
||||
|
||||
|
|
|
@ -14,19 +14,19 @@ rm -rf ~/.cache/coder
|
|||
|
||||
Debian, Ubuntu:
|
||||
|
||||
```sh
|
||||
```console
|
||||
sudo apt remove coder
|
||||
```
|
||||
|
||||
Fedora, CentOS, RHEL, SUSE:
|
||||
|
||||
```sh
|
||||
```console
|
||||
sudo yum remove coder
|
||||
```
|
||||
|
||||
Alpine:
|
||||
|
||||
```sh
|
||||
```console
|
||||
sudo apk del coder
|
||||
```
|
||||
|
||||
|
|
|
@ -52,7 +52,7 @@ You will also need the IP address of the server. Click on the server in the `Ins
|
|||
|
||||
Now that we’ve gathered all the information you will need to SSH into your EC2 instance, on a terminal on your local system, navigate to the `.pem` file downloaded when you created the EC2 instance. Run the following command:
|
||||
|
||||
```sh
|
||||
```console
|
||||
chmod 400 [mykey].pem
|
||||
```
|
||||
|
||||
|
@ -60,7 +60,7 @@ This adds the required permissions for SSH-ing into an EC2 instance.
|
|||
|
||||
Run the following command in terminal, where `mykey` is the security key file, `username` is the username found above for the relevant EC2 operating system image, and the `ip-address` is the IPv4 address for the server:
|
||||
|
||||
```sh
|
||||
```console
|
||||
ssh -i [mykey].pem username@ip-address
|
||||
```
|
||||
|
||||
|
@ -72,7 +72,7 @@ For this instance, we will run Coder as a system service, however you can run Co
|
|||
|
||||
In the EC2 instance, run the following command to install Coder
|
||||
|
||||
```sh
|
||||
```console
|
||||
curl -fsSL https://coder.com/install.sh | sh
|
||||
```
|
||||
|
||||
|
@ -80,13 +80,13 @@ curl -fsSL https://coder.com/install.sh | sh
|
|||
|
||||
Run the following command to start Coder as a system level service:
|
||||
|
||||
```sh
|
||||
```console
|
||||
sudo systemctl enable --now coder
|
||||
```
|
||||
|
||||
The following command will get you information about the Coder launch service
|
||||
|
||||
```sh
|
||||
```console
|
||||
journalctl -u coder.service -b
|
||||
```
|
||||
|
||||
|
@ -98,7 +98,7 @@ In this instance, Coder can be accessed at the url `https://fccad1b6c901511b30cf
|
|||
|
||||
Copy the URL and run the following command to create the first user, either on your local machine or in the AWS EC2 instance terminal.
|
||||
|
||||
```sh
|
||||
```console
|
||||
coder login <url***.try.coder.app>
|
||||
```
|
||||
|
||||
|
@ -122,20 +122,20 @@ Coder runs as a system service under a system user `coder`. The `coder` user wil
|
|||
|
||||
Run the following command to create a folder for the AWS credentials to live in:
|
||||
|
||||
```sh
|
||||
```console
|
||||
sudo mkdir /home/coder/.aws
|
||||
```
|
||||
|
||||
Run the following commands to copy the AWS credentials and give the `coder` user access to them:
|
||||
|
||||
```sh
|
||||
```console
|
||||
sudo cp ~/.aws/credentials /home/coder/.aws/credentials
|
||||
sudo chown coder:coder /home/coder/.aws/credentials
|
||||
```
|
||||
|
||||
Navigate to the `./aws-linux` folder where you created your template and run the following command to put the template on your Coder instance.
|
||||
|
||||
```sh
|
||||
```console
|
||||
coder templates create
|
||||
```
|
||||
|
||||
|
|
|
@ -43,7 +43,7 @@ For this instance, we will run Coder as a system service, however you can run Co
|
|||
|
||||
In the Azure VM instance, run the following command to install Coder
|
||||
|
||||
```sh
|
||||
```console
|
||||
curl -fsSL <https://coder.com/install.sh> | sh
|
||||
```
|
||||
|
||||
|
@ -51,13 +51,13 @@ curl -fsSL <https://coder.com/install.sh> | sh
|
|||
|
||||
Run the following command to start Coder as a system level service:
|
||||
|
||||
```sh
|
||||
```console
|
||||
sudo systemctl enable --now coder
|
||||
```
|
||||
|
||||
The following command will get you information about the Coder launch service
|
||||
|
||||
```sh
|
||||
```console
|
||||
journalctl -u coder.service -b
|
||||
```
|
||||
|
||||
|
@ -65,7 +65,7 @@ This will return a series of logs related to running Coder as a system service.
|
|||
|
||||
Copy the URL and run the following command to create the first user, either on your local machine or in the instance terminal.
|
||||
|
||||
```sh
|
||||
```console
|
||||
coder login <url***.try.coder.app>
|
||||
```
|
||||
|
||||
|
@ -89,14 +89,14 @@ Coder is running as a system service, which creates the system user `coder` for
|
|||
|
||||
Run the following commands to copy the Azure credentials and give the `coder` user access to them:
|
||||
|
||||
```sh
|
||||
```console
|
||||
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.
|
||||
|
||||
```sh
|
||||
```console
|
||||
coder templates create
|
||||
```
|
||||
|
||||
|
|
|
@ -15,7 +15,7 @@ Coder with Docker has the following advantages:
|
|||
|
||||
1. Run Coder with Docker.
|
||||
|
||||
```shell
|
||||
```console
|
||||
export CODER_DATA=$HOME/.config/coderv2-docker
|
||||
export DOCKER_GROUP=$(getent group docker | cut -d: -f3)
|
||||
mkdir -p $CODER_DATA
|
||||
|
@ -30,7 +30,7 @@ Coder with Docker has the following advantages:
|
|||
|
||||
1. In new terminal, [install Coder](../install/) in order to connect to your deployment through the CLI.
|
||||
|
||||
```shell
|
||||
```console
|
||||
curl -L https://coder.com/install.sh | sh
|
||||
```
|
||||
|
||||
|
@ -39,7 +39,7 @@ Coder with Docker has the following advantages:
|
|||
|
||||
1. Pull the "Docker" example template using the interactive `coder templates init`:
|
||||
|
||||
```shell
|
||||
```console
|
||||
coder templates init
|
||||
cd docker
|
||||
```
|
||||
|
|
|
@ -36,7 +36,7 @@ This will give you a terminal into the VM that we will use to install Coder.
|
|||
|
||||
In the terminal, run the following command
|
||||
|
||||
```sh
|
||||
```console
|
||||
curl -fsSL https://coder.com/install.sh | sh
|
||||
```
|
||||
|
||||
|
@ -46,7 +46,7 @@ For this tutorial, we will run Coder as a `systemd` service. You can run Coder i
|
|||
|
||||
First, edit the `coder.env` file to enable `CODER_TUNNEL` by setting the value to true with the following command:
|
||||
|
||||
```sh
|
||||
```console
|
||||
sudo vim /etc/coder.d/coder.env
|
||||
```
|
||||
|
||||
|
@ -54,13 +54,13 @@ sudo vim /etc/coder.d/coder.env
|
|||
|
||||
Exit vim and run the following command to start Coder as a system service:
|
||||
|
||||
```sh
|
||||
```console
|
||||
sudo systemctl enable --now coder
|
||||
```
|
||||
|
||||
The following command shows the Coder service's logs, including the Access URL. The Access URL will be used to access the Coder control plane.
|
||||
|
||||
```sh
|
||||
```console
|
||||
journalctl -u coder.service -b
|
||||
```
|
||||
|
||||
|
@ -70,7 +70,7 @@ In this instance, Coder can be accessed at the URL `https://fcca2f3bfc9d2e3bf1b9
|
|||
|
||||
Copy the URL and run the following command to create the workspace admin:
|
||||
|
||||
```sh
|
||||
```console
|
||||
coder login <url***.try.coder.app>
|
||||
```
|
||||
|
||||
|
@ -86,7 +86,7 @@ Select the `Develop in Linux on Google Cloud`, then `cd ./gcp-linux`.
|
|||
|
||||
Run the following command:
|
||||
|
||||
```sh
|
||||
```console
|
||||
coder templates create
|
||||
```
|
||||
|
||||
|
|
|
@ -1,10 +1,50 @@
|
|||
# Templates
|
||||
|
||||
Templates are written in standard Terraform and describe the infrastructure for
|
||||
workspaces (e.g., aws_instance, kubernetes_pod, or both).
|
||||
Templates are written in [Terraform](https://www.terraform.io/) and describe the
|
||||
infrastructure for workspaces (e.g., docker_container, aws_instance,
|
||||
kubernetes_pod).
|
||||
|
||||
In most cases, a small group of users (Coder admins) manage templates. Then,
|
||||
other users provision their development workspaces from templates.
|
||||
In most cases, a small group of users (team leads or Coder administrators) [have
|
||||
permissions](./admin/users.md#roles) to create and manage templates. Then, other
|
||||
users provision their [workspaces](./workspaces.md) from templates using the UI
|
||||
or CLI.
|
||||
|
||||
## Get the CLI
|
||||
|
||||
The CLI and the server are the same binary. We did this to encourage virality so
|
||||
individuals can start their own Coder deployments.
|
||||
|
||||
From your local machine, download the CLI for your operating system from the
|
||||
[releases](https://github.com/coder/coder/releases) or run:
|
||||
|
||||
```console
|
||||
curl -fsSL https://coder.com/install.sh | sh
|
||||
```
|
||||
|
||||
To see the sub-commands for managing templates, run:
|
||||
|
||||
```console
|
||||
coder templates --help
|
||||
```
|
||||
|
||||
## Login to your Coder Deployment
|
||||
|
||||
Before you can create templates, you must first login to your Coder deployment
|
||||
with the CLI.
|
||||
|
||||
```console
|
||||
coder login https://coder.example.com # aka the URL to your coder instance
|
||||
```
|
||||
|
||||
This will open a browser and ask you to authenticate to your Coder deployment,
|
||||
returning an API Key.
|
||||
|
||||
> Make a note of the API Key. You can re-use the API Key in future CLI logins or
|
||||
> sessions.
|
||||
|
||||
```console
|
||||
coder --token <your-api-key> login https://coder.example.com/ # aka the URL to your coder instance
|
||||
```
|
||||
|
||||
## Add a template
|
||||
|
||||
|
@ -25,28 +65,28 @@ vim <template-name>/main.tf
|
|||
coder templates create <template-name>
|
||||
```
|
||||
|
||||
> See the documentation and source code for each example in the
|
||||
> See the documentation and source code for each example as well as community
|
||||
> templates in the
|
||||
> [examples/](https://github.com/coder/coder/tree/main/examples/templates)
|
||||
> directory in the repo.
|
||||
|
||||
## Customize templates
|
||||
|
||||
Example templates are not designed to support every use (e.g [examples/aws-linux](https://github.com/coder/coder/tree/main/examples/templates/aws-linux) does
|
||||
not support custom VPCs). You can add these features by editing the Terraform
|
||||
code once you run `coder templates init` (new) or `coder templates pull`
|
||||
(existing).
|
||||
Example templates are not designed to support every use (e.g
|
||||
[examples/aws-linux](https://github.com/coder/coder/tree/main/examples/templates/aws-linux)
|
||||
does not support custom VPCs). You can add these features by editing the
|
||||
Terraform code once you run `coder templates init` (new) or `coder templates pull` (existing).
|
||||
|
||||
Refer to the following resources to build your own templates:
|
||||
|
||||
- Terraform: [Documentation](https://developer.hashicorp.com/terraform/docs) and [Registry](https://registry.terraform.io)
|
||||
- Terraform: [Documentation](https://developer.hashicorp.com/terraform/docs) and
|
||||
[Registry](https://registry.terraform.io)
|
||||
- Common [concepts in templates](#concepts-in-templates) and [Coder Terraform provider](https://registry.terraform.io/providers/coder/coder/latest/docs)
|
||||
- [Coder example templates](https://github.com/coder/coder/tree/main/examples/templates) code
|
||||
|
||||
## Concepts in templates
|
||||
|
||||
While templates are written with standard Terraform, the
|
||||
[Coder Terraform Provider](https://registry.terraform.io/providers/coder/coder/latest/docs) is
|
||||
used to define the workspace lifecycle and establish a connection from resources
|
||||
While templates are written with standard Terraform, the [Coder Terraform Provider](https://registry.terraform.io/providers/coder/coder/latest/docs) is used to define the workspace lifecycle and establish a connection from resources
|
||||
to Coder.
|
||||
|
||||
Below is an overview of some key concepts in templates (and workspaces). For all
|
||||
|
@ -55,8 +95,8 @@ template options, reference [Coder Terraform provider docs](https://registry.ter
|
|||
### Resource
|
||||
|
||||
Resources in Coder are simply [Terraform resources](https://www.terraform.io/language/resources).
|
||||
If a Coder agent is attached to a resource, users can connect directly to the resource over
|
||||
SSH or web apps.
|
||||
If a Coder agent is attached to a resource, users can connect directly to the
|
||||
resource over SSH or web apps.
|
||||
|
||||
### Coder agent
|
||||
|
||||
|
@ -93,15 +133,17 @@ resource "kubernetes_pod" "pod1" {
|
|||
}
|
||||
```
|
||||
|
||||
The `coder_agent` resource can be configured as described in the
|
||||
[documentation for the `coder` Terraform provider.](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent)
|
||||
For example, you can use the `env` property to set environment variables that will be
|
||||
inherited by all child processes of the agent, including SSH sessions.
|
||||
The `coder_agent` resource can be configured with additional arguments. For example,
|
||||
you can use the `env` property to set environment variables that will be inherited
|
||||
by all child processes of the agent, including SSH sessions. See the
|
||||
[Coder Terraform Provider documentation](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent)
|
||||
for the full list of supported arguments for the `coder_agent`.
|
||||
|
||||
#### startup_script
|
||||
|
||||
Use the Coder agent's `startup_script` to run additional commands like
|
||||
installing IDEs, [cloning dotfiles](./dotfiles.md#templates), and cloning project repos.
|
||||
installing IDEs, [cloning dotfiles](./dotfiles.md#templates), and cloning
|
||||
project repos.
|
||||
|
||||
```hcl
|
||||
resource "coder_agent" "coder" {
|
||||
|
@ -138,15 +180,15 @@ coder dotfiles -y ${var.dotfiles_uri}
|
|||
Templates often contain _parameters_. These are defined by `variable` blocks in
|
||||
Terraform. There are two types of parameters:
|
||||
|
||||
- **Admin/template-wide parameters** are set when a template is created/updated. These values
|
||||
are often cloud configuration, such as a `VPC`, and are annotated
|
||||
- **Admin/template-wide parameters** are set when a template is created/updated.
|
||||
These values are often cloud configuration, such as a `VPC`, and are annotated
|
||||
with `sensitive = true` in the template code.
|
||||
- **User/workspace parameters** are set when a user creates a workspace. These
|
||||
values are often personalization settings such as "preferred region"
|
||||
or "workspace image".
|
||||
values are often personalization settings such as "preferred region", "machine
|
||||
type" or "workspace image".
|
||||
|
||||
The template sample below uses _admin and user parameters_ to allow developers to
|
||||
create workspaces from any image as long as it is in the proper registry:
|
||||
The template sample below uses _admin and user parameters_ to allow developers
|
||||
to create workspaces from any image as long as it is in the proper registry:
|
||||
|
||||
```hcl
|
||||
variable "image_registry_url" {
|
||||
|
@ -171,14 +213,13 @@ resource "docker_image" "workspace" {
|
|||
|
||||
[Learn about resource persistence in Coder](./templates/resource-persistence.md)
|
||||
|
||||
Coder workspaces can be started/stopped. This is often used to save on cloud costs or enforce
|
||||
ephemeral workflows. When a workspace is started or stopped, the Coder server
|
||||
runs an additional
|
||||
[terraform apply](https://www.terraform.io/cli/commands/apply), informing the
|
||||
Coder provider that the workspace has a new transition state.
|
||||
Coder workspaces can be started/stopped. This is often used to save on cloud
|
||||
costs or enforce ephemeral workflows. When a workspace is started or stopped,
|
||||
the Coder server runs an additional [terraform apply](https://www.terraform.io/cli/commands/apply),
|
||||
informing the Coder provider that the workspace has a new transition state.
|
||||
|
||||
This template sample has one persistent resource (docker volume) and one ephemeral resource
|
||||
(docker image).
|
||||
This template sample has one persistent resource (docker volume) and one
|
||||
ephemeral resource (docker image).
|
||||
|
||||
```hcl
|
||||
data "coder_workspace" "me" {
|
||||
|
@ -228,20 +269,22 @@ resource "kubernetes_pod" "podName" {
|
|||
|
||||
### Edit templates
|
||||
|
||||
You can edit a template using the coder CLI. Only
|
||||
[template admins and owners](./admin/users.md) can edit a template.
|
||||
You can edit a template using the coder CLI. Only [template admins and
|
||||
owners](./admin/users.md) can edit a template.
|
||||
|
||||
Using the CLI, login to Coder and run the following command to edit a single template:
|
||||
Using the CLI, login to Coder and run the following command to edit a single
|
||||
template:
|
||||
|
||||
```sh
|
||||
```console
|
||||
coder templates edit <template-name> --description "This is my template"
|
||||
```
|
||||
|
||||
Review editable template properties by running `coder templates edit -h`.
|
||||
|
||||
Alternatively, you can pull down the template as a tape archive (`.tar`) to your current directory:
|
||||
Alternatively, you can pull down the template as a tape archive (`.tar`) to your
|
||||
current directory:
|
||||
|
||||
```sh
|
||||
```console
|
||||
coder templates pull <template-name> file.tar
|
||||
```
|
||||
|
||||
|
@ -251,36 +294,39 @@ Then, extract it by running:
|
|||
tar -xf file.tar
|
||||
```
|
||||
|
||||
Make the changes to your template then run this command from the root of the template folder:
|
||||
Make the changes to your template then run this command from the root of the
|
||||
template folder:
|
||||
|
||||
```sh
|
||||
```console
|
||||
coder templates push <template-name>
|
||||
```
|
||||
|
||||
Your updated template will now be available. Outdated workspaces will have a prompt in the dashboard to update.
|
||||
Your updated template will now be available. Outdated workspaces will have a
|
||||
prompt in the dashboard to update.
|
||||
|
||||
### Delete templates
|
||||
|
||||
You can delete a template using both the coder CLI and UI. Only
|
||||
[template admins and owners](./admin/users.md) can delete a template, and the template
|
||||
must not have any running workspaces associated to it.
|
||||
You can delete a template using both the coder CLI and UI. Only [template admins
|
||||
and owners](./admin/users.md) can delete a template, and the template must not
|
||||
have any running workspaces associated to it.
|
||||
|
||||
Using the CLI, login to Coder and run the following command to delete a template:
|
||||
Using the CLI, login to Coder and run the following command to delete a
|
||||
template:
|
||||
|
||||
```console
|
||||
coder templates delete <template-name>
|
||||
```
|
||||
|
||||
In the UI, navigate to the template you want to delete, and select the dropdown in
|
||||
the right-hand corner of the page to delete the template.
|
||||
In the UI, navigate to the template you want to delete, and select the dropdown
|
||||
in the right-hand corner of the page to delete the template.
|
||||
|
||||
![delete-template](./images/delete-template.png)
|
||||
|
||||
#### Delete workspaces
|
||||
|
||||
When a workspace is deleted, the Coder server essentially runs a
|
||||
[terraform destroy](https://www.terraform.io/cli/commands/destroy) to remove all
|
||||
resources associated with the workspace.
|
||||
When a workspace is deleted, the Coder server essentially runs a [terraform
|
||||
destroy](https://www.terraform.io/cli/commands/destroy) to remove all resources
|
||||
associated with the workspace.
|
||||
|
||||
> Terraform's
|
||||
> [prevent-destroy](https://www.terraform.io/language/meta-arguments/lifecycle#prevent_destroy)
|
||||
|
@ -291,18 +337,18 @@ resources associated with the workspace.
|
|||
### Coder apps
|
||||
|
||||
By default, all templates allow developers to connect over SSH and a web
|
||||
terminal. See [Configuring Web IDEs](./ides/web-ides.md) to
|
||||
learn how to give users access to additional web applications.
|
||||
terminal. See [Configuring Web IDEs](./ides/web-ides.md) to learn how to give
|
||||
users access to additional web applications.
|
||||
|
||||
### Data source
|
||||
|
||||
When a workspace is being started or stopped, the `coder_workspace` data source provides
|
||||
some useful parameters. See the [documentation for the `coder` Terraform provider](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/workspace)
|
||||
for more information.
|
||||
When a workspace is being started or stopped, the `coder_workspace` data source
|
||||
provides some useful parameters. See the [Coder Terraform provider](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/workspace) for more information.
|
||||
|
||||
For example, the [Docker quick-start template](https://github.com/coder/coder/tree/main/examples/templates/docker)
|
||||
sets a few environment variables based on the username and email address of the workspace's owner, so
|
||||
that you can make Git commits immediately without any manual configuration:
|
||||
sets a few environment variables based on the username and email address of the
|
||||
workspace's owner, so that you can make Git commits immediately without any
|
||||
manual configuration:
|
||||
|
||||
```tf
|
||||
resource "coder_agent" "main" {
|
||||
|
@ -316,14 +362,16 @@ resource "coder_agent" "main" {
|
|||
}
|
||||
```
|
||||
|
||||
You can add these environment variable definitions to your own templates, or customize them however
|
||||
you like.
|
||||
You can add these environment variable definitions to your own templates, or
|
||||
customize them however you like.
|
||||
|
||||
## Troubleshooting templates
|
||||
|
||||
Occasionally, you may run into scenarios where a workspace is created, but the agent is not connected. This means the agent or [init script](https://github.com/coder/coder/tree/main/provisionersdk/scripts) has failed on the resource.
|
||||
Occasionally, you may run into scenarios where a workspace is created, but the
|
||||
agent is not connected. This means the agent or [init script](https://github.com/coder/coder/tree/main/provisionersdk/scripts)
|
||||
has failed on the resource.
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ coder ssh myworkspace
|
||||
Waiting for [agent] to connect...
|
||||
```
|
||||
|
@ -332,18 +380,22 @@ While troubleshooting steps vary by resource, here are some general best
|
|||
practices:
|
||||
|
||||
- Ensure the resource has `curl` installed
|
||||
- Ensure the resource can `curl` your Coder [access URL](./admin/configure.md#access-url)
|
||||
- Manually connect to the resource and check the agent logs (e.g., `docker exec` or AWS console)
|
||||
- Ensure the resource can `curl` your Coder [access
|
||||
URL](./admin/configure.md#access-url)
|
||||
- Manually connect to the resource and check the agent logs (e.g., `kubectl exec`, `docker exec` or AWS console)
|
||||
- The Coder agent logs are typically stored in `/var/log/coder-agent.log`
|
||||
- The Coder agent startup script logs are typically stored in `/var/log/coder-startup-script.log`
|
||||
- The Coder agent startup script logs are typically stored in
|
||||
`/var/log/coder-startup-script.log`
|
||||
|
||||
## Template permissions (enterprise)
|
||||
|
||||
Template permissions can be used to give users and groups access to specific templates. [Learn more about RBAC](./admin/rbac.md).
|
||||
Template permissions can be used to give users and groups access to specific
|
||||
templates. [Learn more about RBAC](./admin/rbac.md).
|
||||
|
||||
## Community Templates
|
||||
|
||||
You can see a list of community templates by our users [here](https://github.com/coder/coder/blob/main/examples/templates/community-templates.md).
|
||||
You can see a list of community templates by our users
|
||||
[here](https://github.com/coder/coder/blob/main/examples/templates/community-templates.md).
|
||||
|
||||
## Next Steps
|
||||
|
||||
|
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
We recommend source controlling your templates as you would other code. [Install Coder](../install/) in CI/CD pipelines to push new template versions.
|
||||
|
||||
```sh
|
||||
```console
|
||||
# Install the Coder CLI
|
||||
curl -L https://coder.com/install.sh | sh
|
||||
# curl -L https://coder.com/install.sh | sh -s -- --version=0.x
|
||||
|
|
|
@ -8,7 +8,7 @@ for software development.
|
|||
Each Coder user has their own workspaces created from [shared
|
||||
templates](./templates.md):
|
||||
|
||||
```sh
|
||||
```console
|
||||
# create a workspace from the template; specify any variables
|
||||
coder create --template="<templateName>" <workspaceName>
|
||||
|
||||
|
@ -66,7 +66,7 @@ one hour. IDE, SSH, Port Forwarding, and coder_app activity trigger this bump.
|
|||
Use the following command to update a workspace to the latest template version.
|
||||
The workspace will be stopped and started:
|
||||
|
||||
```sh
|
||||
```console
|
||||
coder update <workspace-name>
|
||||
```
|
||||
|
||||
|
@ -76,7 +76,7 @@ Use the following command to re-enter template input
|
|||
variables in an existing workspace. This command is useful when a workspace fails
|
||||
to build because its state is out of sync with the template.
|
||||
|
||||
```sh
|
||||
```console
|
||||
coder update <your workspace name> --always-prompt
|
||||
```
|
||||
|
||||
|
|
|
@ -61,7 +61,7 @@ The following explains how to do certain things related to dogfooding.
|
|||
|
||||
### My Docker containers keep failing and I have no idea what's going on!
|
||||
|
||||
```shell
|
||||
```console
|
||||
✔ Queued [236ms]
|
||||
✔ Setting up [5ms]
|
||||
⧗ Starting workspace
|
||||
|
@ -89,7 +89,7 @@ Check the output of `docker ps -a`
|
|||
|
||||
Enable verbose container logging for Docker:
|
||||
|
||||
```shell
|
||||
```console
|
||||
sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.orig
|
||||
sudo cat > /etc/docker/daemon.json << EOF
|
||||
{
|
||||
|
|
|
@ -8,7 +8,7 @@ List template examples in our CLI with `coder templates init`.
|
|||
|
||||
Clone this repository to create a project from any example listed here:
|
||||
|
||||
```sh
|
||||
```console
|
||||
git clone https://github.com/coder/coder
|
||||
cd examples/templates/aws-macos
|
||||
coder templates create
|
||||
|
|
|
@ -20,7 +20,7 @@ on-screen instructions to proceed.
|
|||
|
||||
Create a Dockerfile (e.g `images/golang.Dockerfile`):
|
||||
|
||||
```sh
|
||||
```console
|
||||
vim images/golang.Dockerfile
|
||||
```
|
||||
|
||||
|
@ -48,7 +48,7 @@ USER coder
|
|||
|
||||
Edit the Terraform template (`main.tf`):
|
||||
|
||||
```sh
|
||||
```console
|
||||
vim main.tf
|
||||
```
|
||||
|
||||
|
@ -88,7 +88,7 @@ resource "docker_image" "coder_image" {
|
|||
|
||||
Update the template:
|
||||
|
||||
```sh
|
||||
```console
|
||||
coder template push docker-image-builds
|
||||
```
|
||||
|
||||
|
@ -99,7 +99,7 @@ the removed image until you update the workspace to the latest version.
|
|||
|
||||
Edit the Dockerfile (or related assets):
|
||||
|
||||
```sh
|
||||
```console
|
||||
vim images/node.Dockerfile
|
||||
```
|
||||
|
||||
|
@ -113,7 +113,7 @@ RUN DEBIAN_FRONTEND="noninteractive" apt-get update -y && \
|
|||
|
||||
1. Edit the Terraform template (`main.tf`)
|
||||
|
||||
```sh
|
||||
```console
|
||||
vim main.tf
|
||||
```
|
||||
|
||||
|
@ -136,13 +136,13 @@ resource "docker_image" "coder_image" {
|
|||
|
||||
Update the template:
|
||||
|
||||
```sh
|
||||
```console
|
||||
coder template push docker-image-builds
|
||||
```
|
||||
|
||||
Optional: Update workspaces to the latest template version
|
||||
|
||||
```sh
|
||||
```console
|
||||
coder ls
|
||||
coder update [workspace name]
|
||||
```
|
||||
|
|
|
@ -10,7 +10,7 @@ This is an example configuration of how to use Coder with [caddy](https://caddys
|
|||
|
||||
1. Start with our example configuration
|
||||
|
||||
```sh
|
||||
```console
|
||||
# Create a project folder
|
||||
cd $HOME
|
||||
mkdir coder-with-caddy
|
||||
|
@ -30,7 +30,7 @@ This is an example configuration of how to use Coder with [caddy](https://caddys
|
|||
|
||||
1. Start Coder. Set `CODER_ACCESS_URL` and `CODER_WILDCARD_ACCESS_URL` to the domain you're using in your Caddyfile.
|
||||
|
||||
```sh
|
||||
```console
|
||||
export CODER_ACCESS_URL=https://coder.example.com
|
||||
export CODER_WILDCARD_ACCESS_URL=*.coder.example.com
|
||||
docker compose up -d # Run on startup
|
||||
|
@ -60,19 +60,19 @@ This is an example configuration of how to use Coder with [caddy](https://caddys
|
|||
|
||||
If you're [keeping Caddy running](https://caddyserver.com/docs/running) via a system service:
|
||||
|
||||
```sh
|
||||
```console
|
||||
sudo systemctl restart caddy
|
||||
```
|
||||
|
||||
Or run a standalone server:
|
||||
|
||||
```sh
|
||||
```console
|
||||
caddy run
|
||||
```
|
||||
|
||||
1. Optionally, use [ufw](https://wiki.ubuntu.com/UncomplicatedFirewall) or another firewall to disable external traffic outside of Caddy.
|
||||
|
||||
```sh
|
||||
```console
|
||||
# Check status of UncomplicatedFirewall
|
||||
sudo ufw status
|
||||
|
||||
|
|
Loading…
Reference in New Issue