git.iko.soy/urbit.org
on 514b5fc help sign in
urbit.org/content/using/running/hosting.md
202 lines 10.0 kB history raw
1+++
2title = "Cloud Hosting"
3description = "How to host your ship in the cloud so you can access it from any device."
4template = "doc.html"
5weight = 2
6[extra]
7hidetitle = "true"
8+++
10The goal of this guide is to have clear and easy to follow best practices for deploying an Urbit node to a server you control in the cloud. Deploying in the cloud allows you to access your Urbit from any device.
12Most Urbit users start out running their ship locally on one machine in order to play with it, but this means when your machine is offline your Urbit node is offline too (and can't get updates). You can also only access your Urbit from that one machine.
14This guide uses Digital Ocean as the cloud provider, but others can be used.
16## Create a Digital Ocean droplet
18- Create an account on [Digital Ocean][digital ocean].
19- Create a droplet with the following settings:
20- **Image**: Ubuntu 20.04 x64
21- **Plan**: 4GB RAM
22- **Add block storage**: Skip
23- **Datacenter Region**: Choose the region closest to you.
24- **VPC Network**: No VPC
25- **Additional Options**: None
26- **Authentication**: SSH keys, add a New SSH Key following the instructions DO gives you.
27- **How many Droplets**: 1
28- **Choose a hostname**: This will be the hostname of the box you ssh into (can be whatever you want, I used my Urbit planet name).
29- **Add tags**: None
30- **Project**: It'll select your default.
31- **Backups**: Optional (it costs a little extra, but I have it enabled for peace of mind).
33## Getting your own domain
35Your own domain will make accessing your Urbit a lot easier (it'll also allow you to secure things with a Let's Encrypt cert). Domains are relatively inexpensive and since this guide is about best practices it's a required step.
37There are a lot of domain name registrars you can use, this guide suggests [gandi.net][gandi]. From there you can search for and register a domain that you like.
39## Configuring your domain for your Digital Ocean droplet
41Once you've registered your domain you'll need to configure it to use Digital Ocean for DNS. The following steps are done on the Gandi website.
43- Click Domain on the left panel
44- Click the domain you're going to use for Urbit
45- Click "Gandi's LiveDNS" under Nameservers in the Domain configuration section of the overview page
46- Click Change
47- Click External
48- Add the Digital Ocean nameservers:
49 - `ns1.digitalocean.com`
50 - `ns2.digitalocean.com`
51 - `ns3.digitalocean.com`
52- Save the change.
53- - It can take 12-24 hours for this change to propagate.
54- Now that you've updated the DNS records you can add the domain to your droplet.
55- - Back on the DO site, click Networking from the left panel and then enter the domain you registered.
56- Click on that domain and add an A record that directs to the IP of your droplet (found on your droplet's page).
58## Creating your non-root user
60With our domain in place we're now ready to actually log into the box and start to configure the server itself.
62- Since we don't yet have a user we'll need to log in as root:
63 ```
64 $ ssh root@your_server_ip
65 ```
66- If you set a passphrase on your ssh key, you'll be asked for it. If not, you should automatically be logged in.
67- Create a new user, in our example we'll use _sammy_ (to match the DO docs), but you should use your own username:
68 ```
69 # adduser sammy
70 ```
71- Enter a strong password for your user. The questions `adduser` asks you don't matter, hit enter to skip them.
72- Give your new user sudo access:
73 ```
74 # usermod -aG sudo sammy
75 ```
76- Next we need to enable external access to our new user by moving the ssh key over from root (and setting proper permissions on it).
77- Be careful to note the **lack of trailing slash** in the command below after `/.ssh`:
78 ```
79 # rsync --archive --chown=sammy:sammy ~/.ssh /home/sammy
80 ```
81- Test this connection with `ssh sammy@your_server_ip` from your local machine in a new terminal window.
82- To test that your domain is working try `ssh sammy@your_domain` from a new terminal on your local machine.
83- You should now be able to use this user going forward with `sudo` when necessary.
85## Setting up a basic firewall
87Continuing to follow the DO docs we're going to configure the ufw firewall.
89- The below command shows us the applications available to be easily configured with firewall rules by ufw.
91 ```
92 $ sudo ufw app list
93 ```
95- Next we'll configure ufw to allow connections via ssh and to allow Urbit to use the standard web port when the firewall is enabled,
96 as well as opening a port that we'll later specify for your urbit to use to communicate directly with other ships.
98 ```
99 $ sudo ufw allow OpenSSH
100 $ sudo ufw allow www
101 $ sudo ufw allow https
102 $ sudo ufw allow 34543/udp
103 ```
105 Note that you can choose any port in place of 34543 for Ames. Just be sure to pass the same port via the `-p` option when starting your ship.
107- Next we'll turn on the firewall.
108 ```
109 $ sudo ufw enable
110 ```
111- To see the current firewall status use the following.
112 ```
113 $ sudo ufw status
114 ```
116## Installing Urbit
118Finally we're ready to install Urbit on your very own server. This part is actually pretty easy, if you haven't installed Urbit locally then the instructions are the exact same as the ones in the Urbit [install doc](/getting-started/). If you have a local ship already, we're going to install Urbit on the server and then send your local ship up.
120- **WARNING**: Since Urbit is p2p you don't want to ever run two copies of your
121 ship simultaneously. This is because other nodes that interact with each of
122 your copies will be confused by which one is the most up to date. If you end
123 up accidentally doing this you'll have to do a 'factory reset' described in the [guide to resets](/using/id/guide-to-resets) to fix things.
124- The first thing you're going to want to do is shut down your local ship, either with control-d or `|exit` in dojo.
125- Next we're going to install Urbit on the server and permit it to bind to the web ports:
126 ```
127 $ ssh your_user@your_domain
128 $ mkdir urbit
129 $ cd urbit
130 $ wget --content-disposition https://urbit.org/install/linux64/latest
131 $ tar zxf ./linux64.tgz --strip=1
132 $ sudo setcap 'cap_net_bind_service=+ep' urbit
133 ```
134- Now we're going to tar up your local ship and send it to your server, from your local machine's urbit directory:
135 ```
136 $ tar -zcvf <ship_dir_name>.tar.gz <ship_dir_name>
137 $ scp <ship_dir_name>.tar.gz your_user@your_domain:urbit
138 ```
139- Back on your server let's untar your ship and start it up with the Ames port we allowed through the firewall:
140 ```
141 $ ssh your_user@your_domain
142 $ cd urbit
143 $ tar -zxvf <ship_dir_name>.tar.gz
144 $ ./urbit -p 34543 <ship_dir_name>
145 ```
146- Now we run a few commands in Dojo to request a Let’s Encrypt cert for your
147 domain. Replace `tld` with whatever your top-level domain is e.g. `com` in
148 `example.com`. `your_subdomain` is optional and that part of the command
149 should be omitted if you are not using it):
150 ```
151 ~sampel-palnet:dojo> |start %acme
152 ~sampel-palnet:dojo> :acme &path /tld/your_domain/your_subdomain
153 ```
154- Your ship should now be sailing on the digital ocean. Check `https://your_subdomain.your_domain.tld`, if everything is working properly you should see a login page.
155- Log in with the code from `+code` in dojo like normal and you should see all of your applications.
157## Leaving your Urbit running in a Screen session
159Finally, to leave your Urbit running after you disconnect we can leave it in a Screen session. This is just a way to leave applications running in the background and then reconnect to them later. Alternatively, the same can be done with tmux.
161- First start with your ship stopped, then run the following:
162 ```
163 $ screen -S urbit
164 ```
165- This will start a screen session, we can now start up the Urbit ship from the `urbit` directory in this session:
166 ```
167 $ ./urbit <ship_dir_name>
168 ```
169- Then we can disconnect from the screen session and leave the ship running with `control-a d`
170- To get back into the screen session:
171 ```
172 $ screen -r
173 ```
174- There are more screen commands for interacting with sessions that are easy to find on the internet.
176## Links and Misc.
178A lot of the above documentation comes from combining existing resources.
180On iOS you can save a website to your homescreen as an icon. If you do this for your Urbit domain it's a little like having it as an app.
182- For the docs that made up this guide see the following links.
183 - [Digital Ocean Initial Setup][do initial setup]
184 - [Digital Ocean DNS][do dns]
185 - [Digital Ocean Nginx Installation][do nginx install]
186 - [Digital Ocean Nginx Config][do nginx config]
187 - [Digital Ocean SSL Cert Setup][do ssl config]
188 - [Urbit Install Docs](/getting-started/)
189 - [Urbit Basic Cloud Install][urbit basic cloud install]
191[gandi]: https://www.gandi.net/
192[digital ocean]: https://www.digitalocean.com/
193[do dns]: https://www.digitalocean.com/community/tutorials/how-to-point-to-digitalocean-nameservers-from-common-domain-registrars
194[do nginx install]: https://www.digitalocean.com/community/tutorials/how-to-install-nginx-on-ubuntu-18-04
195[do nginx config]: https://www.digitalocean.com/community/tutorials/how-to-deploy-a-go-web-application-using-nginx-on-ubuntu-18-04
196[do ssl config]: https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-18-04
197[urbit basic cloud install]: https://medium.com/@urbitlive/hello-world-urbit-edition-install-boot-and-run-your-urbit-planet-on-a-10-cloud-server-b9579745b9a8
198[do initial setup]: https://www.digitalocean.com/community/tutorials/initial-server-setup-with-ubuntu-18-04
199[blog github]: https://github.com/zalberico/zalberico.github.io
201If you plan to use Nginx as a reverse proxy for your Urbit, it is important that you include the following settings in your configuration in order to allow the Landscape web client to properly communicate with your Urbit:
202` chunked_transfer_encoding off; proxy_buffering off; proxy_cache off; `