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

Merge branch 'test' of https://github.com/galenwp/urbit into karpi

Browse Source
This commit is contained in:
C. Guy Yarvin 2015-10-20 12:17:22 -07:00
commit 771ce400bc
1 changed files with 95 additions and 244 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

339
README.md
View File

@ -1,44 +1,79 @@
# Urbit
Urbit
=====
Urbit is a clean-slate system software stack. It's patent-free
and MIT licensed. It runs its own encrypted P2P network over UDP.
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.
At present urbit is under heavy development. It's not useful for
any external purpose. Documentation is completely inadequate.
Anyone can try the interpreter, of course, but the network is
officially invitation-only.
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.
If you're interested in keeping in touch or following the project
you can:
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.
- Give us your email address at [urbit.org](http://urbit.org).
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!
- Hit us up by email, `urbit@urbit.org`. We're nice!
Install a package
-----------------
Code of conduct
---------------
#### OS X - Homebrew
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.
Install as a package
--------------------
### OS X - Homebrew
brew install --HEAD homebrew/head-only/urbit
#### Ubuntu or Debian
### Ubuntu or Debian
Third-party packages are available, at:
https://github.com/yebyen/urbit-deb
Urbit is only supported on Jessie onward (but outgoing HTTPS
requests only work on Stretch; I wish we knew why; if you have an
idea why or just think you can help, please let us know).
Urbit is only supported on Jessie onward (but outbound HTTPS requests only work on Stretch; I wish we knew why; help us!)
Install by hand
---------------
Hand-build from source
----------------------
First, install all our external dependencies. Then, make.
First, install all external dependencies. Then, make.
### Dependencies
@ -85,7 +120,7 @@ three packages, at least with Homebrew. Your mileage may vary.
pkg install git gmake gmp libsigsegv openssl automake autoconf ragel cmake re2c libtool
### Build instructions
### Download and make
Clone the repo:
@ -101,260 +136,76 @@ Run `make`:
(On FreeBSD, use `gmake` instead.)
The executable is `bin/urbit`. Install it somewhere, or just use
it in place.
The executable is `bin/urbit`. Install it somewhere, or just use it
where it is.
Create your urbit
---------------
Launch
======
Urbit is a semi-decentralized P2P network. So you may or may not
have an invitation.
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 *ticket* that lets you create
a 32-bit Urbit plot, aka *planet*. If you don't have an
invitation, you have to create a 128-bit plot, aka *comet*.
As a comet, you're not necessarily a bad person. But you could
be anyone, so you have zero reputation. You have no official
access to any Urbit services. Any connectivity you may enjoy
could be shut off at any time. And probably will be.
If you have an invitation, it's a planet like `~fintud-macrep`
and a ticket like `~fortyv-tombyt-tabsen-sonres`. Run
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
If you don't, pick a nickname for your comet, like `mycomet`.
Urbit will randomly generate a 128-bit address, but
(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. Go get
a cup of coffee. Some of this time involves creating keys;
some of it involves downloading code over Urbit itself.
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.
Note that Urbit is a P2P network that runs over random UDP ports;
some firewalls may not like it. Urbit without connectivity isn't
useless, but it can't boot without the network.
Wait until you see a prompt, something like
But however horribly hacked, the `urbit` process can only read
and write inside the `fintud-macrep` or `mycomet` directory,
which we call your *pier*. A pier is portable; any Urbit install
on any OS can execute the same pier.
~fintud-macrep:talk()
In the pier directory is a set of user-level mount points. Mount
points are synced Dropbox style, with Unix file changes
autocommitted to the Urbit revision control system (`%clay`) and
vice versa. You edit Urbit code with vim and emacs, or whatever.
or
Also within the pier is a system directory, `.urb`, which
contains an event log (`egz.hope`), a checkpoint (`.chk`), and
I/O directories for uploads and downloads (`put` and `get`).
You can compact the pier by deleting the checkpoint, although
that means Urbit needs to re-execute its entire event history.
This will take some time. Go have a beer.
~fintud-macrep:dojo>
When it's created (and before it calls `chroot()`), your urbit
creates a passcode file, with a name like `~posluc-darnup`,
in `~/.urbit`. If you want to encrypt the checkpoint and log,
delete this file; Urbit will prompt you for its contents. Please
be warned that Urbit is not at present secure in any way!
Your urbit is launched! Ladies and gentlemen, we are floating in
space.
Wait until you see a prompt, like
Docs
====
~fintud-macrep:talk>
and then press ^D to quit. Your urbit is born.
Execute
-------
To restart your urbit, run with the pier name:
urbit fintud-macrep
urbit mycomet
Your Urbit is a database, at least in theory. You can kill the
process however you like, and it won't lose state. In theory.
In practice, this works better on OS X than Linux. Also, don't
let your filesystem run out of disk!
Out of the box, your urbit is running two default appliances,
`:dojo` (a shell or REPL) and `:talk`. Switch between them with
`^X`. Note that all apps share an output log, but `^X` switches
the prompt.
`^D` from any default appliance exits the urbit process.
Learn more
----------
Your urbit is a web server, so the best place to read about it
is in your browser.
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. If you're running on AWS or another cloud
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. In a last resort, you can use our
server, doznec.urbit.org.
configuration to open it.
Or just talk
------------
(*Always run any urbit HTTP server which is even semi-serious inside a reliable, battle-proven frontline server like nginx.*)
Use `^X` to get into `:talk`, and
From `:talk`,
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
Doing more
----------
http://localhost:8080/home/docs
To test the dojo, run
Doing more
To continue getting setup, start here:
From either of the core
directory. Your pier (all Urbit state, log and checkpoint) will
be in `./fintud-macrep`. The format is portable. Doing `rm -r
fintud-macrep/.urb/chk` will delete the checkpoint, meaning all
your events need to be recomputed, but making the image smaller.
bin/urbit fintud-macrep
Run (without a network invitation)
----------------------------------
To create a comet (128-bit urbit) in the Unix directory
`mycomet`:
bin/urbit -c mycomet
This will take a little while. Go smoke a bowl.
This process can only read and write files within `mycomet`.
To quit Urbit (without destroying any data, since Urbit is a
database): ^D.
To start your comet again, omit the `-c` flag:
bin/urbit mypier
Learn these two control keys first: ^D to quit Urbit (from either
of the two core applications),
Basics
------
`^v` will switch between the task manager and the focussed process. `^x`
will switch between processes.
To start a process that is not yet started, run `*proc` from the task
manager.
To connect your console to a process that has already been started, run
`+proc` from the task manager. Note that the process must be one that
supports console access, such as dojo and talk.
`^d` will exit the pier from the task manager. No matter how you shut
your urbit down you'll be returned to exactly the same state as when you
turned it off.
Talk
----
If you're on the network, you can use its most basic application,
`talk`.
If `talk` is not running, start it with `*talk` from the task manager.
Use `^x` to switch to the `talk` prompt and then run
;join ~doznec/urbit-meta
to join the `urbit-meta` channel. People in there are helpful.
There are three main `talk` commands:
;join ~urbit-name/channel
`;join` subscribes your main feed to a remote channel.
;<number>
`;<number>` activates a previous message number, like a URL that got
clipped.
;<target>
`;<target>` sets the target for your messages, such as `;~urbit-name`
for a private message.
Filesystem Sync
---------------
The Urbit filesystem, `%clay` doesn't automatically sync to unix. If
you'd like to browse the contents of your Urbit from unix you'll need to
use `|mount`.
`|mount` creates a mirror in unix of files from `%clay` that is always
watching for changes. To sync your entire `home/` desk run:
|mount %
you should see a directory called `home/` get created inside your pier.
When you change files in this directory the changes will get synced into
your urbit.
Since each mount point is always watching for changes you may also want
to unmount from time to time.
The full syntax is as follows (from `dojo`):
|mount <path-in-clay> [<mount-name>]
The `<mount-name>` is optional and defaults to the last part of
the `<path-in-clay>`.
|unmount <mount-name>
or:
|unmount <path-in-clay>
Sysadmin
--------
For the most part, updates to the system are automatically synced to
your urbit across the network.
When we make updates to the interpreter you should be able to shut down
your urbit and:
git pull origin master
make
bin/urbit pier
where pier is the name of your pier.
While the network is still young from time to time we reboot the entire
universe. We call this a 'continuity breach' since we're breaking the
continuity of our crypto.
When this happens you'll need to back up your data and start a fresh
pier. Your original ticket will still work.
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),.
[`contributing.md`](https://github.com/urbit/urbit/blob/master/CONTRIBUTING.md).