@@ -10,31 +10,39 @@ Urbit is not yet ready for everyday users — but if you're technically inclined
1010
1111In order to get going on the network, you'll need an [Urbit ID](#id). To try the live network out with a disposable identity, you can always [create a comet](@/using/operations/creating-a-comet.md).
1212
13−## Getting an Urbit ID {#id}
13+## Overview
1414
15−For an introduction to Urbit IDs and the address space more generally, see [Urbit ID](@/understanding-urbit/urbit-id.md) in [Understanding Urbit](@/understanding-urbit/_index.md).
15+There are two major components of the Urbit ecosystem: **Urbit OS** and **Urbit ID**.
1616
17−While Tlon does not currently sell or distribute Urbit IDs, there are still a few ways to get your own Urbit ID:
17+The the Urbit peer-to-peer (p2p) network is composed of instances of Urbit OS -- callled **ships** -- that are virtual machines that run on any Unix platform.
1818
19−- Getting an invitation from a friend
20−- Purchasing an Urbit ID from a third party, such as [urbit.live](https://urbit.live), [OpenSea](https://opensea.io), [planet.market](https://planet.market/), or [Urbit Marketplace](https://urbitmarketplace.com/).
19+Urbit works as a p2p network where others fail because ships are associated with persistent and scarce identities that we refer to as Urbit IDs. The Urbit ID registry is deployed on the Ethereum blockchain, and individual IDs exist as non-fungible ([ERC-721](https://eips.ethereum.org/EIPS/eip-721)) tokens in that cryptographic ecosystem that chain. While Urbit ID is the essential crytopgraphic foundation to the functioning of the Urbit network, it has uses far beyond that. It can be used as general-purpose identity infrastructure for any other project.
2120
22−Tlon occasionally selects candidates to distribute invitations, and users operating galaxies and stars can spawn and distribute a finite number of stars and planets, respectively.
21+On the network, Urbit IDs function as network addresses, represented by pronounceable names like `~padmyn-pasnux`. There are a few kinds of Urbit ID, but ones meant for typical users are called **planets**. Anyone who has a planet can be thought of as a full "citizen" of the Urbit network. But to run your ship on the network, you need to start it with a piece of cryptographic information from its Urbit ID. This guide walk you through getting onto Urbit with an ID.
22+
23+But sometimes a user might not want a persistent identity for whatever reason. In that case, they can use Urbit without an Urbit ID by using something called called a **comet**. Comets can be spun up at will and for free. They are good for bots and 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 peer. If you want to jump right in with a comet, check out [this](#comet) section.
24+
25+### Stars and Galaxies
26+
27+In addition to comets and planets, two other types of ships are **stars** and **galaxies**. Together these can be referred to as "supernodes," because they perform essential infrastructural roles for Urbit OS network and for Urbit ID.
28+
29+On the Urbit ID side galaxies, galaxies are at the top of the ID hierarchy, with 256 in existence. Each galaxy can distribute 256 stars, and each star can distribute 65,536 planets. So any given planet ultimately came from a specific star, which itself came from a specific galaxy.
2330
24−## Using your Urbit ID
31+On the Urbit OS side, stars help route packets, kind of like an ISP. And galaxies are like DNS root servers or ICANN members. The difference is that Urbit IDs are owned cryptographically by many different people and accrue reputation independently.
2532
26−If you have an Urbit ID, you'll use [Bridge](https://bridge.urbit.org) to get your ship's keyfile before you can [boot your ship](#booting-your-ship). For more information on how to use Bridge, see [Using Bridge](@/using/operations/using-bridge.md).
33+If you're trying to get your star or galaxy set up, skip to [this section](#supernode).
2734
28−## Install Urbit {#urbit}
35+## Comet: Install and Setup {#comet}
2936
30−The Urbit binary runs nicely on a Unix-like operating system – Ubuntu, Fedora, or macOS, for example. If you're using Windows, you'll need to get one of the aforementioned systems. But first, some terminology:
37+Eager to try out the Urbit network? A comet is the fastest way to get started.
3138
32−- `vere` or `urbit`: the interpreter that runs when you run a command like `./urbit` in your command line
33−- `arvo`: the deterministic OS that lives in a directory whose name matches your Urbit ID, i.e. `~famreb-todmec` lives in `/famreb-todmec`
39+### Installing Urbit
3440
35−We have different installation instructions for different platforms. To install and run Arvo, the Urbit operating system, and its binary, run the commands that are listed for your operating system.
41+The Urbit binary runs on a Unix-like operating system – Ubuntu, Fedora, or macOS, for example.
3642
37−You can check your Arvo installation on any platform by running the `./urbit` command. Installation was successful if you get a block of output that begins with the line below:
43+We have different installation instructions for different platforms. To install and run Urbit OS, and its binary, run the commands that are listed for your operating system.
44+
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:
3846
3947```
4048Urbit: a personal server operating function
@@ -42,23 +50,19 @@ Urbit: a personal server operating function
4250
4351### macOS
4452
45−We provide static binaries for macOS. You can grab the latest stable release as follows:
46−
4753```sh
48−curl -O https://bootstrap.urbit.org/urbit-v0.10.4-darwin.tgz
49−tar xzf urbit-v0.10.4-darwin.tgz
50−cd urbit-v0.10.4-darwin
54+curl -O https://bootstrap.urbit.org/urbit-v0.10.8-darwin.tgz
55+tar xzf urbit-v0.10.8-darwin.tgz
56+cd urbit-v0.10.8-darwin
5157./urbit
5258```
5359
5460### Linux (64-bit)
5561
56−We also provide static binaries for 64-bit Linux distributions (Ubuntu, Debian, Fedora, Arch, etc.). You can get the latest stable release similarly:
57−
5862```sh
59−curl -O https://bootstrap.urbit.org/urbit-v0.10.4-linux64.tgz
60−tar xzf urbit-v0.10.4-linux64.tgz
61−cd urbit-v0.10.4-linux64
63+curl -O https://bootstrap.urbit.org/urbit-v0.10.8-linux64.tgz
64+tar xzf urbit-v0.10.8-linux64.tgz
65+cd urbit-v0.10.8-linux64
6266./urbit
6367```
6468
@@ -72,45 +76,284 @@ sudo setcap 'cap_net_bind_service=+ep' /path/to/urbit
7276
7377### Windows
7478
75−Please note that this method of installing Urbit is more experimental, and we may not be able to assist you if you encounter issues related to WSL 2, but these instructions have been tested and verified for WSL 2 + Ubuntu 18.04 LTS.
79+> 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. These instructions have been tested and verified for WSL 2 + Ubuntu 18.04 LTS.
7680
77−Urbit cannot run on Windows itself, but there is a convenient way to run a Linux distro using the [Windows Subsystem for Linux 2](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux), an initiative by Microsoft to bring Linux to Windows 10. For Urbit to work, it is necessary to [install WSL 2](https://docs.microsoft.com/en-us/windows/wsl/wsl2-install) and not just WSL, since version 2 uses virtualization and the real Linux kernel under the hood. Currently, WSL 2 is only available if you have signed up for the Windows Insider Program (the ‘Slow’ ring is sufficient), but this will change soon as WSL 2 is scheduled for general release in 2020.
81+Urbit cannot run on Windows itself, but there is a convenient way to run a Linux distro using the [Windows Subsystem for Linux 2](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux) on Windows 10. For Urbit to work, it is necessary to [install WSL 2](https://docs.microsoft.com/en-us/windows/wsl/wsl2-install) and not just WSL.
7882
7983Once WSL 2 is installed, open a Linux terminal in Windows and then follow the Linux installation instructions above. 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, by typing `cd ~`.
8084
81−The latest version of WSL 2 also supports port forwarding, so you should be able to open Chrome on Windows and browse to port 80 on localhost (or port 8080).
85+### Booting Your Comet
86+
87+To boot a new comet, go into the command line and run the following command from the directory that was created during Urbit installation:
88+
89+```sh
90+$ ./urbit -c mycomet
91+```
92+
93+This will take a few minutes to an hour, and will spin out a bunch of boot messages. It will also create a directory called `mycomet` in the Unix directory that you ran the command from.
94+
95+Toward the end of the boot process, you'll see something like:
96+
97+```
98+ames: on localhost, UDP 31337.
99+http: live (insecure, public) on 8080
100+http: live ("secure", public) on 8443
101+http: live (insecure, loopback) on 12321
102+~sampel_commet:dojo>
103+```
104+
105+When your ship is finished booting, you will see either the `~sampel_commet:dojo>` or `~sampel_commet:chat-cli/` prompt. If you're seeing `:chat-cli` press `Ctrl-x` to switch into Dojo. At that point, you should permanently erase your keyfile from your machine.
106+
107+To exit Urbit, use `Ctrl-d`. To start your ship up again, run `./urbit mycomet` from the directory that you first booted from. Now let's do some basic commands from inside your ship.
108+
109+### The Dojo
110+
111+Welcome to your comet! Let's try our first command in the Dojo, the Urbit OS command line and Hoon REPL, to get oriented.
112+
113+Type `(add 2 2)` into the Dojo. You should see the following:
114+
115+```
116+~sampel-palnet:dojo> (add 2 2)
117+```
118+
119+When you press Enter, you should see this:
120+
121+```
122+> (add 2 2)
123+4
124+```
125+
126+Good, your Dojo is working correctly. Now let's run our first useful command in the Dojo. The first thing you generally want to do with a new ship is to **mount** it. A ship being mounted means that it has a presence on your Unix filesystem, allowing files to be shared between Unix and your ship. To mount your ship, type `|mount %` at the Dojo prompt.
127+
128+```
129+|mount %
130+>=
131+```
132+
133+The `>=` output means that a command was successful. Now you can see your ship's files in its Unix directory.
134+
135+### Using Landscape
136+
137+Landscape is the Urbit web interface, and it's the best way to interact with your ship. Chrome and Brave are the recommended browsers for using Landscape. To get onto Landscape:
138+
139+1. Start your ship. 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 ship is using.
140+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.
141+3. Type `+code` into your comet's Dojo. Copy-paste the returned code into the field asking for it in the browser page.
142+4. You're in! Now you can explore apps such as Chat for messages, Publish for blogging, and Weather.
143+
144+### Join a Chat
145+
146+Now that you're on landscape, let's join the Urbit Community chat, a great place for newcomers to ask questions.
147+
148+Click that `Chat` type on your Landscape home page, and then click the `Join Chat` column. Then, enter `~bitbet-bolbel/urbit-community` into the field and press the `Join Chat` button.
149+
150+You can send and receive messages here, just like any other chatroom.
151+
152+### Make a Note
153+
154+Navigate back to your Landscape homepage. Typing `localhost` (or the correct equivalent) into your search bar does the trick.
155+
156+Then click the `Publish` tile. Fill the fields as appropriate to make a new Notebook and invite anyone you want to be able to read it as a subscriber. A Notebook can be treated like a blogs, or a public list of notes. One you have made a Notebook, you can start posting entries to it. Navigate back to it at any time by clicking the tile.
157+
158+## Planet Setup {#planet}
159+
160+If you have a planet, you have a full and persistent peer on the Urbit network.
161+
162+### Getting Urbit ID
163+
164+Tlon doesn't currently sell or distribute Urbit IDs, but there are a few ways to get your own:
165+
166+- Getting an invitation from a friend
167+- Purchasing an Urbit ID from a third party, such as [urbit.live](https://urbit.live), [OpenSea](https://opensea.io), [planet.market](https://planet.market/), or [Urbit Marketplace](https://urbitmarketplace.com/).
168+
169+Tlon occasionally selects candidates to distribute invitations, and users operating galaxies and stars can spawn and distribute a finite number of stars and planets, respectively.
170+
171+### Using your Urbit ID {#id}
172+
173+If you have an Urbit ID, you'll use the [Bridge](https://bridge.urbit.org) client to get your ship's *keyfile* before you can [boot your ship](#booting-your-ship). Your keyfile is a cryptographic secret that allows your Urbit instance to authenticate itself on the network, so you can't boot your planet without it. Your keyfile is deterministically derived from your other cryptographic secrets.
174+
175+### The Urbit ID Wallet
176+
177+Your Urbit ID is actually yours. As long as you control its cryptographic secrets, nobody can take it away from you. That's why it's important to know a little bit about the cryptographic architecture of Urbit secrets.
178+
179+Urbit ID secrets operate as a system of separate but hierarchically realted Ethereum key-pairs. For any given ID, this system of key-pairs is referred to as a **Hierarchical Deterministic (HD) Wallet**. the Urbit HD wallet. Each of these Ethereum addresses have different powers over the same identity, from setting networking keys for communicating in the Urbit network to transferring ownership of identities. Important elements of the HD wallet:
180+
181+- **Master Ticket**: The "password" at the top of the hierarchy that determines the ownership. All other secrets are derived from this. If the rest of the wallet is lost or compromised, the master ticket can rederive everything. You'll log into Bridge with this. Always keep your master ticket extremely safe.
182+
183+- **Management Proxy**: Derived from the master ticket. Can perform non-ownership related operations such as configuring Urbit OS networking keys.
184+
185+- **Keyfile**: Derived from the management proxy. Used as crytographic proof that your Urbit ship it is who it says it is. You use it to start up your ship for the first time.
186+
187+### Getting Your Keyfile {#keyfile}
188+
189+As mentioned previously, there are a few ways to acquire a planet. All methods, however, should result in you receiving at least one secret, such as a **master ticket**. If you received an email invite to Urbit, the master ticket should a `.pdf` the passport folder that you downloaded.
190+
191+1. To connect to Bridge, go to https://bridge.urbit.org.
192+2. Enter the name of your planet and the associated master ticket in the appropriate fields. If you received your secret is in another form, such as a dictionary mnemonic, click the `Metamask, Mnemonic, Hardware Wallet...` button for alternate login methods.
193+3. Once you're logged in, click the `OS` option.
194+4. In resulting page, click the `Download Arvo Keyfile` button. You should receive a `.key` file that contains the secret needed to boot your ship. Hold on to this file.
195+
196+## Installation
197+
198+There are two supported ways of running an Urbit ship: using a [cloud service](#cloud), or running it [locally on your own machine](#local). We recommend using a cloud service for Urbit because it will likely be more reliable than running it locally and allows your ship to be easily accesed from anywhere, without worrying about forwarding ports to and from your home router or your Internet service provider blocking traffic on the default HTTP port. Using a cloud service costs money and has a more involved setup process, but it's more convenient to use than a local install.
199+
200+A cloud service that we like is DigitalOcean, so we give instructions for running Urbit on that service in the section below.
201+
202+If you use Amazon Web Services instead, take note: putting a swap file on Amazon's Elastic Block Store does not work well, and will likely result in your Urbit becoming unresponsive when it tries to access swapped memory. With Amazon instances, swap should only be used on [Instance Stores](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-store-swap-volumes.html).
203+
204+### Option A: DigitalOcean {#cloud}
205+
206+DigitalOcean, a cloud hosting platform, is a good option for hosting an Urbit ship.
207+
208+#### Registration
209+
210+Navigate to https://www.digitalocean.com/ and sign up with your email address. You'll need to add a credit cart or a PayPal to start an account. The final part of the registration process involves choosing what we're trying to get online. Simply choose "Ubuntu server." You'll be asked to create a special password for your "Droplet"; remember it. It's different from your DO account password, and it's used to access your Droplet remotely.
211+
212+The default resources you'll be given with your Droplet is 1 GB of memory, 1 CPU, and 25 GB of storage for 5 USD per month. It must be noted that Urbit ships require at least 2GB of memory to be present, so you'll either need to upgrade your DO Droplet or set up swap space.
213+
214+#### Resizing Your Droplet
215+
216+If you're willing to spend a little bit of extra money, this is the easiest method for getting your Urbit online and running smoothly.
217+
218+An Urbit instance needs 2GB of memory available -- it doesn't need to use all of it, it just needs know that it's there. This memory is in addition to anything that the operating system and other processes require.
219+
220+1. On the sidebar, click `Droplets`.
221+2. There should one option with a name that looks like `ubuntu-s-1vcpu-1gb-nyc1-01`. Click on the the `More`, and on the resulting dropdown menu click `Resize Droplet`.
222+3. On the resize page there is an `On` button for your Droplet. Click it off.
223+4. Make sure the `CPU and RAM only` category is selected. Then scroll down and select the option that provides 3 GB of memory. This will bump your fee to 15 a months
224+5. Turn your Droplet back on.
225+
226+Now you can continue onto installing the Urbit software on your Droplet.
227+
228+#### Setting Up Swap Space
229+
230+If you've set up a Droplet to have more than 2 GB of memory, skip this section.
231+
232+Alternatively, if you don't want to pay the extra money, you can configure swap space to run on a smaller DO instance. Digital Ocean has a post on adding swap [here](https://www.digitalocean.com/community/tutorials/how-to-add-swap-space-on-ubuntu-16-04) that will walk you through the process. Once you've completed, you can continue to installing Urbit on your Droplet.
233+
234+#### Installing Urbit On Your Droplet
235+
236+Let's access your Droplet by using SSH, which is a secure protocol for using a remote computer.
237+
238+1. Find your Droplet's IP address on your DigitalOcean account. It will be under the `Droplets` option on the `Manage` sidebar. Copy the IP address and keep it handy.
239+2. Open you local computer's terminal. Then run the SSH command, which has the syntax `ssh root@1.2.3.4`, where `1.2.3.4` is the IP address that you copied. Your Droplet's default name is `root`, but this can be changed.
240+3. You'll be prompted with a password. Enter the one that you set earlier. If you see a block of messages beginning with something like `Welcome to Ubuntu 18.04.3 LTS (GNU/Linux 4.15.0-66-generic x86_64)` and ending with something like `root@ubuntu-s-1pvcu-1gb-nyc1-01:`, you're in!
241+
242+Now that you're inside your Droplet, you'll want to install the Urbit binary. Run the following commands:
243+
244+```sh
245+curl -O https://bootstrap.urbit.org/urbit-v0.10.8-linux64.tgz
246+tar xzf urbit-v0.10.8-linux64.tgz
247+cd urbit-v0.10.8-linux64
248+./urbit
249+```
250+
251+If you see a block of messages beginning with `Urbit: a personal server operating function`, then you've successfully installed the Urbit software, and it's time to copy your keyfile that from your local machine, the one that ends in `.key` that you got from the [Getting Your Keyfile](#keyfile) instructions. Open it with a text editor and keep it handy so you can copy it. Then return to the terminal window that's running your Droplet.
252+
253+Now, on your Droplet, you'll want to use a Linux functionality called Scree. Screen is used to create virtual terminals (windows) to run persistent processes in the same remote session, so we don't have to close those processes whenever we want to do other things on our Droplet. This makes Screen perfect for running a remote Urbit ship.
254+
255+To start Screen, enter
256+
257+```
258+screen
259+```
260+
261+You'll be met with some copyright information. Hit enter or return to move past this info. Once you're inside Screen, you use `Ctrl-a` to tell it that you're about to enter a command. Screen is controlled through keyboard shortcuts. Here are some useful ones to be run inside a Screen:
262+
263+- To create a new Screen window, enter `Ctrl-a` and then `c`.
264+- To exit a Screen window and go back to your regular Droplet terminal ("Detach" it), enter `Ctrl-a` and then `d`.
265+- To see all Screen shortcuts, enter `Ctrl-a` and then `?`.
266+
267+There are a few useful Screen commands that can be run from your regular Droplet terminal.
268+
269+- To see all running Screen windows, enter `screen -ls`. This is useful if you're not sure if you're inside a Screen window; if you are, it will show a window as "Attached". (Note that you'll only ever need one screen for the purposes of hosting an Urbit remotely)
270+- To return to the Screen window that you made ("Attach" it), enter `screen -r`.
271+- To delete *all* Screen windows, enter `killall screen`.
272+
273+Now, let's put this information to use to boot your Urbit ship in a Screen window.
274+
275+1. Enter `cd urbit-v0.10.8-linux64` to change your directory to the folder containing the Urbit binary.
276+2. Enter `screen -ls`. If you get anything but a message like `No Sockets found in /run/screen/S-root.`, run `killall screen` to wipe the slate clean.
277+3. Enter `screen` and skip past the information. You're in an attached Screen window now; enter `screen -ls` to verify this.
278+4. Open your keyfile on your local machine and copy the contents. On the Screen in your Droplet, enter `./urbit -w sampel-palnet -G rAnDoMkEy`, where `rAnDoMkEy` is the copied contents of the keyfile.
82279
83−### Compile from source
280+Your ship should be booting, and displaying a series of boot messages starting with `urbit 0.10.8`. A directory called `sampel-palnet/` and begin building your ship. It may take a few minutes.
84281
85−If you want to compile from source, see the [instructions on GitHub](https://github.com/urbit/urbit#development).
282+When your ship is finished booting, you will see either the `~sampel-palnet:dojo>` or `~sampel-palnet:chat-cli/` prompt. If you're seeing `:chat-cli` press `Ctrl-x` to switch into Dojo. At that point, you should permanently erase your keyfile from your machine.
283+
284+To shut down your ship, use `Ctrl-d`. Since you're running, you won't have much reason to do this often, since you should always have it running in your Droplet. More frequently you'll want to use `Ctrl-a` and then `d` to go back to your Droplet's command line while keeping your planet running on a detached Screen. Then, to return to your ship, run `screen -r`.
285+
286+If you need to shut down your ship, start it up again by running `./urbit sampel-palnet/` from the directory where your Urbit binary is saved. Note that in this usage, `sampel-palnet/` is the path of a folder, which by default is located in the same folder as the Urbit binary. This folder is called your ship's **pier**.
287+
288+Never boot multiple instances of your ship at the same time. You can prevent this from happening accidently by only ever keeping a single copy of your pier.
86289
87−### About swap space
290+Now you're ready to explore the network and make your ship easily accessible from a remote browser. Jump to the [System Administration](#admin) section to do so.
88291
89−If you're running Urbit in the cloud on a small instance, you may need to additionally configure swap space. If you're not, you can safely ignore this section.
292+### Option B: Local Installation {#local}
90293
91−Urbit wants to map 2GB of memory when it boots up. It won’t necessarily use all this memory, it just wants to see it. On a normal modern PC or Mac, or on a large cloud virtual machine, this is not an issue. On some small cloud virtual machines (Amazon or Digital Ocean) the default memory configuration is smaller than this, and you need to manually configure a swapfile.
294+You can run an Urbit on your laptop, your desktop, or an old tower in your closet. There are fewer steps than installing it on a cloud service, but it won't be as slick of an experience in the long run.
92295
93−Digital Ocean has a post on adding swap [here](https://www.digitalocean.com/community/tutorials/how-to-add-swap-space-on-ubuntu-16-04). For Amazon there’s a StackOverflow thread [here](https://stackoverflow.com/questions/17173972/how-do-you-add-swap-to-an-ec2-instance).
296+The Urbit binary runs on a Unix-like operating system. We have different installation instructions for different platforms. To install and run Urbit OS, the Urbit OS and its binary, run the commands that are listed for your operating system.
297+
298+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:
299+
300+```
301+Urbit: a personal server operating function
302+```
94303
95−## Booting your ship {#booting-your-ship}
304+#### macOS
96305
97−Now the rubber meets the road. You'll be booting your ship with the keyfile that you [downloaded from Bridge](@/using/operations/using-bridge.md).
306+```sh
307+curl -O https://bootstrap.urbit.org/urbit-v0.10.8-darwin.tgz
308+tar xzf urbit-v0.10.8-darwin.tgz
309+cd urbit-v0.10.8-darwin
310+./urbit
311+```
98312
99−Note that this section is only for booting a ship that uses the live Arvo network. If you just want to create an unnetworked ship for development purposes, read [this guide](@/using/develop.md#creating-a-development-ship) instead.
313+#### Linux (64-bit)
100314
101−### Step 1: Find Your Urbit ID
315+```sh
316+curl -O https://bootstrap.urbit.org/urbit-v0.10.8-linux64.tgz
317+tar xzf urbit-v0.10.8-linux64.tgz
318+cd urbit-v0.10.8-linux64
319+./urbit
320+```
102321
103−This will look something like `~lodleb-ritrul`. You can see the name of your Urbit ID when you log into your wallet using the Bridge client.
322+To access your Urbit via HTTP on port 80 on Ubuntu, you may need to run the following:
104323
105−### Step 2: Find the path to your keyfile
324+```sh
325+sudo apt-get install libcap2-bin
326+sudo setcap 'cap_net_bind_service=+ep' /path/to/urbit
327+```
328+(Where `urbit` is the urbit executable downloaded with `curl` prior)
329+
330+#### Windows
331+
332+Please note that this method of installing Urbit is more experimental, and we may not be able to assist you if you encounter issues related to WSL 2, but these instructions have been tested and verified for WSL 2 + Ubuntu 18.04 LTS.
333+
334+Urbit cannot run on Windows itself, but there is a convenient way to run a Linux distro using the [Windows Subsystem for Linux 2](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux), an initiative by Microsoft to bring Linux to Windows 10. For Urbit to work, it is necessary to [install WSL 2](https://docs.microsoft.com/en-us/windows/wsl/wsl2-install) and not just WSL, since version 2 uses virtualization and the real Linux kernel under the hood.
335+
336+Once WSL 2 is installed, open a Linux terminal in Windows and then follow the Linux installation instructions above. 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, by typing `cd ~`.
337+
338+### Booting Your Ship Locally
339+
340+Now the rubber meets the road. You'll be booting your ship with the keyfile that you downloaded from Bridge [earlier in this document](#id).
341+
342+Note that this section is only for booting a ship that uses the live Urbit network.
343+
344+#### Step 1: Find Your Urbit ID
345+
346+This will look something like `~lodleb-ritrul`. You can see the name of your Urbit ID when you log into your wallet using the [Bridge client](#id).
347+
348+#### Step 2: Find the path to your keyfile
106349
107350Find the absolute path to the keyfile that you downloaded from Bridge. Copy it.
108351
109−### Step 3: Run the boot command
352+#### Step 3: Run the boot command
110353
111−Type `cd` in your terminal to return to your home directory. If you want to store your ship somewhere besides your home directory, change the terminal's working directory to the desired directory.
354+If you are not already within the directory you installed above, enter it by running `cd urbit-v0.10.8-darwin` (for Mac) or `cd urbit-v0.10.8-linux64` (for Linux) from where you ran the install commands. It contains your Urbit binary, and your ship will be installed here as well.
112355
113−Run the command below, except with `sampel-palnet` replaced by the name of your
356+Once you're inside, run the command below, except with `sampel-palnet` replaced by the name of your
114357Urbit identity, and `path/to/my-planet.key` replaced with the path to your keyfile:
115358
116359```sh
@@ -127,9 +370,17 @@ Either command will create a directory called `sampel-palnet/` and begin buildin
127370
128371When your ship is finished booting, you will see either the `~sampel-palnet:dojo>` or `~sampel-palnet:chat-cli/` prompt. If you're seeing `:chat-cli` press `Ctrl-x` to switch into Dojo. At that point, you should permanently erase your keyfile from your machine.
129372
130−## The Dojo
373+To shut down your ship, use `Ctrl-d`. To start your ship up again, run `./urbit sampel-palnet/` from the directory where your Urbit binary is saved. Note that in this usage, `sampel-palnet/` is the path of a folder, which by default is located in the same folder as the Urbit binary. This folder is called your ship's **pier**, and you can put it wherever you like.
374+
375+Never boot multiple instances of your ship at the same time. You can prevent this from happening on accident by only ever keeping a single copy of your pier.
376+
377+## System Administration {#admin}
131378
132−Welcome to your ship! Let's try our first command in the Dojo, the Arvo command line and Hoon REPL, to get oriented.
379+Welcome to your ship. Let's start exploring.
380+
381+### The Dojo
382+
383+Let's try our first command in the Dojo, the Urbit OS command line and Hoon REPL, to get oriented.
133384
134385Type `(add 2 2)` into the Dojo. You should see the following:
135386
@@ -153,28 +404,158 @@ Good, your Dojo is working correctly. Now let's run our first useful command in
153404
154405The `>=` output means that a command was successful. Now you can see your ship's files in its Unix directory.
155406
156−### Using Landscape
407+### Setting Up DNS {#dns}
157408
158−Landscape is the Urbit web interface, and it's the best way to interact with your ship. Chrome and Brave are the recommended browsers for using Landscape. To get onto Landscape:
409+Landscape is the Urbit web interface, and it's the best way to interact with your ship. Chrome and Brave are the recommended browsers for using Landscape. The best way to access Landscape is to set DNS proxying, so that you can access your ship easily from a web browser on any computer.
159410
1604111. Start your ship. 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 ship is using.
161−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`. Alternatively, you access landscape by navigating to `ship.arvo.network` into your URL bar, where `sampel-palnet` is the name of your ship, without the `~`. You will need to [set up DNS proxying](@/using/operations/using-your-ship.md#dns-proxying) to use this option.
412+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`. Alternatively, you access landscape by navigating to `sampel-palnet.arvo.network` into your URL bar, where `sampel-palnet` is the name of your ship, without the `~`. You will need to [set up DNS proxying](@/using/operations/using-your-ship.md#dns-proxying) to use this option. To do so, simply run this command in your ship's Dojo: `> -dns-address &dns-address [%if .1.2.3.4]`, where `.1.2.3.4` is the IP address.
1624133. Type `+code` into your ship's Dojo. Copy-paste the returned code into the field asking for it in the browser page.
1634144. You're in! Now you can explore apps such as Chat for messages, Publish for blogging, and Weather.
164415
165416### Joining the community
166417
167−Once you are in Landscape we recommend joining the Urbit Community group. You
168−will need to obtain an invite, which can be had by first joining
169−the `~/~dopzod/urbit-help` chat channel and asking for an invitation from there.
170−This is most likely to succeed quickly during standard US West Coast working hours.
171−Once you have the invite you can accept it by navigating to your Groups by
172−clicking on All Groups in the upper left hand corner of Landscape, then Manage
173−All Groups, and in there you should see an invitation. From this interface you
174−can join the various Chat, Publish, and Link instances contained in the group.
175−
176−You can join `~/~dopzod/urbit-help` from either Landscape or dojo. To join from
177−Landscape first click on the Messaging tile on the home screen. Then press Join Chat
178−in the upper left corner and enter `~/~dopzod/urbit-help` into the prompt and
179−press Join Chat. To join from dojo, enter `;join ~/~dopzod/urbit-help` into dojo
180−and press enter.
418+Once you are in Landscape we recommend joining the Urbit Community group. You will need to obtain an invite, which can be had by first joining the `~/~dopzod/urbit-help` chat channel and asking for an invitation from there. This is most likely to succeed quickly during standard US West Coast working hours. Once you have the invite you can accept it by navigating to your Groups by clicking on All Groups in the upper left hand corner of Landscape, then Manage All Groups, and in there you should see an invitation. From this interface you can join the various Chat, Publish, and Link instances contained in the group.
419+
420+You can join `~/~dopzod/urbit-help` from either Landscape or chat-cli. To join from Landscape first click on the Messaging tile on the home screen. Then press Join Chat in the upper left corner and enter `~/~dopzod/urbit-help` into the prompt and press Join Chat. To join from chat-cli, first make sure your console has been switched from Dojo to the `:chat-cli` application by pressing `Ctrl-x`. The prompt will display `~sampel-palnet:chat-cli` if in the correct mode. Then type `;join ~/~dopzod/urbit-help` and press Enter.
421+
422+### Updating to the latest binary
423+
424+Most updates to Urbit are downloaded and applied automatically as OTA (Over the Air) updates. Occasionally it would be infeasible to distribute an update this way, and a new `urbit` binary is released. This is announced in the [urbit-dev](https://groups.google.com/a/urbit.org/forum/#!forum/dev) Google Group when it occurs (as are all OTA updates). To update to the latest binary, follow the same process outlined above to download and extract it into a new folder. (the binary linked on this page will always be the latest). Then run it as before with `./urbit path/to/sampel-palnet/`.
425+
426+### Breaches
427+
428+An important concept on the Urbit network is that of continuity. Continuity refers to how ships remember the order of their own network messages and the network messages of others -- these messages are numbered, starting from zero. A breach is when ships on the network agree to forget about this sequence and treat one or more ships like they are brand new.
429+
430+There are two kinds of breaches: personal breaches and network breaches.
431+
432+A personal breach can fix many problems with your ship, but should be used as a last resort. A network breach happens when there's a major software update and you must download a new binary.
433+
434+For details on breaching, please read the [Guide to Breaches](@/docs/tutorials/guide-to-breaches.md) documentation.
435+
436+### Reporting Bugs
437+
438+If you find a bug, please report it as an Issue at https://github.com/urbit/urbit/issues/new/choose. Give as much detail as possible with your bug report so the engineer team can fix it.
439+
440+## Running a Supernode
441+
442+Setting up and running a star or galaxy is a little bit different from setting up and running a planet.
443+
444+### Getting a Star or Galaxy
445+
446+Stars are valuable cryptographic assets. They can be bought in one of two ways.
447+
448+- Transacting privately with a star owner.
449+- Buying a star on a marketplace like [OpenSea](https://opensea.io/collection/urbit-id)
450+
451+Galaxies are rare and extremely valuable, meaning that there is no liquid market for them. If you want to buy a galaxy, you'll have to find an individual galaxy owner and transact with them.
452+
453+### A Note Regarding Security
454+
455+As mentioned before, stars are valuable. You are solely responsible for safeguarding your seeds and secret keys, and arming yourself with the computer-security knowledge that is attendant upon that safeguarding. You act at your own risk in reliance upon the contents of the manual. In no way is the Tlon Corporation responsible for the actions, decisions, or other behavior taken or not taken by you in reliance upon this manual.
456+
457+It’s a good idea to store your keys redundantly; for example, on both a USB stick and a piece of paper in the safe, in case one of those methods fails. If you deem a key to be valuable enough, you can shard it into thirds and store each third in secure, geographically distributed locations. Consider these storage media options:
458+
459+- Printing the secret on a piece of paper. However, paper wallets are vulnerable to various forms of physical damage, such as rot, water damage, smoke, or fire. Laminating the paper can mitigates some of these risks, but the lamination can potentially trap moisture. Make sure that you trust the printer: some have memory and network connections.
460+- Storing the secret on a brand-new USB stick or hardware wallet (such as a Ledger) that is never connected to a networked machine.
461+- Engraving the secret on a strip of stainless steel. This medium is resistant to both water damage and fire damage.
462+
463+
464+### Getting a Star's Keyfile
465+
466+1. To connect to Bridge, go to https://bridge.urbit.org.
467+2. Enter the name of your star and the associated master ticket in the appropriate fields. If you received your secret is in another form, such as a dictionary mnemonic, click the `Metamask, Mnemonic, Hardware Wallet...` button for alternate login methods.
468+3. Once you're logged in, click the `OS` option.
469+4. In resulting page, click the `Download Arvo Keyfile` button. You should receive a `.key` file that contains the secret needed to boot your ship. Hold on to this file.
470+
471+### Star: Setup And Install
472+
473+Because of their need for near-perfect uptime Stars should use cloud services. We like to use DigitalOcean (DO), and our instructions here support that service.
474+
475+Navigate to https://www.digitalocean.com/ and sign up. You'll need to add a credit cart or a PayPal to start an account. The final part of the registration process involves choosing what we're trying to get online. Simply choose "Ubuntu server." You'll be asked to create a special password for your "Droplet"; remember it. It's different from your DO account password, and it's used to access your Droplet remotely.
476+
477+The default resources you'll be given with your Droplet is 1 GB of memory, 1 CPU, and 25 GB of storage for 5 USD per month. It must be noted that Urbit ships require at least 2GB of memory to be present, so you'll either need to upgrade your DO Droplet.
478+
479+#### Resizing Your Droplet
480+
481+An Urbit instance needs 2GB of memory available -- it doesn't need to use all of it, it just needs know that it's there. This memory is in addition to anything that the operating system and other processes require.
482+
483+1. On the sidebar, click `Droplets`.
484+2. There should one option with a name that looks like `ubuntu-s-1vcpu-1gb-nyc1-01`. Click on the the `More`, and on the resulting dropdown menu click `Resize Droplet`.
485+3. On the resize page there is an `On` button for your Droplet. Click it off.
486+4. Make sure the `CPU and RAM only` category is selected. Then scroll down and select the option that provides 3 GB of memory. This will bump your fee to 15 a months
487+5. Turn your Droplet back on.
488+
489+Now you can continue onto installing the Urbit software on your Droplet.
490+
491+#### Installing Urbit On Your Droplet
492+
493+Let's access your Droplet by using SSH, which is a secure protocol for using a remote computer.
494+
495+1. Find your Droplet's IP address on your DigitalOcean account. It will be under the `Droplets` option on the `Manage` sidebar. Copy the IP address and keep it handy.
496+2. Open you local computer's terminal. Then run the SSH command, which has the syntax `ssh root@1.2.3.4`, where `1.2.3.4` is the IP address that you copied. Your Droplet's default name is `root`, but this can be changed.
497+3. You'll be prompted with a password. Enter the one that you set earlier. If you see a block of messages beginning with something like `Welcome to Ubuntu 18.04.3 LTS (GNU/Linux 4.15.0-66-generic x86_64)` and ending with something like `root@ubuntu-s-1pvcu-1gb-nyc1-01:`, you're in!
498+
499+Now that you're inside your Droplet, you'll want to install the Urbit binary. Run the following commands:
500+
501+```sh
502+curl -O https://bootstrap.urbit.org/urbit-v0.10.8-linux64.tgz
503+tar xzf urbit-v0.10.8-linux64.tgz
504+cd urbit-v0.10.8-linux64
505+./urbit
506+```
507+
508+If you see a block of messages beginning with `Urbit: a personal server operating function`, then you've successfully installed the Urbit software, and it's time to copy your keyfile that from your local machine, the one that ends in `.key` that you got from the [Getting Your Keyfile](#keyfile) instructions. Open it with a text editor and keep it handy so you can copy it. Then return to the terminal window that's running your Droplet.
509+
510+Now, on your Droplet, you'll want to use a Linux functionality called Scree. Screen is used to create virtual terminals (windows) to run persistent processes in the same remote session, so we don't have to close those processes whenever we want to do other things on our Droplet. This makes Screen perfect for running a remote Urbit ship.
511+
512+To start Screen, enter
513+
514+```
515+screen
516+```
517+
518+You'll be met with some copyright information. Hit enter or return to move past this info. Once you're inside Screen, you use `Ctrl-a` to tell it that you're about to enter a command. Screen is controlled through keyboard shortcuts. Here are some useful ones to be run inside a Screen:
519+
520+- To create a new Screen window, enter `Ctrl-a` and then `c`.
521+- To exit a Screen window and go back to your regular Droplet terminal ("Detach" it), enter `Ctrl-a` and then `d`.
522+- To see all Screen shortcuts, enter `Ctrl-a` and then `?`.
523+
524+There are a few useful Screen commands that can be run from your regular Droplet terminal.
525+
526+- To see all running Screen windows, enter `screen -ls`. This is useful if you're not sure if you're inside a Screen window; if you are, it will show a window as "Attached". (Note that you'll only ever need one screen for the purposes of hosting an Urbit remotely)
527+- To return to the Screen window that you made ("Attach" it), enter `screen -r`.
528+- To delete *all* Screen windows, enter `killall screen`.
529+
530+Now, let's put this information to use to boot your Urbit ship in a Screen window.
531+
532+1. Enter `cd urbit-v0.10.8-linux64` to change your directory to the folder containing the Urbit binary.
533+2. Enter `screen -ls`. If you get anything but a message like `No Sockets found in /run/screen/S-root.`, run `killall screen` to wipe the slate clean.
534+3. Enter `screen` and skip past the information. You're in an attached Screen window now; enter `screen -ls` to verify this.
535+4. Open your keyfile on your local machine and copy the contents. On the Screen in your Droplet, enter `./urbit -w sampel -G rAnDoMkEy`, where `rAnDoMkEy` is the copied contents of the keyfile.
536+
537+Your ship should be booting, and displaying a series of boot messages starting with `urbit 0.10.8`. A directory called `sampel/` and begin building your ship. It may take a few minutes.
538+
539+When your ship is finished booting, you will see either the `~sampel:dojo>` or `~sampel:chat-cli/` prompt. If you're seeing `:chat-cli` press `Ctrl-x` to switch into Dojo. At that point, you should permanently erase your keyfile from your machine.
540+
541+To shut down your ship, use `Ctrl-d`. Since you're running, you won't have much reason to do this often, since you should always have it running in your Droplet. More frequently you'll want to use `Ctrl-a` and then `d` to go back to your Droplet's command line while keeping your planet running on a detached Screen. Then, to return to your ship, run `screen -r`.
542+
543+If you need to shut down your ship, start it up again by running `./urbit sampel` from the directory where your Urbit binary is saved. Note that in this usage, `sampel/` is the path of a folder, which by default is located in the same folder as the Urbit binary. This folder is called your ship's **pier**.
544+
545+Never boot multiple instances of your ship at the same time. You can prevent this from happening accidently by only ever keeping a single copy of your pier.
546+
547+#### Maintaining a Star
548+
549+Being an infrastructure node, a star has certain responsibilities to the Urbit network.
550+
551+By default, your star accepts software updates from its galaxy and routes them to its planets. You can use this mechanism to push custom software to your planets. Keep in mind that planets expect functional, non-breaking software updates, and generally want to be able to communicate with planets that are sponsored by other stars.
552+
553+To ensure new planets can connect to your ship, users are expected to participate in network-wide breaches by updating to the latest Urbit version, deleting (or archiving) your pier, and then booting your ship using the new binary. If you don’t participate, you won’t be able to communicate with anyone on the network who has updated to the new era.
554+
555+Network-wide breaches are distinct from personal breaches, wherein an individual ship cycles its personal network keys using bridge.
556+
557+See our [Guide to Breaches](@/docs/tutorials/guide-to-breaches.md) for more information and for instructions on breaching.
558+
559+### Running a Galaxy
560+
561+A galaxy is at the top of the hierarchy in terms of importance. Thus, if you're interested in running one, please contact support@urbit.org, and we will give you personalized assistance in getting set up.