@@ -0,0 +1,355 @@
1+:- :~ title/'Installation'
2+ preview/'Want to get Urbit running? Look here.'
8+This guide is broken into five parts:
10++ [Acquiring an Urbit Identity](#acquire)
11++ [Using Bridge](#bridge)
12++ [Installing Arvo](#arvo)
13++ [Booting Your Ship](#setup)
14++ [Basic Operations](#operation)
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)._
22+ ;div(id "acquire"): Acquiring an Urbit Identity
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.
31+Throughout this guide, we’ll refer to "Urbit identities" and "points"
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
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.
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.
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
51+Your ownership PDF contains two secrets that must be kept safe.""
53+- *Master Ticket*: This is a master key that allows you to manage every aspect of
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*
62+ ;div(id "bridge"): Using Bridge
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
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.
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.
82+ ;div(id "arvo"): Installing Arvo
86+Now you’re ready to install the Arvo software. You’re almost there!
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.
92+We have different installation instructions for different platforms. To install
93+Arvo, run the Bash commands that are listed for your operating system.
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
100+Urbit: a personal server operating function
105+We recommend using the Homebrew package manager to install Arvo on MacOS.
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
116+sudo ninja -C ./build/ meson-install
120+##### Ubuntu or Debian
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
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
134+git clone git://github.com/ninja-build/ninja.git
136+ git checkout release
137+ ./configure.py --bootstrap
138+ sudo cp ./ninja /usr/local/bin
142+git clone https://github.com/urbit/urbit
146+sudo ninja -C ./build/ install
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
158+# meson requires python 3.5; RHEL supplies wrong version
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
163+ sudo ./configure --enable--optimizations
164+ sudo make altinstall
167+ sudo ln -s python3.5 python3
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
177+git clone git://github.com/ninja-build/ninja.git && cd ninja
179+./configure.py --boostrap
180+sudo cp ./ninja /usr/local/bin
182+git clone https://github.com/urbit/urbit
186+sudo /usr/local/bin/ninja -C ./build/ install
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
203+sudo ninja -C ./build/ meson-install
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`.
211+urbit -F zod -A /path/to/arvo -s -c zod -S
214+If you want to get on the Arvo network with your point, then continue to the
219+ ;div(id "boot"): Booting Your Urbit
223+Now the rubber meets the road. You’ll be booting your ship with the key-file
224+that you downloaded from bridge.
226+##### Step 1: Find Your Point's Name
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.
231+;img@"media.urbit.org/site/bridge-0.png"(width "100%");
233+##### Step 2: Find the path to your key-file
235+Find the absolute path to the key-file that you downloaded from Bridge. Copy it.
237+##### Step 3: Run the boot command
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.
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
248+urbit -w ~sample-planet -k path/to/my-planet.key
251+This will create a directory called `sample-planet/` and begin building your
252+ship. It may take a few minutes.
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
260+ ;div(id "operation"): Basic Operations
264+Welcome to your urbit! There's a few things you should do to become oriented.
268+Let’s try out the Dojo, the Arvo command line and Hoon REPL:
271+~sample-planet:dojo> (add 2 2)
285+Clay, the Arvo filesystem, isn't mounted to Unix by default. Switch to the Dojo
289+~sample-planet:dojo> |mount %
298+which indicates that the command was processed.
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.
306+Use `ctrl-x` to toggle between the Dojo and the Talk prompts.
308+While on the Talk prompt, let’s join the main Urbit chat channel, `/urbit-meta`:
311+~sample-planet:talk[] ;join /urbit-meta
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
318+##### Shutting Down and Restarting
320+You can turn your ship off with `ctrl-d` from the Talk or Dojo prompts.
322+To restart your ship, simply pass the name of your pier:
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
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.
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.
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
354+When you use the web interface, your urbit is automatically subscribed to
355+`/urbit-meta` and Fora, our message-board system.