@@ -1,246 +1,214 @@
2−title = "Install + Setup"
2+title = "Getting Started"
4description = "How to install Urbit."
4description = "How to install Urbit."
5template = "page_indiced.html"
5template = "page_indiced.html"
6aliases = ["/docs/getting-started/"]
6aliases = ["/docs/getting-started/"]
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.
11+The price of using Urbit is your own responsibility — you must run it yourself (or pay someone to run it for you).
12−## Installing Urbit
13+It's easy and it keeps getting easier.
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:
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.
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+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).
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/).
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}
24−### macOS {#macos-and-linux}
23+Choose the code for your operating system and run the commands in your terminal.
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>
29−mkdir urbit
31+mkdir ~/urbit
31curl -JLO https://urbit.org/install/mac/latest
33curl -JLO https://urbit.org/install/mac/latest
32tar zxvf ./darwin.tgz --strip=1
34tar zxvf ./darwin.tgz --strip=1
33−./urbit
35+~/urbit/urbit
39+ <input type="radio" id="linux" name="os">
40+ <label for="linux">Linux</label>
38−mkdir urbit
44+mkdir ~/urbit
40wget --content-disposition https://urbit.org/install/linux64/latest
46wget --content-disposition https://urbit.org/install/linux64/latest
41tar zxvf ./linux64.tgz --strip=1
47tar zxvf ./linux64.tgz --strip=1
42−./urbit
48+~/urbit/urbit
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:
51+Linux users may need to run this command in another terminal window to access your Urbit on port 80:
48−Urbit: a personal server operating function
51−To access your Urbit via HTTP on port 80 on Ubuntu, you may need to run the following:
53sudo apt-get install libcap2-bin
54sudo apt-get install libcap2-bin
54−sudo setcap 'cap_net_bind_service=+ep' /path/to/urbit
55+sudo setcap 'cap_net_bind_service=+ep' ~/urbit/urbit
56−(Where `urbit` is the urbit executable downloaded with `wget` prior)
58−### Choose to boot a comet or a planet
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.
62−To start with a comet, continue below. For planet instructions, see [further below](#boot-your-planet).
64−## Booting a comet {#comet}
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):
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:
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
82−When your comet is finished booting, you will see `~sampel_marzod:dojo>` (Dojo: the Urbit command line).
84−Get your password to log into landscape (the Urbit web interface) by typing:
90−To exit Urbit, use `Ctrl-D` or enter `|exit` into Dojo.
92−To start your comet up again, run the following from your `urbit` directory (note the lack of `-c` argument):
98−### Updating your comet {#updating}
59+ <input type="radio" id="windows" name="os">
99−
60+ <label for="windows">Windows</label>
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.
61+ <div class="tab">
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.
104−```
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/).
105−> |ota (sein:title our now our) %kids
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 ~`.
79+ border-width: 1px 0px 0px 1px;
83+ #os label[for=windows] {
84+ border-right-width: 1px;
86+ #os input[type="radio"] {
95+ #os input[type='radio']:checked + label {
98+ #os input[type='radio']:checked + label + .tab {
103+If successful, you will see a block of output beginning with the line:
112−~sampel_marzod:dojo> |ota
106+Urbit: a personal server operating function
113−OTAs enabled from %kids on ~marzod
114−use |ota %disable or |ota ~sponsor %kids to reset it
119−Now that you’re up and running, skip ahead to the [Setup guide](#setup).
109+## Booting a Free Identity {#comet}
121−## Booting a planet {#boot-your-planet}
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**.
125−### Purchase a planet
113+You have just installed the Operating System on your computer.
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.
129−- Getting an invitation from a friend.
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**.
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/).
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+***
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.
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`.
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.
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)
143−Current hosting providers are:
129+***
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.
131+**Comets** are practically unlimited and free to acquire. At present, these are a great way to try out the network for free.
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.
133+A comet name looks like `~dasres-ragnep-lislyt-ribpyl--mosnyx-bisdem-nidful-marzod`.
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)
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!
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+***
155−### Get your keyfile {#keyfile}
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):
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.**
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.
164−### Run the boot command {#the-dojo}
166−Navigate to your `urbit` directory.
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.**
171−./urbit -w sampel-palnet -G rAnDoMkEy
143+~/urbit/urbit -c mycomet
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:
177−./urbit -w sampel-palnet -k ./my-planet.key
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
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).
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.
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):
187−+code
163+~/urbit/urbit mycomet
190−To shut down your planet, use `Ctrl-D`.
166+## Using Landscape
192−To start your planet up again, run the following from your `urbit` directory.
195−./urbit sampel-palnet
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.
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`.
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.
204−Delete the keyfile with the command below:
177+## Next Steps
206−```sh
179+### Updating your comet {#updating}
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.
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.
215−|mount %
186+> |ota (sein:title our now our) %kids
219−The `>=` output means that a command was successful. Now you can see your planet's files in its directory.
190+If you want to make sure you'll get updates, you can check by typing `|ota` with no arguments:
221−To understand what happened with this command, read more about Urbit’s filesystem (called “clay”) [here](@/docs/tutorials/arvo/clay.md).
225−Landscape is the Urbit web interface, and it's the best way to interact with your planet. To access Landscape:
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.
192+```
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.
193+~sampel_marzod:dojo> |ota
229−3. Type your password you got from running `+code` above.
194+OTAs enabled from %kids on ~marzod
230−4. You're in! Now you can explore groups, join chat channels, share links, and much more.
195+use |ota %disable or |ota ~sponsor %kids to reset it
232−### Join a group
200+### Read More about the Dojo {#the-dojo}
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.
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)
238−From the Urbit Community group you can join a variety of chatrooms, notebooks, and collections.
208+### Purchase a Permanent Identity {#boot-your-planet}
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.
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.
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.
214+[To read instructions on how to purchase and use a planet, visit this page](/using/planet).
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.