@@ -7,443 +7,36 @@
77
88# Getting Started
99
10−This guide is broken into five parts:
10+Pages in this section are guides to getting you started with Urbit.
1111
12−+ [Urbit Identities](#acquire)
13−+ [Using Bridge](#bridge)
14−+ [Installing Arvo](#arvo)
15−+ [Booting Your Ship](#boot)
16−+ [Basic Operations](#operation)
12+But first, the absolute basics. Arvo is the name of the Urbit operating system and the name of network. Azimuth is the name of the Urbit identity layer. Urbit is the project as the whole.
1713
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)._
14+An instance of the Arvo operating system is called a _ship_. If you want to get on the Arvo network, you need an Azimuth identity, called a _point_.
2015
21−;=
22− ;h2
23− ;div(id "acquire"): Urbit Identities
24− ==
25−==
16+## Urbit Identities
2617
27−Urbit's identity layer, called Azimuth, is a public-key infrastructure (PKI)
28−that uses the Ethereum blockchain. An Azimuth address, called a point,
29−functions as an identity and
30−a network address for Arvo, the Urbit OS. An instance of Arvo is called a
31−*ship*. A ship can't use the Arvo network unless it's been booted with the keys
32−registered to a point.
18+An Azimuth point functions as an identity and a network address for Arvo. A ship can't use the Arvo network unless it's been booted with the keys registered to a point.
3319
34−Throughout this guide, we'll refer to \"Urbit identities\" and \"points\"
35−interchangeably.
20+Points are generally not freely available, so you will need to either purchase one or get one from a friend. To receive one, you will need an Ethereum wallet that supports the BIP39 mnemonic seed functionality, which allows you to access your wallet with a series of dictionary words. Hardware wallets, such as Ledger and TREZOR devices, satisfy this requirement. So do various web-based wallets.
3621
37−Points are generally not freely available, so you will need to either
38−purchase one or get one from a friend. To receive one, you will need an Ethereum
39−wallet that supports the BIP39 mnemonic seed functionality, which allows you to
40−access your wallet with a series of dictionary words.
41−Hardware wallets, such as Ledger and TREZOR devices, satisfy this requirement.
42−So do various web-based wallets.
22+Once you have such a wallet, give your Ethereum address to the person who agreed to give you a point. Have them transfer the point to your address, and continue to the with our guides below.
4323
44−Once you have such a wallet, give your Ethereum address to the person who agreed
45−to give you a point. Have them transfer the point to your address, and continue to the
46−next section.
24+## Guides
4725
48−;=
49− ;h2
50− ;div(id "bridge"): Using Bridge
51− ==
52−==
26+Follow these guides in the order that they are listed.
5327
54−Bridge is a client for accessing and managing your Urbit identities.
55−Importantly, Bridge also allows you to generate a keyfile that you will need to
56−boot your ship so that it can use the Arvo network. Once you boot a ship
57−with a keyfile, you can restart it later without the keyfile.
28+### [Using Bridge](azimuth)
5829
59−*Note:* Bridge allows you to make _writes_ to the blockchain, but we ask you to confirm
60−anything that will incur a transaction cost. If you plan to do anything heavy-duty, make
61−sure your Ethereum address has some pocket ETH.
30+Bridge is our client for managing Azimuth points. This guide will tell you how to use it to get your point's _keyfile_, the item you need to boot your ship booted onto the Arvo network.
6231
63−Download Bridge [here](https://github.com/urbit/bridge/releases), and follow
64−the instructions to run that program. Get a little bit of ETH on your address,
65−enough for a couple of transactions.
32+### [Installing Urbit](installing-urbit)
6633
67−Once the program is running in your browser, go through each step according to
68−what kind of wallet you have.
34+This guide will tell you everything you need to know about installing our software.
6935
70−### Accept Your Transfer
36+### [Booting a Ship](booting-a-ship)
7137
72−After you access your Ethereum address, if a point was sent to that address,
73−you'll come to a page that has an `Incoming Transfers` header, under which is
74−a graphic. Click the `Details ->` link under that graphic.
38+This guide will walk you through the process of getting your ship operational and on the Arvo network.
7539
76−Now you'll be on the management page of your point. The transfer isn't completed
77−yet, so click `Accept incoming transfer`. Then check both boxes and and click
78−their associated `Sign Transaction` and `Send Transaction` buttons.
40+### [Creating a Development Ship](creating-a-development-ship)
7941
80−If you already own a point, then click on the `Details ->` under your sigil in the
81−`Your Points` section.
82−
83−### Set Your Networking Keys
84−
85−If you just accepted a point, you'll be returned to your point screen. Notice that
86−that links and buttons are now clickable. You now own this point!
87−
88−Click the link that says `Set Urbit networking keys`. The field that is presented
89−in the resulting page expects a 32-byte hexadecimal string; you can generate
90−this data any way you please, but in the terminal on MacOS or Linux, you can write
91−
92−```
93−hexdump -n 32 -e '4/4 "%08X"' /dev/random
94−```
95−
96−and use the result.
97−
98−It should be noted that setting your network keys is an event on the Ethereum network,
99−and will therefore cost a trivial, but non-zero, amount of
100−[gas](https://github.com/ethereum/wiki/wiki/Design-Rationale#gas-and-fees) to complete.
101−
102−### Generate Your Keyfile
103−
104−From the detail page associated with your point, click the `Generate Arvo Keyfile`
105−link and you'll be taken to a page with a field titled `Network seed`. This
106−field should already be filled in, and should match the hexadecimal string that you
107−entered in the previous step. If its not filled in or does not match, fill it in
108−with the correct string.
109−
110−Click `Generate ->`, which will download a keyfile onto your machine.
111−
112−With that keyfile in hand, you can now exit Bridge.
113−
114−;=
115− ;h2
116− ;div(id "arvo"): Installing Arvo
117− ==
118−==
119−
120−Now you're ready to run Arvo. You're almost there!
121−
122−But first, some terminology:
123−- `vere` or `urbit`: the interpreter that runs when you run a command like `urbit` or `/bin/urbit` in your command line
124−- `arvo`: the deterministic OS that lives in a directory whose name matches your Azimuth point, ie `~famreb-todmec` lives in `/famreb-todmec`
125−
126−Arvo runs nicely on a Unix-like operating system -- Ubuntu,
127−Fedora, macOS, and FreeBSD, for example. If you're using Windows, you'll need
128−to get one of the aforementioned systems. Don't worry: most of them are free.
129−
130−We have different installation instructions for different platforms. To install
131−and run Arvo, run the commands that are listed for your operating system.
132−
133−On any platform, you can check your Arvo installation by running the `urbit`
134−command. Installation was successful if you get a block of output that begins
135−with the line below:
136−
137−```
138−Urbit: a personal server operating function
139−```
140−
141−### Dependencies
142−
143−Urbit depends on:
144−
145−
146−```
147−C compiler (gcc or clang)
148−curses
149−git
150−gmp
151−libcurl
152−libsigsegv
153−libuv
154−meson
155−ninja
156−openssl
157−pkg-config
158−python2
159−zlib
160−```
161−
162−### Instructions
163−
164−#### MacOS
165−
166−We recommend using the Homebrew package manager to run Arvo on MacOS.
167−
168−```
169−# Bash
170−
171−brew update
172−brew install gcc git gmp libsigsegv libtool meson ninja pkg-config python2 openssl
173−git clone https://github.com/urbit/urbit
174−cd urbit
175−./scripts/bootstrap
176−./scripts/build
177−sudo ninja -C ./build/ meson-install
178−urbit
179−```
180−
181−#### Ubuntu or Debian
182−
183−```
184−# Bash
185−
186−sudo apt-get update
187−sudo apt-get install g++ git libcurl4-gnutls-dev libgmp3-dev libncurses5-dev libsigsegv-dev libssl-dev make openssl pkg-config python python3 python3-pip zlib1g-dev ninja-build
188−sudo -H pip3 install --upgrade pip
189−sudo -H pip3 install meson
190−
191−git clone https://github.com/urbit/urbit
192−cd urbit
193−./scripts/bootstrap
194−./scripts/build
195−sudo ninja -C ./build/ install
196−urbit
197−```
198−
199−#### Fedora
200−
201−```
202−# Bash
203−
204−sudo yum upgrade
205−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
206−
207−# meson requires python 3.5; RHEL supplies wrong version
208−pushd /usr/src
209− sudo wget https://www.python.org/ftp/python/3.5.5/Python-3.5.5.tgz
210− sudo tar xzf Python-3.5.5.tgz
211− cd Python-3.5.5
212− sudo ./configure --enable--optimizations
213− sudo make altinstall
214− which python3.5
215− cd /usr/local/bin
216− sudo ln -s python3.5 python3
217− hash python3
218−popd
219−
220−curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
221−sudo /usr/local/bin/python3 get-pip.py
222−# downgrade meson to avoid dependencies that redhat can't meet
223−sudo -H /usr/local/bin/pip3 install meson
224−
225−
226−git clone git://github.com/ninja-build/ninja.git && cd ninja
227−git checkout release
228−./configure.py --boostrap
229−sudo cp ./ninja /usr/local/bin
230−
231−git clone https://github.com/urbit/urbit
232−cd urbit
233−./scripts/bootstrap
234−./scripts/build
235−sudo /usr/local/bin/ninja -C ./build/ install
236−urbit
237−```
238−
239−#### Arch Linux
240−
241−```
242−# Bash
243−
244−sudo pacman -Syyu
245−sudo pacman -S --needed curl gcc git gmp libsigsegv ncurses ninja openssl python python-pip meson
246−git clone https://github.com/urbit/urbit
247−cd urbit
248−./scripts/bootstrap
249−./scripts/build
250−cd build
251−ninja
252−sudo ninja meson-install
253−urbit
254−```
255−
256−#### FreeBSD
257−
258−```
259−# Bash or Sh
260−
261−pkg upgrade
262−sudo pkg install curl gcc git gmake gmp libsigsegv python python3 ncurses openssl gmp
263−curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
264−sudo python3 get-pip.py
265−sudo -H pip install --upgrade pip
266−sudo -H pip install meson
267−sudo pkg install ninja
268−git clone https://github.com/urbit/urbit
269−cd urbit
270−sh ./scripts/bootstrap
271−sh ./scripts/build
272−sudo ninja -C ./build/ meson-install
273−urbit
274−```
275−
276−#### Amazon Web Services
277−
278−```
279−# Bash
280−
281−sudo yum update
282−sudo yum install gcc gcc-c++ git gmp-devel libcurl-devel libsigsegv-devel ncurses-devel openssl openssl-devel pkgconfig python2 python3 python3-pip wget git
283−sudo env "PATH=$PATH" pip3 install --upgrade pip
284−sudo env "PATH=$PATH" pip3 install meson
285−
286−
287−# we need libsigsegv
288−#
289−
290−wget http://dl.fedoraproject.org/pub/fedora/linux/releases/25/Everything/x86_64/os/Packages/l/libsigsegv-2.10-10.fc24.x86_64.rpm
291−wget http://dl.fedoraproject.org/pub/fedora/linux/releases/25/Everything/x86_64/os/Packages/l/libsigsegv-devel-2.10-10.fc24.x86_64.rpm
292−sudo yum localinstall libsigsegv-2.10-10.fc24.x86_64.rpm
293−sudo yum localinstall libsigsegv-devel-2.10-10.fc24.x86_64.rpm
294−
295−git clone git://github.com/ninja-build/ninja.git
296−pushd ninja
297− git checkout release
298− ./configure.py --bootstrap
299− sudo cp ./ninja /usr/local/bin
300−popd
301−
302−
303−git clone https://github.com/urbit/urbit
304−cd urbit
305−./scripts/bootstrap
306−./scripts/build
307−sudo env "PATH=$PATH" ninja -C ./build/ install
308−
309−urbit
310−```
311−
312−### Using a Fake Ship
313−
314−Perhaps you want to boot a ship without an identity. We recommend doing that
315−for development purposes, or if you just want to play around with an
316−un-networked ship without getting a point. You can now use
317−the command of the scheme below to boot a fake `~zod`.
318−
319−```
320−urbit -F zod
321−```
322−
323−If you want to get on the Arvo network with your point, then continue to the
324−next section.
325−
326−;=
327− ;h3
328− ;div(id "swap"): Set Up Swap
329− ==
330−==
331−
332−If you're running Urbit in the cloud on a small instance, you may need to additionally configure swap space. If you're not, skip this section.
333−
334−Urbit wants to map 2GB of memory when it boots up. We won’t necessarily use all this memory, we just want 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.
335−
336−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).
337−
338−Don’t spend a lot of time tweaking these settings; the simplest thing is fine.
339−
340−;=
341− ;h2
342− ;div(id "boot"): Booting Your Ship
343− ==
344−==
345−
346−
347−Now the rubber meets the road. You'll be booting your ship with the keyfile
348−that you downloaded from Bridge.
349−
350−### Step 1: Find Your Point's Name
351−
352−This will look something like `~lodleb-ritrul`. You can see the name of your
353−point(s) when you log into your wallet using the Bridge client.
354−
355−;img@"http://media.urbit.org/site/bridge-0.png"(width "100%");
356−
357−### Step 2: Find the path to your keyfile
358−
359−Find the absolute path to the keyfile that you downloaded from Bridge. Copy it.
360−
361−### Step 3: Run the boot command
362−
363−Type `cd` in your terminal to return to your home directory. If you want to
364−store your ship somewhere besides your home directory, change the terminal's
365−working directory to the desired directory.
366−
367−Run the command below, except with `~sample-planet` replaced by the name of your
368−Urbit identity, and `path/to/my-planet.key` replaced with the path to your
369−keyfile:
370−
371−```
372−urbit -w ~sample-planet -k path/to/my-planet.key
373−```
374−
375−Or, if you'd prefer to copy your key in, you can run:
376−
377−```
378−urbit -w ~sample-planet -G rAnDoMkEy
379−```
380−
381−Either command will create a directory called `sample-planet/` and begin
382−building your ship. It may take a few minutes.
383−
384−When your ship is finished booting, you will see the `~sample-planet:dojo>`
385−prompt. At that point, you should permanently erase your keyfile from your
386−machine.
387−
388−;=
389− ;h2
390− ;div(id "operation"): Basic Operations
391− ==
392−==
393−
394−Welcome to your urbit! There's a few things you should do to become oriented.
395−
396−### Dojo
397−
398−Let's try out the Dojo, the Arvo command line and Hoon REPL:
399−
400−```
401−~sample-planet:dojo> (add 2 2)
402−```
403−
404−Should produce:
405−
406−```
407−> (add 2 2)
408−4
409−```
410−
411−Good.
412−
413−### Mounting
414−
415−Clay, the Arvo filesystem, isn't mounted to Unix by default. Switch to the Dojo
416−prompt and run:
417−
418−```
419−~sample-planet:dojo> |mount %
420−```
421−
422−This should produce:
423−```
424−> |mount %
425−>=
426−```
427−
428−which indicates that the command was processed.
429−
430−`|mount %` will cause a `home/` directory to appear inside your _pier_ folder in
431−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.
432−
433−### Landscape
434−
435−Landscape is web app we built for chatting and making posts on the Urbit network using the Hall messaging protocol. In the future we plan to use Landscape to run a few experimental "cities" -- private discussion communities -- as a closed beta of sorts. If you have an Azimuth point and you'd like to be involved, let us know [by email](mailto:support@urbit.org).
436−
437−### urbit-help
438−
439−If you've successfully booted your Urbit, you can access a support channel we run on the network at `~dopzod/urbit-help`. To join, type `ctrl-x` in your ship's terminal window to toggle between the Dojo and the Talk prompts, then enter the command `;join ~dopzod/urbit-help`.
440−
441−### Shutting Down and Restarting
442−
443−You can turn your ship off with `ctrl-d` from the Talk or Dojo prompts.
444−
445−To restart your ship, simply pass the name of your pier:
446−
447−```
448−$ urbit some-planet
449−```
42+If you just want to do development work with Arvo, and don't need to be on the Urbit network, this section is for you.