From 1358a2aaf29acd96b79877fdc30afd425ef550e9 Mon Sep 17 00:00:00 2001 From: Galen Wolfe-Pauly Date: Tue, 20 Oct 2015 11:40:29 -0700 Subject: [PATCH 1/6] new readme --- README.md | 245 ++++++++++++++++++++++++++---------------------------- 1 file changed, 117 insertions(+), 128 deletions(-) diff --git a/README.md b/README.md index 4f735d65cf..8f05c78bb9 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,86 @@ -urbit +Urbit ===== -Urbit is a new computing environment designed from scratch. +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 use -the interpreter, of course, but the network is 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. -- Enter your email address at [urbit.org](http://urbit.org). -- Subscribe to the +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. -- Get in touch with us via email, +- Hit us up by email, `urbit@urbit.org`. We're nice! -All of the source code is distributed under the MIT license. +Code of conduct +--------------- -Packages --------- +Everyone involved in the Urbit project needs to understand and +respect our code of conduct, which is: "don't be rude." -#### Ubuntu or Debian +Documentation +============= -Third-party package files are maintained at -https://github.com/yebyen/urbit-deb. Urbit is only supported on Jessie -onward. +In-progress documentation can be found at +[urbit.org/docs](http://urbit.org/docs). -#### OS X - Homebrew +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. + +Installation guide +================== + +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 -Dependencies ------------- +### 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 + gcc (or clang) gmp libsigsegv openssl @@ -54,9 +97,6 @@ urbit depends on: sudo apt-get install libgmp3-dev libsigsegv-dev openssl libssl-dev libncurses5-dev git make exuberant-ctags automake autoconf libtool g++ ragel cmake re2c -*note: http requests are not supported on debian jessie due to an ssl -issue* - #### Fedora sudo dnf install gcc gcc-c++ git gmp-devel openssl-devel openssl ncurses-devel libsigsegv-devel ctags automake autoconf libtool ragel cmake re2c @@ -81,8 +121,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 ------ +### Download and make Clone the repo: @@ -92,144 +131,94 @@ Clone the repo: cd urbit -Just run `make`: +Run `make`: make (On FreeBSD, use `gmake` instead.) -Run (with a network invitation) -------------------------------- +The executable is `bin/urbit`. Install it somewhere, or just use it +where it is. -If you have a planet named `~fintud-macrep` and a ticket -`~fortyv-tombyt-tabsen-sonres`, run +Launch procedure +================ - 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. To understand what you're building, +you need to know a little about the network. -Your pier (all Urbit state, log and checkpoint) will be in -`./fintud-macrep`. +Launch instructions +------------------- -To start Urbit again omit the `-w` and `-t` flags: +If you have an invitation, it's a planet like `~fintud-macrep` and a +ticket like `~fortyv-tombyt-tabsen-sonres`. Run - bin/urbit fintud-macrep + urbit -w fintud-macrep -t fortyv-tombyt-tabsen-sonres -Run (without a network invitation) ----------------------------------- +(You can leave the `~` on, but it annoys some Unix shells.) - bin/urbit -c mypier +If you don't have an invitation, pick a nickname for your comet, like +`mycomet`. Urbit will randomly generate a 128-bit plot: -Urbit will create a comet in `mypier`. + urbit -c mycomet -To start Urbit again omit the `-c` flag: +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. - bin/urbit mypier +Wait until you see a prompt, either -Basics ------- + ~fintud-macrep:talk() -`^v` will switch between the task manager and the focussed process. `^x` -will switch between processes. +or -To start a process that is not yet started, run `*proc` from the task -manager. + ~fintud-macrep:dojo> -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. +and then press \^D to quit. -`^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. +Your urbit is launched! Ladies and gentlemen, we are floating in +space. -Talk ----- +Read the docs +============= -If you're on the network, you can use its most basic application, -`talk`. +Your urbit is your personal web server. The best place to read its +docs is by pointing your browser at it. -If `talk` is not running, start it with `*talk` from the task manager. +Urbit prints the HTTP port it's serving when it starts up: -Use `^x` to switch to the `talk` prompt and then run + http: live (insecure) on 8080 - ;join ~doznec/urbit-meta +8080 is the default. If you're running on AWS or another cloud +service, this port may be firewalled; go to the firewall +configuration to open it. -to join the `urbit-meta` channel. People in there are helpful. +(*Always run any urbit HTTP server which is even semi-serious inside +a reliable, battle-proven frontline server like nginx.*) -There are three main `talk` commands: +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). - ;join ~urbit-name/channel +Assuming your Urbit is on `localhost:8080`, the Urbit docs are at -`;join` subscribes your main feed to a remote channel. + http://localhost:8080/home/docs - ; +And `:talk` is: -`;` activates a previous message number, like a URL that got -clipped. + http://localhost:8080/home/pub/talk/fab - ; - -`;` 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. +For the time being the login code is output to your console. First +try any text, then you'll see a printf that looks like +`code='laslyt-mocwyd-hobmyn-rolbyl'` in your terminal. That code will +get you in. 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). From d584387dd5630c5fce584f0f86ee17e776ae6cce Mon Sep 17 00:00:00 2001 From: Galen Wolfe-Pauly Date: Tue, 20 Oct 2015 11:43:56 -0700 Subject: [PATCH 2/6] clarifying --- README.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 8f05c78bb9..2bdc2d09b7 100644 --- a/README.md +++ b/README.md @@ -144,8 +144,7 @@ Launch procedure ================ An urbit is a persistent server on the `%ames` P2P network. You'll -create one of these servers now. To understand what you're building, -you need to know a little about the network. +create one of these servers now. Launch instructions ------------------- @@ -166,7 +165,7 @@ 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, either +Wait until you see a prompt, something like ~fintud-macrep:talk() @@ -174,8 +173,6 @@ or ~fintud-macrep:dojo> -and then press \^D to quit. - Your urbit is launched! Ladies and gentlemen, we are floating in space. @@ -205,14 +202,13 @@ Assuming your Urbit is on `localhost:8080`, the Urbit docs are at http://localhost:8080/home/docs -And `:talk` is: +and `:talk` is http://localhost:8080/home/pub/talk/fab -For the time being the login code is output to your console. First +(For the time being the login code is output to your console. First try any text, then you'll see a printf that looks like -`code='laslyt-mocwyd-hobmyn-rolbyl'` in your terminal. That code will -get you in. +`code='laslyt-mocwyd-hobmyn-rolbyl'` in your terminal. That code will get you in.) Contributing ============ From 5f87e74098ed47c60ac1c5473d759ed2369552cf Mon Sep 17 00:00:00 2001 From: Galen Wolfe-Pauly Date: Tue, 20 Oct 2015 11:44:53 -0700 Subject: [PATCH 3/6] minor --- README.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 2bdc2d09b7..81ff7348ee 100644 --- a/README.md +++ b/README.md @@ -68,8 +68,7 @@ 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!) +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 ---------------------- @@ -190,13 +189,12 @@ Urbit prints the HTTP port it's serving when it starts up: 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.*) +(*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). +those that ship with your urbit.) Assuming your Urbit is on `localhost:8080`, the Urbit docs are at From f1bedbf42c6fcf446861014239af880d325a4634 Mon Sep 17 00:00:00 2001 From: Galen Wolfe-Pauly Date: Tue, 20 Oct 2015 11:46:25 -0700 Subject: [PATCH 4/6] simpler --- README.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 81ff7348ee..bcb3c04e49 100644 --- a/README.md +++ b/README.md @@ -48,8 +48,8 @@ can access them at Assuming you're running on port 8080. The port is printed on startup. -Installation guide -================== +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. @@ -139,15 +139,12 @@ Run `make`: The executable is `bin/urbit`. Install it somewhere, or just use it where it is. -Launch procedure -================ +Launch +====== An urbit is a persistent server on the `%ames` P2P network. You'll create one of these servers now. -Launch instructions -------------------- - If you have an invitation, it's a planet like `~fintud-macrep` and a ticket like `~fortyv-tombyt-tabsen-sonres`. Run @@ -175,8 +172,8 @@ or Your urbit is launched! Ladies and gentlemen, we are floating in space. -Read the docs -============= +Docs +==== Your urbit is your personal web server. The best place to read its docs is by pointing your browser at it. From 6c9feb38e5a8d48e68d94e308c84026a368b03ac Mon Sep 17 00:00:00 2001 From: Galen Wolfe-Pauly Date: Tue, 20 Oct 2015 11:47:43 -0700 Subject: [PATCH 5/6] ports --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bcb3c04e49..fbe7187f2c 100644 --- a/README.md +++ b/README.md @@ -182,7 +182,7 @@ 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. From 8f85bb6eb2a7b7e0640daaf30a51e7324c2b1278 Mon Sep 17 00:00:00 2001 From: Galen Wolfe-Pauly Date: Tue, 20 Oct 2015 11:49:40 -0700 Subject: [PATCH 6/6] simpler --- README.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index fbe7187f2c..4c16c986f8 100644 --- a/README.md +++ b/README.md @@ -193,17 +193,13 @@ 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`, the Urbit docs are at +Assuming your Urbit is on `localhost:8080`, your copy of the docs are at http://localhost:8080/home/docs -and `:talk` is +To continue getting setup, start here: - http://localhost:8080/home/pub/talk/fab - -(For the time being the login code is output to your console. First -try any text, then you'll see a printf that looks like -`code='laslyt-mocwyd-hobmyn-rolbyl'` in your terminal. That code will get you in.) + http://localhost:8080/home/docs/user/start Contributing ============