# New Project (Library)
URL: https://openship.io/docs/dashboard/library.md

The source picker that starts every deployment — upload a folder, import a GitHub repo, paste a Git URL, pick a template, or adopt an existing server.

This screen is where every new deployment begins. When you press **New Project** in the dashboard you land
on the Library page (route `/library`), titled **New Project** with the subtitle *"Import a repository, paste
a URL, or start from a template"*. Its job is simple: pick **where your code comes from**, and Openship hands
you off to the deploy wizard (`/deploy/...`) with everything pre-filled.

Think of this page as the front door with five doors behind it — each tab is a different way to bring code in.
Whichever you choose, they all end in the same place: the wizard where you confirm the framework, choose where
it runs, and press Deploy.

<Callout title="Screenshot">Library page at `/library` — the header "New Project", the row of tabs, the source panel on the left, and the overview sidebar on the right. *(screenshot pending)*</Callout>

## The five tabs

The tab row sits just under the page title. The **GitHub** tab is selected by default. The last tab
(**Existing server**) only appears on self-hosted and desktop installs — Openship Cloud has no server inventory
to adopt from.

| Tab | Icon | What it's for |
|---|---|---|
| **Folder** | folder-up | Deploy from a folder — uploaded from your browser, or read straight off disk on the desktop app. |
| **GitHub** | github | Browse and deploy the repositories on your connected GitHub account. |
| **Git URL** | link-2 | Paste a public GitHub repo link — no account connection needed. |
| **Template** | sparkles | Start from a ready-made starter for a framework. |
| **Existing server** | boxes | *(self-hosted only)* Adopt a Docker/Compose app already running on your own machine. |

On the right of every tab is the **Overview** sidebar — repo counts and a "Quick Tip" — plus your GitHub /
Cloud connection status. It's informational; the action is always on the left.

## Folder

Deploy an app from a folder, no Git required. This tab behaves differently depending on how you're running
Openship:

- **Desktop app** — you get the **Local Projects** panel. Point Openship at a folder on your machine
  (drop it or type the absolute path, then **Scan**), it auto-detects the framework, and builds and runs the
  app locally. No upload happens — the local pipeline reads the folder in place.
- **Browser (Openship Cloud or a remote self-hosted instance)** — you get the **Folder upload** flow. A browser
  can't see your filesystem, so Openship first asks **"What are you deploying?"** and shows a grid of stacks to
  pick from (this fixes the build image). Then you drop or browse to your project folder — it's packed in your
  browser (skipping `node_modules`, `.git`, and build output), uploaded, and you continue to the wizard.

<Callout title="Screenshot">Folder tab in a browser — the "What are you deploying?" stack grid, then the drop zone. On desktop, the "Local Projects" import panel. *(screenshot pending)*</Callout>

<Callout title="Full walkthrough" type="info">
See [Deploy a local folder](/docs/guides/deploy-local-folder) for the desktop picker, the browser upload, and
the one-command CLI equivalent.
</Callout>

## GitHub (Repositories)

The default tab. If your GitHub account isn't connected yet, you'll see a **connect** prompt here instead of a
list — connect once and the repos appear. (Follow [Deploy from GitHub](/docs/guides/deploy-from-github) for the
one-time connection.)

Once connected, this panel lists your repositories with tools to find the right one:

- An **account row** at the top to switch between the GitHub owners/orgs you've granted, plus a **+** to add
  another account.
- A **search** box (`Search repositories...`).
- **Visibility** pills: **All**, **Public**, **Private**.
- A **sort** dropdown: **Recent**, **Name**, **Stars**.

Click any repository and Openship takes you straight into the deploy wizard for it.

<Callout title="'Local only' badge" type="warn">
A repo tagged **Local only** is visible through the `gh` CLI but the Openship GitHub App isn't installed on its
owner — so it can build locally, but remote deploys will be refused. Install the App on that owner (the
**Install GitHub App** action) to enable remote deploys.
</Callout>

<Callout title="Screenshot">GitHub tab, connected — account row, search + visibility + sort controls, and the repo list with an arrow on each row. *(screenshot pending)*</Callout>

## Git URL

For deploying a public repository you don't own or haven't connected. The panel is **Import from Git URL**:
paste a URL like `https://github.com/username/repository` and press **Import Repository**. No GitHub connection
is required. Openship parses the owner and repo from the link and sends you to the wizard.

<Callout title="Public repos only">
This path clones over the public URL. For private repositories, use the **GitHub** tab so Openship can
authenticate. See [Deploy from a template or Git URL](/docs/guides/deploy-template-or-url).
</Callout>

## Template

A grid of framework starters. Pick a framework and Openship opens the wizard seeded from that template — a fast
way to get a working project online without bringing your own code first. (The plain "static" option is omitted
here.)

<Callout title="Screenshot">Template tab — the grid of framework tiles, each with an icon and name. *(screenshot pending)*</Callout>

See [Deploy from a template or Git URL](/docs/guides/deploy-template-or-url) for what each starter includes.

## Existing server

*(Self-hosted and desktop only.)* This tab is for **adopting a deployment you're already running** — the card
is titled **Existing Docker server**, described as *"Migrate a running Docker or Compose deployment into
Openship."* Press **Migrate Docker** to open the migration wizard, which connects over SSH to your box,
inspects the running containers, and brings them under Openship's management.

<Callout title="Needs SSH to your own machine">
Adoption reads containers off a server you control, so it isn't available on Openship Cloud. If you want to add
a fresh machine instead of adopting one, see [Connect your own server](/docs/guides/custom-servers).
</Callout>

<Callout title="Screenshot">Existing server tab — the "Existing Docker server" card with the "Migrate Docker" button, and the migration wizard it opens. *(screenshot pending)*</Callout>

## What happens next

Every tab leads to the same place — the **deploy wizard** at `/deploy/...`, where you confirm the detected
framework, choose where the app runs (Local, Server, or Cloud), and press **Deploy**.

<Cards>
  <Card title="Deploy from GitHub" href="/docs/guides/deploy-from-github" description="Connect a repo and ship it, click-by-click." />
  <Card title="Deploy a local folder" href="/docs/guides/deploy-local-folder" description="Upload from the browser or read off disk on the desktop app." />
  <Card title="Deploy from a template or Git URL" href="/docs/guides/deploy-template-or-url" description="Start without connecting your own GitHub." />
</Cards>