@@ -0,0 +1,468 @@
2+title = "Cloud hosting"
4+description = "How to host your ship in the cloud so you can access it from any device"
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.
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
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.
21+## 1. Create a Droplet
23+Create an account on [Digital Ocean](https://digitalocean.com). Once you make an
24+account, choose "Deploy a virtual machine".
26+You should see the page below where you can create your Droplet, aka Virtual Machine:
28+
30+Fill out the options like so:
39+- CPU options: Regular with SSD
40+- 2GB / 1 CPU ($12/mo)
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.
46+#### Add block storage
48+The $12 plan includes 50GB which should be sufficient for quite some time, so
51+#### Datacenter region
53+Choose the region closest to you.
57+Leave this as default.
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 `~`):
65+```bash {% copy=true %}
66+SHIP="riclen-tinlyr" bash -c 'ssh-keygen -q -N "" -C $SHIP -f ~/.ssh/$SHIP && cat ~/.ssh/$SHIP.pub'
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.
73+#### Additional options
75+Click "User data" and paste the script below into the field provided. This
76+will automatically configure the server and install necessary software.
78+```bash {% copy=true %}
82+fallocate -l 2G /swapfile
86+echo "/swapfile swap swap defaults 0 0" >> /etc/fstab
95+# create and configure user
96+useradd -s /bin/bash -d /home/urbit -m -G sudo urbit
98+echo "urbit ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
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
108+mkdir -p /etc/ssh/sshd_config.d
109+cat > /etc/ssh/sshd_config.d/override.conf <<EOF
111+PubkeyAuthentication yes
112+PasswordAuthentication no
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
127+#### How many Droplets?
131+#### Choose a hostname
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.
142+Leave as the default.
146+Hit this button to create the droplet.
148+## 2. Prepare for upload
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.
159+In the Dojo, use either `"CTRL + D"` or `|exit` to shut down your ship.
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).
164+## 3. Connect to the server
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):
173+ HostName 161.35.148.247
175+ IdentityFile ~/.ssh/riclen-tinlyr
181+{% tab label="If you have an existing pier" %}
184+Copy the archived pier to the server with the following (substituting your ship
187+```bash {% copy=true %}
188+scp riclen-tinlyr.tar.gz riclen-tinlyr:
191+It may take a while to upload if your pier is large and/or your internet is
196+{% tab label="If you have a key file" %}
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.
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:
207+
209+If you hit "Claim", it'll bring you here:
212+screenshot](https://media.urbit.org/operators/manual/running/hosting/download-passport.png)
214+Hit "Download Backup (Passport)" and it'll have you download a file named like
215+`riclen-tinlyr-passport.zip`.
219+```bash {% copy=true %}
220+unzip ~/path/to/download/folder/riclen-tinlyr-passport.zip
223+It'll create a folder called `riclen-tinlyr-passport` which will contain three files:
225+- `riclen-tinlyr-1.key`
226+- `riclen-tinlyr-Management Proxy.png`
227+- `riclen-tinlyr-Master Ticket.png`
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.
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
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):
248+```bash {% copy=true %}
249+scp riclen-tinlyr-passport/riclen-tinlyr-1.key riclen-tinlyr:
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.
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:
263+```bash {% copy=true %}
266+You'll be taken to the shell on your server.
272+{% tab label="If you have an existing pier" %}
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:
277+```bash {% copy=true %}
278+tar xvzf riclen-tinlyr.tar.gz && rm riclen-tinlyr.tar.gz
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
288+```bash {% copy=true %}
292+You should now be in tmux. First, dock your ship:
294+```bash {% copy=true %}
295+./urbit dock riclen-tinlyr
298+That will copy the `urbit` runtime inside the pier, so you can now delete the
301+```bash {% copy=true %}
307+{% tab label="If you have a key file" %}
309+In the previous section you ssh'd into the server. In the same ssh session,
312+```bash {% copy=true}
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:
320+```bash {% copy=true %}
321+./urbit -w riclen-tinlyr -k riclen-tinlyr-1.key -p 34543
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:
330+```bash {% copy=true %}
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:
337+```bash {% copy=true %}
338+rm riclen-tinlyr-1.key
345+Run the following to allow the runtime to bind ports 80 and 443:
347+```bash {% copy=true %}
348+sudo setcap 'cap_net_bind_service=+ep' riclen-tinlyr/.run
351+Now you can start your ship up with the following:
353+```bash {% copy=true %}
354+./riclen-tinlyr/.run -p 34543
357+After a few moments it'll show the Dojo prompt like `~riclen-tinlyr:dojo>`.
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:
366+-dns-address [%if .161.35.148.247]
369+This will request a subdomain of your ship like `riclen-tinlyr.arvo.network`.
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:
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
385+XX check via nslookup
389+If that happens, wait five or ten minutes and then try again. You should
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
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
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.
413+## 7. Log in to Landscape
415+In order to login to the web interface, you need to get the web login code. Run
416+the following in the Dojo:
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.
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:
430+
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
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:
443+```bash {% copy=true %}
447+Finally, you can disconnect from the ssh session completely by hitting `CTRL+d`.
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.
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.
465+- Kep your Urbit runtime up-to-date to take advantage of the latest Landscape and Application over-the-air updates. See [Step #5 in the CLI guide](/getting-started/cli#5-runtime-upgrades) to update your runtime.
467+- Learn how to [get around your
468+urbit](/getting-started/getting-around).