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