diff --git a/docs/images/quickstart/aws/aws1.png b/docs/images/quickstart/aws/aws1.png new file mode 100644 index 0000000000000..88f01e21dc2a0 Binary files /dev/null and b/docs/images/quickstart/aws/aws1.png differ diff --git a/docs/images/quickstart/aws/aws10.png b/docs/images/quickstart/aws/aws10.png new file mode 100644 index 0000000000000..8869a93957e4a Binary files /dev/null and b/docs/images/quickstart/aws/aws10.png differ diff --git a/docs/images/quickstart/aws/aws11.png b/docs/images/quickstart/aws/aws11.png new file mode 100644 index 0000000000000..2e7da3c944a5c Binary files /dev/null and b/docs/images/quickstart/aws/aws11.png differ diff --git a/docs/images/quickstart/aws/aws2.png b/docs/images/quickstart/aws/aws2.png new file mode 100644 index 0000000000000..e4ed959e83c92 Binary files /dev/null and b/docs/images/quickstart/aws/aws2.png differ diff --git a/docs/images/quickstart/aws/aws3.png b/docs/images/quickstart/aws/aws3.png new file mode 100644 index 0000000000000..9a4d02ea3cb51 Binary files /dev/null and b/docs/images/quickstart/aws/aws3.png differ diff --git a/docs/images/quickstart/aws/aws4.png b/docs/images/quickstart/aws/aws4.png new file mode 100644 index 0000000000000..ad9f7405d3de9 Binary files /dev/null and b/docs/images/quickstart/aws/aws4.png differ diff --git a/docs/images/quickstart/aws/aws5.png b/docs/images/quickstart/aws/aws5.png new file mode 100644 index 0000000000000..0496b7a024916 Binary files /dev/null and b/docs/images/quickstart/aws/aws5.png differ diff --git a/docs/images/quickstart/aws/aws6.png b/docs/images/quickstart/aws/aws6.png new file mode 100644 index 0000000000000..4979ca48dcd47 Binary files /dev/null and b/docs/images/quickstart/aws/aws6.png differ diff --git a/docs/images/quickstart/aws/aws7.png b/docs/images/quickstart/aws/aws7.png new file mode 100644 index 0000000000000..3d7b08f3da53d Binary files /dev/null and b/docs/images/quickstart/aws/aws7.png differ diff --git a/docs/images/quickstart/aws/aws8.png b/docs/images/quickstart/aws/aws8.png new file mode 100644 index 0000000000000..a4d90020ff4e8 Binary files /dev/null and b/docs/images/quickstart/aws/aws8.png differ diff --git a/docs/images/quickstart/aws/aws9.png b/docs/images/quickstart/aws/aws9.png new file mode 100644 index 0000000000000..c4d9096d575c7 Binary files /dev/null and b/docs/images/quickstart/aws/aws9.png differ diff --git a/docs/images/quickstart/azure/azure1.jpg b/docs/images/quickstart/azure/azure1.jpg new file mode 100644 index 0000000000000..9b1836c0f13b9 Binary files /dev/null and b/docs/images/quickstart/azure/azure1.jpg differ diff --git a/docs/images/quickstart/azure/azure10.png b/docs/images/quickstart/azure/azure10.png new file mode 100644 index 0000000000000..394c256fc4b56 Binary files /dev/null and b/docs/images/quickstart/azure/azure10.png differ diff --git a/docs/images/quickstart/azure/azure2.png b/docs/images/quickstart/azure/azure2.png new file mode 100644 index 0000000000000..8937bc3302dd4 Binary files /dev/null and b/docs/images/quickstart/azure/azure2.png differ diff --git a/docs/images/quickstart/azure/azure3.png b/docs/images/quickstart/azure/azure3.png new file mode 100644 index 0000000000000..85523d40a88ee Binary files /dev/null and b/docs/images/quickstart/azure/azure3.png differ diff --git a/docs/images/quickstart/azure/azure4.png b/docs/images/quickstart/azure/azure4.png new file mode 100644 index 0000000000000..074d057eeb8bf Binary files /dev/null and b/docs/images/quickstart/azure/azure4.png differ diff --git a/docs/images/quickstart/azure/azure5.png b/docs/images/quickstart/azure/azure5.png new file mode 100644 index 0000000000000..87e977f4c115f Binary files /dev/null and b/docs/images/quickstart/azure/azure5.png differ diff --git a/docs/images/quickstart/azure/azure6.png b/docs/images/quickstart/azure/azure6.png new file mode 100644 index 0000000000000..48a13f79a923f Binary files /dev/null and b/docs/images/quickstart/azure/azure6.png differ diff --git a/docs/images/quickstart/azure/azure7.png b/docs/images/quickstart/azure/azure7.png new file mode 100644 index 0000000000000..3d7b08f3da53d Binary files /dev/null and b/docs/images/quickstart/azure/azure7.png differ diff --git a/docs/images/quickstart/azure/azure8.png b/docs/images/quickstart/azure/azure8.png new file mode 100644 index 0000000000000..a4d90020ff4e8 Binary files /dev/null and b/docs/images/quickstart/azure/azure8.png differ diff --git a/docs/images/quickstart/azure/azure9.png b/docs/images/quickstart/azure/azure9.png new file mode 100644 index 0000000000000..821f0e88e0341 Binary files /dev/null and b/docs/images/quickstart/azure/azure9.png differ diff --git a/docs/manifest.json b/docs/manifest.json index a0aa731d77d61..79d7b51f809a1 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -64,6 +64,16 @@ "description": "Setup Coder with Docker", "icon_path": "./images/icons/docker.svg", "path": "./quickstart/docker.md" + }, + { + "title": "AWS", + "description": "Setup Coder with AWS", + "path": "./quickstart/aws.md" + }, + { + "title": "Azure", + "description": "Setup Coder with Azure", + "path": "./quickstart/azure.md" } ] }, diff --git a/docs/quickstart/aws.md b/docs/quickstart/aws.md new file mode 100644 index 0000000000000..7eb454556121d --- /dev/null +++ b/docs/quickstart/aws.md @@ -0,0 +1,144 @@ +## Requirements + +This quickstart assumes you are assigned `AdministratorAccess` policy to AWS. + +## Setting Up Security Groups for EC2 + +To set up a security group for an EC2 instance, navigate to the AWS EC2 Dashboard. In the side panel click `Security Groups`. + +In the upper right hand corner, click `Create Security Group`. In the creator screen, name the security group something relevant to the EC2 instance you will create. + + + +For ease of use, we are going to set this up using the simplest rules. + + + +Create a new `Inbound Rule` that allows for SSH from your computer’s IP address. + +You’ve now created a security group that will be used by your EC2 instance. + +## Setting Up Your EC2 instance + +On the EC2 dashboard, click `Instances`. This will take you to all the EC2 instances you have created. Click `Launch New Instance`. Name the EC2 instance following the naming convention of your choice. + + + +For this tutorial, we are going to launch this as the base Ubuntu server. + +For the `Create key pair`, we are using ED25519 and `.pem` as we will SSH into the instance later in the tutorial. + + +Next, under `Network Settings`, change your Firewall security group to Select existing security group and from the resulting dropdown, select the security group you created in the previous section. + +You don’t need to change anything else - click `Launch Instance`. + + + +It’ll take a few minutes for it to show up in your existing instances, so take a break as it starts up. + +## SSHing into the EC2 instance + +If you’ve launched a new EC2 instance following the previous steps of this tutorial, find the username for the EC2 instance [here](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connection-prereqs.html). The version launched in the previous steps was a version of the Amazon Linux so the username is `ubuntu`. + +You will also need the IP address of the server. Click on the server in the `Instances` dashboard, and copy the IPv4 address + + + +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 +chmod 400 [mykey].pem +``` + +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 +ssh -i [mykey].pem username@ip-address +``` + +Congrats you’ve SSH’d into the server. + +## 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 EC2 instance, run the following command to install Coder + +```sh +curl -fsSL https://coder.com/install.sh | sh +``` + +## Run Coder + +First, edit the `coder.env` file to enable `CODER_TUNNEL` by setting the value to true with the following command: + +```sh +sudo vim /etc/coder.d/coder.env +``` + + +Exit vim and run the following command to start Coder as a system level service: + +```sh +sudo systemctl enable --now coder +``` + +The following command will get you information about the Coder launch service + +```sh +journalctl -u coder.service -b +``` + +This will return a series of Coder logs, however, embedded in the launch is the URL for accessing Coder. + + + +In this instance, Coder can be accessed at the url `https://fccad1b6c901511b30cf2cf4fbd0973e.pit-1.try.coder.app`. + +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 +coder login +``` + +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 + +Run `coder template init` to create your first template. You’ll be given a list of possible templates. This tutorial will show you how to set up your Coder instance to create Linux based machines on AWS. + + + +Press `enter` to select `Develop in Linux` on AWS template. This will return the following: + + + +Now, we must install the AWS CLI and authorize the template. Follow [these instructions to install the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) and [add your credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html). + +Coder runs as a system service under a system user `coder`. The `coder` user will require access to the AWS credentials to initialize the template and provision workspaces. + +Run the following command to create a folder for the AWS credentials to live in: + +```sh +sudo mkdir /home/coder/.aws +``` + +Run the following commands to copy the AWS credentials and give the `coder` user access to them: + +```sh +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 +coder templates create +``` + +Congrats! You can now navigate to your Coder dashboard and use this Linux on AWS template to create a new workspace! diff --git a/docs/quickstart/azure.md b/docs/quickstart/azure.md new file mode 100644 index 0000000000000..046ac64c36e48 --- /dev/null +++ b/docs/quickstart/azure.md @@ -0,0 +1,106 @@ +## Requirements + +This quickstart will show you how to set up the Coder server on Azure and then set up an Azure hosted Linux based workspace, which allows users to create there own instances of these workspaces and use the Coder product. This quickstart assumes you have access to admin level access to 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 . + + + +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. + + + + + +Up next, under `Inbound port rules` modify the Select `inbound ports` to also take in `HTTPS` and `HTTP`. + + + +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. + + + +Click `Return to create a virtual machine`. Your VM will start up! + + + +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 + +```sh +curl -fsSL | sh +``` + +## Run Coder + +First, edit the `coder.env` file to enable `CODER_TUNNEL` by setting the value to true with the following command: + +```sh +sudo vim /etc/coder.d/coder.env +``` + + +Exit vim and run the following command to start Coder as a system level service: + +```sh + sudo systemctl enable --now coder +``` + +The following command will get you information about the Coder launch service + +```sh + 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. + +```sh +coder login +``` + +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. + + + +Press `enter` to select `Develop in Linux on Azure` template. This will return the following: + + + +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: + +```sh +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 +coder templates create +``` + +Congrats! You can now navigate to your Coder dashboard and use this Linux on Azure template to create a new workspace! +