Blog How to install Urbit on a $5/month Linode VPS
Jeremy Tunnell at
Updated May 24, 2023.
This guide assumes you have purchased or acquired an urbit planet or star and you would like to set it up on a cloud VPS so it is always on.
This guide also works for installing on Linux, just skip step 1.
If you want to install on desktop Windows, I recommend using virtualization to install Urbit running on ubuntu on windows. There is also an officially unsupported and experimental port application for desktop, but use at your own risk. Sorry, official Windows support may come someday, but not today.
You can always reference the official install instructions here.
There is also an alternate method of installing using Docker and Caddy. You can find a script that will install Urbit using Docker and Caddy here.
Step 1: Create a Linode VPS
Visit Linode (referral link gives you a free two months and $25 credit) and sign up for an account.
Options:
- OS: Ubuntu 20.04 LTS
- Region: Nearest to you
- Plan: Nanode 1GB
- Label: *your planet name*
Step 2: Generate your key file on Bridge
There are a few ways to acquire a planet, but they all either result in you getting a master ticket, or the planet will be sent to an ETH address where you have the login credentials.
- Connect to Bridge.
- Pick the way you want to log in to Bridge. If you purchased a layer 2 planet (You'll know because you didn't pay a gas fee) or if you received a master ticket, choose "Master Ticket". If you purchased a layer 1 planet, and do not have a master ticket, you will need to log in to the Ethereum address holding your planet. In that case, choose "Metamask" or "Recovery Phrase". Hardware wallets use Metamask. Before you continue ensure that you have "Ethereum Mainnet" selected in Metamask, that you have the correct eth address selected, and that it says "Connected". If you miss any of these it will tell you "No account connected".
- Once you're logged in, click your planet and then the "OS" option.
- In resulting page, it will say "No network keys found" in red. Click the "Initialize" button.
- If this planet is brand new, leave "Factory Reset" and "Custom Network Seed" unchecked. If you bought a used planet, check "Factory Reset".
- Click "Set Network Keys". Click "Send Transaction".
- Validate the transaction using your wallet, and then click Send Transaction (This will use gas).
- You should now be able to receive a .key file that contains the secret needed to boot your ship.
Step 3: Connect to your VPS
You need to get command line access to your Linode VPS. This is done with a utility called SSH, which comes standard on Linux and Mac. If you run Linux or Mac on your personal computer just use:
ssh root@vps_ip_address
I am on Windows and I use a small utility called Putty.
Once you connect, it will ask you for the root password, and you'll type in the root password that you created when you made the Linode.
Step 4: Configure the VPS
Note: See here for different commands if you are installing on Mac or AArch64.
curl -L https://urbit.org/install/linux-x86_64/latest | tar xzk --transform='s/.*/urbit/g' && ./urbit
Everything that follows creates a 2GB swap file because this VPS has 1GB of memory. If you have 2G of available memory, this is unneccesary.
sudo fallocate -l 2G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile sudo cp /etc/fstab /etc/fstab.bak echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
Step 5: Get the urbit boot key in the right place
You have a keyfile from step 2. It should end in ".key". To boot your urbit, you either need to upload the keyfile to your new Linode, or you need to open the keyfile on your personal computer and copy the key value which is inside (the keyfile is just a text file). You can open it with any text editor.
- To upload: Use an FTP utility or SCP to upload the keyfile (ends in .key) to your new VPS. I recommend FileZilla if you don't know how to do that. You will need to place the key file in the same directory as your urbit executable that you downloaded in step 4.
- To open the keyfile and get the key: On linux, use nano. On mac, use Textedit. On Windows, use Notepad.
Step 6: Boot your Urbit
Run this command from the folder where your pier is (the folder with your planet name). Replace *planetname* with your planet name and *keyfile.key* with your keyfile name. Do not include the tilde (~) on your planet name.
./urbit -w *planetname* -k ./*keyfile.key*
You can also open the .key file and copy the key from it and type it into the boot command directly, like this:
./urbit -w *planetname* -G 0w2~Wsd.isle8.YFYUg.PHjqh.SyuLd.POEsn.j3T7s.ls8g2.Adifl.Tis2s.lse9g.asd45.JO-jL$
It will take a while to boot (10 minutes)? After it boots you will get a dojo prompt, and then you will probably see a bunch of "behn" which means your planet is downloading updates. It could take several hours to download all of the updates. Your urbit will seem unresponsive while you're downloading/installing updates.
Test it by typing (dopzod is another star)
|hi ~dopzod hi ~dopzod successful; ~dopzod is your neighbor
And by the way, grab your passcode so you can log into the web interface of your Urbit.
+code
Step 7: Shut down your Urbit
ctrl-d
Step 8 Restart your Urbit within a screen
A screen will allow you to keep your urbit running if you exit your shell (putty) session.
screen -S name_of_the_screen
Name it whatever you want. Now restart your Urbit. Restarting an Urbit uses an abbreviated command. Replace *pier*
Also, if you are on a machine with 4gb of ram or more, you can add --loom32 as an option below to use the extra memory.
./*pier*/.run *planetname* -p 32123
Again, leave off the tilde (~). Now you can close the screen (Urbit will continue running)
ctrl-a d
When you want to open the screen again, just use:
screen -r
Step 9: Delete your keyfile
Once your Urbit has been started the first time, you don't need your keyfile anymore. Do not use your keyfile to boot again. It will destroy your pier and you will have to factory reset.
Optional - Set up HTTPS
(Official guide here: https://urbit.org/using/operations/hosting/) To set up SSL, you need to add an A record at your DNS provider that points to where your urbit is. So if your urbit is at 100.100.100.100, then you'll need to add an A record that points to this. After you do this at your DNS provider, typing "yourdomain.com" will send you to 100.100.100.100. Use https://dnschecker.org/ to see if your new DNS is pointing to the right place.
After that, make sure you have ports 80 and 443 open where your urbit is. On ubuntu it is:
ufw allow 80 ufw allow 443
Then you need to go to your dojo prompt and request a certificate. It will use LetsEncrypt, and it will first make sure that it can access your urbit on port 80 ( if it cannot, it will fail). Change /tld/domain/subdomain into whatever your domain is, so example.com would be /com/example, subdomain.example.com would be /com/example/subdomain.
:acme &path /tld/domain/subdomainIf you are successful, you will get the following response:
acme: requesting an https certificate for subdomain.example.com acme: received https certificate for subdomain.example.comhttp: restarting servers to apply configuration http: web interface live on https://localhost:443 http: web interface live on http://localhost:80 http: loopback live on http://localhost:12321
Optional: Join some groups and install some apps
When you first boot up your urbit, you'll be connected with nothing. Here are some suggestions of groups you might join to get a feel for things:
- ~bitbet-bolbel/urbit-community
- ~tirrel/the-marketplace
- ~wolref-podlex/foundation
- ~rondev/group-discovery
There is now a curated app discovery app here: ~worpet-bildet/portal. Many more apps listed here: https://urbit.org/ecosystem?type=applications
If you have any trouble, check out the Urbit Troubleshooting page.