# New Project (Library)
URL: https://synquic.tech/docs/dashboard/library.md

The page that starts every deployment. One tab per source, a one-click app, a folder or archive, a GitHub repository, any Git URL, a Docker image, a pasted Dockerfile or Compose file, a starter template, or apps already running on a server.

Every new project starts here. Click **New Project** in the sidebar and you land on the Library page
(`/library`), titled **New Project**: "Import a repository, paste a URL, or start from a template". Pick
where the code or app comes from, and Synq takes you to the next step.

## The tabs

The tab row sits under the title. The page opens on the **GitHub** tab. A link to `/library#image`,
`#dockerfile`, `#compose`, `#git` or `#archive` opens that tab directly.

| Tab | What it's for | Next step | Guide |
|---|---|---|---|
| **Apps** | The one-click app catalog: databases, CMSs, analytics, automation and more. | The app's install wizard. | [One-click apps](/docs/guides/one-click-apps) |
| **Folder** | Upload a project folder from your computer. | The deploy screen. | [Deploy a folder or archive](/docs/guides/deploy-local-folder) |
| **Archive** | Upload a `.zip`, `.tar`, `.tar.gz`/`.tgz`, `.tar.bz2`, `.tar.xz` or `.tar.zst` of your app, up to 300 MB (not 7z or rar). | The deploy screen. | [Upload an archive](/docs/guides/deploy-local-folder#upload-an-archive) |
| **GitHub** | Browse and deploy the repositories of your connected GitHub accounts. | The deploy screen. | [Deploy from GitHub](/docs/guides/deploy-from-github) |
| **Git URL** | Any HTTPS or SSH repository: GitLab, Bitbucket, Gitea, Forgejo or your own Git server, public or private. | The deploy screen. | [Deploy from any Git URL](/docs/guides/deploy-from-git-url) |
| **Docker image** | Run a prebuilt image from Docker Hub or any registry, including private ones. | Deploys straight away. | [Deploy a Docker image](/docs/guides/deploy-docker-image) |
| **Dockerfile** | Write or paste a Dockerfile; Synq builds and runs it. | Deploys straight away. | [Paste a Dockerfile](/docs/guides/deploy-dockerfile-or-compose) |
| **Compose** | Paste a `docker-compose.yml`; Synq deploys each service. | Deploys straight away. | [Paste a Compose file](/docs/guides/deploy-dockerfile-or-compose#deploy-a-pasted-compose-file) |
| **Template** | Framework starter tiles. | The deploy screen. | [Framework starters](/docs/guides/deploy-template-or-url#framework-starters) |
| **Existing server** | Adopt Docker or Compose apps that already run on one of your servers. | The migration wizard. | [Migrate from Coolify, Dokploy, or Dokku](/docs/guides/migrate-from-coolify-dokploy-dokku) |

The **Docker image**, **Dockerfile** and **Compose** tabs are complete forms: they create the project and
start the first deploy in one step, with a **Server** picker and an environment variables box. The other
tabs lead to the [deploy screen](/docs/dashboard/deploy-wizard), where you review the detected build first.

On the right of every tab is the **Overview** sidebar: repository counts (**Total**, **Public**,
**Private**), a **Quick Tip**, and your GitHub **Connection** status. It is informational; the action is
always on the left.

## GitHub

If GitHub is not connected yet, the tab shows **Connect GitHub to deploy** with the ways to connect
(**Sign in with GitHub**, **SSH key or access token**, or **Set up in Settings** for your own GitHub App or
the `gh` CLI). Connect once and your repositories appear.

Once connected, the list has:

- an **account row** to switch between the GitHub users and organizations you granted, with a **+** to add
  another account;
- **Search repositories...**;
- **All**, **Public** and **Private** filters;
- a **Recent**, **Name**, **Stars** sort;
- page controls ("Page 1 of 4") for long lists.

Click a repository to open the deploy screen for it.

<Callout title="“Local only” badge" type="warn">
A repository marked **Local only** is visible through the `gh` CLI, but the GitHub App is not installed on
its owner. It can build on the Synq host, but remote deploys are refused. Install the App on that owner
(**Install GitHub App**) to enable them.
</Callout>

The first time the list would come from the `gh` CLI signed in on the host, the tab asks
**Read your repositories?** first. Press **Allow** to list them; the list never leaves this machine.

## Folder

**What are you deploying?** asks for the stack, then you drop or browse to the folder. It is packed in the
browser (skipping `node_modules`, `.git` and build output) and uploaded; **Continue** opens the deploy screen.
The desktop app shows the same tab. To deploy a folder from a terminal, use
[`synq deploy --folder`](/docs/guides/deploy-local-folder#cli).

## Git URL

**Deploy from a Git URL**: paste a **Repository URL**, choose **Access** (**Public**, **Access token** or
**Deploy key**), press **Test access**, pick the **Branch**, **Project name** and optional
**Root directory**, then **Continue**. For an `https://` GitHub URL with public access, the tab suggests
**Use the GitHub importer** instead.

## Apps

The one-click catalog, also at `/apps/new` (**Install an app**). **Search apps…** and the category buttons
narrow it down. The **Custom templates** button opens your organization's
[custom templates](/docs/guides/custom-templates). Clicking an app opens its install wizard.

## Existing server

Self-hosted only. The **Existing services** card ("Migrate a running Docker or Compose deployment into
Synq.") has a **Migrate apps** button that opens the migration wizard: it connects to one of your servers
over SSH, scans the running containers, and brings them under Synq's management without rebuilding them.
Connect the server first under **Servers** (see [Custom servers](/docs/guides/custom-servers)).

## What happens next

Most tabs end on the **deploy screen** (`/deploy/...`), where you confirm the detected build, choose the
server, add a domain, and press **Deploy**. See [The deploy wizard](/docs/dashboard/deploy-wizard).

<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 from any Git URL" href="/docs/guides/deploy-from-git-url" description="GitLab, Bitbucket, Gitea, Forgejo or your own server." />
  <Card title="One-click apps" href="/docs/guides/one-click-apps" description="Install a ready-made app from the catalog." />
</Cards>