@@ -0,0 +1,355 @@
1+:- :~ title/'Installation'
2+ preview/'Want to get Urbit running? Look here.'
3+ ==
4+;>
5+
6+# Installation
7+
8+This guide is broken into five parts:
9+
10++ [Acquiring an Urbit Identity](#acquire)
11++ [Using Bridge](#bridge)
12++ [Installing Arvo](#arvo)
13++ [Booting Your Ship](#setup)
14++ [Basic Operations](#operation)
15+
16+_If you just want to install the Urbit OS, Arvo, and don’t need to be on the
17+Urbit network, you can skip to [Installing Arvo](#arvo)._
18+
19+
20+;=
21+ ;h3
22+ ;div(id "acquire"): Acquiring an Urbit Identity
23+ ==
24+==
25+
26+Urbit’s identity layer, called Azimuth, is a suite of contracts on the Ethereum
27+blockchain. An Azimuth address, called a *point*, functions as an identity and
28+a network address for Arvo, the Urbit OS. An instance of Arvo is called a
29+*ship*. A ship can't use the Arvo network until it's combined with a point.
30+
31+Throughout this guide, we’ll refer to "Urbit identities" and "points"
32+interchangeably.
33+
34+Points are generally not freely available, so you will need to either
35+purchase one or get one from a friend. This guide assumes you have found a way
36+to acquire a point.
37+
38+To get Urbit address space, you’ll need two things: an Ethereum address and a
39+person willing to send you the Urbit address space.
40+
41+You’ll probably want to start with a planet. Those are cheap identities for
42+everyday use. Find someone who is willing to part with a point: a friend or a
43+stranger selling address space via smart contract. Once they’ve sent the address
44+space, you can access it using our Bridge software, or any other interface for
45+the Ethereum blockchain.
46+
47+If you bought address space from Tlon, then you should have have received a .zip
48+file that contains an Ethereum address and cryptographic secrets in
49+the form of a PDF.
50+
51+Your ownership PDF contains two secrets that must be kept safe.""
52+
53+- *Master Ticket*: This is a master key that allows you to manage every aspect of
54+ your address.
55+
56+- *Ownership Seed BIP39 Mnemonic*: The master ticket encoded as a BIP39 mnemonic
57+ for compatibility with most Ethereum wallet software, including our own *Bridge*
58+ client.
59+
60+;=
61+ ;h3
62+ ;div(id "bridge"): Using Bridge
63+ ==
64+==
65+
66+Bridge is client that we built for accessing and managing your Urbit identities.
67+Like Wallet Generator, Bridge comes in the form of an offline HTML application
68+that can be run in Firefox on all platforms, and also in Chrome if you’re using
69+a Mac.
70+
71+Importantly, Bridge also automates the process of generating the key-file that
72+you will need a single time to boot your ship on the Arvo network. Once a ship
73+is booted, it isn’t booted again. It stays booted forever.
74+
75+Download bridge [here](https://github.com/urbit/bridge/releases). It runs in
76+your browser contains instructions to get the key that you need to boot your
77+urbit. We recommend using the "BIP39 Mnemonic" method to access your wallet.
78+
79+
80+;=
81+ ;h3
82+ ;div(id "arvo"): Installing Arvo
83+ ==
84+==
85+
86+Now you’re ready to install the Arvo software. You’re almost there!
87+
88+Arvo can only run on a Unix-like operating system -- Ubuntu,
89+Fedora, macOS, and FreeBSD all work well. If you’re using Windows, you’ll need
90+to get one of the aforementioned systems. Don’t worry: most of them are free.
91+
92+We have different installation instructions for different platforms. To install
93+Arvo, run the Bash commands that are listed for your operating system.
94+
95+On any platform, you can check your Arvo installation by running the `urbit`
96+command. Installation was successful if you get a block of output that begins
97+with the line below:
98+
99+```
100+Urbit: a personal server operating function
101+```
102+
103+##### MacOS
104+
105+We recommend using the Homebrew package manager to install Arvo on MacOS.
106+
107+```
108+#Bash
109+
110+brew update
111+brew install autoconf automake cmake gcc git gmp libsigsegv libtool meson ninja pkg-config python2 openssl re2c
112+git clone https://github.com/urbit/urbit
113+cd urbit
114+./scripts/bootstrap
115+./scripts/build
116+sudo ninja -C ./build/ meson-install
117+urbit
118+```
119+
120+##### Ubuntu or Debian
121+
122+```
123+# Bash
124+
125+sudo apt-get update
126+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
127+sudo -H pip3 install --upgrade pip
128+sudo -H pip3 install meson==0.29
129+
130+# we need ninja 1.5.1
131+# 'apt-get install ninja-build' gives us 0.1.3
132+# 'apt-get install ninja-build' gives us 1.3.4
133+#
134+git clone git://github.com/ninja-build/ninja.git
135+pushd ninja
136+ git checkout release
137+ ./configure.py --bootstrap
138+ sudo cp ./ninja /usr/local/bin
139+popd
140+
141+
142+git clone https://github.com/urbit/urbit
143+cd urbit
144+./scripts/bootstrap
145+./scripts/build
146+sudo ninja -C ./build/ install
147+urbit
148+```
149+
150+##### Fedora
151+
152+```
153+# Bash
154+
155+sudo yum upgrade
156+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
157+
158+# meson requires python 3.5; RHEL supplies wrong version
159+pushd /usr/src
160+ sudo wget https://www.python.org/ftp/python/3.5.5/Python-3.5.5.tgz
161+ sudo tar xzf Python-3.5.5.tgz
162+ cd Python-3.5.5
163+ sudo ./configure --enable--optimizations
164+ sudo make altinstall
165+ which python3.5
166+ cd /usr/local/bin
167+ sudo ln -s python3.5 python3
168+ hash python3
169+popd
170+
171+curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
172+sudo /usr/local/bin/python3 get-pip.py
173+# downgrade meson to avoid dependencies that redhat can't meet
174+sudo -H /usr/local/bin/pip3 install meson==0.29
175+
176+
177+git clone git://github.com/ninja-build/ninja.git && cd ninja
178+git checkout release
179+./configure.py --boostrap
180+sudo cp ./ninja /usr/local/bin
181+
182+git clone https://github.com/urbit/urbit
183+cd urbit
184+./scripts/bootstrap
185+./scripts/build
186+sudo /usr/local/bin/ninja -C ./build/ install
187+urbit
188+```
189+
190+##### Arch Linux
191+
192+```
193+# Bash
194+
195+sudo pacman -Syu
196+sudo pacman -S autoconf automake cmake curl gcc git gmp libsigsegv libtool ncurses ninja openssl python ragel re2c
197+curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
198+sudo python3 get-pip.py
199+git clone https://github.com/urbit/urbit
200+cd urbit
201+./scripts/bootstrap
202+./scripts/build
203+sudo ninja -C ./build/ meson-install
204+urbit
205+```
206+
207+If you just want to use a fake ship for development purposes, you can now use
208+the command of the scheme below to boot a fake `~zod`.
209+
210+```
211+urbit -F zod -A /path/to/arvo -s -c zod -S
212+```
213+
214+If you want to get on the Arvo network with your point, then continue to the
215+next section.
216+
217+;=
218+ ;h3
219+ ;div(id "boot"): Booting Your Urbit
220+ ==
221+==
222+
223+Now the rubber meets the road. You’ll be booting your ship with the key-file
224+that you downloaded from bridge.
225+
226+##### Step 1: Find Your Point's Name
227+
228+This will look something like `~lodleb-ritrul`. You can see the name of your
229+point(s) when you log into your wallet using the Bridge client.
230+
231+;img@"media.urbit.org/site/bridge-0.png"(width "100%");
232+
233+##### Step 2: Find the path to your key-file
234+
235+Find the absolute path to the key-file that you downloaded from Bridge. Copy it.
236+
237+##### Step 3: Run the boot command
238+
239+Type `cd` in your terminal to return to your home directory. If you want to
240+store your ship somewhere besides your home directory, change the terminal’s
241+working directory to the desired directory.
242+
243+Run the command below, except with `~sample-planet` replaced by the name of your
244+Urbit identity, and `path/to/my-planet.key` replaced with the path to your
245+key-file:
246+
247+```
248+urbit -w ~sample-planet -k path/to/my-planet.key
249+```
250+
251+This will create a directory called `sample-planet/` and begin building your
252+ship. It may take a few minutes.
253+
254+When your ship is finished booting, you will see the `~sample-planet:dojo>`
255+prompt. At that point, you should permanently erase your key-file from your
256+machine.
257+
258+;=
259+ ;h3
260+ ;div(id "operation"): Basic Operations
261+ ==
262+==
263+
264+Welcome to your urbit! There's a few things you should do to become oriented.
265+
266+##### Dojo
267+
268+Let’s try out the Dojo, the Arvo command line and Hoon REPL:
269+
270+```
271+~sample-planet:dojo> (add 2 2)
272+```
273+
274+Should produce:
275+
276+```
277+> (add 2 2)
278+4
279+```
280+
281+Good.
282+
283+##### Mounting
284+
285+Clay, the Arvo filesystem, isn't mounted to Unix by default. Switch to the Dojo
286+prompt and run:
287+
288+```
289+~sample-planet:dojo> |mount %
290+```
291+
292+This should produce:
293+```
294+> |mount %
295+>=
296+```
297+
298+which indicates that the command was processed.
299+
300+`|mount %` will cause a `home/` directory to appear inside your _pier_ folder in
301+Unix. Changes to these files are automatically synced into your ship.
302+
303+
304+##### Talk
305+
306+Use `ctrl-x` to toggle between the Dojo and the Talk prompts.
307+
308+While on the Talk prompt, let’s join the main Urbit chat channel, `/urbit-meta`:
309+
310+```
311+~sample-planet:talk[] ;join /urbit-meta
312+```
313+
314+Talk is stateful, so your ship will download a backlog. `/urbit-meta` is the
315+place to ask questions, get help, talk about anything Urbit-related, and meet
316+everyone on here.
317+
318+##### Shutting Down and Restarting
319+
320+You can turn your ship off with `ctrl-d` from the Talk or Dojo prompts.
321+
322+To restart your ship, simply pass the name of your pier:
323+
324+```
325+$ urbit some-planet
326+```
327+
328+##### Landscape
329+
330+Your ship is also accessible through its own web interface. Through the web
331+interface you’ll have access to our chat and message boards, the two components
332+of our "Landscape" feature. This is a user-friendly way to chat with Talk on the
333+Arvo network and access and materials you’ve published on your ship. If You're
334+running Arvo locally on your own machine, try opening `http://localhost/` in
335+your browser.
336+
337+Or if you're running your ship on a cloud instance with a static IP address
338+(which we recommend!), something like 212.131.240.20, assuming you've opened up
339+the HTTP port that Arvo uses -- the default is port 80. So
340+`http://212.131.240.20:80/~~/` would go into your browser's URL bar.
341+
342+This way, if you keep your ship running securely in the cloud (usually in a
343+screen or tmux session), you can always access your ships's web interface in any
344+browser on any device, so long as you have your password on hand.
345+
346+The `/~~/` in the URL will redirect you to a login page, which was generated by
347+Tree, the basic Arvo web interface. The page will tell you to run the +code
348+generator (an Arvo shell script) in your Dojo to get your password. Copy and
349+paste that into your password input box and hit Enter. After loading, you'll
350+find yourself redirected to your home page, authenticated, where you can then
351+use the navigation bar at the top of the page to visit your Talk web interface
352+and static files.
353+
354+When you use the web interface, your urbit is automatically subscribed to
355+`/urbit-meta` and Fora, our message-board system.