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: rename quickstart to platforms + Kubernetes guide (#6972)

Browse Source 
* rename quickstart to platforms + Kubernetes guide

* fmt
This commit is contained in:
Ben Potter
2023-04-03 09:51:07 -05:00
committed by GitHub
parent 2d051094e7
commit ded931f0f6
47 changed files with 103 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/platforms/aws.md
+63
View File
@@ -0,0 +1,63 @@
# Amazon Web Services
This guide is designed to get you up and running with a Coder proof-of-concept VM on AWS EC2 using a [Coder-provided AMI](https://github.com/coder/packages). If you are familiar with EC2 however, you can use our [install script](../install/install.sh.md) to run Coder on any popular Linux distribution.
## Requirements
This guide assumes your AWS account has `AmazonEC2FullAccess` permissions.
## Launch a Coder instance from the from AWS Marketplace
We publish an Ubuntu 22.04 AMI with Coder and Docker pre-installed. Search for `Coder` in the EC2 "Launch an Instance" screen or [launch directly from the marketplace](https://aws.amazon.com/marketplace/pp/prodview-5gxjyur2vc7rg).
![Coder on AWS Marketplace](../images/platforms/aws/marketplace.png)
Be sure to keep the default firewall (SecurityGroup) options checked so you can connect over HTTP, HTTPS, and SSH.
![AWS Security Groups](../images/platforms/aws/security-groups.png)
We recommend keeping the default instance type (`t2.xlarge`, 4 cores and 16 GB memory) if you plan on provisioning Docker containers as workspaces on this EC2 instance. Keep in mind this platforms is intended for proof-of-concept deployments and you should adjust your infrastructure when preparing for production use. See: [Scaling Coder](../admin/scale.md)
Be sure to add a keypair so that you can connect over SSH to further [configure Coder](../admin/configure.md).
After launching the instance, wait 30 seconds and navigate to the public IPv4 address. You should be redirected to a public tunnel URL.
<video autoplay playsinline loop>
<source src="https://github.com/coder/coder/blob/main/docs/images/platforms/aws/launch.mp4?raw=true" type="video/mp4">
Your browser does not support the video tag.
</video>
That's all! Use the UI to create your first user, template, and workspace. We recommend starting with a Docker template since the instance has Docker pre-installed.
![Coder Workspace and IDE in AWS EC2](../images/platforms/aws/workspace.png)
## Configuring Coder server
Coder is primarily configured by server-side flags and environment variables. Given you created or added key-pairs when launching the instance, you can [configure your Coder deployment](../admin/configure.md) by logging in via SSH or using the console:
```sh
ssh ubuntu@<ec2-public-IPv4>
sudo vim /etc/coder.d/coder.env # edit config
sudo service coder restart # restart Coder
```
## Give developers EC2 workspaces (optional)
Instead of running containers on the Coder instance, you can offer developers full EC2 instances with the [aws-linux](https://github.com/coder/coder/tree/main/examples/templates/aws-linux) template.
Before you add the AWS template from the dashboard or CLI, you'll need to modify the instance IAM role.
![Modify IAM role](../images/platforms/aws/modify-iam.png)
You must create or select a role that has `EC2FullAccess` permissions or a limited [Coder-specific permissions policy](https://github.com/coder/coder/tree/main/examples/templates/aws-linux#required-permissions--policy).
From there, you can import the AWS starter template in the dashboard and begin creating VM-based workspaces.
![Modify IAM role](../images/platforms/aws/aws-linux.png)
## Next steps
- [IDEs with Coder](../ides.md)
- [Writing custom templates for Coder](../templates.md)
- [Configure the Coder server](../admin/configure.md)
- [Use your own domain + TLS](../admin/configure.md#tls--reverse-proxy)
docs/platforms/azure.md
+109
View File
@@ -0,0 +1,109 @@
# Microsoft Azure
This guide shows you how to set up the Coder server on Azure which will
provision Azure-hosted Linux workspaces.
## Requirements
This guide assumes you have full administrator privileges on Azure.
## Create An Azure VM
From the Azure Portal, navigate to the Virtual Machines Dashboard. Click Create, and select creating a new Azure Virtual machine .
<img src="../images/platforms/azure/azure1.jpg">
This will bring you to the `Create a virtual machine` page. Select the subscription group of your choice, or create one if necessary.
Next, name the VM something relevant to this project using the naming convention of your choice. Change the region to something more appropriate for your current location. For this tutorial, we will use the base selection of the Ubuntu Gen2 Image and keep the rest of the base settings for this image the same.
<img src="../images/platforms/azure/azure2.png">
<img src="../images/platforms/azure/azure3.png">
Up next, under `Inbound port rules` modify the Select `inbound ports` to also take in `HTTPS` and `HTTP`.
<img src="../images/platforms/azure/azure4.png">
The set up for the image is complete at this stage. Click `Review and Create` - review the information and click `Create`. A popup will appear asking you to download the key pair for the server. Click `Download private key and create resource` and place it into a folder of your choice on your local system.
<img src="../images/platforms/azure/azure5.png">
Click `Return to create a virtual machine`. Your VM will start up!
<img src="../images/platforms/azure/azure6.png">
Click `Go to resource` in the virtual machine and copy the public IP address. You will need it to SSH into the virtual machine via your local machine.
Follow [these instructions](https://learn.microsoft.com/en-us/azure/virtual-machines/linux-vm-connect?tabs=Linux) to SSH into the virtual machine. Once on the VM, you can run and install Coder using your method of choice. For the fastest install, we recommend running Coder as a system service.
## Install Coder
For this instance, we will run Coder as a system service, however you can run Coder a multitude of different ways. You can learn more about those [here](https://coder.com/docs/coder-oss/latest/install).
In the Azure VM instance, run the following command to install Coder
```console
curl -fsSL <https://coder.com/install.sh> | sh
```
## Run Coder
Run the following command to start Coder as a system level service:
```console
sudo systemctl enable --now coder
```
The following command will get you information about the Coder launch service
```console
journalctl -u coder.service -b
```
This will return a series of logs related to running Coder as a system service. Embedded in the logs is the Coder Access URL.
Copy the URL and run the following command to create the first user, either on your local machine or in the instance terminal.
```console
coder login <url***.try.coder.app>
```
Fill out the prompts. Be sure to save use email and password as these are your admin username and password.
You can now access Coder on your local machine with the relevant `***.try.coder.app` URL and logging in with the username and password.
## Creating and Uploading Your First Template
First, run `coder template init` to create your first template. You’ll be given a list of possible templates to use. This tutorial will show you how to set up your Coder instance to create a Linux based machine on Azure.
<img src="../images/platforms/azure/azure9.png">
Press `enter` to select `Develop in Linux on Azure` template. This will return the following:
<img src="../images/platforms/azure/azure10.png">
To get started using the Azure template, install the Azure CLI by following the instructions [here](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli-linux?pivots=apt). Run `az login` and follow the instructions to configure the Azure command line.
Coder is running as a system service, which creates the system user `coder` for handling processes. The Coder user will require access to the Azure credentials to initialize the template.
Run the following commands to copy the Azure credentials and give the `coder` user access to them:
```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.
```console
coder templates create
```
Congrats! You can now navigate to your Coder dashboard and use this Linux on Azure template to create a new workspace!
## Next Steps
- [Port-forward](../networking/port-forwarding.md)
- [Learn more about template configuration](../templates.md)
- [Configure more IDEs](../ides/web-ides.md)
docs/platforms/docker.md
+87
View File
@@ -0,0 +1,87 @@
# 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
> Note that the below steps are only supported on a Linux distribution.
> If on macOS, please [run Coder via the standalone binary](./binary.md).
## Requirements
- A Linux machine
- A running Docker daemon
## Instructions
1. Run Coder with Docker.
```console
export CODER_DATA=$HOME/.config/coderv2-docker
export DOCKER_GROUP=$(getent group docker | cut -d: -f3)
mkdir -p $CODER_DATA
docker run --rm -it \
-v $CODER_DATA:/home/coder/.config \
-v /var/run/docker.sock:/var/run/docker.sock \
--group-add $DOCKER_GROUP \
ghcr.io/coder/coder:latest
```
> This will use Coder's tunnel and built-in database. See our [Docker documentation](../install/docker.md) for other configuration options such as running on localhost, using docker-compose, and external PostgreSQL.
1. In new terminal, [install Coder](../install/) in order to connect to your deployment through the CLI.
```console
curl -L https://coder.com/install.sh | sh
```
1. Run `coder login <access url>` and follow the
interactive instructions to create your user.
1. Pull the "Docker" example template using the interactive `coder templates init`:
```console
coder templates init
cd docker
```
1. Push up the template with `coder templates create`
1. Open the dashboard in your browser to create your
first workspace:
<img src="../images/platforms/docker/login.png">
Then navigate to `Templates > docker > Create workspace`
<img src="../images/platforms/docker/create-workspace.png">
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. Your workspace is ready to go!
<img src="../images/platforms/docker/ides.png">
Open up a web application or [SSH in](../ides.md#ssh-configuration).
1. If you want to modify the Docker image or template, edit the files in the
previously created `./docker` directory, then run `coder templates push`.
## Troubleshooting
### Docker-based workspace is stuck in "Connecting..."
Ensure you have an externally-reachable `CODER_ACCESS_URL` set. See [troubleshooting templates](../templates.md#creating-and-troubleshooting-templates) for more steps.
### Permission denied while trying to connect to the Docker daemon socket
See Docker's official documentation to [Manage Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user).
## Next Steps
- [Port-forward](../networking/port-forwarding.md)
- [Learn more about template configuration](../templates.md)
- [Configure more IDEs](../ides/web-ides.md)
docs/platforms/google-cloud-platform.md
+114
View File
@@ -0,0 +1,114 @@
# Google Cloud Platform
In this guide, you will learn how to deploy the Coder control plane instance and your first template.
## Requirements
This guide assumes you have `roles/compute.instanceAdmin.v1` access to your Google Cloud Platform project.
## Setting Up your VM
If this is the first time you’re creating a VM on this project, you will need to enable the `Compute Engine API`. On the Compute Engine API page, click `enable` and wait for the service to finish connecting.
<img src="../images/platforms/google-cloud-platform/gcp0.png">
This will pull up the `Create an Instance` page - name the instance something relevant to this project, following your naming convention of choice. In addition, select a region and zone that is close to your physical location. For this instance, we will use the base suggested image.
<img src="../images/platforms/google-cloud-platform/gcp1.png">
Under `Identity and API Access`, click `Allow full access to all Cloud APIs`. Scroll down to `Firewall` and click `Allow HTTPS traffic` and `Allow HTTP traffic`.
<img src="../images/platforms/google-cloud-platform/gcp2.png">
Scroll down to the bottom and click `Create` to create and deploy the VM.
Congrats you’ve created your VM instance!
## SSH-ing into the VM
On the Compute Engine Dashboard, click on the VM for this project. Under `Details`, click `SSH` and select `Open in browser window`.
<img src="../images/platforms/google-cloud-platform/gcp3.png">
This will give you a terminal into the VM that we will use to install Coder.
## Install Coder
In the terminal, run the following command
```console
curl -fsSL https://coder.com/install.sh | sh
```
## Run Coder
For this tutorial, we will run Coder as a `systemd` service. You can run Coder in [a multitude of different ways](https://coder.com/docs/coder-oss/latest/install).
First, edit the `coder.env` file to enable `CODER_TUNNEL` by setting the value to true with the following command:
```console
sudo vim /etc/coder.d/coder.env
```
<img src="../images/platforms/google-cloud-platform/gcp4.png">
Exit vim and run the following command to start Coder as a system service:
```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.
```console
journalctl -u coder.service -b
```
<img src="../images/platforms/google-cloud-platform/gcp5.png">
In this instance, Coder can be accessed at the URL `https://fcca2f3bfc9d2e3bf1b9feb50e723448.pit-1.try.coder.app`.
Copy the URL and run the following command to create the workspace admin:
```console
coder login <url***.try.coder.app>
```
Fill out the prompts and be sure to save use email and password. This is your admin login. Now, you can now access Coder from your local machine by navigating to the `***.try.coder.app` URL and logging in with that same username and password.
## Creating and Uploading your First Template
First, run `coder template init` to create your first template. You’ll be given a list of prefabricated templates. This tutorial shows you how to create a Linux based template on GCP.
<img src="../images/platforms/google-cloud-platform/gcp6.png">
Select the `Develop in Linux on Google Cloud`, then `cd ./gcp-linux`.
Run the following command:
```console
coder templates create
```
It will ask for your `project-id`, which you can find on the home page of your GCP Dashboard.
Given it’s your first time setting up Coder, it may give an error that will look like the following:
<img src="../images/platforms/google-cloud-platform/gcp7.png">
In the error message will be a link. In this case, the URL is `https://console.developes.google.com/apis/api/iam.googles.com/overview:?project=1073148106645`. Copy the respective URL from your error message, and visit it via your browser. It may ask you to enable `Identity and Access Management (IAM) API`.
Click `enable` and wait as the API initializes for your account.
Once initialized, click create credentials in the upper right-hand corner. Select the `Compute Engine API` from the dropdown, and select `Application Data` under `What data will you be accessing?`. In addition, select `Yes, I’m using one or more` under `Are you planning on using this API with Compute Engine, Kubernetes Engine, App Engine, or Cloud Functions?`.
<img src="../images/platforms/google-cloud-platform/gcp8.png">
Back in your GCP terminal, run the `coder templates create` one more time.
Congrats! You can now create new Linux-based workspaces that use Google Cloud Platform. Go onto your Coder dashboard, build your workspace, and get started coding!
## Next Steps
- [Learn more about template configuration](../templates.md)
- [Configure more IDEs](../ides/web-ides.md)
docs/platforms/kubernetes.md
+26
View File
@@ -0,0 +1,26 @@
# Guide: Coder on Kubernetes
Coder's control plane and/or workspaces can be deployed on Kubernetes.
## Installation
Refer to our [Helm install docs](../install/kubernetes.md) to deploy Coder on Kubernetes. The default helm values will provision the following:
- Coder control plane (as a `Deployment`)
- ServiceAccount + Role + RoleBinding to provision pods + PVCS in the current namespace (used for Kubernetes workspaces)
- LoadBalancer to access control plane
## Kubernetes templates
From the dashboard, import the Kubernetes starter template:
![Kubernetes starter template](../images/platforms/kubernetes/starter-template.png)
In the next screen, set the following template variables:
- use_kubeconfig: `false` (The ServiceAccount will authorize Coder to create pods on your cluster)
- `namespace`: `coder` (or whatever namespace you deployed Coder on)
![Variables for Kubernetes template](../images/platforms/kubernetes/template-variables.png)
> If you deployed Coder on another platform besides Kubernetes, you can set `use_kubeconfig: true` for Coder to read the config from your VM, for example.
docs/platforms/other.md
+11
View File
@@ -0,0 +1,11 @@
# Other platforms
Coder is highly extensible and is not limited to the platforms outlined in these docs. The control plane can be provisioned on any VM or container compute, and workspaces can include any Terraform resource. See our [architecture diagram](./about/architecture.md) for more details.
The following resources may help as you're deploying Coder.
- [Coder packages: one-click install on cloud providers](https://github.com/coder/packages)
- [Run Coder as a system service](../install/packages.md)
- [Deploy Coder offline](../enterprise/offline.md)
- [Supported resources (Terraform registry)](https://registry.terraform.io)
- [Writing custom templates](../templates.md)