@@ -1,10 +1,386 @@
11:- :~ navhome/'/docs/'
2− sort/'2'
3− title/'Using'
2+ next/'true'
3+ sort/'1'
4+ title/'Getting Started'
45 ==
56;>
67
78# Getting Started
89
9−These short guides will get you installed, setup, and will walk you through the
10−basic features of Urbit.
10+This guide is broken into five parts:
11+
12++ [Acquiring an Urbit Identity](#acquire)
13++ [Using Bridge](#bridge)
14++ [Installing Arvo](#arvo)
15++ [Booting Your Ship](#boot)
16++ [Basic Operations](#operation)
17+
18+_If you just want to install the Urbit OS, Arvo, and don't need to be on the
19+Urbit network, you can skip to [Installing Arvo](#arvo)._
20+
21+;=
22+ ;h2
23+ ;div(id "acquire"): Acquiring an Urbit Identity
24+ ==
25+==
26+
27+Urbit's identity layer, called Azimuth, is a suite of contracts on the Ethereum
28+blockchain. An Azimuth address, called a *point*, functions as an identity and
29+a network address for Arvo, the Urbit OS. An instance of Arvo is called a
30+*ship*. A ship can't use the Arvo network until it's combined with a point.
31+
32+Throughout this guide, we'll refer to \"Urbit identities\" and \"points\"
33+interchangeably.
34+
35+Points are generally not freely available, so you will need to either
36+purchase one or get one from a friend. This guide assumes you have found a way
37+to acquire a point.
38+
39+If you went through the address registration process and used [Wallet Generator](https://github.com/urbit/urbit-wallet-generator),
40+then you should have have received a .zip file that contains an Ethereum address
41+and cryptographic secrets in the form of a PDF.
42+
43+Your ownership PDF contains two secrets that must be kept safe.
44+
45+- *Master Ticket*: This is a master key that allows you to manage every aspect of
46+ your address.
47+
48+- *Ownership Seed BIP39 Mnemonic*: The master ticket encoded as a BIP39 mnemonic
49+ for compatibility with most Ethereum wallet software, including our own *Bridge*
50+ client.
51+
52+;=
53+ ;h2
54+ ;div(id "bridge"): Using Bridge
55+ ==
56+==
57+
58+Bridge is client that we built for accessing and managing your Urbit identities.
59+Like Wallet Generator, Bridge is a web application that can also be run in offline mode.
60+It can be run in Firefox on all platforms, and also in Chrome if you're using
61+a Mac.
62+
63+Importantly, Bridge also allows you to generate a keyfile that
64+you will need to boot your ship on the Arvo network for the first time. Once a ship
65+with a keyfile, you can restart it later without the keyfile.
66+
67+*Note* Bridge allows you to make _writes_ to the blockchain, but we ask you to confirm
68+anything that will incur a transaction cost. If you plan to do anything heavy-duty, make
69+sure your Ethereum address has some pocket ETH.
70+
71+Download bridge [here](https://github.com/urbit/bridge/releases) and follow
72+the instructions below.
73+
74+#### Step 1: Welcome
75+
76+Click `Open a Wallet`.
77+
78+#### Step 2: Select a Network
79+
80+On the dropdown menu, make sure that `Main Network` is selected. Then click
81+`Continue ->`.
82+
83+#### Step 3: Open a Wallet
84+
85+On this dropdown menu, choose how you'd like to access your Ethereum wallet.
86+If you aren't using a hardware wallet (we support Ledger and Trezor), you'll
87+want to use your Ethereum wallet's BIP39 Mnemonic.
88+
89+If you used Wallet Generator to generate an HD wallet, you have a few choices:
90+you can choose `Urbit Master Ticket,` which is high-value, but allows you unfettered
91+permissions to update your point. The mnemonic associated with your management
92+seed is also useful to perform everyday operations (such as boot your ship!).
93+
94+Select the appropriate option and click `Continue ->`.
95+
96+#### Step 4: (optional) Accept Your Transfer
97+
98+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.
100+
101+Now you'll be on the management page of your point. The transfer isn't completed
102+yet, so click `Accept incoming transfer`. Then check both boxes and and click
103+their associated `Sign Transaction` and `Send Transaction` buttons.
104+
105+If you already own a point, then click on the `Details ->` under your sigil in the
106+`Your Points` section.
107+
108+#### Step 5: (optional) Set Your Networking Keys
109+
110+If you just accepted a point, you'll be returned to your point screen. Notice that
111+that links and buttons are now clickable. You now own this point!
112+
113+Click the link that says `Generate Urbit networking keys`. Bridge will let you either
114+download a keyfile derived from your networking keys are you can paste in your own
115+network seed and derive a new keyfile. See our
116+[HD Wallet Spec](https://github.com/urbit/proposals/blob/master/proposals/8.md)
117+for more information.
118+
119+#### Step 6: Generate Your Keyfile
120+
121+From the detail page associated with your point, click the `Generate Urbit Keyfile`
122+button and you'll be taken to a page with a field titled `Network key`. If you went
123+through the address registration process, this should be filled in already.
124+Click `Generate ->`, which will download a keyfile onto your machine.
125+
126+With that keyfile in hand, you can now exit Bridge.
127+
128+;=
129+ ;h2
130+ ;div(id "arvo"): Installing Arvo
131+ ==
132+==
133+
134+Now you're ready to run Arvo. You're almost there!
135+
136+But first, some terminology:
137+- `vere` or `urbit`: the interpreter that runs when you run a command like `urbit` or `/bin/urbit` in your command line
138+- `arvo`: the deterministic OS that lives in a directory whose name matches your Azimuth point, ie `~famreb-todmec` lives in `/famreb-todmec`
139+
140+Arvo runs nicely on a Unix-like operating system -- Ubuntu,
141+Fedora, macOS, and FreeBSD. If you're using Windows, you'll need
142+to get one of the aforementioned systems. Don't worry: most of them are free.
143+
144+We have different installation instructions for different platforms. To install
145+and run Arvo, run the commands that are listed for your operating system.
146+
147+On any platform, you can check your Arvo installation by running the `urbit`
148+command. Installation was successful if you get a block of output that begins
149+with the line below:
150+
151+```
152+Urbit: a personal server operating function
153+```
154+
155+#### MacOS
156+
157+We recommend using the Homebrew package manager to run Arvo on MacOS.
158+
159+```
160+# Bash
161+
162+brew update
163+brew install autoconf automake cmake gcc git gmp libsigsegv libtool meson ninja pkg-config python2 openssl re2c
164+git clone https://github.com/urbit/urbit
165+cd urbit
166+./scripts/bootstrap
167+./scripts/build
168+sudo ninja -C ./build/ meson-install
169+urbit
170+```
171+
172+#### Ubuntu or Debian
173+
174+```
175+# Bash
176+
177+sudo apt-get update
178+sudo apt-get install autoconf automake cmake exuberant-ctags g++ git libcurl4-gnutls-dev libgmp3-dev libncurses5-dev libsigsegv-dev libssl-dev libtool make openssl pkg-config python python3 python3-pip ragel re2c zlib1g-dev
179+sudo -H pip3 install --upgrade pip
180+sudo -H pip3 install meson==0.29
181+
182+# we need ninja 1.5.1
183+# 'apt-get install ninja-build' gives us 0.1.3
184+# 'apt-get install ninja-build' gives us 1.3.4
185+#
186+git clone git://github.com/ninja-build/ninja.git
187+pushd ninja
188+ git checkout release
189+ ./configure.py --bootstrap
190+ sudo cp ./ninja /usr/local/bin
191+popd
192+
193+
194+git clone https://github.com/urbit/urbit
195+cd urbit
196+./scripts/bootstrap
197+./scripts/build
198+sudo ninja -C ./build/ install
199+urbit
200+```
201+
202+#### Fedora
203+
204+```
205+# Bash
206+
207+sudo yum upgrade
208+sudo yum install autoconf automake cmake ctags gcc gcc-c++ git gmp-devel libcurl-devel libsigsegv-devel libtool ncurses-devel ninja-build openssl openssl-devel pkgconfig python2 python3 ragel re2c wget
209+
210+# meson requires python 3.5; RHEL supplies wrong version
211+pushd /usr/src
212+ sudo wget https://www.python.org/ftp/python/3.5.5/Python-3.5.5.tgz
213+ sudo tar xzf Python-3.5.5.tgz
214+ cd Python-3.5.5
215+ sudo ./configure --enable--optimizations
216+ sudo make altinstall
217+ which python3.5
218+ cd /usr/local/bin
219+ sudo ln -s python3.5 python3
220+ hash python3
221+popd
222+
223+curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
224+sudo /usr/local/bin/python3 get-pip.py
225+# downgrade meson to avoid dependencies that redhat can't meet
226+sudo -H /usr/local/bin/pip3 install meson==0.29
227+
228+
229+git clone git://github.com/ninja-build/ninja.git && cd ninja
230+git checkout release
231+./configure.py --boostrap
232+sudo cp ./ninja /usr/local/bin
233+
234+git clone https://github.com/urbit/urbit
235+cd urbit
236+./scripts/bootstrap
237+./scripts/build
238+sudo /usr/local/bin/ninja -C ./build/ install
239+urbit
240+```
241+
242+#### Arch Linux
243+
244+```
245+# Bash
246+
247+sudo pacman -Syu
248+sudo pacman -S autoconf automake cmake curl gcc git gmp libsigsegv libtool ncurses ninja openssl python ragel re2c
249+curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
250+sudo python3 get-pip.py
251+git clone https://github.com/urbit/urbit
252+cd urbit
253+./scripts/bootstrap
254+./scripts/build
255+sudo ninja -C ./build/ meson-install
256+urbit
257+```
258+
259+If you just want to use a fake ship for development purposes, you can now use
260+the command of the scheme below to boot a fake `~zod`.
261+
262+```
263+urbit -F zod -A /path/to/arvo -s -c zod
264+```
265+
266+If you want to get on the Arvo network with your point, then continue to the
267+next section.
268+
269+
270+;=
271+ ;h2
272+ ;div(id "boot"): Booting Your Ship
273+ ==
274+==
275+
276+
277+Now the rubber meets the road. You'll be booting your ship with the keyfile
278+that you downloaded from Bridge.
279+
280+#### Step 1: Find Your Point's Name
281+
282+This will look something like `~lodleb-ritrul`. You can see the name of your
283+point(s) when you log into your wallet using the Bridge client.
284+
285+;img@"http://media.urbit.org/site/bridge-0.png"(width "100%");
286+
287+#### Step 2: Find the path to your keyfile
288+
289+Find the absolute path to the keyfile that you downloaded from Bridge. Copy it.
290+
291+#### Step 3: Run the boot command
292+
293+Type `cd` in your terminal to return to your home directory. If you want to
294+store your ship somewhere besides your home directory, change the terminal's
295+working directory to the desired directory.
296+
297+Run the command below, except with `~sample-planet` replaced by the name of your
298+Urbit identity, and `path/to/my-planet.key` replaced with the path to your
299+keyfile:
300+
301+```
302+urbit -w ~sample-planet -k path/to/my-planet.key
303+```
304+
305+if you'd prefer to copy your key in you can run
306+
307+```
308+urbit -w ~sample-planet -G rAnDoMkEy
309+```
310+
311+
312+This will create a directory called `sample-planet/` and begin building your
313+ship. It may take a few minutes.
314+
315+When your ship is finished booting, you will see the `~sample-planet:dojo>`
316+prompt. At that point, you should permanently erase your keyfile from your
317+machine.
318+
319+;=
320+ ;h2
321+ ;div(id "operation"): Basic Operations
322+ ==
323+==
324+
325+Welcome to your urbit! There's a few things you should do to become oriented.
326+
327+#### Dojo
328+
329+Let's try out the Dojo, the Arvo command line and Hoon REPL:
330+
331+```
332+~sample-planet:dojo> (add 2 2)
333+```
334+
335+Should produce:
336+
337+```
338+> (add 2 2)
339+4
340+```
341+
342+Good.
343+
344+#### Mounting
345+
346+Clay, the Arvo filesystem, isn't mounted to Unix by default. Switch to the Dojo
347+prompt and run:
348+
349+```
350+~sample-planet:dojo> |mount %
351+```
352+
353+This should produce:
354+```
355+> |mount %
356+>=
357+```
358+
359+which indicates that the command was processed.
360+
361+`|mount %` will cause a `home/` directory to appear inside your _pier_ folder in
362+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.
363+
364+
365+#### Talk
366+
367+Use `ctrl-x` to toggle between the Dojo and the Talk prompts.
368+
369+While on the Talk prompt, let's join the main Urbit support chat channel, `/urbit-help`:
370+
371+```
372+~sample-planet:talk[] ;join /urbit-help
373+```
374+
375+Talk is stateful, so your ship will download a backlog. `/urbit-help` is the
376+place to ask questions about getting up and running.
377+
378+#### Shutting Down and Restarting
379+
380+You can turn your ship off with `ctrl-d` from the Talk or Dojo prompts.
381+
382+To restart your ship, simply pass the name of your pier:
383+
384+```
385+$ urbit some-planet
386+```