git.iko.soy/urbit.org
on 099c808 help sign in
urbit.org/docs/using/setup.umd
226 lines 6.3 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 is an append-only log and a checkpoint. Or, in
12simpler terms, a directory where we keep your urbit’s state. We call
13this a _pier_.
15## Initialize
17To create an urbit, we need an identity. This identity is both a network
18address and a memorable name.
20You are probably creating one of two kinds of urbit: a 32-bit _planet_
21or a 128-bit _comet_. For a quick terminology guide and high-level
22refresher, refer to this [handy reference sheet](../../about/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 `sampel-palnet/` and begin building your
33urbit. This may take a few minutes.
35> If you are booting a star, the process is the same as above, with your
36> respective star name and ticket.
37> If you are booting a galaxy, see
38> [this Fora post](https://urbit.org/fora/posts/~2016.8.17..21.04.11..1450~/).
40If you do not have a ticket, you can still make a _comet_, a wild urbit
41drifting through cyberspace. Pick your own directory name, it doesn't
42matter:
44```
45$ urbit -c mycomet
46```
48This will create the directory `mycomet/` and generate a 128-bit
49identity for your urbit.
51## Orientation
53After about five to ten minutes, when your urbit is finished booting,
54you should see a `dojo>` prompt. Welcome!
56By default your urbit is quite bare-bones. Let's stroll through what's
57already running:
59### Shell — Dojo
61The command prompt in front of you is a simple shell and Hoon REPL.
62Let's make sure it works:
64```
65~your-urbit:dojo> (add 2 2)
66```
68Should produce:
70```
71> (add 2 2)
73```
75Good.
78### Messaging — Talk
80Use `ctrl-x` to change your prompt. Let's join the main Urbit chat
81channel, `/urbit-meta`:
83```
84~your-urbit:talk[] ;join /urbit-meta
85```
87Talk is stateful, so your urbit will download a backlog.
88`/urbit-meta` is the place to ask questions, get help, talk about
89anything Urbit-related, and meet everyone on here.
91### Web — Tree
93Your Urbit is also accessible through its own web interface. If you're
94running Urbit locally on your own machine, try opening:
96```
97http://localhost:8080/~~/
98```
100in your favorite browser.
102Or if you're running your urbit on a cloud instance with a static IP
103address (which we recommend!), something like `212.131.240.20`, assuming
104you've opened up the HTTP/HTTPS ports that Urbit uses (`8080` and `8443`
105by default), try opening:
108```
109http://212.131.240.20:8080/~~/
110```
112This way, if you keep your urbit running securely in the cloud (usually
113in a [`screen`](https://www.gnu.org/software/screen/) or
114[`tmux`](https://github.com/tmux/tmux/wiki) session), you can always
115access your urbit's web interface in any browser on any device, so long
116as you have your password on hand.
118The `/~~/` in the URL will redirect you to a login page, which was
119generated by Tree, the basic Urbit web interface. The page will tell
120you to run the `+code` generator (an Urbit functional shell script) in
121your Dojo to get your password. Copy and paste that into your password
122input box and hit Enter. After loading, you'll find yourself redirected
123to your home page, authenticated, where you can then use the navigation
124bar at the top of the page to visit your Talk web interface and static
125files.
127You can also access your urbit through
128`https://your-urbit.urbit.org/~~/`. Note that this latter approach is
129slower for the time being because we proxy over the Urbit network, Ames,
130but a better, faster solution for this is in the works.
132### Filesystem — Clay
134Clay, the Urbit filesystem, isn't mounted to Unix by default. Switch
135to the Dojo prompt and run:
137```
138~your-urbit:dojo> |mount %
139```
141This should produce:
143```
144> |mount %
145>=
146```
148which indicates the command was processed.
150`|mount %` will cause a `home/` directory to appear inside your pier
151folder. Changes to these files are automatically synced into your urbit.
153<br />
155Here are a few other things you can do to get up and running:
157### Discussion — Fora
159Fora is the place for long-form Urbit discussion. It's hosted on an
160Urbit and served over HTTP via Eyre, Urbit's web server.
162Head on over to:
164```
165https://fora.urbit.org/~~/
166```
168Like on your own web interface, you'll be redirected to a login page and
169prompted to run `+code` in your Dojo to retrive your password and log
170in.
172After loading, you'll get redirected to the Fora home page where you
173can post and comment authenticated as your ship name. Like Talk, Fora
174is a great place to ask questions, get help, chat about anything Urbit, and
175see what's going on.
177### Docs
179We host our docs on `urbit.org`, but it's faster to view them locally
180through your own ship's web interface. So we also host the docs on a
181Clay desk on one of our `urbit.org` planets, which you can merge and
182sync onto your live ship over the network.
184Run in your Dojo:
186```
187~your-urbit:dojo> |sync %home ~ladnub-lorwyn %docs
188```
190Depending on network traffic, this initial merge and sync could take
191anywhere between thirty seconds to a few minutes.
193Upon a successful sync you'll see the output:
195```
196sync succeeded from %docs on ~ladnub-lorwyn to %home
197```
199If for some reason that doesn't work, head to the
200[urbit/docs](https://github.com/urbit/docs) repo and follow the local
201install steps.
203Otherwise, your docs are now live, and you can view them at:
205```
206http://localhost:8080/~~/docs
207```
209We'll update our planet's desk with new doc changes as they happen. You
210should get sync updates automatically through Clay over Ames.
212### Examples
214Similarly, we host some Urbit examples on our same `urbit.org` planet as
215above. Head to our [examples repo](https://github.com/urbit/examples) for
216full instructions if you're interested, though you may want to start
217with the [Urbyte](../../urbyte/), [Nock](../../nock/),
218[Hoon](../../hoon/) or [Arvo](../../arvo/) sections so you can really
219understand the example code.
221## Learn more
223If you're eager to get started programming you're ready to head over to
224[the Hoon section](../../hoon/mission/).
226To learn more about using the system, let's keep going: