diff --git a/assets/getting-started/account-preferences.png b/assets/getting-started/account-preferences.png new file mode 100644 index 000000000..448698eb3 Binary files /dev/null and b/assets/getting-started/account-preferences.png differ diff --git a/assets/getting-started/create-devurl.png b/assets/getting-started/create-devurl.png new file mode 100644 index 000000000..b468b7f00 Binary files /dev/null and b/assets/getting-started/create-devurl.png differ diff --git a/assets/getting-started/create-workspace.png b/assets/getting-started/create-workspace.png new file mode 100644 index 000000000..b37edf145 Binary files /dev/null and b/assets/getting-started/create-workspace.png differ diff --git a/assets/getting-started/hello-world.png b/assets/getting-started/hello-world.png new file mode 100644 index 000000000..2ec699f3b Binary files /dev/null and b/assets/getting-started/hello-world.png differ diff --git a/assets/getting-started/launch-devurl.png b/assets/getting-started/launch-devurl.png new file mode 100644 index 000000000..85e1226d4 Binary files /dev/null and b/assets/getting-started/launch-devurl.png differ diff --git a/assets/getting-started/linked-accounts.png b/assets/getting-started/linked-accounts.png new file mode 100644 index 000000000..8ab99ee5c Binary files /dev/null and b/assets/getting-started/linked-accounts.png differ diff --git a/assets/getting-started/open-folder.png b/assets/getting-started/open-folder.png new file mode 100644 index 000000000..b3cccafde Binary files /dev/null and b/assets/getting-started/open-folder.png differ diff --git a/assets/getting-started/ssh-keys.png b/assets/getting-started/ssh-keys.png new file mode 100644 index 000000000..de90e0383 Binary files /dev/null and b/assets/getting-started/ssh-keys.png differ diff --git a/assets/getting-started/view-files.png b/assets/getting-started/view-files.png new file mode 100644 index 000000000..3e3cd1663 Binary files /dev/null and b/assets/getting-started/view-files.png differ diff --git a/getting-started/developers.md b/getting-started/developers.md new file mode 100644 index 000000000..f8ed8b913 --- /dev/null +++ b/getting-started/developers.md @@ -0,0 +1,142 @@ +--- +title: Developers +description: Get started with Coder as a developer. +--- + +This article will walk you through the process of getting started with a Coder +workspace and a web development project featuring Node.js and React.js. You'll +learn how to: + +- Connect Coder to your Git provider; +- Create a workspace; +- Add a sample project to your workspace; +- Create a dev URL and preview changes to your project. + +## Prerequisites + +This guide assumes that you have a Coder deployment available to you and that +you have the credentials needed to access the deployment. + +## Step 1: Log in and connect Coder to your Git provider + +In this step, you'll log into Coder and connect and authenticate with your Git +provider. This will allow you to do things like pull repositories and push +changes. + +1. Navigate to the Coder deployment using the URL provided to you by your site + manager, and log in. + +1. Click on your avatar in the top-right, and select **Account**. + + ![Set account preferences](../assets/getting-started/account-preferences.png) + +1. Provide Coder with your SSH key to connect and authenticate to GitHub. + + If your site manager has configured OAuth, go to **Linked Accounts** and + follow the on-screen instructions to link your GitHub account. + + ![Link GitHub account](../assets/getting-started/linked-accounts.png) + + If your site manager has _not_ configured OAuth, go to **SSH keys**. Copy + your public SSH key and + [provide it to GitHub](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account). + + ![Add SSH key](../assets/getting-started/ssh-keys.png) + +## Step 2: Create your workspace + +You will now create the workspace where you'll work on your development project. + +1. Return to **Workspaces** using the top navigation bar. + +1. Click **New workspace** to launch the workspace-creation dialog. + +1. Provide a **Workspace Name**. + +1. In the **Image** section, click **Packaged** (this tab contains + Coder-provided images hosted in a Docker registry). Select **NodeJS**. This + will populate the form in the **Import** tab. + +1. Under **Workspace providers**, leave the default option (which is + **built-in**) selected. + +1. Expand the **Advanced** section. If the **Run as a container-based virtual + machine** option is selected, _unselect_ the box. Leave the **CPU**, + **Memory**, **Disk**, and **GPU** allocations as-is. + +1. Scroll to the bottom, and click **Create workspace**. The dialog will close, + allowing you to see the main workspace page. You can track the workspace + build process using the **Build log** on the right-hand side. + +![Create a workspace](../assets/getting-started/create-workspace.png) + +Once your workspace is ready for use, you'll see a chip that says **Running** +next to the name of your workspace. + +## Step 3: Add a sample project to your workspace + +Once you've created your workspace, you can start using Coder after adding a +sample project to your workspace. + +1. Under **Browser applications**, click **Code Web** to open VS Code in your + browser. + +1. When VS Code launches in your browser, click **Open folder...**. In the + prompt, you'll see `/home/coder`. This directory is where you'll clone a + sample React app project Git repository. Click **OK** to proceed. + + ![Open folder](../assets/getting-started/open-folder.png) + +1. Click the hamburger icon in the top right, and select **Terminal** > **New + Terminal** to open a new terminal. + +1. Clone the `create-react-app` repository: + + ```console + git clone git@github.com:facebook/create-react-app.git + ``` + + Once you've cloned the repository, you can click the **Explorer** icon and + expand the **create-react-app** folder in the left-have nav bar to see the + contents of the repo. + + ![View files](../assets/getting-started/view-files.png) + + You're now ready to make changes to the application. + +## Step 4: Preview your app and view changes live + +Dev URLs allow you to access the web services you're developing in your +workspace. Once you've created a dev URL, Coder listens on the port you +specified and renders a browser link you can use to view your application. + +> Please note that your site manager must have enabled and configured dev URLs +> for your Coder deployment before you can use this feature. + +1. Return to your workspace overview page, and find the **Dev URLs** section. + +1. Click **Add port**. + +1. Provide a **Name** for your port, and leave the remaining fields as-is. Click + **Save**. + + ![Create dev URL](../assets/getting-started/create-devurl.png) + +1. At this point, you can build and run the sample app by returning to your Code + Web window and running the following in the terminal: + + ```console + npx create-react-app my-app + cd my-app + npm start + ``` + +1. From the workspace overview, launch your dev URL by clicking its name; Coder + will open a new browser window and point you to the appropriate URL. + + ![Launch dev URL](../assets/getting-started/launch-devurl.png) + +1. You can test preview by making changes to the `src/App.js` file; every time + you save your changes to this file, your preview will reload. + + ![Preview changes](../assets/getting-started/hello-world.png) diff --git a/getting-started/docker.md b/getting-started/docker.md new file mode 100644 index 000000000..3a9d42681 --- /dev/null +++ b/getting-started/docker.md @@ -0,0 +1,135 @@ +--- +title: Coder for Docker +description: Get started with Coder for Docker as a developer. +--- + +This tutorial shows you how to create a Coder development workspace and getting +set up to work on a web development project requiring Node.js and React.js. +You'll learn how to: + +- Connect Coder to your Git provider; +- Create a workspace; +- Add a sample project to your workspace; +- Create a dev URL and preview changes to your project. + +## Prerequisites + +Please [install Coder for Docker](../setup/docker.md) before proceeding. + +## Step 1: Log in and connect Coder to your Git provider + +In this step, you'll log into Coder and connect and authenticate with your Git +provider. This will allow you to do things like pull repositories and push +changes. + +1. Navigate to the Coder deployment using the URL provided to you during the + Coder for Docker installation process, and log in. + +1. Click on your avatar in the top-right, and select **Account**. + + ![Set account preferences](../assets/getting-started/account-preferences.png) + +1. Provide Coder with your SSH key to connect and authenticate to GitHub. + + If your site manager has configured OAuth, go to **Linked Accounts** and + follow the on-screen instructions to link your GitHub account. + + ![Link GitHub account](../assets/getting-started/linked-accounts.png) + + If your site manager has _not_ configured OAuth, go to **SSH keys**. Copy + your public SSH key and + [provide it to GitHub](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account). + + ![Add SSH key](../assets/getting-started/ssh-keys.png) + +## Step 2: Create your workspace + +You will now create the workspace where you'll work on your development project. + +1. Return to **Workspaces** using the top navigation bar. + +1. Click **New workspace** to launch the workspace-creation dialog. + +1. Provide a **Workspace Name**. + +1. In the **Image** section, click **Packaged** (this tab contains + Coder-provided images hosted in a Docker registry). Select **Ubuntu**. This + will populate the form in the **Import** tab. + +1. Under **Workspace providers**, leave the default option (which is **Docker**) + selected. + +1. Scroll to the bottom, and click **Create workspace**. The dialog will close, + allowing you to see the main workspace page. You can track the workspace + build process using the **Build log** on the right-hand side. + +![Create a workspace](../assets/getting-started/create-workspace.png) + +Once your workspace is ready for use, you'll see a chip that says **Running** +next to the name of your workspace. + +## Step 3: Add a sample project to your workspace + +Once you've created your workspace, you can start using Coder after adding a +sample project to your workspace. + +1. Under **Browser applications**, click **Code Web** to open VS Code in your + browser. + +1. When VS Code launches in your browser, click **Open folder...**. In the + prompt, you'll see `/home/coder`. This directory is where you'll clone a + sample React app project Git repository. Click **OK** to proceed. + + ![Open folder](../assets/getting-started/open-folder.png) + +1. Click the hamburger icon in the top right, and select **Terminal** > **New + Terminal** to open a new terminal. + +1. Clone the `create-react-app` repository: + + ```console + git clone git@github.com:facebook/create-react-app.git + ``` + + Once you've cloned the repository, you can click the **Explorer** icon and + expand the **create-react-app** folder in the left-have nav bar to see the + contents of the repo. + + ![View files](../assets/getting-started/view-files.png) + + You're now ready to make changes to the application. + +## Step 4: Preview your app and view changes live + +Dev URLs allow you to access the web services you're developing in your +workspace. Once you've created a dev URL, Coder listens on the port you +specified and renders a browser link you can use to view your application. + +1. Return to your workspace overview page, and find the **Dev URLs** section. + +1. Click **Add port**. + +1. Provide a **Name** for your port, and leave the remaining fields as-is. Click + **Save**. + + ![Create dev URL](../assets/getting-started/create-devurl.png) + +1. At this point, you can build and run the sample app by returning to your Code + Web window and running the following in the terminal: + + ```console + npx create-react-app my-app + cd my-app + npm start + ``` + +1. From the workspace overview, launch your dev URL by clicking its name; Coder + will open a new browser window and point you to the appropriate URL. + + ![Launch dev URL](../assets/getting-started/launch-devurl.png) + +1. You can test preview by making changes to the `src/App.js` file; every time + you save your changes to this file and refresh your browser window, your + preview will update. + + ![Preview changes](../assets/getting-started/hello-world.png) diff --git a/getting-started.md b/getting-started/index.md similarity index 93% rename from getting-started.md rename to getting-started/index.md index e5d877f58..e0fed7f48 100644 --- a/getting-started.md +++ b/getting-started/index.md @@ -37,11 +37,11 @@ the application (you can get a trial license for free [create organizations](./admin/organizations/index.md), and create an OAuth app for your users to [connect to your Git provider](./admin/git.md). -At a minimum, you’ll want to ensure you [add a container -registry](./admin/registries/index.md) for your development environments to pull -from, and [import an image](./images/importing.md) with the tools your -developers need. You can [create custom images](./images/writing.md) for your -developer workspaces as well. +At a minimum, you’ll want to ensure you +[add a container registry](./admin/registries/index.md) for your development +environments to pull from, and [import an image](./images/importing.md) with the +tools your developers need. You can [create custom images](./images/writing.md) +for your developer workspaces as well. ## Provision users diff --git a/manifest.json b/manifest.json index c6c40b565..996e8a7d6 100644 --- a/manifest.json +++ b/manifest.json @@ -27,7 +27,15 @@ ] }, { - "path": "getting-started.md" + "path": "getting-started/index.md", + "children": [ + { + "path": "getting-started/developers.md" + }, + { + "path": "getting-started/docker.md" + } + ] }, { "path": "./workspaces/index.md", diff --git a/setup/configuration.md b/setup/configuration.md index ff8a3b0f7..9eb7ce38b 100644 --- a/setup/configuration.md +++ b/setup/configuration.md @@ -58,3 +58,8 @@ dashboard, where you can create new users, images, and workspaces. Coder's default values during the setup/configuration process are acceptable only by a deployment used for evaluation purposes. + +## Next steps + +See our [getting started guide](../getting-started/developers.md) for detailed +instructions on getting your first workspace up and running. diff --git a/setup/docker.md b/setup/docker.md index 642a78556..fe8202ed9 100644 --- a/setup/docker.md +++ b/setup/docker.md @@ -60,7 +60,9 @@ Coder requires x86-64 and does not support Arm-based processors at this time. using one of the **Packaged** images by clicking on **New workspace** in the center of the UI. -At this point, you're ready to use your workspace. +At this point, you're ready to use your workspace. See our +[getting started guide](../getting-started/docker.md) for detailed instructions +on getting your first workspace up and running. ## Usage notes