git.iko.soy/urbit.org
on c2f44cf help sign in
urbit.org/docs/using/setup.umd
251 lines 7.8 kB history raw
1:- :~ navhome/'/docs/'
2 navuptwo/'true'
3 next/'true'
4 sort/'2'
5 title/'Setup'
6 ==
7;>
9# Getting started
11On disk, your urbit - also referred to as your _ship_ - is an append-only log
12and a checkpoint. Or, in simpler terms, a directory where we keep your urbit’s
13state. We call this a _pier_.
15## Initialize
17To create a ship, we need an identity. This identity is both a network
18address and a memorable name.
20You are probably creating one of two kinds of ships: a 32-bit _planet_
21or a 128-bit _comet_. For a quick terminology guide and high-level
22refresher, refer to this [handy reference sheet](../../reference/glossary/).
24If you have an Urbit invitation, you'll have a planet like
25`~sampel-palnet` and `~sampel-sompel-simpel-sampel`. To create your
26pier:
28```
29$ urbit -w sampel-palnet -t sampel-sompel-simpel-sampel
30```
32This will create a directory (pier) `sampel-palnet/` and begin building your
33ship. You can feel free to rename the directory, or append a `-c <piername>`
34to the end of it to give it a custom name from the start:
36```
37$ urbit -w sampel-palnet -t sampel-sompel-simpel-sampel -c myplanet
38```
40Booting may take a few minutes. Note that your planet will begin as a
41_comet_, a wild ship drifting through cyberspace. So don't be alarmed if it
42doesn't have the name you expected - all ships begin as such, at least for now.
43This step exists because you need to communicate with the Urbit network to
44authenticate your planet, and you need to have a ship of some sort to
45communicate with the Urbit network.
47> If you are booting a star, the process is the same as above, with your
48 respective star name and ticket.
49 If you are booting a galaxy, see
50 [this Fora post](https://urbit.org/fora/posts/~2016.8.17..21.04.11..1450~/).
52If you do not have a ticket, you can still make a comet that stays as a comet.
53Pick your own directory name, it doesn't matter:
55```
56$ urbit -c mycomet
57```
59This will create the directory `mycomet/` and generate a 128-bit
60identity for your urbit. The identity of your comet will be random, but it
61will look like `~lantug-fitsum-tinrum-fitnys--silwes-docnet-solteb-lopten` in
62terms of length and structure.
64## Orientation
66Booting your urbit takes about ten minutes. After that, you should see a `dojo>`
67prompt. Welcome!
69Note that "booting," in our usage, refers to starting a ship for the
70first time; a ship is considered "booted" if it has connected to the network.
71Its state is a pure function of its events, meaning that it has no concept of
72shutting down. While you can end an Urbit process, that termination won't be
73reflected in the state. When you start it up again, it will begin exactly where
74it left off, as if nothing happened.
76Your ship is quite bare-bones by default. A few user-facing apps are running by
77default: *Dojo*, our shell; *Talk*, our messaging app; *Clay*, our filesystem;
78*Tree*, our web interface. Let's stroll through them.
80### Shell — Dojo
82The command prompt in front of you is a simple shell and Hoon REPL. Let's make
83sure it works:
85```
86~your-urbit:dojo> (add 2 2)
87```
89Should produce:
91```
92> (add 2 2)
94```
96Good.
98### Filesystem — Clay
100Clay, the Urbit filesystem, isn't mounted to Unix by default. From the Dojo
101prompt, run:
103```
104~your-urbit:dojo> |mount %
105```
107This should produce:
109```
110> |mount %
111>=
112```
114which indicates that the command was processed.
116`|mount %` will cause a `home/` directory to appear inside your pier
117folder in Unix. Changes to the contained files are automatically synced from
118Unix into your ship, and vice versa.
120For more information on Tree, check out the [Clay](../filesystem) section.
122### Messaging — Talk
124Use `ctrl-x` to toggle your prompt. Let's join the main Urbit chat
125channel, `/urbit-meta`:
127```
128~your-urbit:talk[] ;join /urbit-meta
129```
131Talk is stateful, so your urbit will download a backlog.
132`/urbit-meta` is the place to ask questions, get help, talk about
133anything Urbit-related, and meet everyone on here.
135For more information on the Dojo, check out the [Shell](../shell) section.
137### Web — Tree
139Your ship is also accessible through its own web interface. If you're
140running Urbit locally on your own machine, try opening:
142```
143http://localhost:8080/~~/
144```
146in your favorite browser. The actual port that's being used depends
147if other things (including other urbits) are running on port `8080` and
148its succeeding ports when your when your ship was turned on. To see what port is
149being used be a given ship, look for a message like
150`http: live (insecure, public) on 8081` when you start it up.
152Or if you're running your ship on a cloud instance with a static IP
153address (which we recommend!), something like `212.131.240.20`, assuming
154you've opened up the HTTP/HTTPS ports that Urbit uses (`8080` and `8443`
155by default), try opening:
158```
159http://212.131.240.20:8080/~~/
160```
162This way, if you keep your ship running securely in the cloud (usually
163in a [`screen`](https://www.gnu.org/software/screen/) or
164[`tmux`](https://github.com/tmux/tmux/wiki) session), you can always
165access your ship's web interface in any browser on any device, so long
166as you have your password on hand.
168The `/~~/` in the URL will redirect you to a login page, which was
169generated by Tree, the basic Urbit web interface. The page will tell
170you to run the `+code` generator (an Urbit functional shell script) in
171your Dojo to get your password. Copy and paste that into your password
172input box and hit Enter. After loading, you'll find yourself redirected
173to your home page, authenticated, where you can then use the navigation
174bar at the top of the page to visit your Talk web interface and static
175files.
177You can also access your ship through `https://your-urbit.urbit.org/~~/`. Note
178that this latter approach is slower for the time being because we proxy over the
179Urbit network, Ames, but a better, faster solution for this is in the works.
181For more information on Tree, check out the [Web](../web) section.
184---
187Here are a few other things you can do to get up and running:
190### Discussion — Fora
192Fora is the place for long-form Urbit discussion, our take on the message
193board. It's hosted on an Urbit and served over HTTP via [Eyre](../web), Urbit's
194web server.
196Head on over to:
198```
199https://fora.urbit.org/~~/
200```
202Like on your own web interface, you'll be redirected to a login page and
203prompted to run `+code` in your Dojo to retrieve your password and log
204in.
206After loading, you'll get redirected to the Fora home page where you
207can post and comment authenticated as your ship name. Like Talk, Fora
208is a great place to ask questions, get help, chat about anything Urbit, and
209see what's going on.
211### Docs
213We host our docs on `urbit.org`, but it's faster to view them locally
214through your own ship's web interface. So we also host the docs on a
215Clay desk on one of our `urbit.org` planets named `~ladnub-lorwyn`, which you
216can merge and sync onto your live ship over the network.
218Run in your Dojo:
220```
221~your-urbit:dojo> |sync %home ~ladnub-lorwyn %docs
222```
224Depending on network traffic, this initial merge and sync could take
225anywhere between thirty seconds to a few minutes.
227Upon a successful sync you'll see the output:
229```
230sync succeeded from %docs on ~ladnub-lorwyn to %home
231```
233If for some reason that doesn't work, head to the
234[urbit/docs](https://github.com/urbit/docs) repo and follow the local
235install steps.
237Otherwise, your docs are now live, and you can view them at:
239```
240http://localhost:8080/~~/docs
241```
243We'll update our planet's desk with new doc changes as they happen. You
244should get sync updates automatically through Clay over Ames.
246## Learn more
248If you're eager to get started programming, you're ready to head over to
249[the Hoon tutorial](../../tutorials/hoon-ch1/).
251To learn more about using the system, let's keep going: