diff --git a/docker-compose.yaml b/docker-compose.yaml index 8e9a3a505a..0e66c51406 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -1,7 +1,9 @@ version: "3.9" services: coder: - image: ghcr.io/coder/coder:v${CODER_VERSION:-latest} + # This MUST be stable for our documentation and + # other automations. + image: ghcr.io/coder/coder:${CODER_VERSION:-latest} ports: - "7080:7080" environment: diff --git a/docs/ides/configuring-web-ides.md b/docs/ides/configuring-web-ides.md index 8bc4e8b7e2..4a1a532fba 100644 --- a/docs/ides/configuring-web-ides.md +++ b/docs/ides/configuring-web-ides.md @@ -70,9 +70,9 @@ You'll also need to specify a `coder_app` resource related to the agent. This is ```hcl resource "coder_app" "code-server" { agent_id = coder_agent.dev.id - name = "VS Code" + name = "code-server" url = "http://localhost:13337/?folder=/home/coder" - icon = "/code.svg" + icon = "/icon/code.svg" } ``` diff --git a/docs/images/quickstart/docker/create-workspace.png b/docs/images/quickstart/docker/create-workspace.png new file mode 100644 index 0000000000..a1b13c8e21 Binary files /dev/null and b/docs/images/quickstart/docker/create-workspace.png differ diff --git a/docs/images/quickstart/docker/ides.png b/docs/images/quickstart/docker/ides.png new file mode 100644 index 0000000000..2a912c294c Binary files /dev/null and b/docs/images/quickstart/docker/ides.png differ diff --git a/docs/images/quickstart/docker/login.png b/docs/images/quickstart/docker/login.png new file mode 100644 index 0000000000..9abf7c69c5 Binary files /dev/null and b/docs/images/quickstart/docker/login.png differ diff --git a/docs/install.md b/docs/install.md index fbd517a9fa..64669f1d7f 100644 --- a/docs/install.md +++ b/docs/install.md @@ -55,13 +55,16 @@ Coder](https://github.com/coder/coder/releases) installed. git clone https://github.com/coder/coder.git ``` -2. Navigate into the `coder` folder. Coder requires a non-`localhost` access URL - for non-Docker-based examples; if you have a public IP or a domain/reverse - proxy, you can provide this value before running `docker-compose up` to - start the service: +2. Navigate into the `coder` folder and run `docker-compose up`: ```console cd coder + # Coder will bind to localhost:7080. + # You may use localhost:7080 as your access URL + # when using Docker workspaces exclusively. + # CODER_ACCESS_URL=http://localhost:7080 + # Otherwise, an internet accessible access URL + # is required. CODER_ACCESS_URL=https://coder.mydomain.com docker-compose up ``` diff --git a/docs/manifest.json b/docs/manifest.json index 0d6268ce33..048f8e5c8e 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -39,7 +39,21 @@ "title": "Quickstart", "description": "Create your first template and workspace", "icon": "", - "path": "./quickstart.md" + "path": "./quickstart.md", + "children": [ + { + "title": "Docker", + "description": "Setup Coder with Docker", + "icon": "<\/svg>", + "path": "./quickstart/docker.md" + }, + { + "title": "Generic", + "description": "Setup Coder on anything", + "icon": "<\/ellipse><\/ellipse><\/path><\/path><\/path><\/path><\/svg>", + "path": "./quickstart/generic.md" + } + ] }, { "title": "Templates", diff --git a/docs/quickstart.md b/docs/quickstart.md index a6c43e9b6b..1abb94453c 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,51 +1,6 @@ # Quickstart -## Prerequisites +See our [Docker quickstart](./quickstart/docker.md) for the easiest +possible way to use Coder. -Please [install Coder](./install.md) before proceeding with the steps outlined in this article. - -## Creating your first template and workspace - -In a new terminal window, run the following to copy a sample template: - -```bash -coder templates init -``` - -Follow the CLI instructions to select an example that you can modify for your -specific usage (e.g., a template to **Develop code-server in Docker**): - -1. Navigate into your new templates folder and create your first template using - the provided command (e.g., `cd ./docker-code-server && coder templates create`) - -1. Answer the CLI prompts; when done, confirm that you want to create your template. - -Create a workspace using your template: - -```bash -coder create --template="yourTemplate" -``` - -Connect to your workspace via SSH: - -```bash -coder ssh -``` - -You can also access your workspace using the **access URL** you provided when -deploying Coder (if you're using a temporary deployment and you opted to use -Coder's tunnel, use the access URL you were provided). Log in with the admin -credentials provided to you by Coder. - -![Coder Web UI with code-server](images/code-server.png) - -## Modifying templates - -You can edit the Terraform template as follows: - -```sh -coder templates init -cd gcp-linux # modify this line as needed to access the template -vim main.tf -coder templates update gcp-linux # updates the template -``` +Otherwise, you can check out the [generic quickstart](./quickstart/generic.md). diff --git a/docs/quickstart/docker.md b/docs/quickstart/docker.md new file mode 100644 index 0000000000..6d12a5d117 --- /dev/null +++ b/docs/quickstart/docker.md @@ -0,0 +1,83 @@ +# Docker + +Coder with Docker has the following advantages: + +- Simple installation (everything is on a single box) +- Workspace images are easily configured +- Workspaces share resources for burst operations + +## Requirements + +- A single MacOS or Linux box +- A running Docker daemon + +## Instructions + +1. [Install and launch Coder](../install.md) + + You may use `CODER_ACCESS_URL=http://localhost:7080` since we're using local + Docker workspaces exclusively. The rest of the guide will assume that this is your + access URL. + + ```bash + coder server -a $CODER_ACCESS_URL + ``` + +1. Run `coder login http://localhost:7080` in a new terminal and follow the + interactive instructions to create your user. + +1. Pull the example template: + + ```bash + echo "docker" | coder templates init + cd docker + # You should see a `main.tf` file in this directory + ``` + +1. Open up `main.tf` in your preferred editor to edit the images + + You can skip this step if you're fine with our default, generic OS images. + + Search for the following section in `main.tf`: + + ```hcl + ... + variable "docker_image" { + description = "Which Docker image would you like to use for your workspace?" + # The codercom/enterprise-* images are only built for amd64 + default = "codercom/enterprise-base:ubuntu" + validation { + condition = contains(["codercom/enterprise-base:ubuntu", "codercom/enterprise-node:ubuntu", + "codercom/enterprise-intellij:ubuntu", "codercom/enterprise-golang:ubuntu"], var.docker_image) + error_message = "Invalid Docker image!" + } + } + ... + ``` + + And edit the strings in `condition = contains([...])` and `default = ...` + with your preferred images. + +1. Push up the template to Coder with `coder templates create` +1. Open the dashboard in your browser (http://localhost:7080) to create your + first workspace: + + + + Then navigate to `Templates > docker > Create workspace` + + + + Now wait a few moments for the workspace to build... After the first build + the image is cached and subsequent builds will take a few seconds. + +1. All done! + + + + Open up a web application or [SSH in](../ides.md#ssh-configuration). + +## Next Steps + +- [Learn more about template configuration](../templates.md) +- [Configure more IDEs](../ides/configuring-web-ides.md) diff --git a/docs/quickstart/generic.md b/docs/quickstart/generic.md new file mode 100644 index 0000000000..c64b464499 --- /dev/null +++ b/docs/quickstart/generic.md @@ -0,0 +1,49 @@ +## Prerequisites + +Please [install Coder](./install.md) before proceeding with the steps outlined in this article. + +## Creating your first template and workspace + +In a new terminal window, run the following to copy a sample template: + +```bash +coder templates init +``` + +Follow the CLI instructions to select an example that you can modify for your +specific usage (e.g., a template to **Develop code-server in Docker**): + +1. Navigate into your new templates folder and create your first template using + the provided command (e.g., `cd ./docker-code-server && coder templates create`) + +1. Answer the CLI prompts; when done, confirm that you want to create your template. + +Create a workspace using your template: + +```bash +coder create --template="yourTemplate" +``` + +Connect to your workspace via SSH: + +```bash +coder ssh +``` + +You can also access your workspace using the **access URL** you provided when +deploying Coder (if you're using a temporary deployment and you opted to use +Coder's tunnel, use the access URL you were provided). Log in with the admin +credentials provided to you by Coder. + +![Coder Web UI with code-server](images/code-server.png) + +## Modifying templates + +You can edit the Terraform template as follows: + +```sh +coder templates init +cd gcp-linux # modify this line as needed to access the template +vim main.tf +coder templates update gcp-linux # updates the template +``` diff --git a/examples/templates/docker/main.tf b/examples/templates/docker/main.tf index 435163af55..474ec5c2aa 100644 --- a/examples/templates/docker/main.tf +++ b/examples/templates/docker/main.tf @@ -66,10 +66,24 @@ data "coder_workspace" "me" { } resource "coder_agent" "dev" { - arch = var.step2_arch - os = "linux" + arch = var.step2_arch + os = "linux" + startup_script = <