diff --git a/README.md b/README.md index 11b79e9e8..36e250904 100644 --- a/README.md +++ b/README.md @@ -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, . 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. - - ; - -`;` activates a previous message number, like a URL that got -clipped. - - ; - -`;` 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 [] - -The `` is optional and defaults to the last part of -the ``. - - |unmount - -or: - - |unmount - -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). \ No newline at end of file