@@ -1,246 +1,214 @@
11+++
2−title = "Install + Setup"
2+title = "Getting Started"
33weight = 1
44description = "How to install Urbit."
55template = "page_indiced.html"
66aliases = ["/docs/getting-started/"]
77+++
88
9−This guide covers how to install and set up your own planet (or comet), but installation for a star is exactly the same. You will first install the Urbit binary, then you will either boot a comet or a planet. It's not too difficult, but if you would prefer to have someone run your urbit for you, consider a [hosting provider](#hosting-providers).
9+The price of using other platforms is your data and its security. There's a reason they're free to use.
1010
11+The price of using Urbit is your own responsibility — you must run it yourself (or pay someone to run it for you).
1112
12−## Installing Urbit
13+It's easy and it keeps getting easier.
1314
14−You'll want to install Urbit binary first. Follow the instructions below to install the binary on Windows, MacOS, or Linux.
15+There are currently two ways to run Urbit:
1516
16−### Windows
17+If you use Mac or Linux and are not afraid of a few terminal commands, we recommend you run it yourself. That is the aim of this guide.
1718
18−> Please note that this method of installing Urbit is experimental, and we may not be able to assist you if you encounter issues related to WSL 2.
19−
20−Urbit cannot run on Windows itself, but there is a convenient way to run Linux using the [Windows Subsystem for Linux 2](https://docs.microsoft.com/en-us/windows/wsl/wsl2-install) on Windows 10. Install the Windows Subsystem for Linux 2 and open a Linux terminal in Windows, then follow the Linux installation instructions below. These instructions have been tested and verified for WSL 2 + Ubuntu 18.04 LTS, as demonstrated in `~sitful-hatred`'s step-by-step setup guide [here](https://subject.network/posts/urbit-wsl2/).
19+If you run Windows or just want to give it a shot without worrying about the gritty bits, you may want to consider a [hosting provider](/using/planet#hosting-providers).
2120
22−For performance reasons, do not install Urbit in the mounted Windows volume, but install it in the Linux file system. For example, in your home directory, which can be navigated to by entering `cd ~`.
21+## Installing Urbit {#macos-and-linux}
2322
24−### macOS {#macos-and-linux}
23+Choose the code for your operating system and run the commands in your terminal.
2524
26−**The macOS binary does not work on M1 macs. Sorry. We're working on an M1 release**
25+<div id="os">
26+ <input type="radio" id="macos" name="os" checked>
27+ <label for="macos">MacOS</label>
28+ <div class="tab">
2729
2830```sh
29−mkdir urbit
30−cd urbit
31+mkdir ~/urbit
32+cd ~/urbit
3133curl -JLO https://urbit.org/install/mac/latest
3234tar zxvf ./darwin.tgz --strip=1
33−./urbit
34−
35+~/urbit/urbit
3536```
36−### Linux
37+ </div>
38+
39+ <input type="radio" id="linux" name="os">
40+ <label for="linux">Linux</label>
41+ <div class="tab">
42+
3743```sh
38−mkdir urbit
39−cd urbit
44+mkdir ~/urbit
45+cd ~/urbit
4046wget --content-disposition https://urbit.org/install/linux64/latest
4147tar zxvf ./linux64.tgz --strip=1
42−./urbit
48+~/urbit/urbit
4349```
4450
45−Once you've followed the appropriate install instructions, you can check if everything went right by running the `./urbit` command. Installation was successful if you get a block of output that begins with the line below:
46−
47−```
48−Urbit: a personal server operating function
49−```
51+Linux users may need to run this command in another terminal window to access your Urbit on port 80:
5052
51−To access your Urbit via HTTP on port 80 on Ubuntu, you may need to run the following:
5253```sh
5354sudo apt-get install libcap2-bin
54−sudo setcap 'cap_net_bind_service=+ep' /path/to/urbit
55−```
56−(Where `urbit` is the urbit executable downloaded with `wget` prior)
57−
58−### Choose to boot a comet or a planet
59−
60−If you just want to try Urbit out, you can use a comet. These are disposable, free identities, that are good for people who are new to Urbit and want to check out the network, but they aren't good for building a reputation as a friendly and responsible resident. Their long names (example: `~dasres-ragnep-lislyt-ribpyl--mosnyx-bisdem-nidful-marzod`) make them difficult to remember—and some communities ban comets to prevent spam—but they're still a good way to see what Urbit is about before buying your own planet.
61−
62−To start with a comet, continue below. For planet instructions, see [further below](#boot-your-planet).
63−
64−## Booting a comet {#comet}
65−
66−To boot a comet, go into the command line and run the following command from the `urbit` directory you created during [Urbit installation](#installing-urbit):
67−
68−```sh
69−./urbit -c mycomet
70−```
71−
72−Since your identity on the network is not verified, it may take up to an hour to generate your comet. As it boots, it will spit out a bunch of boot messages and create a directory called `mycomet`. Toward the end of the boot process, you'll see something like:
73−
74−```
75−ames: on localhost, UDP 31337.
76−http: live (insecure, public) on 8080
77−http: live ("secure", public) on 8443
78−http: live (insecure, loopback) on 12321
79−~sampel_marzod:dojo>
80−```
81−
82−When your comet is finished booting, you will see `~sampel_marzod:dojo>` (Dojo: the Urbit command line).
83−
84−Get your password to log into landscape (the Urbit web interface) by typing:
85−
86−```sh
87−+code
88−```
89−
90−To exit Urbit, use `Ctrl-D` or enter `|exit` into Dojo.
91−
92−To start your comet up again, run the following from your `urbit` directory (note the lack of `-c` argument):
93−
94−```sh
95−./urbit mycomet
55+sudo setcap 'cap_net_bind_service=+ep' ~/urbit/urbit
9656```
57+</div>
9758
98−### Updating your comet {#updating}
99−
100−The Urbit binary comes with a somewhat recent release of the Urbit OS, but ships can update automatically ("over the air"), so new binaries aren't necessary every time it's updated. Planets have automatic updates enabled by default, but this is not the case for comets. Many comets are used only once and thrown away, so it would be wasteful to update every single comet as soon as it boots. If you plan to use your comet for more than a quick test, you'll probably want to ensure you're running the latest version of the OS.
59+ <input type="radio" id="windows" name="os">
60+ <label for="windows">Windows</label>
61+ <div class="tab">
10162
102−You can enable updates for your comet by typing `|ota (sein:title our now our) %kids` into Dojo and pressing Enter.
63+> Please note that this method of installing Urbit is experimental, and we may not be able to assist you if you encounter issues related to WSL 2.
10364
104−```
105−> |ota (sein:title our now our) %kids
106−>=
107−```
65+Urbit cannot run on Windows itself, but there is a convenient way to run Linux using the [Windows Subsystem for Linux 2](https://docs.microsoft.com/en-us/windows/wsl/wsl2-install) on Windows 10. Install the Windows Subsystem for Linux 2 and open a Linux terminal in Windows, then follow the Linux installation instructions below. These instructions have been tested and verified for WSL 2 + Ubuntu 18.04 LTS, as demonstrated in `~sitful-hatred`'s step-by-step setup guide [here](https://subject.network/posts/urbit-wsl2/).
10866
109−If you want to make sure you'll get updates, you can check by typing `|ota` with no arguments:
67+For performance reasons, do not install Urbit in the mounted Windows volume, but install it in the Linux file system. For example, in your home directory, which can be navigated to by entering `cd ~`.
68+</div>
69+</div>
70+
71+<style>
72+ #os {
73+ display: flex;
74+ flex-wrap: wrap;
75+ }
76+ #os label {
77+ order: -1;
78+ padding: .5rem;
79+ border-width: 1px 0px 0px 1px;
80+ border-style: solid;
81+ cursor: pointer;
82+ }
83+ #os label[for=windows] {
84+ border-right-width: 1px;
85+ }
86+ #os input[type="radio"] {
87+ display: none;
88+ }
89+ #os .tab {
90+ display: none;
91+ border: 1px solid;
92+ padding: 1rem;
93+ max-width: 100%;
94+ }
95+ #os input[type='radio']:checked + label {
96+ font-weight: bold;
97+ }
98+ #os input[type='radio']:checked + label + .tab {
99+ display: block;
100+}
101+</style>
102+
103+If successful, you will see a block of output beginning with the line:
110104
111105```
112−~sampel_marzod:dojo> |ota
113−OTAs enabled from %kids on ~marzod
114−use |ota %disable or |ota ~sponsor %kids to reset it
115−> |ota
116−>=
106+Urbit: a personal server operating function
117107```
118108
119−Now that you’re up and running, skip ahead to the [Setup guide](#setup).
120−
121−## Booting a planet {#boot-your-planet}
109+## Booting a Free Identity {#comet}
122110
123−There are two options for getting started with a planet. You can purchase one on your own and run Urbit yourself, or you can purchase a planet and hosting services through a [hosting provider](#hosting-providers).
111+There are two parts to Urbit: an **ID** and an **Operating System**.
124112
125−### Purchase a planet
113+You have just installed the Operating System on your computer.
126114
127−There are a few ways to get your own planet:
115+The **ID** is similar to a username and password on another site. The difference is that the public part (the username) is verified by thousands of people around the world while only you hold the key (the password) to that ID.
128116
129−- Getting an invitation from a friend.
130−- Purchasing a planet, including hosting, from a [hosting provider](#hosting-providers) such as [geturbitid.com](https://www.geturbitid.com/).
131−- Manually setting up and hosting an planet purchased from a third party such as [urbit.live](https://urbit.live), [OpenSea](https://opensea.io), [planet.market](https://planet.market/), [urbit.me](https://urbit.me), [urth systems](https://urth.systems/), or [Urbit Marketplace](https://urbitmarketplace.com/).
117+There are five kinds of Urbit IDs but to get started you only need to know about two: we call them **planets** and **comets**.
132118
133−Note that when you buy a planet, you should ensure with the provider that your parent star is operating. If you need to escape a non-operational star, see [Escaping A Sponsor](@/using/operations/using-your-ship.md#escape).
119+***
134120
135−### Hosting Providers {#hosting-providers}
121+**Planets** are scarce (this prevents spamming, among other things) and usually require a price to acquire. This is the recommended way to run Urbit, but it's a bit more involved.
136122
137−Hosting providers will often sell you a planet and run it for you. This option is very simple but will probably cost a regular fee.
123+A planet name looks like `~sampel-palnet`.
138124
139−Urbit is designed to be portable. This means that if you sign up for hosting now but later want to leave your hosting provider and run your Urbit yourself, you should be able to work with them to obtain all of your data and boot your planet back up without losing anything.
125+[Follow this guide](/using/planet) if you have already acquired a planet.
140126
141−Using hosting does mean that you're trusting your provider with your data, but so long as you have your planet, you'll always own your identity.
127+[Find a planet to purchase](/using/planet#purchase)
142128
143−Current hosting providers are:
129+***
144130
145−- [Tlon Corporation](https://tlon.io): Tlon is the creator of Landscape and is primarily responsible for the creation and maintenance of the Urbit project itself.
146−- [Get an Urbit ID](https://www.geturbitid.com/): Get an Urbit ID was the first hosting provider and is run by a member of the Urbit community.
131+**Comets** are practically unlimited and free to acquire. At present, these are a great way to try out the network for free.
147132
133+A comet name looks like `~dasres-ragnep-lislyt-ribpyl--mosnyx-bisdem-nidful-marzod`.
148134
149−### Choose to run your planet on your computer or on a cloud service
135+[Read more about Urbit ID here](/understanding-urbit/urbit-id)
150136
151−Urbit must run on an existing computer somewhere. Most users run their planet on their personal computer, but we recommend eventually using a cloud service (Digital Ocean, Linode, etc) because it allows your planet to be accessed from anywhere on multiple devices. Hosting your planet in the cloud also allows it to always be online and ready for automatic updates. You are welcome to run from your personal computer and switch to the cloud later...all without losing any data!
152137
153−There is a guide for [hosting your planet on DigitalOcean](@/using/operations/hosting.md) and [hosting your planet on Linode](https://jeremytunnell.com/2021/01/09/how-to-install-urbit-on-a-linode-vps), but any cloud hosting service should work.
138+***
154139
155−### Get your keyfile {#keyfile}
156−
157−If you received an email invite to Urbit, the master ticket should be a .pdf file in the passport folder inside the archive that you downloaded. **If you bought your planet or someone sent you one you probably do not have a master ticket, and you probably don't need one. Do not issue a new master ticket unless you are sure you need to.**
158−
159−1. Connect to [Bridge](https://bridge.urbit.org). (Bridge is like an Urbit wallet)
160−2. Enter the name of your planet and the associated master ticket if you have one. Click the "Metamask, Mnemonic, Hardware Wallet..." button if you don't have a master ticket.
161−3. Once you're logged in, click the "OS" option.
162−4. Click the "Download Arvo Keyfile" button. If this is grayed out, click on "Reset Networking Keys", then click on "Reset Networking Keys" on the following page, validate the transaction using your wallet, and then click "Send Trasaction". Once the transaction is complete, the "Download Arvo Keyfile" button should be available for you to press. You should receive a `.key` file that contains the secret needed to boot your planet. Hold onto this file.
163−
164−### Run the boot command {#the-dojo}
165−
166−Navigate to your `urbit` directory.
167−
168−Open your keyfile (it is just a text file) and copy the key inside. Paste it into the following command, with `sampel-palnet` replaced by the name of your planet. **Do not include the tilde in your planet name.**
140+To boot a comet, go into the command line and run the following command from the `urbit` directory you created during [Urbit installation](#installing-urbit):
169141
170142```sh
171−./urbit -w sampel-palnet -G rAnDoMkEy
143+~/urbit/urbit -c mycomet
172144```
173145
174−Or you can copy the keyfile into the current directory and run:
146+It may take a while to load the comet (probably only take a few minutes, but it could take longer). This comes along with it being free. When it's done you'll some messages ending like this:
175147
176−```sh
177−./urbit -w sampel-palnet -k ./my-planet.key
148+```
149+ames: on localhost, UDP 31337.
150+http: live (insecure, public) on 8080
151+http: live ("secure", public) on 8443
152+http: live (insecure, loopback) on 12321
153+~sampel_marzod:dojo>
178154```
179155
180−Either command will create a directory called `sampel-palnet/` and begin booting your planet. It may take a few minutes.
156+When your comet is finished booting, you will see `~sampel_marzod:dojo>` (Dojo: the Urbit command line).
181157
182−When your planet is finished booting, you will see `~sampel-palnet:dojo>` (Dojo: the Urbit command line).
158+To exit Urbit, use `Ctrl-D` or enter `|exit` into Dojo.
183159
184−Get your password to log into landscape (the Urbit web interface) by typing:
160+To start your comet up again, run the following from your `urbit` directory (note the lack of `-c` argument):
185161
186162```sh
187−+code
163+~/urbit/urbit mycomet
188164```
189165
190−To shut down your planet, use `Ctrl-D`.
191−
192−To start your planet up again, run the following from your `urbit` directory.
193−
194−```sh
195−./urbit sampel-palnet
196−```
166+## Using Landscape
197167
198−Note that `sampel-palnet/` is the path of a folder, which we just created in your `urbit` directory. This folder is called your planet's **pier**, and it holds all of your data.
168+Urbit is an entirely new computer, so by default it drops you into the "dojo," which is its terminal. Like your current computer, it can be used to do just about anything if you know the right commands. You only need to know one command for now.
199169
200−Never boot multiple instances of your planet at the same time. You can prevent this from happening on accident by only ever keeping a single copy of your pier.
170+At the moment, the most common way to use Urbit is through a web app named Landscape, which comes with Urbit. It runs in your browser and provides an interface to Urbit without using the terminal. You need to get the password, or `code`.
201171
202−**Important:** once a key has been used to boot a planet onto the network, it cannot be used to boot that planet again later - doing so will cause communication problems with other planets. For this reason you should **delete the keyfile from your machine once your planet has booted successfully**. If you do use the same key twice, you'll need to reset your planet to restore its functionality.
172+1. With your Urbit running, look for a line that says something like `http: live (insecure, public) on 80`. The number given is the port that your ship is using. It will probably be 80, but we're just making sure. (Don't worry about the "insecure, public" part — that just means you can access it from your own web browser. It doesn't give anyone else access.)
173+2. If the port given is `80`, simply type `localhost` into your browser's address bar. If the given port is a different number, such as `8080`, you would type `localhost:8080`. You'll be met with a login prompt.
174+3. In the window where you found the port number, type `+code` and press return. Copy-paste the code that appears into the "Access Key" field in the browser, and press continue.
175+4. Once in, take a look around and read the instructions on screen. If you ever get logged out, follow these instructions again.
203176
204−Delete the keyfile with the command below:
177+## Next Steps
205178
206−```sh
207−rm ./my-planet.key
208−```
179+### Updating your comet {#updating}
209180
210−## Setup {#setup}
181+The Urbit application comes with a recent release of the Urbit OS, but automatic updates ("over the air") can be enabled so new binaries aren't necessary for each update. Planets have automatic updates enabled by default, but this is not the case for comets. Many comets are used only once and thrown away, so it would be wasteful to update every single comet as soon as it boots. If you plan to use your comet for more than a quick test, you'll probably want to ensure you're running the latest version of the OS.
211182
212−The first thing you generally want to do with a new planet is to **mount** it. A planet being mounted means that it can be seen by Linux, allowing files to be shared between it and your planet. To mount your planet, type `|mount %` at the Dojo prompt.
183+You can enable updates for your comet by typing `|ota (sein:title our now our) %kids` into Dojo and pressing Enter.
213184
214185```
215−|mount %
186+> |ota (sein:title our now our) %kids
216187>=
217188```
218189
219−The `>=` output means that a command was successful. Now you can see your planet's files in its directory.
220−
221−To understand what happened with this command, read more about Urbit’s filesystem (called “clay”) [here](@/docs/tutorials/arvo/clay.md).
222−
223−### Using Landscape
224−
225−Landscape is the Urbit web interface, and it's the best way to interact with your planet. To access Landscape:
190+If you want to make sure you'll get updates, you can check by typing `|ota` with no arguments:
226191
227−1. Start your planet. In the boot messages, look for a line that says something like `http: live (insecure, public) on 80`. The number given is the port that your planet is using.
228−2. If the port given is 80, and you are running Urbit on your personal computer, simply type `localhost` into your browser's address bar. If you are running urbit on a cloud server, type the ip of your cloud server. If the given port is a different number, such as `8080`, you would type `localhost:8080` or `your-cloud-ip:8080`. You'll be met with a login prompt.
229−3. Type your password you got from running `+code` above.
230−4. You're in! Now you can explore groups, join chat channels, share links, and much more.
192+```
193+~sampel_marzod:dojo> |ota
194+OTAs enabled from %kids on ~marzod
195+use |ota %disable or |ota ~sponsor %kids to reset it
196+> |ota
197+>=
198+```
231199
232−### Join a group
200+### Read More about the Dojo {#the-dojo}
233201
234−Now that you're on Landscape, join the Urbit Community, a great place for newcomers to ask questions.
202+The dojo is Urbit's command line. You can use it to control your ship, or to execute arbitrary code. Check out the links below for more information.
235203
236−Click the `Join a Group` button, then enter `~bitbet-bolbel/urbit-community` into the field and press the `Join Group` button.
204+- [Basic Operations](/using/operations/using-your-ship)
205+- [Basic Hoon](/docs/tutorials/hoon/hoon-school/setup)
206+- [Glossary Entry](/docs/glossary/dojo)
237207
238−From the Urbit Community group you can join a variety of chatrooms, notebooks, and collections.
208+### Purchase a Permanent Identity {#boot-your-planet}
239209
240−### Next Steps
210+You can continue using this comet indefinitely. There are currently few differences between using a comet-level identity and a planet-level one. However, some groups will not allow comets entry in order to maintain a certain level of quality, and changes may be made in the future that further devalue comets. They will always, however, be able to access the basic functions of the network.
241211
242−Now that you’re up and running, take some time to deepen your understanding by checking out some of our other guides:
212+A comet also comes with a long and fairly unmemorable name whereas a planet has a short name and a "sigil" (avatar) associated with it that makes it more identifiable on the network. You may notice all this within the first few minutes of using Urbit.
243213
244−- [Host your Ship in the Cloud](@/using/operations/hosting.md): Follow this guide to set your ship up to run as a cloud server, accessible from anywhere.
245−- [Read the Operations Manual](@/using/operations/using-your-ship.md): Become an expert pilot by learning to use your ship.
246−- [Learn to Develop on Urbit](@/using/develop.md): Learn how to contribute to or develop on Urbit.
214+[To read instructions on how to purchase and use a planet, visit this page](/using/planet).