@@ -14,7 +14,7 @@ This guide is broken into five parts:
14+ [Basic Operations](#operation)
14+ [Basic Operations](#operation)
16_If you just want to install the Urbit OS, Arvo, and don't need to be on the
16_If you just want to install the Urbit OS, Arvo, and don't need to be on the
17−network, you can skip to [Installing Arvo](#arvo)._
17+Urbit network, you can skip to [Installing Arvo](#arvo)._
@@ -24,9 +24,8 @@ network, you can skip to [Installing Arvo](#arvo)._
25Urbit's identity layer, called Azimuth, is a suite of contracts on the Ethereum
25Urbit's identity layer, called Azimuth, is a suite of contracts on the Ethereum
26blockchain. An Azimuth address, called a *point*, functions as an identity and
26blockchain. An Azimuth address, called a *point*, functions as an identity and
27−a network address for Arvo, the Urbit operating system. An instance of Arvo is
27+a network address for Arvo, the Urbit OS. An instance of Arvo is called a
28−called a *ship*. A ship can't use the Arvo network until it's combined with a
28+*ship*. A ship can't use the Arvo network until it's combined with a point.
31Throughout this guide, we'll refer to \"Urbit identities\" and \"points\"
30Throughout this guide, we'll refer to \"Urbit identities\" and \"points\"
32interchangeably.
31interchangeably.
@@ -35,26 +34,18 @@ Points are generally not freely available, so you will need to either
35purchase one or get one from a friend. This guide assumes you have found a way
34purchase one or get one from a friend. This guide assumes you have found a way
36to acquire a point.
35to acquire a point.
38−To get an Urbit identity, you'll need two things: an Ethereum address and a
37+If you went through the address registration process and used [Wallet Generator](https://github.com/urbit/urbit-wallet-generator),
39−person willing to send you the identity.
38+then you should have have received a .zip file that contains an Ethereum address
39+and cryptographic secrets in the form of a PDF.
41−You'll probably want to start with a planet. Those are cheap identities for
41+Your ownership PDF contains two secrets that must be kept safe.
42−everyday use. Find someone who is willing to part with a point: a friend, or a
43−stranger selling a point via smart contract. Once they've sent the point, you
44−can access it using our Bridge software.
46−If you bought address space from Tlon, then you should have have received a .zip
47−file that contains an Ethereum address and cryptographic secrets on a PDF. Your
48−ownership PDF contains two secrets that must be kept safe:
50−- *Master Ticket*: This is a master key that allows you to manage every aspect
43+- *Master Ticket*: This is a master key that allows you to manage every aspect of
51− of your address.
44+ your address.
53- *Ownership Seed BIP39 Mnemonic*: The master ticket encoded as a BIP39 mnemonic
46- *Ownership Seed BIP39 Mnemonic*: The master ticket encoded as a BIP39 mnemonic
54− for compatibility with most Ethereum wallet software, including our own
47+ for compatibility with most Ethereum wallet software, including our own *Bridge*
55− *Bridge* client.
48+ client.
@@ -62,13 +53,14 @@ Once you
65−Bridge is a client that we built for accessing and managing your Urbit
56+Bridge is client that we built for accessing and managing your Urbit identities.
66−identities. Bridge comes in the form of an offline HTML application that can be
57+Like Wallet Generator, Bridge is a web application that can also be run in offline mode.
67−run in Firefox, Safari, or Chrome.
58+It can be run in Firefox on all platforms, and also in Chrome if you're using
69−Importantly, Bridge also automates the process of generating the keyfile that
61+Importantly, Bridge also allows you to generate a keyfile that
70−you will need a single time to boot your ship on the Arvo network. Once a ship
62+you will need to boot your ship on the Arvo network for the first time. Once a ship
71−is booted, it stays booted forever.
63+with a keyfile, you can restart it later without the keyfile.
73Download bridge [here](https://github.com/urbit/bridge/releases) and follow
65Download bridge [here](https://github.com/urbit/bridge/releases) and follow
74the instructions below.
66the instructions below.
@@ -85,41 +77,47 @@ On the dropdown menu, make sure that `Main Network` is selected. Then click
85#### Step 3: Open a Wallet
77#### Step 3: Open a Wallet
87On this dropdown menu, choose how you'd like to access your Ethereum wallet.
79On this dropdown menu, choose how you'd like to access your Ethereum wallet.
88−If you aren't using Hardware wallets (a Ledger or a Trezor), you'll want to use
80+If you aren't using a hardware wallet (we support Ledger and Trezor), you'll
89−your Ethereum wallet's BIP39 Mnemonic.
81+want to use your Ethereum wallet's BIP39 Mnemonic.
91−If you received a point from Tlon and received paper wallets in the form of
83+If you used Wallet Generator to generate an HD wallet, you have a few choices:
92−PDFs, choose `Urbit Master Ticket`.
84+you can choose `Urbit Master Ticket,` which is high-value, but allows you unfettered
85+permissions to update your point. The mnemonic associated with your management
86+seed is also quite useful to perform everyday operations (such as boot your ship!).
94Select the appropriate option and click `Continue ->`.
88Select the appropriate option and click `Continue ->`.
96−#### Step 4: Accept Your Transfer
90+#### Step 4: (optional) Accept Your Transfer
98−If you were sent a point, then you should see a graphic under
92+If you were sent a point by a friend, then you should see a graphic under
99`Incoming Transfers`. Click the `Details ->` link under that graphic.
93`Incoming Transfers`. Click the `Details ->` link under that graphic.
101Now you'll be on the management page of your point. The transfer isn't completed
95Now you'll be on the management page of your point. The transfer isn't completed
102yet, so click `Accept incoming transfer`. Then check both boxes and and click
96yet, so click `Accept incoming transfer`. Then check both boxes and and click
103their associated `Sign Transaction` and `Send Transaction` buttons.
97their associated `Sign Transaction` and `Send Transaction` buttons.
105−#### Step 5: Set Your Networking Keys
99+If you already own a point, then click on the `Details ->` under your sigil in the
100+`Your Points` section.
107−You'll be returned to your point screen. Notice that that links and buttons
102+#### Step 5: (optional) Set Your Networking Keys
108−are now clickable. You know own this point!
110−Click the link that says `Set Urbit networking keys`. Choose two different,
104+If you just accepted a point, you'll be returned to your point screen. Notice that
111−64-character long strings of hexademical, check the box, and, like before, check
105+that links and buttons are now clickable. You now own this point!
112−both boxes and press both buttons.
114−#### Step 6: Generate Your Keyfile
107+Click the link that says `Generate Urbit networking keys`. Bridge will let you either
108+download a keyfile derived from your networking keys are you can paste in your own
109+network seed and derive a new keyfile. See our
110+[HD Wallet Spec](https://github.com/urbit/proposals/blob/master/proposals/8.md)
111+for more information.
116−Return to your point by clicking its name at the navigation bar on the top of
113+#### Step 6: Generate Your Keyfile
115+From the detail page associated with your point, click the `Generate Urbit Keyfile`
119−Click the `Generate Urbit Keyfile` button and you'll be taken to a page with a
116+button and you'll be taken to a page with a field titled `Network key`. If you went
120−field titled `Network key`. That field should be filled in already. Click
117+through the address registration process, this should be filled in already.
121−`Generate ->`, which will download a the keyfile onto your machine.
118+Click `Generate ->`, which will download a keyfile onto your machine.
120+With that keyfile in hand, you can now exit Bridge.
@@ -127,14 +125,18 @@ field titled `Network key`. That field should be filled in already. Click
130−Now you're ready to install the Arvo software. You're almost there!
128+Now you're ready to run Arvo. You're almost there!
130+But first, some terminology:
131+- `vere` or `urbit`: the interpreter that runs when you run a command like `urbit` or `/bin/urbit` in your command line
132+- `arvo`: the deterministic OS that lives in a directory whose name matches your Azimuth point, ie `~famreb-todmec` lives in `/famreb-todmec`
132−Arvo can only run on a Unix-like operating system -- Ubuntu,
134+Arvo runs nicely on a Unix-like operating system -- Ubuntu,
133−Fedora, macOS, and FreeBSD all work well. If you're using Windows, you'll need
135+Fedora, macOS, and FreeBSD. If you're using Windows, you'll need
134to get one of the aforementioned systems. Don't worry: most of them are free.
136to get one of the aforementioned systems. Don't worry: most of them are free.
136We have different installation instructions for different platforms. To install
138We have different installation instructions for different platforms. To install
137−Arvo, run the Bash commands that are listed for your operating system.
139+and run Arvo, run the commands that are listed for your operating system.
139On any platform, you can check your Arvo installation by running the `urbit`
141On any platform, you can check your Arvo installation by running the `urbit`
140command. Installation was successful if you get a block of output that begins
142command. Installation was successful if you get a block of output that begins
@@ -146,7 +148,7 @@ Urbit: a personal server operating function
147#### MacOS
149#### MacOS
149−We recommend using the Homebrew package manager to install Arvo on MacOS.
151+We recommend using the Homebrew package manager to run Arvo on MacOS.
@@ -252,7 +254,7 @@ If you just want to use a fake ship for development purposes, you can now use
252the command of the scheme below to boot a fake `~zod`.
254the command of the scheme below to boot a fake `~zod`.
255−urbit -F zod -A /path/to/arvo -s -c zod -S
257+urbit -F zod -A /path/to/arvo -s -c zod
258If you want to get on the Arvo network with your point, then continue to the
260If you want to get on the Arvo network with your point, then continue to the
@@ -261,20 +263,20 @@ next section.
264− ;div(id "boot"): Booting Your Urbit
266+ ;div(id "boot"): Booting Your Ship
269Now the rubber meets the road. You'll be booting your ship with the keyfile
271Now the rubber meets the road. You'll be booting your ship with the keyfile
270−that you downloaded from bridge.
272+that you downloaded from Bridge.
272#### Step 1: Find Your Point's Name
274#### Step 1: Find Your Point's Name
274This will look something like `~lodleb-ritrul`. You can see the name of your
276This will look something like `~lodleb-ritrul`. You can see the name of your
275point(s) when you log into your wallet using the Bridge client.
277point(s) when you log into your wallet using the Bridge client.
277−;img@"http://media.urbit.org/site/bridge-0.png"(width "100%");
279+;img@"media.urbit.org/site/bridge-0.png"(width "100%");
279#### Step 2: Find the path to your keyfile
281#### Step 2: Find the path to your keyfile
@@ -294,6 +296,13 @@ keyfile:
294urbit -w ~sample-planet -k path/to/my-planet.key
296urbit -w ~sample-planet -k path/to/my-planet.key
299+if you'd prefer to copy your key in you can run
302+urbit -w ~sample-planet -G rAnDoMkEy
297This will create a directory called `sample-planet/` and begin building your
306This will create a directory called `sample-planet/` and begin building your
298ship. It may take a few minutes.
307ship. It may take a few minutes.
@@ -344,22 +353,21 @@ This should produce:
344which indicates that the command was processed.
353which indicates that the command was processed.
346`|mount %` will cause a `home/` directory to appear inside your _pier_ folder in
355`|mount %` will cause a `home/` directory to appear inside your _pier_ folder in
347−Unix. Changes to these files are automatically synced into your ship.
356+Unix (the "pier" is our shorthand for the directory whose name corresponds to your Azimuth point). Changes to these files are automatically synced into your ship.
352Use `ctrl-x` to toggle between the Dojo and the Talk prompts.
361Use `ctrl-x` to toggle between the Dojo and the Talk prompts.
354−While on the Talk prompt, let's join the main Urbit chat channel, `/urbit-meta`:
363+While on the Talk prompt, let's join the main Urbit support chat channel, `/urbit-help`:
357−~sample-planet:talk[] ;join /urbit-meta
366+~sample-planet:talk[] ;join /urbit-help
360−Talk is stateful, so your ship will download a backlog. `/urbit-meta` is the
369+Talk is stateful, so your ship will download a backlog. `/urbit-help` is the
361−place to ask questions, get help, talk about anything Urbit-related, and meet
370+place to ask questions about getting up and running.
364#### Shutting Down and Restarting
372#### Shutting Down and Restarting
@@ -375,25 +383,27 @@ $ urbit some-planet
376Your ship is also accessible through its own web interface. Through the web
384Your ship is also accessible through its own web interface. Through the web
377interface you'll have access to our chat and message boards, the two components
385interface you'll have access to our chat and message boards, the two components
378−of our _Landscape_ feature. This is a user-friendly way to use Talk on the
386+of our _Landscape_ feature. This is a user-friendly way to chat with Talk on the
379Arvo network and access and materials you've published on your ship. If You're
387Arvo network and access and materials you've published on your ship. If You're
380running Arvo locally on your own machine, try opening `http://localhost/` in
388running Arvo locally on your own machine, try opening `http://localhost/` in
381your browser.
389your browser.
383−Or, if you're running your ship on a cloud instance with a static IP address
391+Or if you're running your ship on a cloud instance with a static IP address
384−(which we recommend!), something like 212.131.240.20,
392+(which we recommend!), something like 212.131.240.20, assuming you've opened up
393+the HTTP port that Arvo uses -- the default is port 80. So
385−`http://212.131.240.20:80/~~/` would go into your browser's URL bar. This way,
394+`http://212.131.240.20:80/~~/` would go into your browser's URL bar.
386−if you keep your ship running securely in the cloud (usually in a screen or tmux
396+This way, if you keep your ship running securely in the cloud (usually in a
387−session), you can always access your ships's web interface in any browser on
397+screen or tmux session), you can always access your ships's web interface in any
388−any device.
398+browser on any device, so long as you have your password on hand.
390The `/~~/` in the URL will redirect you to a login page, which was generated by
400The `/~~/` in the URL will redirect you to a login page, which was generated by
391−Tree, the basic Arvo web interface. The page will tell you to run the `+code`
401+Tree, the basic Arvo web interface. The page will tell you to run the +code
392−generator (an Arvo shell-script) in your Dojo to get your password. Copy and
402+generator (an Arvo shell script) in your Dojo to get your password. Copy and
393−paste that into the password-input field and hit Enter. After loading, you'll
403+paste that into your password input box and hit Enter. After loading, you'll
394find yourself redirected to your home page, authenticated, where you can then
404find yourself redirected to your home page, authenticated, where you can then
395use the navigation bar at the top of the page to visit your Talk web interface
405use the navigation bar at the top of the page to visit your Talk web interface
396and static files.
406and static files.
398When you use the web interface, your urbit is automatically subscribed to
408When you use the web interface, your urbit is automatically subscribed to
399−`/urbit-meta` and our message-board system, Posts.
409+`/urbit-meta` and Fora, our message-board system.