git.iko.soy/urbit.org
on 33eebbc help sign in
urbit.org/content/getting-started/server.md
161 lines 7.0 kB history raw
1+++
2title = "Server setup"
3description = "Run urbit on a local or cloud server"
4weight = 2
5+++
7### 1. Get yourself a planet
9Here's some of the hard fun work we talked about earlier.
11There are two ways to get a planet.
13**A) Ask nicely**
15Visit the instructions for [launching a temporary comet with Port](/getting-started/desktop), get yourself onto the network, find a group, and start conversations with people with planets to spare. Many urbiters are also active on [Twitter](https://twitter.com), where you can also ask around.
17**B) Buy a planet**
19There are many markets and individuals selling planets such as [azimuth.shop](https://azimuth.shop), [Networked Subject](https://subject.network), and [Wexpert Systems](https://wexpert.systems) for Ethereum, Bitcoin, and USD respectively.
21{% callout %}
23**Layer 1 vs Layer 2 planet purchasing**
25The websites listed in B) sell Layer 2 (L2) planets -- which means they avoid Ethereum’s volatile and expensive gas fees. However, markets such as [OpenSea](https://opensea.io) and many Urbit-specific markets such as [Urbitex](https://urbitex.io) sell planets directly on Ethereum L1, which means they are significantly more expensive.
27For this reason we generally advise using a L2 planet market, unless you are interested in a very rare sigil or a particular planet name.
29{% /callout %}
30### 2. Claim your planet
32An invitation to claim your planet comes in one of two forms.
34The first is an email invitation with an Urbit ID and a Master Ticket.
36The second, only recently made available through our [L2 solution](/using/id/layer-2-for-planets), is an activation code or a link to activate on [Bridge](https://bridge.urbit.org), which can be thought of as an Urbit account management tool.
38![](https://media.urbit.org/site/getting-started/Server-setup-1.jpg)
40Clicking a link to activate a planet on Bridge will take you to page which will generate a Master Ticket for you. Follow the instructions which will prompt you to download a copy of your Passport - your Master Ticket, management proxy, and keyfile. Store your Master Ticket and management proxy somewhere safe, hold on to the keyfile, and proceed to the next step.
42{% callout %}
44**Claiming L1 planets**
46If you’ve purchased an L1 planet, you won’t need to claim it because you already own it as an NFT. Simply log into Bridge using Metamask or your wallet of choice.
48{% /callout %}
49### 3. Use Bridge to get your keyfile
51Now that you have your planet, you can create your keyfile (eg. `sample-palnet.key`), which is the cryptographic signature required to encrypt and decrypt messages on Urbit's P2P network.
53- **Claimed L2 planets**
54 If you’ve claimed your L2 Planet then you should already have downloaded your Passport, which contains your Master Ticket and keyfile.
56- **Master Ticket holders**
57 If you haven’t downloaded your Passport but have a Master Ticket, then you can simply log in with Bridge using the Master Ticket option with your planet name and Master Ticket password. Click the ID box near the bottom of the page to open the ID page, then click the **Download Passport** button, which contains your keyfile.
59- **L1 Planet Purchasers**
60 Log in to Bridge with your Ethereum wallet using Metamask or the wallet of your choice with WalletConnect. Click the “OS” box on the bottom of the page to open the OS page, and then click the **Download Keyfile** button.
62### Install Urbit via the command line
64These instructions assume you have access to a **remote Linux system** running on a **VPS or cloud provider** of your choice. If you want to run Urbit locally, whether on Linux, macOS, or Windows, click the appropriate section below.
66You may also want to see the cloud hosting guide for additional details like setting your domain name and establishing a firewall, but for now, we'll focus on getting you set up as soon as possible.
68Download Urbit with the following commands:
70{% tabs %}
72{% tab label="MacOS" %}
74```bash
75mkdir ~/urbit
76cd ~/urbit
77curl -JLO https://urbit.org/install/mac/latest
78tar zxvf ./darwin.tgz --strip=1
79~/urbit/urbit
80```
82{% /tab %}
84{% tab label="Linux" %}
86```shell
87mkdir ~/urbit
88cd ~/urbit
89wget --content-disposition https://urbit.org/install/linux64/latest
90tar zxvf ./linux64.tgz --strip=1
91~/urbit/urbit
92```
94Linux users may need to run this command in another terminal window to access your Urbit on port 80:
96```shell
97sudo apt-get install libcap2-bin
98sudo setcap 'cap_net_bind_service=+ep' ~/urbit/urbit
99```
101{% /tab %}
103{% tab label="Windows" %}
105```winbatch
106mkdir %USERPROFILE%\urbit
107cd %USERPROFILE%\urbit
108curl -JLO https://urbit.org/install/windows/latest
109tar zxvf .\windows.tgz --strip=1
110%USERPROFILE%\urbit\urbit
111```
113> Windows 10 build 17063 and later includes the familiar `curl` and `tar` command-line tools.
115{% /tab %}
117{% /tabs %}
119Next, transfer `your-keyfile.key` to your server using scp or an FTP client, then move it to the `~/urbit` directory you created in the last step.
121Now you can run Urbit for the first time. Run the below command, replacing ames_port with a public port number between 49152 to 65535, sampel-palnet with the name of your planet, and sampel-palnet.key with the name of your keyfile.
123```sh
124./urbit -p ames_port -w sampel-palnet -k ./sampel-palnet.key
125```
127Arvo, the Urbit OS, now creates a directory called `sampel-palnet/` and begins booting your planet and establishing connections with the P2P network. When that's finished, you'll see Dojo, the Urbit command line:
129```
130~sampel-palnet:dojo>
131```
133Welcome to Urbit! You can skip ahead to [log in](#log-in), or stick around for some tips.
135### 4. Tips
137Check out the [cloud hosting guide](/using/running/hosting) for tips on improving the environment for Urbit, with a particular focus on establishing your domain name and using SSL for encryption.
139Shut down your planet by typing Ctrl+D into Dojo.
141To boot your planet up again, run the following command, once again replacing `ames_port` with the port you used previously, and now referencing your planet's folder.
143Your planet's folder, `sampel-palnet/`, is called your pier, and it holds all your data. If you want to migrate your data from one system to another, you must bring your pier.
145You should also delete your keyfile from your remote system to prevent yourself from using the same key twice, which will cause communication problems with other planets.
147```sh
148rm ./your-keyfile.key
149```
151### 5. Log in
153First, use your browser to navigate to the URL+port where your ship is running. This could be an IP address or a fully-qualified domain name, depending on how you set yours up.
155Instead of a static password, Urbit uses an Access Key, which is given by your ship itself.
157Open up the Urbit CLI again if it's not still running, and enter +code. The output is your Access Key, which you need to copy and paste into your browser. Click Continue to finish authentication and log in.
159### Next steps
161Learn how to [get around your urbit](/getting-started/getting-around).