urbit/shrub
1
1
Fork 0
mirror of https://github.com/urbit/shrub.git synced 2024-12-25 21:12:56 +03:00
Code Issues Packages Projects Releases Wiki Activity

sub doznec

Browse Source
This commit is contained in:
Tobias Merkle 2016-06-29 15:21:40 -07:00
parent 2a41962c2f
commit a1f068d852
1 changed files with 159 additions and 119 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

278
README.md
View File

@ -1,36 +1,84 @@
Urbit # Urbit
=====
Urbit is a clean-slate system software stack defined as a Urbit is a clean-slate system software stack defined as a deterministic
deterministic computer. An encrypted P2P network, `%ames`, runs on a computer. An encrypted P2P network, `%ames`, runs on a functional
functional operating system, Arvo, written in a strict, typed operating system, Arvo, written in a strict, typed functional language,
functional language, Hoon, which compiles itself to a combinator Hoon, which compiles itself to a combinator interpreter, Nock, whose
interpreter, Nock, whose spec gzips to 340 bytes. spec gzips to 340 bytes.
What is this for? Most directly, Urbit is designed as a personal What is this for? Most directly, Urbit is designed as a personal cloud
cloud server for self-hosted web apps. It also uses HTTP APIs to server for self-hosted web apps. It also uses HTTP APIs to manage data
manage data stuck in traditional web applications. stuck in traditional web applications.
More broadly, Urbit's network tackles identity and security problems More broadly, Urbit's network tackles identity and security problems
which the Internet can't easily address. Programming for a which the Internet can't easily address. Programming for a deterministic
deterministic single-level store is also a different experience from single-level store is also a different experience from Unix programming,
Unix programming, regardless of language. regardless of language.
Install ## Getting involved
=======
Urbit is designed to run on any Unix box with an internet connection. Debian If you're interested in following Urbit, you can:
(jessie), OS X, FreeBSD and Fedora all work well.
Urbit is alpha software. It’s not yet completely stable, its crypto hasn’t - Read our documentation at [urbit.org](http://urbit.org/docs)
been audited, and there are plenty of rough edges. Urbit is lots of fun to play - Subscribe to our newsletter at [urbit.org](http://urbit.org).
with, but not quite ready for your important or sensitive data. - Check out the
[urbit-dev](https://groups.google.com/forum/#!forum/urbit-dev)
mailing list.
- Follow [@urbit \_](https://twitter.com/urbit\_) on Twitter.
- Email us: [`urbit@urbit.org`](mailto:urbit@urbit.org). We're happy
to answer questions and chat.
## Build from source ## Code of conduct
Everyone involved in the Urbit project needs to understand and respect
our code of conduct, which is: "don't be rude."
# 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, [read
this](https://www.digitalocean.com/community/tutorials/how-to-add-swap-on-ubuntu-14-04).
To add swap on an Amazon instance, [read
this](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
<!--
waiting on makefile changes.
### 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 ### Dependencies
Urbit depends on: urbit depends on:
gcc (or clang) gcc (or clang)
gmp gmp
@ -40,158 +88,150 @@ Urbit depends on:
autoconf autoconf
ragel ragel
cmake cmake
re2c
libtool libtool
libssl-dev (Linux only) libssl-dev (Linux only)
ncurses (Linux only) ncurses (Linux only)
Which can usually be installed with the following one-liners: #### 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
# Mac OS X [Homebrew]
brew install git gmp libsigsegv openssl libtool autoconf automake cmake brew install git gmp libsigsegv openssl libtool autoconf automake cmake
# Mac OS X [Macports] #### OS X - Macports
sudo port install git gmp libsigsegv openssl autoconf automake cmake sudo port install git gmp libsigsegv openssl autoconf automake cmake
# Ubuntu or Debian Although `automake`/`autoconf`/`libtool` are generally installed by
sudo apt-get install libgmp3-dev libsigsegv-dev openssl libssl-dev libncurses5-dev git make exuberant-ctags automake autoconf libtool g++ ragel cmake default, some have reported needing to uninstall and reinstall those
three packages, at least with Homebrew. Your mileage may vary.
# Fedora #### FreeBSD
sudo dnf install gcc gcc-c++ git gmp-devel openssl-devel openssl ncurses-devel libsigsegv-devel ctags automake autoconf libtool ragel cmake
# FreeBSD pkg install git gmake gmp libsigsegv openssl automake autoconf ragel cmake re2c libtool
pkg install git gmake gmp libsigsegv openssl automake autoconf ragel cmake libtool
# Arch #### Archlinux
pacman -S gcc gmp libsigsegv openssl automake autoconf ragel cmake libtool ncurses
# AWS pacman -S gcc gmp libsigsegv openssl automake autoconf ragel cmake re2c libtool ncurses
sudo yum —enablerepo epel install gcc gcc-c++ git gmp-devel openssl-devel ncurses-devel libsigsegv-devel ctags automake autoconf libtool cmake
### Setting up swap ### Download and make
Urbit wants to map 2GB of memory when it boots up. We won’t Clone the repo:
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.
Digital Ocean has a post on adding swap [here](https://www.digitalocean.com/community/tutorials/how-to-add-swap-on-ubuntu-14-04). For Amazon there’s a StackOverflow thread [here](http://stackoverflow.com/questions/17173972/how-do-you-add-swap-to-an-ec2-instance). git clone https://github.com/urbit/urbit.git
Don’t spend a lot of time tweaking these settings; the simplest `cd` to the directory you just created:
thing is fine.
### Clone and make
Once your dependencies are installed the rest is easy:
git clone https://github.com/urbit/urbit
cd urbit cd urbit
Run `make`:
make make
curl -o urbit.pill https://bootstrap.urbit.org/latest.pill
After running `make`, your Urbit executable lives at `bin/urbit`. The `.pill` file is a compiled binary of Arvo that Urbit uses to bootstrap itself. (On FreeBSD, use `gmake` instead.)
# Getting started The executable is `bin/urbit`.
On disk your Urbit is an append-only log and a checkpoint. Or, in simpler terms, a directory where we keep all of your Urbit’s state. We call this a ‘pier’. Fetch the latest bootstrapping pill:
## Initialize curl -o urbit.pill http://bootstrap.urbit.org/latest.pill
When you first start an Urbit we create this pier directory and write to it. You can use your preferred way to fetch things from the web here. Urbit
looks for a pill named `urbit.pill` in the current directory by default,
so if you have anything different, you'll need to tell Urbit where it is
(on first launch only) with the `-B` command-line option.
To start with a planet (`~fintud-macrep`) and ticket (`~fortyv-tombyt-tabsen-sonres`): # Start
bin/urbit -w fintud-macrep -t fortyv-tombyt-tabsen-sonres An urbit is a persistent server on the `%ames` P2P network. You'll
create one of these servers now.
This will create a directory `fintud-macrep/` and begin the initialization process for that planet. Be patient, it can take a few minutes. If you have an invitation, it's a planet like `~fintud-macrep` and a
ticket like `~fortyv-tombyt-tabsen-sonres`. Run
Without a planet anyone can create a comet: urbit -w fintud-macrep -t fortyv-tombyt-tabsen-sonres
bin/urbit -c comet (You can leave the `~` on, but it annoys some Unix shells.)
This will create a directory `comet/` and start up a random 128-bit comet. You can specify any name you like. If you don't have an invitation, pick a nickname for your comet, like
`mycomet`. Urbit will randomly generate a 128-bit plot:
## Orientation urbit -c mycomet
When your Urbit is finished booting you should see a `dojo>` prompt. Welcome! 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.
By default your Urbit is quite bare bones. Let's take a very short stroll through what's running by default: Wait until you see a prompt, something like
### Shell — `:dojo` ~fintud-macrep:dojo>
The command prompt in front of you is a simple shell and Hoon REPL. Let's make sure it works: Your urbit is launched! Ladies and gentlemen, we are floating in space.
~fitund-macrep:dojo> (add 2 2) In either case you'll notice that we created a directory in unix called
either `mycomet` or `fintud-macrep`. All of your state (a log and
checkpoint) lives in that directory. You can move it around, but don't
delete it!
Should produce: ### Restarting
> (add 2 2) If you want to shut your Urbit down you can `^d` from the `dojo>`
4 prompt. To use Urbit normally after creating your planet or comet
there's no need for the `-w -t` or `-c` options.
Good. Instead:
### Messaging — `:talk` urbit fintud-macrep
Use `^X` to change your prompt. Let's join the main Urbit chat channel: or
~fitund-macrep:talk() ;join ~doznec/urbit-meta urbit mycomet
This may take a bit as `:talk` is stateful so your Urbit will download some backlog. `/urbit-meta` is the place to ask questions, get help and talk about anything Urbit related. ### Continuity breaches / network reboots
### Web — `:tree` Urbit is still young, and we reboot the network from time to time. Urbit
can upgrade itself over the air, but at this stage it's easier to bring
in breaking api changes this way. Since our crypto is stateful we call
this a 'continuity breach'.
Urbit is also accessible through the web. Try opening: If you have files in your Urbit you'd like to backup first make a copy
of your pier. Then you'll need to shut down your urbit (with `^d`) and:
http://localhost:8080/ git pull origin master
make clean; make
curl -o urbit.pill http://bootstrap.urbit.org/latest.pill
in your favorite browser. You'll be prompted to use `+code`. This page was generated by `:tree`, the basic Urbit web interface. You can also access your Urbit through `http://fintud-macrep.urbit.org` (where `fintud-macrep` is your planet name). Then start over at the top of this section.
### Filesystem — `%clay` # Talk
`%clay`, the Urbit filesystem, isn't mounted to unix by default. Switch to the `:dojo` prompt and run: We use Urbit to talk to each other and coordinate about building the
system. To join the main Urbit talk station use `^x` to switch to the
`talk()` prompt, then run:
~fitund-macrep:dojo> |mount % ;join ~dozbud/urbit-meta
This should produce: # Learn more
> |mount % Urbit's own official planet `~winsen-pagdel` hosts the public docs
>= [here](http://urbit.org/docs). The docs also live in their own repo,
[`urbit/docs`](http://github.com/urbit/docs).
which indicates the command was processed. If this is your first time using Urbit, we'd recommend starting
[here](http://urbit.org/docs/user/basic#-basic-operation).
`|mount %` will cause a `home/` directory to appear inside your pier folder. Changes to these files are automatically synced into your Urbit. # Contributing
Learn more
==========
If this is your first time using Urbit, and you've followed the instructions above, we'd recommend continuing the sequence [here](http://urbit.org/docs/using/admin/).
### Docs
[urbit.org/docs](http://urbit.org/docs/) is the public documentation site.
The source is also in its own repo: [urbit/docs](http://github.com/urbit/docs).
### About
[urbit.org/posts](http://urbit.org/docs/) contains some essays on the theory and future of urbit.
### Keep in touch
- Check out the [urbit-dev](https://groups.google.com/forum/#!forum/urbit-dev) mailing list for long-form discussion.
- Follow [@urbit_](https://twitter.com/urbit\_) on Twitter.
- Email [urbit@urbit.org](mailto:urbit@urbit.org). We're happy to answer questions and chat.
Code of conduct
===============
Everyone involved in the Urbit project needs to understand and
respect our code of conduct, which is: "don't be rude."
Contributing
============
The first step in contributing to urbit is to come and join us on The first step in contributing to urbit is to come and join us on
`:talk`. `:talk`.