Skip to content

Commit 558d84b

Browse files
author
Katie Horne
authored
chore: Getting Started tutorials (coder#760)
1 parent 9c94ac0 commit 558d84b

15 files changed

+299
-7
lines changed

‎assets/getting-started/account-preferences.png

281 KB
Loading

‎assets/getting-started/create-devurl.png

298 KB
Loading

‎assets/getting-started/create-workspace.png

235 KB
Loading

‎assets/getting-started/hello-world.png

130 KB
Loading

‎assets/getting-started/launch-devurl.png

207 KB
Loading

‎assets/getting-started/linked-accounts.png

105 KB
Loading

‎assets/getting-started/open-folder.png

227 KB
Loading

‎assets/getting-started/ssh-keys.png

102 KB
Loading

‎assets/getting-started/view-files.png

381 KB
Loading

‎getting-started/developers.md

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
---
2+
title: Developers
3+
description: Get started with Coder as a developer.
4+
---
5+
6+
This article will walk you through the process of getting started with a Coder
7+
workspace and a web development project featuring Node.js and React.js. You'll
8+
learn how to:
9+
10+
- Connect Coder to your Git provider;
11+
- Create a workspace;
12+
- Add a sample project to your workspace;
13+
- Create a dev URL and preview changes to your project.
14+
15+
## Prerequisites
16+
17+
This guide assumes that you have a Coder deployment available to you and that
18+
you have the credentials needed to access the deployment.
19+
20+
## Step 1: Log in and connect Coder to your Git provider
21+
22+
In this step, you'll log into Coder and connect and authenticate with your Git
23+
provider. This will allow you to do things like pull repositories and push
24+
changes.
25+
26+
1. Navigate to the Coder deployment using the URL provided to you by your site
27+
manager, and log in.
28+
29+
1. Click on your avatar in the top-right, and select **Account**.
30+
31+
![Set account preferences](../assets/getting-started/account-preferences.png)
32+
33+
1. Provide Coder with your SSH key to connect and authenticate to GitHub.
34+
35+
If your site manager has configured OAuth, go to **Linked Accounts** and
36+
follow the on-screen instructions to link your GitHub account.
37+
38+
![Link GitHub account](../assets/getting-started/linked-accounts.png)
39+
40+
If your site manager has _not_ configured OAuth, go to **SSH keys**. Copy
41+
your public SSH key and
42+
[provide it to GitHub](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account).
43+
44+
![Add SSH key](../assets/getting-started/ssh-keys.png)
45+
46+
## Step 2: Create your workspace
47+
48+
You will now create the workspace where you'll work on your development project.
49+
50+
1. Return to **Workspaces** using the top navigation bar.
51+
52+
1. Click **New workspace** to launch the workspace-creation dialog.
53+
54+
1. Provide a **Workspace Name**.
55+
56+
1. In the **Image** section, click **Packaged** (this tab contains
57+
Coder-provided images hosted in a Docker registry). Select **NodeJS**. This
58+
will populate the form in the **Import** tab.
59+
60+
1. Under **Workspace providers**, leave the default option (which is
61+
**built-in**) selected.
62+
63+
1. Expand the **Advanced** section. If the **Run as a container-based virtual
64+
machine** option is selected, _unselect_ the box. Leave the **CPU**,
65+
**Memory**, **Disk**, and **GPU** allocations as-is.
66+
67+
1. Scroll to the bottom, and click **Create workspace**. The dialog will close,
68+
allowing you to see the main workspace page. You can track the workspace
69+
build process using the **Build log** on the right-hand side.
70+
71+
![Create a workspace](../assets/getting-started/create-workspace.png)
72+
73+
Once your workspace is ready for use, you'll see a chip that says **Running**
74+
next to the name of your workspace.
75+
76+
## Step 3: Add a sample project to your workspace
77+
78+
Once you've created your workspace, you can start using Coder after adding a
79+
sample project to your workspace.
80+
81+
1. Under **Browser applications**, click **Code Web** to open VS Code in your
82+
browser.
83+
84+
1. When VS Code launches in your browser, click **Open folder...**. In the
85+
prompt, you'll see `/home/coder`. This directory is where you'll clone a
86+
sample React app project Git repository. Click **OK** to proceed.
87+
88+
![Open folder](../assets/getting-started/open-folder.png)
89+
90+
1. Click the hamburger icon in the top right, and select **Terminal** > **New
91+
Terminal** to open a new terminal.
92+
93+
1. Clone the `create-react-app` repository:
94+
95+
```console
96+
git clone git@github.com:facebook/create-react-app.git
97+
```
98+
99+
Once you've cloned the repository, you can click the **Explorer** icon and
100+
expand the **create-react-app** folder in the left-have nav bar to see the
101+
contents of the repo.
102+
103+
![View files](../assets/getting-started/view-files.png)
104+
105+
You're now ready to make changes to the application.
106+
107+
## Step 4: Preview your app and view changes live
108+
109+
Dev URLs allow you to access the web services you're developing in your
110+
workspace. Once you've created a dev URL, Coder listens on the port you
111+
specified and renders a browser link you can use to view your application.
112+
113+
> Please note that your site manager must have enabled and configured dev URLs
114+
> for your Coder deployment before you can use this feature.
115+
116+
1. Return to your workspace overview page, and find the **Dev URLs** section.
117+
118+
1. Click **Add port**.
119+
120+
1. Provide a **Name** for your port, and leave the remaining fields as-is. Click
121+
**Save**.
122+
123+
![Create dev URL](../assets/getting-started/create-devurl.png)
124+
125+
1. At this point, you can build and run the sample app by returning to your Code
126+
Web window and running the following in the terminal:
127+
128+
```console
129+
npx create-react-app my-app
130+
cd my-app
131+
npm start
132+
```
133+
134+
1. From the workspace overview, launch your dev URL by clicking its name; Coder
135+
will open a new browser window and point you to the appropriate URL.
136+
137+
![Launch dev URL](../assets/getting-started/launch-devurl.png)
138+
139+
1. You can test preview by making changes to the `src/App.js` file; every time
140+
you save your changes to this file, your preview will reload.
141+
142+
![Preview changes](../assets/getting-started/hello-world.png)

‎getting-started/docker.md

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
title: Coder for Docker
3+
description: Get started with Coder for Docker as a developer.
4+
---
5+
6+
This tutorial shows you how to create a Coder development workspace and getting
7+
set up to work on a web development project requiring Node.js and React.js.
8+
You'll learn how to:
9+
10+
- Connect Coder to your Git provider;
11+
- Create a workspace;
12+
- Add a sample project to your workspace;
13+
- Create a dev URL and preview changes to your project.
14+
15+
## Prerequisites
16+
17+
Please [install Coder for Docker](../setup/docker.md) before proceeding.
18+
19+
## Step 1: Log in and connect Coder to your Git provider
20+
21+
In this step, you'll log into Coder and connect and authenticate with your Git
22+
provider. This will allow you to do things like pull repositories and push
23+
changes.
24+
25+
1. Navigate to the Coder deployment using the URL provided to you during the
26+
Coder for Docker installation process, and log in.
27+
28+
1. Click on your avatar in the top-right, and select **Account**.
29+
30+
![Set account preferences](../assets/getting-started/account-preferences.png)
31+
32+
1. Provide Coder with your SSH key to connect and authenticate to GitHub.
33+
34+
If your site manager has configured OAuth, go to **Linked Accounts** and
35+
follow the on-screen instructions to link your GitHub account.
36+
37+
![Link GitHub account](../assets/getting-started/linked-accounts.png)
38+
39+
If your site manager has _not_ configured OAuth, go to **SSH keys**. Copy
40+
your public SSH key and
41+
[provide it to GitHub](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account).
42+
43+
![Add SSH key](../assets/getting-started/ssh-keys.png)
44+
45+
## Step 2: Create your workspace
46+
47+
You will now create the workspace where you'll work on your development project.
48+
49+
1. Return to **Workspaces** using the top navigation bar.
50+
51+
1. Click **New workspace** to launch the workspace-creation dialog.
52+
53+
1. Provide a **Workspace Name**.
54+
55+
1. In the **Image** section, click **Packaged** (this tab contains
56+
Coder-provided images hosted in a Docker registry). Select **Ubuntu**. This
57+
will populate the form in the **Import** tab.
58+
59+
1. Under **Workspace providers**, leave the default option (which is **Docker**)
60+
selected.
61+
62+
1. Scroll to the bottom, and click **Create workspace**. The dialog will close,
63+
allowing you to see the main workspace page. You can track the workspace
64+
build process using the **Build log** on the right-hand side.
65+
66+
![Create a workspace](../assets/getting-started/create-workspace.png)
67+
68+
Once your workspace is ready for use, you'll see a chip that says **Running**
69+
next to the name of your workspace.
70+
71+
## Step 3: Add a sample project to your workspace
72+
73+
Once you've created your workspace, you can start using Coder after adding a
74+
sample project to your workspace.
75+
76+
1. Under **Browser applications**, click **Code Web** to open VS Code in your
77+
browser.
78+
79+
1. When VS Code launches in your browser, click **Open folder...**. In the
80+
prompt, you'll see `/home/coder`. This directory is where you'll clone a
81+
sample React app project Git repository. Click **OK** to proceed.
82+
83+
![Open folder](../assets/getting-started/open-folder.png)
84+
85+
1. Click the hamburger icon in the top right, and select **Terminal** > **New
86+
Terminal** to open a new terminal.
87+
88+
1. Clone the `create-react-app` repository:
89+
90+
```console
91+
git clone git@github.com:facebook/create-react-app.git
92+
```
93+
94+
Once you've cloned the repository, you can click the **Explorer** icon and
95+
expand the **create-react-app** folder in the left-have nav bar to see the
96+
contents of the repo.
97+
98+
![View files](../assets/getting-started/view-files.png)
99+
100+
You're now ready to make changes to the application.
101+
102+
## Step 4: Preview your app and view changes live
103+
104+
Dev URLs allow you to access the web services you're developing in your
105+
workspace. Once you've created a dev URL, Coder listens on the port you
106+
specified and renders a browser link you can use to view your application.
107+
108+
1. Return to your workspace overview page, and find the **Dev URLs** section.
109+
110+
1. Click **Add port**.
111+
112+
1. Provide a **Name** for your port, and leave the remaining fields as-is. Click
113+
**Save**.
114+
115+
![Create dev URL](../assets/getting-started/create-devurl.png)
116+
117+
1. At this point, you can build and run the sample app by returning to your Code
118+
Web window and running the following in the terminal:
119+
120+
```console
121+
npx create-react-app my-app
122+
cd my-app
123+
npm start
124+
```
125+
126+
1. From the workspace overview, launch your dev URL by clicking its name; Coder
127+
will open a new browser window and point you to the appropriate URL.
128+
129+
![Launch dev URL](../assets/getting-started/launch-devurl.png)
130+
131+
1. You can test preview by making changes to the `src/App.js` file; every time
132+
you save your changes to this file and refresh your browser window, your
133+
preview will update.
134+
135+
![Preview changes](../assets/getting-started/hello-world.png)

‎getting-started.md renamed to ‎getting-started/index.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -37,11 +37,11 @@ the application (you can get a trial license for free
3737
[create organizations](./admin/organizations/index.md), and create an OAuth app
3838
for your users to [connect to your Git provider](./admin/git.md).
3939

40-
At a minimum, you’ll want to ensure you [add a container
41-
registry](./admin/registries/index.md) for your development environments to pull
42-
from, and [import an image](./images/importing.md) with the tools your
43-
developers need. You can [create custom images](./images/writing.md) for your
44-
developer workspaces as well.
40+
At a minimum, you’ll want to ensure you
41+
[add a container registry](./admin/registries/index.md) for your development
42+
environments to pull from, and [import an image](./images/importing.md) with the
43+
tools your developers need. You can [create custom images](./images/writing.md)
44+
for your developer workspaces as well.
4545

4646
## Provision users
4747

‎manifest.json

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,15 @@
2727
]
2828
},
2929
{
30-
"path": "getting-started.md"
30+
"path": "getting-started/index.md",
31+
"children": [
32+
{
33+
"path": "getting-started/developers.md"
34+
},
35+
{
36+
"path": "getting-started/docker.md"
37+
}
38+
]
3139
},
3240
{
3341
"path": "./workspaces/index.md",

‎setup/configuration.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,3 +58,8 @@ dashboard, where you can create new users, images, and workspaces.
5858

5959
Coder's default values during the setup/configuration process are acceptable
6060
only by a deployment used for evaluation purposes.
61+
62+
## Next steps
63+
64+
See our [getting started guide](../getting-started/developers.md) for detailed
65+
instructions on getting your first workspace up and running.

‎setup/docker.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,9 @@ Coder requires x86-64 and does not support ARM-based processors at this time.
6060
using one of the **Packaged** images by clicking on **New workspace** in the
6161
center of the UI.
6262

63-
At this point, you're ready to use your workspace.
63+
At this point, you're ready to use your workspace. See our
64+
[getting started guide](../getting-started/docker.md) for detailed instructions
65+
on getting your first workspace up and running.
6466

6567
## Usage notes
6668

0 commit comments

Comments
 (0)