@@ -1,27 +1,106 @@
11+++
2−title = "Getting Started"
2+title = "Getting started with Urbit"
33weight = 0
44description = "How to install Urbit."
55page_template = "page_indiced.html"
66template = "getting-started/index.html"
77+++
88
9−Don't know what Urbit is? Spend ten minutes or so reading our page on
10−[Understanding Urbit](/understanding-urbit/).
9+Nothing about building a new OS from scratch has been easy. Or creating an identity system that adequately replaces the
10+IP address.
1111
12−If you want to jump right in and try out Urbit with a free, disposible ID called a **Comet**, you can download the desktop app [**Port**](#port). Once installed, start it up and hit the `Start without an ID` button. It'll take a few minutes to spin up the new Comet, then click `Launch Ship into Urbit` and you'll be at the login screen. Click on `Copy Access Key` at the bottom-left, paste it into the `Access Key` field, and hit `Continue`. You'll now be at your ship's home screen and ready to explore Urbit. You can also have a look at the [Next Steps](#next-steps) section below to help you get going.
12+Getting on Urbit isn't always easy, either. The onboarding process hasn't been optimized by product managers in search
13+of maximal profit. There's no checkbox for your interests—you have to discover them yourself.
1314
14−If you want to get a permanent Urbit ID called a **Planet**, have a look at the [Get a planet](#get-a-planet) section below.
15+But we like to think this hard work is exactly what makes Urbit special. **Consider yourself warned.**
1516
16−If you have a **Planet** and want some help getting it up and running the first time, see the [Setting up your urbit](/getting-started/planet) guide.
17+Why should you keep going? Urbit is a new computing stack based on you owning your networks, identity, and data. It's
18+well on its way to becoming your Final Computer.
1719
18−If you want to use a **Planet** without worrying about the gritty bits, you may want to consider a [hosting provider](#hosting-providers).
20+- **As a user**, you can explore the people, community, and sheer novelty of the Urbit ecosystem while owning your
21+ entire experience. Your data, your messages, your apps.
22+- **As a developer**, you can now build apps, a protocol for a whole suite of apps, or an entire online subculture, and
23+ distribute your work directly to your users' operating systems. No middlemen, no MEGACORPs, and no lock-in.
1924
20−If you're technically proficient and would like greater control over the Urbit virtual machine than is possible with [Port](#port), or are setting up Urbit on a cloud droplet, try [installation using the command line](/getting-started/cli).
25+Someone once said, "All the smart people I know disappear into Urbit." If you're smart, you will too — not just
26+installing and running Urbit, but taking the first step toward deploying your Final Computer.
2127
22−## Get Port {#port}
28+## Launch into Urbit
2329
24−**Port** is a desktop GUI application that allows you to spin up, access, and manage your Urbit ships without any knowledge of the command line or Urbit binary.
30+Choose how you want to disappear into Urbit.
31+
32+<div id="launch-type" class="grid grid-cols-1 lg:grid-cols-3 gap-4">
33+ <a class="type block !p-8 bg-wall-100 rounded-xl hover:bg-wall-200 hover:opacity-100" href="#easy-steps">
34+
35+### Easy
36+
37+Deploy Urbit on your local system
38+
39+- Zero cost to you
40+- Setup in minutes using a desktop GUI
41+
42+- Not a permanent way to use Urbit
43+
44+ </a>
45+ <a class="type block p-8 bg-wall-100 rounded-xl hover:bg-wall-200 hover:opacity-100" href="#fun-steps">
46+
47+### Fun
48+
49+Deploy Urbit on a cloud/VPS provider
50+
51+- Self-host and own your data
52+- Portable identity and data accessible from anywhere
53+
54+- Requires investment in planet (one-time) and cloud service (monthly)
55+- Requires Linux proficiency
56+
57+ </a>
58+ <a class="type block p-8 bg-wall-100 rounded-xl hover:bg-wall-200 hover:opacity-100" href="#hosted-steps">
59+
60+### Hosted
61+
62+Deploy Urbit on a managed service
63+
64+- Streamlined setup for ownership and identity
65+- No technical proficiency required
66+
67+- Need to trust your provider
68+- Requires monthly investment
69+
70+ </a>
71+</div>
72+
73+<style>
74+ .type h3 {
75+ margin-bottom: 0.5rem;
76+ }
77+ .type > p {
78+ font-size: 1rem;
79+ margin-top: 0.5rem;
80+ margin-bottom: 0.5rem;
81+ }
82+ .type ul {
83+ margin-top: 1rem;
84+ margin-bottom: 0rem;
85+ }
86+ .type li {
87+ margin-top: 0.2rem;
88+ margin-bottom: 0.2rem;
89+ }
90+ .type li p {
91+ font-size: 0.925rem;
92+ }
93+</style>
94+
95+## Easy {#easy-steps}
96+
97+### Get Port
98+
99+Port is a desktop GUI application that allows you to spin up, access, and manage your Urbit ships without any knowledge
100+of the command line or Urbit binary.
101+
102+Port isn't considered a permanent way to run Urbit, but you can start with it now and migrate your data to a VPS/cloud
103+provider later using scp.
25104
26105<div id="port-os" class="os mv3">
27106 <input type="radio" id="port-macos" name="port-os" checked>
@@ -97,36 +176,259 @@ Or to install `snap` for your distribution, snapcraft provides [installation ins
97176}
98177</style>
99178
100−## Get a planet
179+### Launch a comet without an Urbit ID
180+
181+Start Port and hit the **Start without an ID** button. It'll take a few minutes to spin up the new comet. Once that's
182+finished, click **Launch Ship into Urbit** and you'll be at the login screen.
183+
184+> Want to combine the simplicity of Port with a permanent Urbit ID?
185+>
186+> If you already have a planet, first get your keyfile using the steps below. Start Port, click the **Boot a fresh ID**
187+> option. Give your ship a name, and in the **Shipname** field, enter your planet name, like `~sampel-palnet`. For the
188+> **Key File** field, browse to the keyfile, select it, and hit **Continue**. Port will boot your Urbit in a few
189+> minutes!
190+
191+### Log in
192+
193+Within Port, click on **Copy Access Key**, paste it into the **Access Key** field, and hit **Continue**. You'll now be
194+at your ship's home screen and ready to explore Urbit.
195+
196+Jump ahead to the [getting around your Urbit](#get-around-your-urbit) section for more.
197+
198+## Fun {#fun-steps}
199+
200+### Get yourself a planet
201+
202+Here's some of the hard fun work we talked about earlier. While you can purchase a planet, we recommend asking for one.
203+Find someone who can give you a planet and make your case! That's the spirit of Urbit, after all — novel and esoteric.
204+
205+- Ask for one on Twitter! Start with [@urbit](https://twitter.com/urbit) and explore from there.
206+- Go back to the instructions for launching a [temporary comet with Port](#easy-steps), get yourself onto the network,
207+ find a group, and start conversations with people with planets to spare.
208+
209+An invitation to claim your planet comes in one of two forms. The first is an email invitation with an Urbit ID and a
210+Master Ticket. The second, only recently made available through our [Layer 2 (L2)
211+solution](/getting-started/layer-2-for-planets), is an activation code or a link to activate on Bridge.
212+
213+### Use Bridge to get your keyfile
214+
215+Now that you have your planet, you can create your keyfile (`sample-palnet.key`), which is the cryptographic signature
216+required to encrypt and decrypt messages on Urbit's P2P network.
217+
218+If you don't already have your keyfile — a common situation for those receiving a L2 planet in particular — you can
219+download one from [Bridge](https://bridge.urbit.org/).
220+
221+Login to Bridge and choose the **Master Ticket** option. Enter the name of your newly-acquired planet and the Master
222+Ticket password. Click the **ID** box near the bottom of the page, then the** Download Passport** button to download a
223+`.zip` file (named `sampel-palnet-passport.zip`), which contains your keyfile.
224+
225+**[screenshot of the ID section on Bridge, once you've authenticated, with the Download Passport button visible]**
226+
227+Unzip the passport to access your keyfile and the Master Ticket secret, which you should store somewhere secure. You'll
228+use your keyfile in the next step.
229+
230+### Install Urbit via the command line
231+
232+These fun instructions assume you have access to a **remote Linux system** running at a **VPS or cloud provider** of
233+your choice. If you want to run Urbit locally, whether on Linux, macOS, or Windows, you can adapt the [command line
234+install instructions](/getting-started/cli) for your base OS to what you'll find below.
235+
236+You may also want to see the [cloud hosting guide](/using/running/hosting) for additional details like setting your
237+domain name and establishing a firewall, but for now, we'll focus on getting you set up as soon as possible.
238+
239+Download Urbit with the following:
240+
241+```
242+mkdir ~/urbit
243+cd ~/urbit
244+wget --content-disposition https://urbit.org/install/linux64/latest
245+tar zxvf ./linux64.tgz --strip=1
246+```
247+
248+Next, transfer your `keyfile.key` to your server using scp or an FTP client, then move it to the `~/urbit` directory you
249+created in the last step.
250+
251+Now you can run Urbit for the first time. Run the below command, replacing `ames_port` with a public port number between
252+`49152` to `65535`, `sampel-palnet` with the name of your planet, and `sampel-palnet.key` with the name of your keyfile.
253+
254+```
255+./urbit -p ames_port -w sampel-palnet -k ./sampel-palnet.key
256+```
257+
258+Arvo, the Urbit OS, now creates a directory called `sampel-palnet/` and begins booting your planet and establishing
259+connections with the P2P network. When that's finished, you'll see Dojo, the Urbit command line:
260+
261+```
262+~sampel-palnet:dojo>
263+```
264+
265+Welcome to Urbit! You can skip ahead to [log in](#fun-log-in), or stick around for some tips.
266+
267+### The aforementioned tips
268+
269+Check out the [cloud hosting guide](/using/running/hosting) for tips on improving the environment for Urbit, with a
270+particular focus on establishing your domain name and using SSL for encryption.
271+
272+Shut down your planet by typing `Ctrl+D` into Dojo.
273+
274+To boot your planet up again, run the following command, once again replacing `ames_port` with the port you used
275+previously, and now referencing your planet's folder.
276+
277+```
278+./urbit -p ames_port sampel-palnet
279+```
280+
281+Your planet's folder, `sampel-palnet/`, is called your **pier**, and it holds all your data. If you want to migrate your
282+data from one system to another, you must bring your pier.
283+
284+You should also delete your keyfile from your remote system to prevent yourself from using the same key twice, which
285+will cause communication problems with other planets.
286+
287+```
288+rm ./my-planet.key
289+```
290+
291+### Log in {#fun-log-in}
292+
293+First, use your browser to navigate to the URL+port where your ship is running. This could be an IP address or a
294+fully-qualified domain name, depending on how you set yours up.
295+
296+Instead of a static password, Urbit uses an Access Key, which is given by your ship itself.
297+
298+Open up the Urbit CLI again if it's not still running, and enter `+code`. The output is your Access Key, which you need
299+to copy and paste into your browser. Click **Continue** to finish authentication and log in.
300+
301+Jump ahead to the [getting around your Urbit](#get-around-your-urbit) section for more.
302+
303+## Hosted {#hosted-steps}
304+
305+Hosting providers can sell you a planet and manage the hosting for you for a regular fee. We recommend [Urbit
306+Host](https://urbithost.com/) (not directly affiliated with Urbit) for quickly acquiring a planet and the hosting
307+required to make your Urbit experience accessible from anywhere.
308+
309+Two important points about hosting providers:
310+
311+- Because the provider has access to the resources that run your Urbit experience, you must trust them with your data.
312+- Urbit has portable data, so you should be able to work with a hosting provider to download all your data and boot up
313+ elsewhere if you choose to migrate or start self-hosting.
314+
315+### Log in
316+
317+The exact steps for logging into your Urbit will depend on your hosting provider's infrastructure and the flow they've
318+developed. If you have questions about logging into your hosted Urbit ship, contact their support.
319+
320+Check out the next section for more.
321+
322+## Get around your Urbit
323+
324+After you've logged into your Urbit for the first time, you're officially an Urbiter! You've unlocked the entire Urbit
325+network with your newly-minted ID — the key to your new digital life.
326+
327+**SCREENSHOT**
328+
329+You'll see your Home and a few pre-installed applications: Terminal, Groups, and Bitcoin. More on them in a moment.
330+
331+Above those are buttons to view **System Preferences** and **Help and Support** and check out notifications for
332+newly-installed or recently-updated applications, respectively. The search bar helps you surface applications you
333+already have installed, or discover developers and applications across the Urbit network.
334+
335+You'll likely want to focus on finding and joining new communities, which you can do with the **Groups** app, which is
336+sometimes referred to as Landscape. Click on the box to open the application.
337+
338+## Join a few groups with fellow Urbiters
339+
340+No two people will ever have the same experience on Urbit. That depends entirely on who you find and where they invite
341+you to join them. But we can set you down a good path.
342+
343+With Groups open, you'll see three boxes for **My Channels**, your local weather, and a stylized clock. You can dig into
344+those later, but let's focus on joining new communities, which is likely one of the reasons you wanted to try out Urbit
345+in the first place.
346+
347+Click on **Join Group**, and in that modal, enter `~bitbet-bolbel/urbit-community` — the official Urbit community. You
348+can either automatically join all channels by clicking the Join all channels checkbox, or leave it blank and hit Join
349+Group right away. Your Urbit will connect to the P2P network and download information about the group, like a list of
350+all its participants. When that's finished, click **View Group**.
351+
352+You're now looking at a single group and all of its channels. If you didn't choose to join all channels right away,
353+click on an individual channel and then **Join Channel**, which immediately opens the feed of latest messages.
354+
355+Here are a few more useful groups to join:
356+
357+- `~wolref-podlex/foundation`: The official community for the Urbit Foundation, which is one of the organizations behind
358+ Urbit's development. There are channels around pitching Urbit to others, applying for grants, planning meetups, and
359+ much more.
360+- `~rondev/group-discovery`: A group for finding other groups.
361+- `~middev/the-forge`: A group for sharing, discussing, discovering new Urbit applications.
362+- `~hocwyn-tipwex/uqbar-event-horizon`: A community around [Uqbar](https://uqbar.network/), a company creating
363+ applications and experiences on top of Urbit — notably EScape, which is an alternative to the default Groups
364+ application for joining communities and messaging with other Urbiters.
365+
366+## Get more Urbit apps
367+
368+Groups are great, but Urbit goes way deeper with apps that are developed specifically for Urbit and use P2P networking
369+for everything.
370+
371+We'll use Canvas — a collaborative app for creating pixel art with others — as an example to show the process.
372+
373+Head back to your Urbit's home — the URL you used to log in and view your preinstalled apps. From there, click on the
374+search bar and enter `~dister-norsyr-torryn/canvas`. Click on the first result, which shows you details about the
375+developer, the license, a website for more information, and when the app was last updated.
376+
377+Click **Get App**, then **Get "Canvas"** to continue. Your Urbit gets to work, and once installation is finished, click
378+**Open App** to see it in action.
379+
380+Some popular apps to get things moving:
381+
382+- **EScape** / `~dister-fabnev-hinmur/escape`: An alternative UI to the core groups, communities, and messaging
383+ capabilities in Urbit.
384+- **Studio** / `~tirrel/studio`: Tools for making money on the Urbit network.
385+- **Wrdu** / `~magped-magped-rabsef-bicrym/wrdu`: A Wordle clone.
386+- **cliff** / `~paldev/cliff`: An filesystem explorer for your ship.
387+
388+Don't forget [awesome-urbit](https://github.com/urbit/awesome-urbit) on GitHub. Some of the applications there require
389+more manual setup, but they're all Urbit-first.
390+
391+## Get help
392+
393+If you need help getting around Urbit, the best place to go is the official Urbit community:
394+`~bitbet-bolbel/urbit-community`. Those in the Help channel are willing to troubleshoot or provide links to resources to
395+help you get out of a jam.
396+
397+That community isn't for every support request, however. If your question involves an app, you're better served reaching
398+out to the developer — for example, if you have an issue with EScape's notifications feature, reach out to Uqbar in
399+`~hocwyn-tipwex/uqbar-event-horizon`.
101400
102−There are a few ways to get your own planet:
401+If you're having trouble with your planet or the hosting provider that's running your ship, try their support, as
402+they'll have more context and resources to help solve your issue.
103403
104−- Getting an invitation from a friend (or stranger).
105−- Purchasing a planet, including hosting, from a [hosting provider](#hosting-providers).
106−- Manually setting up and hosting a planet purchased from a third party such as [azimuth.shop](https://azimuth.shop/), [urbit.live](https://urbit.live), [urbit.me](https://urbit.me), [Urbitex](https://urbitex.io), [Urbit Marketplace](https://urbitmarketplace.com/), or [Wexpert Systems](https://wexpert.systems).
404+And if you can't get through this guide and launch into Urbit, you may have luck with the [urbit live
405+community](https://t.me/UrbitLiveGroup) on Telegram.
107406
108−## Hosting Providers {#hosting-providers}
407+## What's next?
109408
110−Hosting providers will often sell you a planet and run it for you. This option is very simple but will probably cost a regular fee.
409+You made it! You did the work and now have your Final Computer.
111410
112−Urbit is designed to be portable. This means that if you sign up for hosting now but later want to leave your hosting provider and run your Urbit yourself, you should be able to work with them to obtain all of your data and boot your planet back up without losing anything.
411+What you do with it is up to you. Where you go from here is up to you. No two experiences on Urbit will be the same, so
412+we encourage you to follow your own. Explore. Discover! Get lost and find the people who make you feel like you're not
413+lost any more.
113414
114−Using hosting does mean that you're trusting your provider with your data, but so long as you have your planet, you'll always own your identity.
415+Still need some bumpers to guide you along the way?
115416
116−Current hosting providers are:
417+**Learn more about using Urbit**: Check out the [User's Manual](/using).
117418
118−- [escape pod store](https://www.escapepod.store/)
119−- [Third Earth](https://third.earth/)
120−- [Tlon Corporation](https://tlon.io)
121−- [UrbitHost](https://urbithost.com)
419+**Get updates about Urbit**:
420+[Subscribe](https://urbit.us11.list-manage.com/subscribe/post?u=972a03db9e0c6c25bb58de8c8&id=be143888d2) to the
421+Urbit Newsletter for new blog posts and events from one of the primary organizations responsible for Urbit development.
122422
123−## Next steps
423+**Join an event or meetup**: Many of the organizations and people behind Urbit host virtual and in-person events on a
424+regular basis — check out the latest on our [Events feed](/events).
124425
125−Once you've got your ship up and running, you might like to join the official Urbit Community group and say hello. Just click on the `Groups` app and it will open Urbit's communications suite. In Groups, hit `Join Group` and enter `~bitbet-bolbel/urbit-community`. Once joined, a new tile for the group will appear on the Groups home screen. Open that, click on the `General` channel in the sidebar, and hit `Join Channel`. It'll take a couple of minutes to download the chat history, then you'll be able to post a message.
426+**Learn how to build on Urbit**: If you're the kind of person who wants to build applications directly for discerning
427+communities with built-in identity and networking primitives, or even jump into the Urbit kernel's core, we have the
428+most phenomenally-comprehensive information to get you started.
126429
127−If you haven't already done so, we recommend spending a few minutes reading
128−[Understanding Urbit](/understanding-urbit) to get acquainted with the project.
129−Then once you've been become acquainted with your ship and explored the network
130−for awhile, consider checking out the [User's Manual](/using) which provides
131−guidance and reference material for operating your ship, as well as explanations
132−for Urbit concepts everyone should eventually learn.
430+- Read the [Development Docs](/docs).
431+- Check out the development-driven [Getting Started guide](/docs/development/develop).
432+- Join [Hoon School Live (HSL)](https://hooniversity.org/), the cohort-driven course that teaches you Hoon, with the
433+ goal of getting you comfortable writing generators, working with core concepts, using the standard library, and
434+ distributing code using desks.