@@ -0,0 +1,460 @@
1++++
2+title = "Cloud Hosting"
3+weight = 4
4+description = "How to host your ship in the cloud so you can access it from any device"
5+tag = "selfhost"
6++++
7+
8+The goal of this guide is to have clear and easy to follow best practices for
9+deploying an Urbit node to a server you control in the cloud. Deploying in the
10+cloud allows you to access your Urbit from any device.
11+
12+Most Urbit users start out running their ship locally on one machine in order to
13+play with it, but this means when your machine is offline your Urbit node is
14+offline too (and can't get updates). You can also only access your Urbit from
15+that one machine.
16+
17+This guide uses Digital Ocean as the cloud provider, but others can be used. If
18+using another provider, the setup script provided and other server configuration
19+instructions may need to be modified or done manually.
20+
21+## 1. Create a Droplet
22+
23+Create an account on [Digital Ocean](https://digitalocean.com). Once you make an
24+account, choose "Deploy a virtual machine".
25+
26+You should see the page below where you can create your Droplet, aka Virtual Machine:
27+
28+
29+
30+Fill out the options like so:
31+
32+#### Image
33+
34+Ubuntu 22.04 x64
35+
36+#### Plan
37+
38+- Shared CPU: Basic
39+- CPU options: Regular with SSD
40+- 2GB / 1 CPU ($12/mo)
41+
42+You can choose a more powerful option if you'd like but the $12 option should be
43+sufficient. Note Urbit needs 2GB of memory; it's possible to choose a cheaper
44+option and run it with less memory by using swap but it will impact performance.
45+
46+#### Add block storage
47+
48+The $12 plan includes 50GB which should be sufficient for quite some time, so
49+you can skip this.
50+
51+#### Datacenter region
52+
53+Choose the region closest to you.
54+
55+#### VPC Network
56+
57+Leave this as default.
58+
59+#### Authentication
60+
61+In the "Authentication" field, select "SSH keys" and hit "New SSH Key". Run the
62+following command in the terminal on your local machine, replacing
63+`riclen-tinlyr` with the name of your ship (sans the leading `~`):
64+
65+```bash {% copy=true %}
66+SHIP="riclen-tinlyr" bash -c 'ssh-keygen -q -N "" -C $SHIP -f ~/.ssh/$SHIP && cat ~/.ssh/$SHIP.pub'
67+```
68+
69+It should spit out a long string of letters and numbers beginning with `ssh-rsa`
70+and ending with your ship name. Copy the whole thing and paste it into the "SSH
71+key content" field on Digital Ocean. In the "Name" field, enter your ship name.
72+
73+#### Additional options
74+
75+Click "User data" and paste the script below into the field provided. This
76+will automatically configure the server and install necessary software.
77+
78+```bash {% copy=true %}
79+#!/bin/bash
80+
81+# configure swap
82+fallocate -l 2G /swapfile
83+chmod 600 /swapfile
84+mkswap /swapfile
85+swapon /swapfile
86+echo "/swapfile swap swap defaults 0 0" >> /etc/fstab
87+
88+# setup firewall
89+ufw allow OpenSSH
90+ufw allow www
91+ufw allow https
92+ufw allow 34543/udp
93+ufw enable
94+
95+# create and configure user
96+useradd -s /bin/bash -d /home/urbit -m -G sudo urbit
97+passwd -d urbit
98+echo "urbit ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
99+
100+# configure ssh keys for user
101+mkdir -p /home/urbit/.ssh
102+chmod 700 /home/urbit/.ssh
103+cp /root/.ssh/authorized_keys /home/urbit/.ssh/authorized_keys
104+chmod 600 /home/urbit/.ssh/authorized_keys
105+chown -R urbit:urbit /home/urbit/.ssh
106+
107+# configure sshd
108+mkdir -p /etc/ssh/sshd_config.d
109+cat > /etc/ssh/sshd_config.d/override.conf <<EOF
110+PermitRootLogin no
111+PubkeyAuthentication yes
112+PasswordAuthentication no
113+EOF
114+
115+# fetch and extract urbit binary
116+curl -L https://urbit.org/install/linux-x86_64/latest | tar xzk --transform='s/.*/urbit/g' -C /home/urbit/
117+chown urbit:urbit /home/urbit/urbit
118+
119+# install tmux
120+apt -y update
121+apt install -y tmux
122+
123+# reboot
124+systemctl reboot
125+```
126+
127+#### How many Droplets?
128+
129+1
130+
131+#### Choose a hostname
132+
133+This will be the name the server calls itself locally, you can put in whatever
134+you want. Your planet name is a good choice.
135+
136+#### Add tags
137+
138+Leave empty.
139+
140+#### Select project
141+
142+Leave as the default.
143+
144+#### Create Droplet
145+
146+Hit this button to create the droplet.
147+
148+## 2. Prepare for upload
149+
150+{% callout %}
151+
152+**Note**
153+
154+This step is necessary if you already have a ship running locally and want to
155+move it to the cloud. If you don't, you can skip this step.
156+
157+{% /callout %}
158+
159+In the Dojo, use either `"CTRL + D"` or `|exit` to shut down your ship.
160+
161+Archive your pier by running `tar cvzf riclen-tinlyr.tar.gz ~/path/to/your/pier`
162+(substitute your own ship name and pier location).
163+
164+## 3. Connect to the server
165+
166+To make connecting simple, you can add an alias to `~/.ssh/config` on your local
167+machine. Open `~/.ssh/config` in an editor (you may need to create it if the
168+file doesn't exist), and add the following to the bottom of the file (replacing
169+the ship name with your own and the IP address with that of your droplet):
170+
171+``` {% copy=true %}
172+Host riclen-tinlyr
173+ HostName 161.35.148.247
174+ User urbit
175+ IdentityFile ~/.ssh/riclen-tinlyr
176+ IdentitiesOnly yes
177+```
178+
179+{% tabs %}
180+
181+{% tab label="If you have an existing pier" %}
182+
183+
184+Copy the archived pier to the server with the following (substituting your ship
185+name and Host):
186+
187+```bash {% copy=true %}
188+scp riclen-tinlyr.tar.gz riclen-tinlyr:
189+```
190+
191+It may take a while to upload if your pier is large and/or your internet is
192+slow.
193+
194+{% /tab %}
195+
196+{% tab label="If you have a key file" %}
197+
198+If you have obtained a planet and want to boot it for the first time, you'll
199+need to upload its key file to the server. These instructions assume you've
200+received an invite. If you've got a planet by another method, you can also login
201+to [Bridge](https://bridge.urbit.org) and download the key file from there.
202+
203+If you've received a planet invite via email or a claim link like
204+`https://bridge.urbit.org/#labfur-batteg-dapnex-binsup-riclen-tinlyr`, open it
205+in a browser and you should see a page like the following:
206+
207+
208+
209+If you hit "Claim", it'll bring you here:
210+
211+
213+
214+Hit "Download Backup (Passport)" and it'll have you download a file named like
215+`riclen-tinlyr-passport.zip`.
216+
217+Unzip the file with:
218+
219+```bash {% copy=true %}
220+unzip ~/path/to/download/folder/riclen-tinlyr-passport.zip
221+```
222+
223+It'll create a folder called `riclen-tinlyr-passport` which will contain three files:
224+
225+- `riclen-tinlyr-1.key`
226+- `riclen-tinlyr-Management Proxy.png`
227+- `riclen-tinlyr-Master Ticket.png`
228+
229+You can physically print out the two `.png` files and store them in a safe and
230+secure location. Importantly, you should ensure the *master ticket* (which will
231+look something like `~tarnes-pilryd-dassed-sogsul`) is securely and safely
232+stored. If anyone gains access to the master ticket they'll have ownership and
233+control of your Urbit ID, and if you lose it you'll irreversibly lose ownership
234+and control of your Urbit ID.
235+
236+The next screen on the claim page will ask you to re-enter the master ticket to
237+ensure you've recorded it accurately, and then the claim process is complete.
238+Once you've securely, physically backed up the master ticket and the `.png`
239+passports, it's a good idea to delete the `riclen-tinlyr-passport.zip` file and
240+the two `.png` files, so if someone gains access to your computer, your Urbit ID
241+will be safe.
242+
243+This will leave only the `riclen-tinlyr-1.key` file. The key file contains your
244+planet's private keys, which are necessary to boot it up for the first time.
245+You'll need to copy that file to the server with the following command (again,
246+replacing `riclen-tinlyr` with your own ship and Host):
247+
248+```bash {% copy=true %}
249+scp riclen-tinlyr-passport/riclen-tinlyr-1.key riclen-tinlyr:
250+```
251+
252+Note: you should keep the `riclen-tinlyr-1.key` until you've completed this
253+guide and your ship is booted to be sure it was copied successfully, but
254+afterwards you should also delete that file for security.
255+
256+{% /tab %}
257+
258+{% /tabs %}
259+
260+Once you've either uploaded your pier or uploaded your key file as the case may
261+be, you can connect to your server:
262+
263+```bash {% copy=true %}
264+ssh riclen-tinlyr
265+```
266+You'll be taken to the shell on your server.
267+
268+## 5. Boot your ship
269+
270+{% tabs %}
271+
272+{% tab label="If you have an existing pier" %}
273+
274+In the previous section you ssh'd into the server. In the same ssh session,
275+extract the pier archive you previously uploaded, then delete the archive:
276+
277+```bash {% copy=true %}
278+tar xvzf riclen-tinlyr.tar.gz && rm riclen-tinlyr.tar.gz
279+```
280+
281+You'll now have a folder called `riclen-tinlyr`, which is your pier. Urbit is
282+best run in a tmux or screen session so it's easy to keep it running when
283+you disconnect. In this case we'll use tmux, which has already been installed
284+by the setup script.
285+
286+Run tmux:
287+
288+```bash {% copy=true %}
289+tmux
290+```
291+
292+You should now be in tmux. First, dock your ship:
293+
294+```bash {% copy=true %}
295+./urbit dock riclen-tinlyr
296+```
297+
298+That will copy the `urbit` runtime inside the pier, so you can now delete the
299+separate binary:
300+
301+```bash {% copy=true %}
302+rm urbit
303+```
304+
305+{% /tab %}
306+
307+{% tab label="If you have a key file" %}
308+
309+In the previous section you ssh'd into the server. In the same ssh session,
310+start tmux:
311+
312+```bash {% copy=true}
313+tmux
314+```
315+
316+You should now be in tmux. Boot a new ship with the following command,
317+specifying the ship name and key file, as well as the Ames port that was
318+previously opened in the firewall by the setup script:
319+
320+```bash {% copy=true %}
321+./urbit -w riclen-tinlyr -k riclen-tinlyr-1.key -p 34543
322+```
323+
324+It may take several minutes to boot the new ship. Eventually, it'll take you to
325+the Dojo (Urbit's shell) and show a prompt like `~riclen-tinlyr:dojo>`. Once
326+booted, shut the ship down again by typing `|exit` in the Dojo. After it quits,
327+it should print something like "docked successfully", which means the binary has
328+been copied inside the pier. This means you can delete the separate binary:
329+
330+```bash {% copy=true %}
331+rm urbit
332+```
333+
334+The key file is only needed when you first boot the ship, so it's good practice
335+to delete it after first boot:
336+
337+```bash {% copy=true %}
338+rm riclen-tinlyr-1.key
339+```
340+
341+{% /tab %}
342+
343+{% /tabs %}
344+
345+Run the following to allow the runtime to bind ports 80 and 443:
346+
347+```bash {% copy=true %}
348+sudo setcap 'cap_net_bind_service=+ep' riclen-tinlyr/.run
349+```
350+
351+Now you can start your ship up with the following:
352+
353+```bash {% copy=true %}
354+./riclen-tinlyr/.run -p 34543
355+```
356+
357+After a few moments it'll show the Dojo prompt like `~riclen-tinlyr:dojo>`.
358+
359+## 6. Get a domain
360+
361+To make accessing the web interface convenient, you should request an
362+`arvo.network` domain name. To do so, run the following command in the Dojo,
363+replacing the IP address with your droplet's:
364+
365+``` {% copy=true %}
366+-dns-address [%if .161.35.148.247]
367+```
368+
369+This will request a subdomain of your ship like `riclen-tinlyr.arvo.network`.
370+
371+The domain should be registered almost instantly, but sometimes it takes a while
372+for it to propagate to other DNS servers. You might therefore see the following:
373+
374+```
375+> -dns-address [%if .161.35.148.247]
376+dns: request for DNS sent to ~deg
377+dns: awaiting response from ~deg
378+http: fail (13, 504): unknown node or service
379+http: fail (14, 504): unknown node or service
380+http: fail (15, 504): unknown node or service
381+http: fail (16, 504): unknown node or service
382+http: fail (17, 504): unknown node or service
383+dns: unable to access via riclen-tinlyr.arvo.network
384+XX confirm port 80
385+XX check via nslookup
386+0
387+```
388+
389+If that happens, wait five or ten minutes and then try again. You should
390+eventually see:
391+
392+```
393+> -dns-address [%if .161.35.148.247]
394+dns: request for DNS sent to ~deg
395+dns: awaiting response from ~deg
396+[%key iter=0 width=2.047]
397+[%key iter=1 width=2.047]
398+[%key iter=2 width=2.047]
399+[%key iter=3 width=2.047]
400+acme: requesting an https certificate for riclen-tinlyr.arvo.network
401+dns: confirmed access via riclen-tinlyr.arvo.network
402+0
403+acme: received https certificate for riclen-tinlyr.arvo.network
404+http: restarting servers to apply configuration
405+http: web interface live on https://localhost:443
406+http: web interface live on http://localhost:80
407+http: loopback live on http://localhost:12321
408+```
409+
410+That means the domain has been registered and an SSL certificate has been
411+installed, so you can access the web interface securely with HTTPS.
412+
413+## 7. Log in to Landscape
414+
415+In order to login to the web interface, you need to get the web login code. Run
416+the following in the Dojo:
417+
418+``` {% copy=true %}
419++code
420+```
421+
422+It'll spit out something like `ropnys-batwyd-nossyt-mapwet`. That's your web
423+login code, you can copy that and save it in a password manager or similar. Note
424+that the web login code is separate from the master ticket.
425+
426+The server configuration should now be complete, and you can access Landscape in
427+the browser. Navigate to the domain you configured previously, in this case
428+`riclen-tinlyr.arvo.network`. You should see the Landscape login screen:
429+
430+
431+
432+Enter the web login code and you'll be taken to your ship's homescreen. Your
433+ship is now running in the cloud, and you can access it from any device by
434+visiting its URL.
435+
436+## 8. Disconnect
437+
438+You can now disconnect from the tmux session by hitting `CTRL+b d` (that is, you
439+hit `CTRL+b`, release it, and then hit `d`). You'll be taken back to the
440+ordinary shell, but the ship will still be running in the background. If you
441+want to get back to the Dojo again, you can reattach the tmux session with:
442+
443+```bash {% copy=true %}
444+tmux a
445+```
446+
447+Finally, you can disconnect from the ssh session completely by hitting `CTRL+d`.
448+
449+## 9. Cleanup
450+
451+If you booted a new ship by uploading a key file, it's a good idea to now delete
452+the key file on your local machine.
453+
454+If you uploaded an existing pier, you should delete the old copy of both the
455+pier directory and the `.tar.gz` archive on your local machine. You might be
456+tempted to keep one of these as a backup, but note that **you must never again
457+boot the old copy on the live network**. Doing so will create unfixable
458+networking problems and require you to perform a factory reset through Bridge,
459+wiping your ship's data. We therefore don't recommend you keep duplicates of
460+your pier lying around.