@@ -0,0 +1,240 @@
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.
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.
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.
20+If you're interested in following Urbit, you can:
22+- Read our documentation at [urbit.org](http://urbit.org/docs)
23+- Subscribe to our newsletter at [urbit.org](http://urbit.org).
25+ [urbit-dev](https://groups.google.com/forum/#!forum/urbit-dev)
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.
33+Everyone involved in the Urbit project needs to understand and respect
34+our code of conduct, which is: "don't be rude."
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.
41+## Configure swap if needed
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.
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)
54+Don't spend a lot of time tweaking these settings; the simplest thing is
57+## Install as a package
60+waiting on makefile changes.
63+ brew install --HEAD homebrew/head-only/urbit
68+Third-party packages are available, at:
70+ https://github.com/yebyen/urbit-deb
72+Urbit is only supported on Jessie onward (but outbound HTTPS requests
73+only work on Stretch; I wish we knew why; help us!)
75+## Hand-build from source
77+First, install all external dependencies. Then, make.
93+ libssl-dev (Linux only)
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
102+ sudo dnf install gcc gcc-c++ git gmp-devel openssl-devel openssl ncurses-devel libsigsegv-devel ctags automake autoconf libtool ragel cmake re2c
106+ sudo yum --enablerepo epel install gcc gcc-c++ git gmp-devel openssl-devel ncurses-devel libsigsegv-devel ctags automake autoconf libtool cmake re2c
110+ brew install git gmp libsigsegv openssl libtool autoconf automake cmake
114+ sudo port install git gmp libsigsegv openssl autoconf automake cmake
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.
122+ pkg install git gmake gmp libsigsegv openssl automake autoconf ragel cmake re2c libtool
126+ pacman -S gcc gmp libsigsegv openssl automake autoconf ragel cmake re2c libtool ncurses
128+### Download and make
132+ git clone https://github.com/urbit/urbit.git
134+`cd` to the directory you just created:
142+(On FreeBSD, use `gmake` instead.)
144+The executable is `bin/urbit`.
146+Fetch the latest bootstrapping pill:
148+ curl -o urbit.pill http://bootstrap.urbit.org/latest.pill
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.
157+An urbit is a persistent server on the `%ames` P2P network. You'll
158+create one of these servers now.
160+If you have an invitation, it's a planet like `~fintud-macrep` and a
161+ticket like `~fortyv-tombyt-tabsen-sonres`. Run
163+ urbit -w fintud-macrep -t fortyv-tombyt-tabsen-sonres
165+(You can leave the `~` on, but it annoys some Unix shells.)
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:
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.
176+Wait until you see a prompt, something like
178+ ~fintud-macrep:dojo>
180+Your urbit is launched! Ladies and gentlemen, we are floating in space.
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
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.
201+### Continuity breaches / network reboots
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'.
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:
211+ git pull origin master
213+ curl -o urbit.pill http://bootstrap.urbit.org/latest.pill
215+Then start over at the top of this section.
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:
223+ ;join ~dozbud/urbit-meta
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).
231+If this is your first time using Urbit, we'd recommend starting
232+[here](http://urbit.org/docs/user/basic#-basic-operation).
236+The first step in contributing to urbit is to come and join us on
239+For more detailed instructions check out
240+[`CONTRIBUTING.md`](https://github.com/urbit/urbit/blob/master/CONTRIBUTING.md).