@@ -0,0 +1,157 @@
1++++
2+title = "Port"
3+template = "doc.html"
4+weight = 1
5++++
6+
7+Port is a desktop GUI application that allows you to spin up, access, and manage
8+your Urbit ships without any knowledge of the command line or Urbit binary.
9+
10+## Features
11+
12+- Boot a new comet, planet, moon or star.
13+- Import an existing pier
14+- Use a ship via its web interface.
15+- Manage and run multiple ships.
16+- Connect to the web interface of a remote ship.
17+- Start/stop a ship.
18+- Export a pier in a zip file.
19+
20+## Install
21+
22+Port is available for Linux, MacOS and Windows. See the [Getting
23+Started](/getting-started#port) for installation instructions.
24+
25+## Boot a comet
26+
27+With Port freshly installed, you can select `Start without an ID` on its home
28+screen. If Port already has other ships installed, you can navigate to `Home`,
29+drop down the `Boot Menu` and select `Comet`. You'll be presented with the
30+following screen:
31+
32+
33+
34+Give your comet a name in the `Name` field. This name is just displayed locally
35+in Port for convenience. Next, hit `Continue`. It'll take a few minutes to spin
36+up the new Comet, then you can click on `Launch Ship into Urbit` and it'll take
37+you to the login screen. Click on `Copy Access Key` at the bottom-left, paste it
38+into the `Access Key` field, and hit `Continue`. You'll now be at your ship's
39+home screen and ready to explore Urbit.
40+
41+## Boot another ship
42+
43+**Important: This is for booting a ship for the first time, or for booting a
44+ship which has just undergone a [breach](/docs/glossary/breach). A ship should
45+only be booted from its keyfile in its current
46+[rift](/docs/azimuth/life-and-rift#rift) once. If your ship has already been
47+booted elsewhere, see the [Import pier](#import-pier) section instead.**
48+
49+With Port freshly installed, you can select `Boot a fresh ID` on its home
50+screen. If Port already has other ships installed, you can navigate to `Home`,
51+drop down the `Boot Menu` and select either `Planet`, `Moon` or `Star` depending
52+on the kind of ship you're booting. You'll be presented with a screen that looks
53+something like this:
54+
55+
56+
57+Enter a name for your ship in the `Name` field. This name is just displayed
58+locally in Port for convenience. Next, enter your ship's name (e.g.
59+`~sampel-palnet`) in the `Shipname` field. For `Key File`, select `Choose Key File` and browse to its location on your computer. If you don't have your
60+keyfile yet, see _step one_ of the [Setting up your
61+urbit](/getting-started/planet#keyfile) guide. Once you've selected the keyfile,
62+hit `Continue`.
63+
64+It'll take a few minutes to spin up the ship, then you can click `Launch Ship into Urbit` and it'll take you to the login screen. Click `Copy Access Key` at
65+the bottom-left, paste it into the `Access Key` field, and hit `Continue`.
66+You'll now be at your ship's home screen and ready to explore Urbit.
67+
68+## Import pier
69+
70+Port can import existing [piers](/docs/glossary/pier). For example, if you've
71+been running your ship with the Urbit binary from the command line, and would
72+now like to run it with Port instead, you can do so.
73+
74+With Port freshly installed, you can hit `See More Options` on the home screen
75+and then `Boot an existing ship`. It should bring up this screen:
76+
77+
78+
79+In the `Name` field, give your ship a name. This name is just displayed locally
80+in Port for convenience. Next, select the type of the ship you're importing from
81+the `Ship Type` drop-down menu. Under `Upload Pier`, click `Choose Directory`,
82+then browse to your pier in the file system.
83+
84+**Important: Make sure you have shut down your pier before trying to import it.**
85+
86+By default, Port will move it into its own directory for piers it manages. If
87+you want to keep it in its current location instead, check the `Keep pier in current directory` checkbox. Finally, hit `Continue` and then `Launch Ship into Urbit` and it'll take you to the login screen. Click `Copy Access Key` at the
88+bottom-left, paste it into the `Access Key` field, and hit `Continue`. You'll
89+now be at your ship's home screen.
90+
91+## Connect to remote
92+
93+Rather than running ships locally, Port can also connect to remote ships, for
94+example those running on cloud servers. This simply connects to the web
95+interface of the remote ship, it doesn't move its pier.
96+
97+With Port freshly installed, you can hit `See More Options` on the home screen
98+and then `Access remote ship`. It should bring up this screen:
99+
100+
101+
102+In the `Name` field, give your ship a name. This name is just displayed locally
103+in Port for convenience. Next, enter the full URL (including the `http[s]://`
104+part) of the remote ship's web interface and hit `Continue`. You'll now be at
105+your ship's login screen. Enter your web code and login, you'll now be able to
106+use it from Port.
107+
108+If you want to remove the ship from Port you can go `Home`, hit the `Manage`
109+button for the ship, and select `Remove` under `Ship Migration`. This will
110+remove it from Port and disconnect it from the web interface, but the ship will
111+keep running as usual on the remote host.
112+
113+## Navigation
114+
115+From the home screen of Port, you can hit `Open` on a ship to access its web
116+interface. When you're in a ship's web interface, you can hit `Home` in the
117+bottom-left to return to the Port home screen.
118+
119+To manage a ship in Port and see details about it, you can hit the `Manage`
120+button for the ship in question on the home screen.
121+
122+## Start/stop a ship
123+
124+To stop a ship in Port, hit the `Manage` button for the ship on the home screen.
125+Then, hit the `Stop` button, and the ship will be shut down. Its status will
126+have changed from `Running` to `Stopped`.
127+
128+To start a ship again, just hit the `Launch` button on the ship's `Manage`
129+screen. It'll automatically open the ship's web interface, and the ship's status
130+will be back to `Running` again.
131+
132+## Eject pier
133+
134+If don't want Port to manage a particular ship any longer, for example if you
135+want to move it to a cloud server, you can export it from Port.
136+
137+From Port's home screen, hit the `Manage` button for the ship in question. Then,
138+under `Ship Migration`, hit the `Eject` button. Port will shut down the ship,
139+remove it from Port and compress its pier into a `.zip` file. It will also open
140+a file browser so you can copy it somewhere else. The location of the `.zip`
141+file will be the path to the pier shown on its `Manage` screen.
142+
143+Once you've moved the `.zip` file to its new location, it can simply be unzipped
144+and started again. If it's being moved to another machine which also runs Port,
145+see the [Import pier](#import-pier) section for details of importing it.
146+
147+## Delete pier
148+
149+**Warning: Deleting a pier is irreversible, and all data will be lost. If the
150+ship is a comet, the comet name will be unusable again. If the ship is a planet
151+or star, you will need to perform a [breach](/docs/glossary/breach) via Bridge
152+to be able to use it again (and all of its data will still be lost).**
153+
154+To completely delete the pier of a ship managed by Port, go to the home screen
155+and click `Manage` for the ship in question. Then, under `Ship Migration`, hit
156+`Delete Permanently` and accept any warnings. The ship's pier will be deleted
157+and it will be removed from Port.