:- :~ navhome/'/docs/' navuptwo/'true' next/'true' sort/'2' title/'Setup' == ;> # Getting started On disk, your urbit - also referred to as your _ship_ - is an append-only log and a checkpoint. Or, in simpler terms, a directory where we keep your urbit’s state. We call this a _pier_. > Note: we use the word 'urbit' (lowercase 'u') to indicate a particular ship, as opposed to 'Urbit' (capital 'u') to refer to the whole software stack and/or network in general. ## Initialize To create a ship, we need an identity. This identity is both a network address and a memorable name. You are probably creating one of two kinds of ships: a 32-bit _planet_ or a 128-bit _comet_. For a quick terminology guide and high-level refresher, refer to this [handy reference sheet](../../reference/glossary/). If you have an Urbit invitation, you'll have a planet name and ticket like `~sampel-palnet` and `~sampel-sompel-simpel-sampel`. To create your pier: ``` $ urbit -w sampel-palnet -t sampel-sompel-simpel-sampel ``` This will create a directory (pier) `sampel-palnet/` and begin building your ship. You can feel free to rename the directory, or append a `-c ` to the end of it to give it a custom name from the start: ``` $ urbit -w sampel-palnet -t sampel-sompel-simpel-sampel -c myplanet ``` Booting may take a few minutes. Note that your planet will begin as a _comet_, a wild ship drifting through cyberspace. So don't be alarmed if it doesn't have the name you expected -- all ships begin as such, at least for now. This step exists because you need to communicate with the Urbit network to authenticate your planet, and you need to have a ship of some sort to communicate with the Urbit network. > If you are booting a star, the process is the same as above, with your respective star name and ticket. If you are booting a galaxy, see [this Fora post](https://urbit.org/fora/posts/~2016.8.17..21.04.11..1450~/). If you do not have a ticket, you can still make a comet that stays as a comet. Pick your own directory name, it doesn't matter: ``` $ urbit -c mycomet ``` This will create the directory `mycomet/` and generate a 128-bit identity for your urbit. The identity of your comet will be random, but it will look like `~lantug-fitsum-tinrum-fitnys--silwes-docnet-solteb-lopten` in terms of length and structure. ## Orientation Booting your urbit takes about ten minutes. After that, you should see a `dojo>` prompt. Welcome! Note that "booting," in our usage, refers to starting a ship for the first time; a ship is considered "booted" if it has connected to the network. Its state is a pure function of its events, meaning that it has no concept of shutting down. While you can end an Urbit process, that termination won't be reflected in the state. When you start it up again, it will begin exactly where it left off, as if nothing happened. Your ship is quite bare-bones by default. A few user-facing apps are running by default: *Dojo*, our shell; *Talk*, our messaging app; *Clay*, our filesystem; *Tree*, our web interface. Let's stroll through them. ### Shell — Dojo The command prompt in front of you is a simple shell and Hoon REPL. Let's make sure it works: ``` ~your-urbit:dojo> (add 2 2) ``` Should produce: ``` > (add 2 2) 4 ``` Good. ### Filesystem — Clay Clay, the Urbit filesystem, isn't mounted to Unix by default. From the Dojo prompt, run: ``` ~your-urbit:dojo> |mount % ``` This should produce: ``` > |mount % >= ``` which indicates that the command was processed. `|mount %` will cause a `home/` directory to appear inside your pier folder in Unix. Changes to the contained files are automatically synced from Unix into your ship, and vice versa. For more information on Tree, check out the [Clay](../filesystem) section. ### Messaging — Talk Use `ctrl-x` to toggle your prompt. Let's join the main Urbit chat channel, `/urbit-meta`: ``` ~your-urbit:talk[] ;join /urbit-meta ``` Talk is stateful, so your urbit will download a backlog. `/urbit-meta` is the place to ask questions, get help, talk about anything Urbit-related, and meet everyone on here. For more information on the Dojo, check out the [Shell](../shell) section. ### Web — Tree Your ship is also accessible through its own web interface. If you're running Urbit locally on your own machine, try opening: ``` http://localhost:8080/~~/ ``` in your favorite browser. The actual port that's being used depends if other things (including other urbits) are running on port `8080` and its succeeding ports when your when your ship was turned on. To see what port is being used be a given ship, look for a message like `http: live (insecure, public) on 8081` when you start it up. Or if you're running your ship on a cloud instance with a static IP address (which we recommend!), something like `212.131.240.20`, assuming you've opened up the HTTP/HTTPS ports that Urbit uses (`8080` and `8443` by default), try opening: ``` http://212.131.240.20:8080/~~/ ``` This way, if you keep your ship running securely in the cloud (usually in a [`screen`](https://www.gnu.org/software/screen/) or [`tmux`](https://github.com/tmux/tmux/wiki) session), you can always access your ship's web interface in any browser on any device, so long as you have your password on hand. The `/~~/` in the URL will redirect you to a login page, which was generated by Tree, the basic Urbit web interface. The page will tell you to run the `+code` generator (an Urbit functional shell script) in your Dojo to get your password. Copy and paste that into your password input box and hit Enter. After loading, you'll find yourself redirected to your home page, authenticated, where you can then use the navigation bar at the top of the page to visit your Talk web interface and static files. You can also access your ship through `https://your-urbit.urbit.org/~~/`. Note that this latter approach is slower for the time being because we proxy over the Urbit network, Ames, but a better, faster solution for this is in the works. For more information on Tree, check out the [Web](../web) section. --- Here are a few other things you can do to get up and running: ### Discussion — Fora Fora is the place for long-form Urbit discussion, our take on the message board. It's hosted on an Urbit and served over HTTP via [Eyre](../web), Urbit's web server. Head on over to: ``` https://fora.urbit.org/~~/ ``` Like on your own web interface, you'll be redirected to a login page and prompted to run `+code` in your Dojo to retrieve your password and log in. After loading, you'll get redirected to the Fora home page where you can post and comment authenticated as your ship name. Like Talk, Fora is a great place to ask questions, get help, chat about anything Urbit, and see what's going on. ### Docs We host our docs on `urbit.org`, but it's faster to view them locally through your own ship's web interface. So we also host the docs on a Clay desk on one of our `urbit.org` planets named `~ladnub-lorwyn`, which you can merge and sync onto your live ship over the network. Run in your Dojo: ``` ~your-urbit:dojo> |sync %home ~ladnub-lorwyn %docs ``` Depending on network traffic, this initial merge and sync could take anywhere between thirty seconds to a few minutes. Upon a successful sync you'll see the output: ``` sync succeeded from %docs on ~ladnub-lorwyn to %home ``` If for some reason that doesn't work, head to the [urbit/docs](https://github.com/urbit/docs) repo and follow the local install steps. Otherwise, your docs are now live, and you can view them at: ``` http://localhost:8080/~~/docs ``` We'll update our planet's desk with new doc changes as they happen. You should get sync updates automatically through Clay over Ames. ## Learn more If you're eager to get started programming, you're ready to head over to [the Hoon tutorial](../../tutorials/hoon-ch1/). To learn more about using the system, let's keep going: