@@ -0,0 +1,240 @@
1+# Urbit
2+
3+Urbit is a clean-slate system software stack defined as a deterministic
4+computer. An encrypted P2P network, `%ames`, runs on a functional
5+operating system, Arvo, written in a strict, typed functional language,
6+Hoon, which compiles itself to a combinator interpreter, Nock, whose
7+spec gzips to 340 bytes.
8+
9+What is this for? Most directly, Urbit is designed as a personal cloud
10+server for self-hosted web apps. It also uses HTTP APIs to manage data
11+stuck in traditional web applications.
12+
13+More broadly, Urbit's network tackles identity and security problems
14+which the Internet can't easily address. Programming for a deterministic
15+single-level store is also a different experience from Unix programming,
16+regardless of language.
17+
18+## Getting involved
19+
20+If you're interested in following Urbit, you can:
21+
22+- Read our documentation at [urbit.org](http://urbit.org/docs)
23+- Subscribe to our newsletter at [urbit.org](http://urbit.org).
24+- Check out the
25+ [urbit-dev](https://groups.google.com/forum/#!forum/urbit-dev)
26+ mailing list.
27+- Follow [@urbit\_](https://twitter.com/urbit_) on Twitter.
28+- Email us: [`urbit@urbit.org`](mailto:urbit@urbit.org). We're happy
29+ to answer questions and chat.
30+
31+## Code of conduct
32+
33+Everyone involved in the Urbit project needs to understand and respect
34+our code of conduct, which is: "don't be rude."
35+
36+# Install
37+
38+Urbit can be installed on most Unix systems. There is no Windows port.
39+Windows is a wonderful OS, we just haven't gotten to it yet. Use a VM.
40+
41+## Configure swap if needed
42+
43+Urbit wants to map 2GB of memory when it boots up. We won't necessarily
44+use all this memory, we just want to see it. On a normal modern PC or
45+Mac, this is not an issue. On some small cloud virtual machines (Amazon
46+or Digital Ocean), the default memory configuration is smaller than
47+this, and you need to manually configure a swapfile.
48+
49+To add swap to a DO droplet, [read
50+this](https://www.digitalocean.com/community/tutorials/how-to-add-swap-on-ubuntu-14-04).
51+To add swap on an Amazon instance, [read
52+this](http://stackoverflow.com/questions/17173972/how-do-you-add-swap-to-an-ec2-instance)
53+
54+Don't spend a lot of time tweaking these settings; the simplest thing is
55+fine.
56+
57+## Install as a package
58+
59+<!--
60+waiting on makefile changes.
61+### OS X - Homebrew
62+
63+ brew install --HEAD homebrew/head-only/urbit
64+-->
65+
66+### Ubuntu or Debian
67+
68+Third-party packages are available, at:
69+
70+ https://github.com/yebyen/urbit-deb
71+
72+Urbit is only supported on Jessie onward (but outbound HTTPS requests
73+only work on Stretch; I wish we knew why; help us!)
74+
75+## Hand-build from source
76+
77+First, install all external dependencies. Then, make.
78+
79+### Dependencies
80+
81+urbit depends on:
82+
83+ gcc (or clang)
84+ gmp
85+ libsigsegv
86+ openssl
87+ automake
88+ autoconf
89+ ragel
90+ cmake
91+ re2c
92+ libtool
93+ libssl-dev (Linux only)
94+ ncurses (Linux only)
95+
96+#### Ubuntu or Debian
97+
98+ sudo apt-get install libgmp3-dev libsigsegv-dev openssl libssl-dev libncurses5-dev git make exuberant-ctags automake autoconf libtool g++ ragel cmake re2c
99+
100+#### Fedora
101+
102+ sudo dnf install gcc gcc-c++ git gmp-devel openssl-devel openssl ncurses-devel libsigsegv-devel ctags automake autoconf libtool ragel cmake re2c
103+
104+#### AWS
105+
106+ sudo yum --enablerepo epel install gcc gcc-c++ git gmp-devel openssl-devel ncurses-devel libsigsegv-devel ctags automake autoconf libtool cmake re2c
107+
108+#### OS X - Homebrew
109+
110+ brew install git gmp libsigsegv openssl libtool autoconf automake cmake
111+
112+#### OS X - Macports
113+
114+ sudo port install git gmp libsigsegv openssl autoconf automake cmake
115+
116+Although `automake`/`autoconf`/`libtool` are generally installed by
117+default, some have reported needing to uninstall and reinstall those
118+three packages, at least with Homebrew. Your mileage may vary.
119+
120+#### FreeBSD
121+
122+ pkg install git gmake gmp libsigsegv openssl automake autoconf ragel cmake re2c libtool
123+
124+#### Archlinux
125+
126+ pacman -S gcc gmp libsigsegv openssl automake autoconf ragel cmake re2c libtool ncurses
127+
128+### Download and make
129+
130+Clone the repo:
131+
132+ git clone https://github.com/urbit/urbit.git
133+
134+`cd` to the directory you just created:
135+
136+ cd urbit
137+
138+Run `make`:
139+
140+ make
141+
142+(On FreeBSD, use `gmake` instead.)
143+
144+The executable is `bin/urbit`.
145+
146+Fetch the latest bootstrapping pill:
147+
148+ curl -o urbit.pill http://bootstrap.urbit.org/latest.pill
149+
150+You can use your preferred way to fetch things from the web here. Urbit
151+looks for a pill named `urbit.pill` in the current directory by default,
152+so if you have anything different, you'll need to tell Urbit where it is
153+(on first launch only) with the `-B` command-line option.
154+
155+# Start
156+
157+An urbit is a persistent server on the `%ames` P2P network. You'll
158+create one of these servers now.
159+
160+If you have an invitation, it's a planet like `~fintud-macrep` and a
161+ticket like `~fortyv-tombyt-tabsen-sonres`. Run
162+
163+ urbit -w fintud-macrep -t fortyv-tombyt-tabsen-sonres
164+
165+(You can leave the `~` on, but it annoys some Unix shells.)
166+
167+If you don't have an invitation, pick a nickname for your comet, like
168+`mycomet`. Urbit will randomly generate a 128-bit plot:
169+
170+ urbit -c mycomet
171+
172+Either way, creating your urbit will take some time. Some of this time
173+involves creating keys; some of it involves downloading code over Urbit
174+itself. Go get a cup of coffee. Or a beer.
175+
176+Wait until you see a prompt, something like
177+
178+ ~fintud-macrep:dojo>
179+
180+Your urbit is launched! Ladies and gentlemen, we are floating in space.
181+
182+In either case you'll notice that we created a directory in unix called
183+either `mycomet` or `fintud-macrep`. All of your state (a log and
184+checkpoint) lives in that directory. You can move it around, but don't
185+delete it!
186+
187+### Restarting
188+
189+If you want to shut your Urbit down you can `^d` from the `dojo>`
190+prompt. To use Urbit normally after creating your planet or comet
191+there's no need for the `-w -t` or `-c` options.
192+
193+Instead:
194+
195+ urbit fintud-macrep
196+
197+or
198+
199+ urbit mycomet
200+
201+### Continuity breaches / network reboots
202+
203+Urbit is still young, and we reboot the network from time to time. Urbit
204+can upgrade itself over the air, but at this stage it's easier to bring
205+in breaking api changes this way. Since our crypto is stateful we call
206+this a 'continuity breach'.
207+
208+If you have files in your Urbit you'd like to backup first make a copy
209+of your pier. Then you'll need to shut down your urbit (with `^d`) and:
210+
211+ git pull origin master
212+ make clean; make
213+ curl -o urbit.pill http://bootstrap.urbit.org/latest.pill
214+
215+Then start over at the top of this section.
216+
217+# Talk
218+
219+We use Urbit to talk to each other and coordinate about building the
220+system. To join the main Urbit talk station use `^x` to switch to the
221+`talk()` prompt, then run:
222+
223+ ;join ~dozbud/urbit-meta
224+
225+# Learn more
226+
227+Urbit's own official planet `~winsen-pagdel` hosts the public docs
228+[here](http://urbit.org/docs). The docs also live in their own repo,
229+[`urbit/docs`](http://github.com/urbit/docs).
230+
231+If this is your first time using Urbit, we'd recommend starting
232+[here](http://urbit.org/docs/user/basic#-basic-operation).
233+
234+# Contributing
235+
236+The first step in contributing to urbit is to come and join us on
237+`:talk`.
238+
239+For more detailed instructions check out
240+[`CONTRIBUTING.md`](https://github.com/urbit/urbit/blob/master/CONTRIBUTING.md).