Skip to content

Commit 04217a8

Browse files
EdwardAngertEdwardAngert
committed
add quickstart tutorial
1 parent c9313bc commit 04217a8

File tree

6 files changed

+248
-1
lines changed

6 files changed

+248
-1
lines changed

‎docs/images/screenshots/create-template.png

80.1 KB
Loading

‎docs/images/screenshots/welcome-create-admin-user.png

46.7 KB
Loading

‎docs/images/screenshots/workspace-running-with-topbar.png

57.6 KB
Loading

‎docs/manifest.json

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -634,6 +634,11 @@
634634
"path": "./tutorials/index.md",
635635
"icon_path": "./images/icons/generic.svg",
636636
"children": [
637+
{
638+
"title": "Get started with Coder",
639+
"description": "Learn how to install and run Coder quickly",
640+
"path": "./tutorials/quickstart.md"
641+
},
637642
{
638643
"title": "Write a Template from Scratch",
639644
"description": "Learn how to author Coder templates",

‎docs/tutorials/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,5 @@ Enterprise. These tutorials are hosted on our
66
request new topics to be covered.
77

88
<children>
9-
This page is rendered on https://coder.com/docs/guides. Refer to the other documents in the `guides/` directory for specific employee-written guides.
9+
This page is rendered on <https://coder.com/docs/tutorials>. Refer to the other documents in the `guides/` directory for specific employee-written guides.
1010
</children>

‎docs/tutorials/quickstart.md

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
# Get started with Coder
2+
3+
<div style="padding: 0px; margin: 0px;">
4+
<span style="vertical-align:middle;">Author: </span>
5+
<a href="https://github.com/EdwardAngert" style="text-decoration: none; color: inherit; margin-bottom: 0px;">
6+
<span style="vertical-align:middle;">Edward Angert</span>
7+
<img src="https://avatars.githubusercontent.com/u/17991901?v=4" width="24px" height="24px" style="vertical-align:middle; margin: 0px;"/>
8+
</a>
9+
</div>
10+
September 23, 2024
11+
12+
---
13+
14+
Follow the steps in this guide to install Coder locally or on a cloud-hosting
15+
provider, set up a workspace, and connect to it from VS Code.
16+
17+
By the end of this guide, you'll have a remote development environment that you
18+
can connect to from any device anywhere, so you can work on the same files in a
19+
persistent environment from your main device, a tablet, or your phone.
20+
21+
## Install and start Coder
22+
23+
<div class="tabs">
24+
25+
## Linux/macOS
26+
27+
1. Install Docker:
28+
29+
```bash
30+
curl -sSL https://get.docker.com | sh
31+
```
32+
33+
For more details, visit:
34+
35+
- [Linux instructions](https://docs.docker.com/desktop/install/linux-install/)
36+
- [Mac instructions](https://docs.docker.com/desktop/install/mac-install/)
37+
38+
1. Set up the Docker daemon in rootless mode for your user to run Docker as a
39+
non-privileged user:
40+
41+
```shell
42+
dockerd-rootless-setuptool.sh install
43+
```
44+
45+
Depending on your system's dependencies, you might need to run other commands
46+
before you retry this step. Read the output of this command for further
47+
instructions.
48+
49+
1. Assign your user to the Docker group:
50+
51+
```shell
52+
sudo usermod -aG docker $USER
53+
```
54+
55+
1. Install Coder:
56+
57+
```shell
58+
curl -L https://coder.com/install.sh | sh
59+
```
60+
61+
- For standalone binaries, system packages, or other alternate installation
62+
methods, refer to the
63+
[latest release on GitHub](https://github.com/coder/coder/releases/latest).
64+
65+
1. Start Coder:
66+
67+
```shell
68+
coder server
69+
```
70+
71+
## Windows
72+
73+
> **Important:** If you plan to use the built-in PostgreSQL database, ensure
74+
> that the
75+
> [Visual C++ Runtime](https://learn.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist#latest-microsoft-visual-c-redistributable-version)
76+
> is installed.
77+
78+
1. [Install Docker](https://docs.docker.com/desktop/install/windows-install/).
79+
80+
1. Use the
81+
[`winget`](https://learn.microsoft.com/en-us/windows/package-manager/winget/#use-winget)
82+
package manager to install Coder:
83+
84+
```powershell
85+
winget install Coder.Coder
86+
```
87+
88+
1. Start Coder:
89+
90+
```shell
91+
coder server
92+
```
93+
94+
</div>
95+
96+
## Configure Coder with a new Workspace
97+
98+
1. If you're running Coder locally, go to <http://0.0.0.0:3001/setup>.
99+
100+
- If you get a browser warning similar to `Secure Site Not Available`, you
101+
can ignore the warning and continue to the setup page.
102+
103+
If your Coder server is on a network or cloud device, locate the message in
104+
your terminal that reads,
105+
`View the Web UI: https://<CUSTOM-STRING>.<TUNNEL>.try.coder.app`. The server
106+
begins to stream logs immediately and you might have to scroll up to find it.
107+
108+
1. On the **Welcome to Coder** page, enter the information to create an admin
109+
user, then select **Create account**.
110+
111+
![Welcome to Coder - Create admin user](../images/screenshots/welcome-create-admin-user.png)_Welcome
112+
to Coder - Create admin user_
113+
114+
1. On the **Workspaces** page, select **Go to templates** to create a new
115+
template.
116+
117+
1. For this guide, use a Docker container. Locate **Docker Containers** and
118+
select **Use template**.
119+
120+
1. Give the template a **Name** that you'll recognize both in the Coder UI and
121+
in command-line calls.
122+
123+
The rest of the template details are optional, but will be helpful when you
124+
have more templates.
125+
126+
![Create template](../images/screenshots/create-template.png)_Create
127+
template_
128+
129+
1. Select **Create template**.
130+
131+
1. After the template is ready, select **Create Workspace**.
132+
133+
1. Give the workspace a name and select **Create Workspace**.
134+
135+
1. Coder starts your new workspace:
136+
137+
![getting-started-workspace is running](../images/screenshots/workspace-running-with-topbar.png)_Workspace
138+
is running_
139+
140+
1. Select **VS Code Desktop** to install the Coder extension and connect to your
141+
Coder workspace.
142+
143+
## Work on some code
144+
145+
After VS Code loads the remote environment, you can select **Open Folder** to
146+
explore directories in the Docker container or work on something new.
147+
148+
To clone an existing repository:
149+
150+
1. Select **Clone Repository** and enter the repository URL.
151+
152+
For example, to clone the Coder repo, enter
153+
`https://github.com/coder/coder.git`.
154+
155+
Learn more about how to find the repository URL in the
156+
[GitHub documentation](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository).
157+
158+
1. Choose the folder to which VS Code should clone the repo. It will be in its
159+
own directory within this folder.
160+
161+
Note that you cannot create a new parent directory in this step.
162+
163+
1. After VS Code completes the clone, select **Open** to open the directory.
164+
165+
1. You are now using VS Code in your Coder environment!
166+
167+
## What's next?
168+
169+
Now that you have your own workspace, use the same template to set one up for a
170+
teammate.
171+
172+
Go to **Templates** and select **Create Workspace** and continue from Step 7 in
173+
[Configure Coder with a new workspace](#configure-coder-with-a-new-workspace).
174+
175+
After that, you can try to:
176+
177+
- [Customize templates](../admin/templates/extending-templates//index.md)
178+
- [Enable Prometheus metrics](../admin/integrations/prometheus.md)
179+
- [Deploy to Google Cloud Platform (GCP)](../install/cloud/compute-engine.md)
180+
181+
## Troubleshooting
182+
183+
### Cannot connect to the Docker daemon
184+
185+
> Error: Error pinging Docker server: Cannot connect to the Docker daemon at
186+
> unix:///var/run/docker.sock. Is the docker daemon running?
187+
188+
1. Install Docker for your system:
189+
190+
```shell
191+
curl -sSL https://get.docker.com | sh
192+
```
193+
194+
1. Set up the Docker daemon in rootless mode for your user to run Docker as a
195+
non-privileged user:
196+
197+
```shell
198+
dockerd-rootless-setuptool.sh install
199+
```
200+
201+
Depending on your system's dependencies, you might need to run other commands
202+
before you retry this step. Read the output of this command for further
203+
instructions.
204+
205+
1. Assign your user to the Docker group:
206+
207+
```shell
208+
sudo usermod -aG docker $USER
209+
```
210+
211+
1. Confirm that the user has been added:
212+
213+
```console
214+
$ groups
215+
docker sudo users
216+
```
217+
218+
- Ubuntu users might not see the group membership update. In that case, run
219+
the following command or reboot the machine:
220+
221+
```shell
222+
newgrp docker
223+
```
224+
225+
### Can't start Coder server: Address already in use
226+
227+
```shell
228+
Encountered an error running "coder server", see "coder server --help" for more information
229+
error: configure http(s): listen tcp 127.0.0.1:3000: bind: address already in use
230+
```
231+
232+
1. Stop the process:
233+
234+
```shell
235+
sudo systemctl stop coder
236+
```
237+
238+
1. Start Coder:
239+
240+
```shell
241+
coder server
242+
```

0 commit comments

Comments
 (0)