mirror of
https://github.com/urbit/shrub.git
synced 2024-12-17 07:14:52 +03:00
243 lines
6.5 KiB
Markdown
243 lines
6.5 KiB
Markdown
Urbit
|
|
=====
|
|
|
|
Urbit is a clean-slate system software stack defined as a
|
|
deterministic computer. An encrypted P2P network, `%ames`, runs on a
|
|
functional operating system, Arvo, written in a strict, typed
|
|
functional language, Hoon, which compiles itself to a combinator
|
|
interpreter, Nock, whose spec gzips to 340 bytes.
|
|
|
|
What is this for? Most directly, Urbit is designed as a personal
|
|
cloud server for self-hosted web apps. It also uses HTTP APIs to
|
|
manage data stuck in traditional web applications.
|
|
|
|
More broadly, Urbit's network tackles identity and security problems
|
|
which the Internet can't easily address. Programming for a
|
|
deterministic single-level store is also a different experience from
|
|
Unix programming, regardless of language.
|
|
|
|
Getting involved
|
|
----------------
|
|
|
|
If you're interested in following Urbit, you can:
|
|
|
|
- Read our documentation at [urbit.org](http://urbit.org/docs)
|
|
- Subscribe to our newsletter at [urbit.org](http://urbit.org).
|
|
- Check out the
|
|
[urbit-dev](https://groups.google.com/forum/#!forum/urbit-dev)
|
|
mailing list.
|
|
- Follow [@urbit_](https://twitter.com/urbit\_) on Twitter.
|
|
- Hit us up by email, `urbit@urbit.org`. We're nice!
|
|
|
|
Code of conduct
|
|
---------------
|
|
|
|
Everyone involved in the Urbit project needs to understand and
|
|
respect our code of conduct, which is: "don't be rude."
|
|
|
|
Documentation
|
|
=============
|
|
|
|
In-progress documentation can be found at
|
|
[urbit.org/docs](http://urbit.org/docs).
|
|
|
|
These docs ship with your urbit. If you're running one locally you
|
|
can access them at
|
|
|
|
http://localhost:8080/home/docs
|
|
|
|
Assuming you're running on port 8080. The port is printed on startup.
|
|
|
|
Install
|
|
=======
|
|
|
|
Urbit can be installed on most Unix systems. There is no Windows
|
|
port. Windows is a wonderful OS, we just haven't gotten to it yet.
|
|
Use a VM.
|
|
|
|
Configure swap if needed
|
|
------------------------
|
|
|
|
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, 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.
|
|
|
|
To add swap to a DO droplet:
|
|
|
|
https://www.digitalocean.com/community/tutorials/how-to-add-swap-on-ubuntu-14-04
|
|
|
|
To add swap on an Amazon instance:
|
|
|
|
http://stackoverflow.com/questions/17173972/how-do-you-add-swap-to-an-ec2-instance
|
|
|
|
Don't spend a lot of time tweaking these settings; the simplest
|
|
thing is fine.
|
|
|
|
Install as a package
|
|
--------------------
|
|
|
|
### OS X - Homebrew
|
|
|
|
brew install --HEAD homebrew/head-only/urbit
|
|
|
|
### Ubuntu or Debian
|
|
|
|
Third-party packages are available, at:
|
|
|
|
https://github.com/yebyen/urbit-deb
|
|
|
|
Urbit is only supported on Jessie onward (but outbound HTTPS requests only work on Stretch; I wish we knew why; help us!)
|
|
|
|
Hand-build from source
|
|
----------------------
|
|
|
|
First, install all external dependencies. Then, make.
|
|
|
|
### Dependencies
|
|
|
|
urbit depends on:
|
|
|
|
gcc (or clang)
|
|
gmp
|
|
libsigsegv
|
|
openssl
|
|
automake
|
|
autoconf
|
|
ragel
|
|
cmake
|
|
re2c
|
|
libtool
|
|
libssl-dev (Linux only)
|
|
ncurses (Linux only)
|
|
|
|
#### Ubuntu or Debian
|
|
|
|
sudo apt-get install libgmp3-dev libsigsegv-dev openssl libssl-dev libncurses5-dev git make exuberant-ctags automake autoconf libtool g++ ragel cmake re2c
|
|
|
|
#### Fedora
|
|
|
|
sudo dnf install gcc gcc-c++ git gmp-devel openssl-devel openssl ncurses-devel libsigsegv-devel ctags automake autoconf libtool ragel cmake re2c
|
|
|
|
#### AWS
|
|
|
|
sudo yum --enablerepo epel install gcc gcc-c++ git gmp-devel openssl-devel ncurses-devel libsigsegv-devel ctags automake autoconf libtool cmake re2c
|
|
|
|
#### OS X - Homebrew
|
|
|
|
brew install git gmp libsigsegv openssl libtool autoconf automake cmake
|
|
|
|
#### OS X - Macports
|
|
|
|
sudo port install git gmp libsigsegv openssl autoconf automake cmake
|
|
|
|
Although `automake`/`autoconf`/`libtool` are generally installed by
|
|
default, some have reported needing to uninstall and reinstall those
|
|
three packages, at least with Homebrew. Your mileage may vary.
|
|
|
|
#### FreeBSD
|
|
|
|
pkg install git gmake gmp libsigsegv openssl automake autoconf ragel cmake re2c libtool
|
|
|
|
### Download and make
|
|
|
|
Clone the repo:
|
|
|
|
git clone git://github.com/urbit/urbit.git
|
|
|
|
`cd` to the directory you just created:
|
|
|
|
cd urbit
|
|
|
|
Run `make`:
|
|
|
|
make
|
|
|
|
(On FreeBSD, use `gmake` instead.)
|
|
|
|
The executable is `bin/urbit`. Install it somewhere, or just use it
|
|
where it is.
|
|
|
|
Launch
|
|
======
|
|
|
|
An urbit is a persistent server on the `%ames` P2P network. You'll
|
|
create one of these servers now.
|
|
|
|
If you have an invitation, it's a planet like `~fintud-macrep` and a
|
|
ticket like `~fortyv-tombyt-tabsen-sonres`. Run
|
|
|
|
urbit -w fintud-macrep -t fortyv-tombyt-tabsen-sonres
|
|
|
|
(You can leave the `~` on, but it annoys some Unix shells.)
|
|
|
|
If you don't have an invitation, pick a nickname for your comet, like
|
|
`mycomet`. Urbit will randomly generate a 128-bit plot:
|
|
|
|
urbit -c mycomet
|
|
|
|
Either way, creating your urbit will take some time. Some of this
|
|
time involves creating keys; some of it involves downloading code
|
|
over Urbit itself. Go get a cup of coffee. Or a beer.
|
|
|
|
Wait until you see a prompt, something like
|
|
|
|
~fintud-macrep:talk()
|
|
|
|
or
|
|
|
|
~fintud-macrep:dojo>
|
|
|
|
Your urbit is launched! Ladies and gentlemen, we are floating in
|
|
space.
|
|
|
|
### Relaunch
|
|
|
|
To use Urbit normally after creating your planet or comet:
|
|
|
|
urbit fintud-macrep
|
|
|
|
or
|
|
|
|
urbit mycomet
|
|
|
|
Docs
|
|
====
|
|
|
|
Your urbit is your personal web server. The best place to read its
|
|
docs is by pointing your browser at it.
|
|
|
|
Urbit prints the HTTP port it's serving when it starts up:
|
|
|
|
http: live (insecure) on 8080
|
|
|
|
8080 is the default. When it's not available we use 8081. Then 8082, and so on. If you're running on AWS or another cloud
|
|
service, this port may be firewalled; go to the firewall
|
|
configuration to open it.
|
|
|
|
(*Always run any urbit HTTP server which is even semi-serious inside a reliable, battle-proven frontline server like nginx.*)
|
|
|
|
Urbit's own official planet `~winsen-pagdel` is also bound to just
|
|
plain `urbit.org`, and hosts the public docs
|
|
[here](http://urbit.org/docs). (They are, of course, the same as
|
|
those that ship with your urbit.)
|
|
|
|
Assuming your Urbit is on `localhost:8080`, your copy of the docs are at
|
|
|
|
http://localhost:8080/home/docs
|
|
|
|
To continue getting setup, start here:
|
|
|
|
http://localhost:8080/home/docs/user/start
|
|
|
|
Contributing
|
|
============
|
|
|
|
The first step in contributing to urbit is to come and join us on
|
|
`:talk`.
|
|
|
|
For more detailed instructions check out
|
|
[`CONTRIBUTING.md`](https://github.com/urbit/urbit/blob/master/CONTRIBUTING.md).
|