e2e9ea6 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

docs: add cloud hosting docs

e2e9ea6Zach Alberico6 years ago

content/using/operations/hosting.mdnew file+264

compare with master

unifiedsplit

@@ -0,0 +1,264 @@

1++++

2+title = "Hosting Your Ship On The Cloud"

3+description = "How to host your ship in the cloud so you can access it from any device."

4+template = "page_indiced.html"

5+weight = 2

6+aliases = ["docs/using/hosting/"]

7+[extra]

8+hidetitle = "true"

9++++

10+

11+## Hosting Your Ship On The Cloud

12+The 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.

13+

14+Most 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).

15+You can also only access your Urbit from that one machine.

16+

17+This guide uses Digital Ocean as the cloud provider, but others can be used.

18+

19+## Create a Digital Ocean droplet

20+ - Create an account on [Digital Ocean][Digital Ocean].

21+ - Create a droplet with the following settings:

22+ - **Image**: Ubuntu 18.04 x64

23+ - **Plan**: Standard

24+ - **Size**:

25+ - **Minimum**: $10 (2GB/1CPU)

26+ - **Recommended**: $15 (3GB/1CPU)

27+ - **Bonus**: $20 (4GB/2CPU)

28+ - **Add block storage**: Skip

29+ - **Datacenter Region**: Choose the region closest to you.

30+ - **VPC Network**: No VPC

31+ - **Additional Options**: None

32+ - **Authentication**: SSH keys, add a New SSH Key following the instructions DO gives you.

33+ - **How many Droplets**: 1

34+ - **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).

35+ - **Add tags**: None

36+ - **Project**: It'll select your default.

37+ - **Backups**: Optional (it costs a little extra, but I have it enabled for peace of mind).

38+

39+## Getting your own domain

40+Your 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 I'm making it a required step.

41+

42+There are a lot of domain name registrars you can use, this guide suggests [gandi.net][Gandi] because that's the one I use. From there you can search for and register a domain that you like.

43+

44+## Configuring your domain for your Digital Ocean droplet

45+Once 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.

46+ - Click Domain on the left panel

47+ - Click the domain you're going to use for Urbit

48+ - Click "Gandi's LiveDNS nameservers" under name servers on the overview page

49+ - Click Change

50+ - Remove Gandi servers and add the Digital Ocean ones instead:

51+ - `ns1.digitalocean.com`

52+ - `ns2.digitalocean.com`

53+ - `ns3.digitalocean.com`

54+ - Save the change.

55+ - It can take some time for this change to propagate, but I found it to be pretty quick (a few minutes).

56+ - Now that you've updated the DNS records you can add the domain to your droplet.

57+ - Back on the DO site, click Networking from the left panel and then enter the domain you registered to have it set for your project.

58+

59+## Creating your non-root user

60+With our domain in place we're now ready to actually log into the box and start to configure the server itself.

61+ - Since we don't yet have a user we'll need to log in as root:

62+ ```

63+ $ ssh root@your_server_ip

64+ ```

65+ - If you set a passphrase on your ssh key, you'll be asked for it. If not, you should automatically be logged in.

66+ - Create a new user, in our example we'll use *sammy* (to match the DO docs), but you should use your own username:

67+ ```

68+ # adduser sammy

69+ ```

70+ - Enter a strong password for your user. The questions `adduser` asks you don't matter, hit enter to skip them.

71+ - Give your new user sudo access:

72+ ```

73+ # usermod -aG sudo sammy

74+ ```

75+ - 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).

76+ - Be careful to note the **lack of trailing slash** in the command below after `/.ssh`:

77+ ```

78+ # rsync --archive --chown=sammy:sammy ~/.ssh /home/sammy

79+ ```

80+ - Test this connection with `ssh sammy@your_server_ip` from your local machine in a new terminal window.

81+ - To test that your domain is working try `ssh sammy@your_domain` from a new terminal on your local machine.

82+ - You should now be able to use this user going forward with `sudo` when necessary.

83+

84+## Setting up a basic firewall

85+Continuing to follow the DO docs we're going to configure the ufw firewall.

86+ - The below command shows us the applications available to be easily configured with firewall rules by ufw.

87+ ```

88+ $ sudo ufw app list

89+ ```

90+ - Next we'll configure ufw to allow connections via ssh when the firewall is enabled.

91+ ```

92+ $ sudo ufw allow OpenSSH

93+ ```

94+ - This command will allow UDP connections on a port that we'll later tell Urbit to use for Ames (the Urbit to Urbit communication protocol)

95+ ```

96+ $ sudo ufw allow 32123/udp

97+ ```

98+ - Next we'll turn on the firewall.

99+ ```

100+ $ sudo ufw enable

101+ ```

102+ - To see the current the current firewall status use the following.

103+ ```

104+ $ sudo ufw status

105+ ```

106+

107+## Installing Nginx

108+Nginx is a webserver we're going to use as a reverse proxy. All incoming traffic to our Digital Ocean droplet will pass through Nginx and from there to Urbit. This allows us to lock everything else down and secure just that entry point.

109+ - First we need to update available packages and install Nginx.

110+ ```

111+ $ sudo apt update

112+ $ sudo apt install nginx

113+ ```

114+ - Now that we've installed Nginx we have to update the firewall settings:

115+ ```

116+ $ sudo ufw allow 'Nginx Full'

117+ ```

118+ - You can verify this change with:

119+ ```

120+ $ sudo ufw status

121+ ```

122+ - Nginx should automatically be started after installation, you can confirm this with:

123+ ```

124+ $ systemctl status nginx

125+ ```

126+ - You can also confirm that it's up by going to your droplet's IP address, you should see a "Welcome to nginx!" message.

127+ - You can start/stop/restart Nginx with commands like the following:

128+ ```

129+ $ sudo systemctl restart nginx

130+ ```

131+ - You can also reload config without restarting with:

132+ ```

133+ $ sudo systemctl reload nginx

134+ ```

135+

136+## Configuring Nginx

137+Now we're going to configure Nginx so it serves up your Urbit traffic securely.

138+ - Navigate to the `sites-available` directory:

139+ ```

140+ $ cd /etc/nginx/sites-available

141+ ```

142+ - Create a new file for your domain:

143+ ```

144+ $ sudo vim your_domain

145+ ```

146+ - Add the following config (putting your domain in the **your_domain** location):

147+ ```

148+ server {

149+ server_name your_domain;

150+

151+ location / {

152+ proxy_pass http://localhost:8080;

153+ proxy_set_header Forwarded for=$remote_addr;

154+ proxy_set_header Connection '';

155+ proxy_http_version 1.1;

156+ chunked_transfer_encoding off;

157+ proxy_buffering off;

158+ proxy_cache off;

159+ }

160+ }

161+ ```

162+ *Note*: **your_domain** should be of the form `example.com` without www or https.

163+ - Next we're going to create a symlink to enable this in `sites-enabled` for Nginx:

164+ ```

165+ $ sudo ln -s /etc/nginx/sites-available/your_domain /etc/nginx/sites-enabled/your_domain

166+ ```

167+ - Now reload the Nginx config:

168+ ```

169+ $ sudo nginx -s reload

170+ ```

171+

172+## Configuring Let's Encrypt secure certificate

173+Now that we've got the Nginx reverse proxy installed we're going to get a Let's Encrypt SSL cert for it and configure it to automatically renew.

174+ - We're going to do this with certbot, first we have to add the up to date repository:

175+ ```

176+ $ sudo add-apt-repository ppa:certbot/certbot

177+ ```

178+ - Next we're going to install the package:

179+ ```

180+ $ sudo apt install python-certbot-nginx

181+ ```

182+ - Next we're going to request a cert from certbot:

183+ ```

184+ $ sudo certbot --nginx -d your_domain

185+ ```

186+ - You'll have to agree to the TOS and then it'll run a test to verify that you control the domain you're requesting a cert for.

187+ - Certbot will then ask if you want to redirect all traffic to HTTPS. You should select yes for this (option 2).

188+ - Certbot will automatically update your Nginx config with the settings it needs. It'll also automatically renew before cert expiration.

189+ - You can now verify your site is working properly by going to `https://your_domain`, you should see a secure certificate.

190+ - To confirm that certbot will renew properly you can run the following command:

191+ ```

192+ $ sudo certbot renew --dry-run

193+ ```

194+

195+## Installing Urbit

196+Finally 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][Urbit Install]. If you have a local ship already, we're going to install Urbit on the server and then send your local ship up.

197+ - **WARN**: Since Urbit is p2p you don't want to ever run two copies of your ship simultaneously. This is because other nodes that interact with each of your copies will be confused by which one is the most up to date. If you end up accidentally doing this you'll have to do a 'personal breach' described in the Urbit docs to fix things.

198+ - The first thing you're going to want to do is shut down your local ship, either with control-d or `|exit` in dojo.

199+ - Next we're going to install Urbit on the server:

200+ ```

201+ $ ssh your_user@your_domain

202+ $ curl -O https://bootstrap.urbit.org/urbit-v0.10.8-linux64.tgz

203+ $ tar xzf urbit-v0.10.8-linux64.tgz

204+ $ cd urbit-v0.10.8-linux64

205+ ```

206+ - Now we're going to tar up your local ship and send it to your server, from your local machine's urbit directory:

207+ ```

208+ $ tar -zcvf <ship_dir_name>.tar.gz <ship_dir_name>

209+ $ scp <ship_dir_name>.tar.gz your_user@your_domain:/home/your_user/urbit-v0.10.8-linux64

210+ ```

211+ - Back on your server let's untar your ship and start it up with the Ames port we allowed through the firewall:

212+ ```

213+ $ ssh your_user@your_domain

214+ $ cd urbit-v0.10.8-linux64

215+ $ tar -zxvf <ship_dir_name>.tar.gz

216+ $ ./urbit -p 32123 <ship_dir_name>

217+ ```

218+ - Your ship should now be sailing on the digital ocean. Check `https://your_domain`, if everything is working properly you should see a login page.

219+ - Log in with the code from `+code` in dojo like normal and you should see all of your applications.

220+

221+## Leaving your Urbit running in a Screen session

222+Finally, 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.

223+ - First start with your ship stopped, then run the following:

224+ ```

225+ $ screen -S urbit

226+ ```

227+ - This will start a screen session, we can now start up the Urbit ship in this session:

228+ ```

229+ $ ./urbit <ship_dir_name>

230+ ```

231+ - Then we can disconnect from the screen session and leave the ship running with `control-a d`

232+ - To get back into the screen sesssion:

233+ ```

234+ $ screen -r

235+ ```

236+- There are more screen commands for interacting with sessions that are easy to find on the internet.

237+

238+## Links and Misc.

239+A lot of the above documentation comes from combining existing resources.

240+

241+Nginx is also pretty powerful and configurable. You can do things like have your Urbit on an existing server under a subdomain.

242+

243+On 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.

244+

245+ - For the docs that made up this guide see the following links.

246+ - [Digital Ocean Initial Setup][DO Initial Setup]

247+ - [Digital Ocean DNS][DO DNS]

248+ - [Digital Ocean Nginx Installation][DO Nginx Install]

249+ - [Digital Ocean Nginx Config][DO Nginx Config]

250+ - [Digital Ocean SSL Cert Setup][DO SSL Config]

251+ - [Urbit Install Docs][Urbit Install]

252+ - [Urbit Basic Cloud Install][Urbit Basic Cloud Install]

253+

254+ [Gandi]: https://www.gandi.net/

255+ [Digital Ocean]: https://www.digitalocean.com/

256+ [DO DNS]: https://www.digitalocean.com/community/tutorials/how-to-point-to-digitalocean-nameservers-from-common-domain-registrars

257+ [DO Nginx Install]: https://www.digitalocean.com/community/tutorials/how-to-install-nginx-on-ubuntu-18-04

258+ [DO Nginx Config]: https://www.digitalocean.com/community/tutorials/how-to-deploy-a-go-web-application-using-nginx-on-ubuntu-18-04

259+ [DO SSL Config]: https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-18-04

260+ [Urbit Install]: https://urbit.org/using/install/

261+ [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

262+ [DO Initial Setup]: https://www.digitalocean.com/community/tutorials/initial-server-setup-with-ubuntu-18-04

263+ [Blog Github]: https://github.com/zalberico/zalberico.github.io

264+