@@ -1,216 +0,0 @@
1−+++
2−title = "Setting up your urbit"
3−weight = 2
4−description = "Getting started with a permanent Urbit identity."
5−+++
6−
7−A planet is a permanent Urbit identity. Like all Urbit identities, they can
8−never be taken away from you. Unlike comets which are free, planets are designed
9−for use well into the future. If you're not yet familiar with the Urbit network
10−and are looking to try it out with a free Comet, are looking to purchase a
11−planet, or are looking for an easy hosting solution, see the [Getting Started
12−guide](/getting-started/) instead. This guide is for those who have already
13−obtained a planet and want to get it running for the first time.
14−
15−## Step 1: Keyfile {#keyfile}
16−
17−The Urbit runtime needs a planet's keyfile in order to boot it up for the first
18−time. The keyfile contains the private cryptographic keys necessary for a planet
19−to sign messages it sends and decrypt messages it receives. These keys are
20−separate from either your Master Ticket (if applicable) or the Ethereum keys
21−used to manage your Urbit ID. The method to obtain your planet's keyfile differs
22−slightly, depending on whether you're on a Master Ticket or use an alternative
23−custody method like a Metamask wallet, hardware wallet, etc.
24−
25−### Master Ticket
26−
27−A Master Ticket is like a paper wallet for your planet. From the planet name and
28−Master Ticket password, [Bridge](https://bridge.urbit.org) can derive everything
29−necessary to manage your Urbit ID, such as Ethereum addresses, networking keys,
30−and so on.
31−
32−If you received an email invite to Urbit or were otherwise given an invite URL
33−and claimed your planet that way, you'll likely be on a Master Ticket. To get
34−the keyfile, you can look in the `.zip` file you downloaded when claiming your
35−planet - it'll be named `sampel-palnet-1.key` (except with your planet rather
36−than `sampel-palnet`).
37−
38−If you have misplaced that `.key` file, you can also download it from
39−[Bridge](https://bridge.urbit.org). First, login to Bridge with your planet name
40−and Master Ticket password. Once in, click on `OS` and then `Download Arvo Keyfile`.
41−
42−### Other methods
43−
44−If you bought your planet from a third party such as
45−[OpenSea](https://opensea.io), [urbit.live](#https://urbit.live), or another
46−[third party](/getting-started#get-a-planet), or otherwise if someone
47−transferred the planet to an Ethereum address you own, you will probably not be
48−on a Master Ticket. This is perfectly fine and you don't need to transfer your
49−planet to a Master Ticket if you don't want to. The one small difference,
50−though, is that Bridge will not have automatically derived your keyfile.
51−Instead, you'll need to login to [Bridge](https://bridge.urbit.org) and perform
52−a transaction to set your Networking keys.
53−
54−When you visit [Bridge](https://bridge.urbit.org), you'll need to select the
55−login option that says `Metamask, Mnemonic, Hardware Wallet...`, and it will
56−have a list of options:
57−
58−- `Metamask` - If your planet is owned by your Metamask wallet, select this. It
59− may prompt you to login to Metamask, then it will ask you to sign the `Bridge Authentication Token`. Once signed, you'll be logged into Bridge.
60−
61−- `Ledger` and `Trezor` - If your planet is owned by one of these hardware
62− wallets, select the appropriate one and follow its connection process.
63−
64−- `WalletConnect` - If your planet is owned by a wallet which supports the
65− WalletConnect protocol, select this and either scan the QR code or select one
66− of the desktop options.
67−
68−- `Mnemonic`, `Ethereum Private Key` and `Ethereum Keystore` - If your planet is
69− owned by another Ethereum wallet which does not support WalletConnect, you can
70− still login with one of these. `Mnemonic` lets you paste in the BIP39 mnemonic
71− seed phrase (a series of random words) for your wallet. `Ethereum Private Key`, as the name suggests, lets you paste in the private key of the Ethereum
72− address which owns your planet. `Ethereum Keystore` lets you upload an
73− Ethereum keystore file and specify its password for decryption.
74−
75−<small>Note: Bridge runs purely in your local browser, it does not transfer any
76−secrets across the network or store any secrets on a remote server. If you'd
77−prefer though, it's also possible to run the Bridge software locally (though
78−it's a little more more complicated), see the [Readme in the Bridge Github
79−repo](https://github.com/urbit/bridge) for details.</small>
80−
81−If you've been transferred a planet and not yet accepted it, you'll need to do
82−that first (you can skip this bit if you've already done it). Having logged in
83−with one of the methods described above, you'll see see an `Incoming Transfer`
84−request. Click `Accept`, then click `Generate & Sign Transaction` (This will
85−require some ETH for transaction fees). Once the transaction's complete, click
86−on `return`.
87−
88−Now that you're logged in to Bridge and have your planet, you can set the
89−networking keys. From the main screen for your planet, hit `OS` and then
90−`Initialize Networking Keys`. If the planet has never been spawned before, you
91−can leave `Breach Continuity` unchecked. Send the transaction (this will require
92−some ETH for transaction fees). Once complete, you can click `Download Arvo Keyfile` and save the `.key` file on your computer.
93−
94−## Step 2: Install
95−
96−Urbit must run on an existing computer somewhere. Some users run their planet on
97−their personal computer, but we recommend eventually using a cloud service
98−(Digital Ocean, Linode, etc) because it allows your planet to be accessed from
99−anywhere on multiple devices. Hosting your planet in the cloud also allows it to
100−always be online and ready for automatic updates. You are welcome to run from
101−your personal computer and switch to the cloud later...all without losing any
102−data!
103−
104−### Port
105−
106−Port is an Urbit GUI application available for MacOS, Linux and Windows. This
107−option is much easier but runs locally rather than in the cloud. Note that if
108−you have your planet in the cloud, Port can also be used as a client to connect
109−to your planet's web interface. [You can download Port
110−here](/getting-started#port).
111−
112−### Command line
113−
114−Running Urbit from the command line is suitable for either a cloud installation
115−or a local installation. If you're comfortable with the command line and would
116−like greater control over the Urbit virtual machine, this is the right option.
117−The Urbit runtime is available for Linux, MacOS and Windows.
118−Additionally, there are guides for [hosting your planet on
119−DigitalOcean](/using/running/hosting) and [hosting your planet on Linode
120−(external
121−link)](https://jeremytunnell.com/2021/01/09/how-to-install-urbit-on-a-linode-vps),
122−though most other cloud providers should be fine as well. [See here for download
123−and installation instructions](/getting-started/cli).
124−
125−## Step 3: Boot
126−
127−### Port
128−
129−If you've decided to use Port, booting is very simple. Just start up Port and select `Boot a fresh ID`. Then, give your ship a name in the `Name` field - this is just for convenience, a label used locally by Port to identify your planet. In the `Shipname` field, just enter your planet name like `~sampel-palnet`. Lastly, for the `Key File`, you can browse to the keyfile you downloaded in [Step 2](#keyfile), select it, and hit `Continue`. It'll take a few minutes to boot up your ship, and then you should be good to go.
130−
131−**Important:** once a key has been used to boot a planet onto the network, it
132−cannot be used to boot that planet again later - doing so will cause
133−communication problems with other planets. For this reason you should **delete
134−the keyfile from your machine once your planet has booted successfully**. If you
135−do use the same key twice, you'll need to reset your planet to restore its
136−functionality.
137−
138−### Command line
139−
140−For other ships on the network to communicate with your ship, the computer it's
141−running on needs to be able to receive inbound UDP traffic. Therefore, it's
142−important when running your ship locally to use the `-p ames_port` flag (replace
143−`ames_port` with a public port number from 49152 to 65535) to specify on which
144−port you'll receive UDP traffic, and to forward inbound UDP traffic arriving at
145−your router on that port to your computer.
146−
147−Navigate to your `urbit` directory. Open your keyfile (it is just a text file)
148−and copy the key inside to the clipboard. Paste it into the following command,
149−except with `ames_port` replaced with a public port number, and `sampel-palnet`
150−replaced by the name of your planet. **Do not include the tilde in your planet
151−name.**
152−
153−```sh
154−./urbit -p ames_port -w sampel-palnet -G rAnDoMkEy
155−```
156−
157−Or you can copy the keyfile into the current directory and run:
158−
159−```sh
160−./urbit -p ames_port -w sampel-palnet -k ./my-planet.key
161−```
162−
163−Either command will create a directory called `sampel-palnet/` and begin booting
164−your planet. It may take a few minutes.
165−
166−When your planet is finished booting, you will see `~sampel-palnet:dojo>` (Dojo:
167−the Urbit command line).
168−
169−To log into [Landscape](/docs/glossary/landscape), check out the directions
170−[here](/getting-started/#using-landscape).
171−
172−To shut down your planet, use `Ctrl-D`.
173−
174−To start your planet up again, run the following from your `urbit` directory,
175−with `ames_port` replaced with the public port number you used when first
176−booting your ship.
177−
178−```sh
179−./urbit -p ames_port sampel-palnet
180−```
181−
182−Note that `sampel-palnet/` is the path of a folder, which we just created in
183−your `urbit` directory. This folder is called your planet's **pier**, and it
184−holds all of your data.
185−
186−Never boot multiple instances of your planet at the same time. You can prevent
187−this from happening on accident by only ever keeping a single copy of your pier.
188−
189−**Important:** once a key has been used to boot a planet onto the network, it
190−cannot be used to boot that planet again later - doing so will cause
191−communication problems with other planets. For this reason you should **delete
192−the keyfile from your machine once your planet has booted successfully**. If you
193−do use the same key twice, you'll need to reset your planet to restore its
194−functionality.
195−
196−Delete the keyfile with the command below:
197−
198−```sh
199−rm ./my-planet.key
200−```
201−
202−## Next Steps
203−
204−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.
205−
206−If you haven't already done so, we recommend spending a few minutes reading
207−[Understanding Urbit](/understanding-urbit) to get acquainted with the project.
208−Then once you've been become acquainted with your ship and explored the network
209−for awhile, consider checking out the [User's Manual](/using) which provides
210−guidance and reference material for operating your ship, as well as explanations
211−for Urbit concepts everyone should eventually learn.
212−
213−If you're interested in developing on Urbit, check out:
214−
215−- [Learn to Develop on Urbit](/docs/development/develop): Learn how to
216− contribute to or develop on Urbit.