# One-click apps
URL: https://synquic.tech/docs/guides/one-click-apps.md

Install a ready-made app (a database, a CMS, an automation tool and more than 150 others) from the Apps catalog. Covers the install wizard, exposure and domains, host requirements, first login, connection details, settings and updates.

import { Step, Steps } from 'fumadocs-ui/components/steps';

A **one-click app** is a ready-made stack from the Synq catalog: the images, how the containers connect,
the passwords to generate, what to expose, and what to show you afterwards. You pick an app, answer a few
questions, and Synq creates the project and deploys it. Underneath it is a normal
[multi-service project](/docs/guides/compose-multi-service) on your server, so logs, backups, domains and
rollbacks work the same as everywhere else.

See every available app in the [Templates catalog](/docs/reference/templates-catalog).

## Find an app

- Click **New Project** in the sidebar. The first tab, **Apps**, is the catalog.
- Or open `/apps/new` (the **Install an app** page).

Search by name, description or tag with **Search apps…**, or filter with the category buttons: **All**,
**Backend**, **Database**, **CMS**, **Analytics**, **Automation**, **Mail** and **Tools**. Cards can carry:

| Mark | Meaning |
|---|---|
| **Verified app** (check mark) | A curated catalog app, reviewed for the catalog. |
| **Experimental** | It runs, but it is heavy or not production-grade upstream. The card and the install wizard show an **Experimental** badge; hover it for the caveat. |
| **Custom** | One of your organization's [custom templates](/docs/guides/custom-templates). Not reviewed by Synq. |
| **Coming soon** | Listed but not installable yet. |
| **Needs v…** or **Needs update** | The app needs a newer Synq. [Update Synq](/docs/guides/updating) to install it. |

Installable apps are listed first; locked ones (coming soon, needs update) come after them.

## Install an app

<Steps>

<Step>

### Open the app

Click the card. Most apps open the install wizard at `/apps/new/<app-id>`. A few apps have their own
setup flow instead, such as **Synq Mail**, which opens the mail setup.

</Step>

<Step>

### Name it

**Name** is how the app appears in Synq ("How this app appears in Synq."). It defaults to the app's name.

</Step>

<Step>

### Choose how it is reached

Under **Exposure**, the wizard lists what the app offers, each marked **Web** or **Database**:

- A **Web** endpoint can be:
  - **Domain**: reach it on a domain. Pick the free subdomain on your install's apps domain, or enter
    your own domain such as `app.example.com` (no `https://`, port or path). Your own domain needs a DNS record pointing at the server; see
    [Custom domains](/docs/guides/custom-domains).
  - **Port only (no domain)**: reachable at the server's address and port, with no domain.
- A **Database** (TCP) endpoint can be:
  - **Internal only**: only the app's own services can reach it. The safe default.
  - **Publish port**: published on the host so external tools can connect. Open that port on your
    server's firewall too.

</Step>

<Step>

### Fill in the app's own questions

Some apps ask a few questions of their own (an admin email, a site title, a feature toggle). Required
ones must be filled before **Install** works. Passwords and keys are never asked for: Synq generates them
and stores them encrypted.

</Step>

<Step>

### Pick where it runs

**Where to install** ("Pick the server or cloud this app runs on.") chooses the server. Apps that need a
minimum amount of memory or CPU show it under **What it needs** (for example "4 GB RAM"). If the chosen
server is too small, the wizard says so before anything is created, for example "This server is smaller
than PostHog needs", followed by how much memory or CPU it needs and how much the server has. Pick a
bigger server; otherwise the first deploy is refused.

</Step>

<Step>

### Press Install

The **Configuration** summary shows the **Destination** and the number of **Services**. Press **Install**.
Synq creates the project and deploys it, and the wizard follows the steps: **Preparing images**,
**Starting services**, **Finishing setup**, **Live**. **Show logs** opens the deploy output; **Stop install**
cancels it.

</Step>

</Steps>

When it finishes you see **Your app is live** with **Open app** and **Go to app**. Apps that ship with a
default login show it under **First login** (**Username** and **Password**); change it right after you
sign in. Many apps instead ask you to create the owner account on your first visit, and the app's
description says so.

**Advanced deployment options** opens the full [deploy screen](/docs/dashboard/deploy-wizard) for this app,
for when you need to change something the wizard does not ask about.

### If the install fails or you stop it

- **Install failed**: "It stopped before everything was running." **View technical details** opens the
  full build and deploy log. Fix the cause (often the server's memory, disk, or a port already in use) and
  press **Start over**.
- **Install cancelled**: the containers and images it created are removed, and data volumes are kept, so
  installing again reuses them. Anything already live is left alone.

## After install

The app is a project on the **Projects** page. Open it:

- **Overview** shows the **Connection** card: the URLs, usernames, passwords and connection strings the app
  provides, with secrets masked until you reveal them. **Use in a project** hands a value (for example a
  `DATABASE_URL`) to another project's environment in one step.
- **Configuration** has two modes. **App settings** is the app's curated settings form: change a value,
  press **Save changes**, then **Apply now** (or wait for the next deploy). Some changes restart the app;
  some recreate it, and the form says so. **Deployment** shows the raw services, like any project.
- **Source & Triggers → Source** shows the app's version source. **Check for updates** looks for a newer
  release, and **Update to** installs it.
- **Domains & Routes**, **Logs**, **Backup** and the other tabs work as for any project.

## From the CLI

```bash
# Browse the catalog, and read one app's definition
synq app list
synq app get uptime-kuma

# Check an app's requirements against a server first
synq app host-fit posthog --server <server-id>

# Create the app's project (answers from a JSON file), then deploy it
synq app install uptime-kuma --name status
synq deploy --project <project-id> --watch

# Read the installed app's connection details (includes credentials)
synq app connection <project-id>
```

`synq app install` accepts `--config <file>` with a JSON object of answers and `--routes <file>` with the
endpoint choices. See the [app command reference](/docs/cli/reference/app).

## Limits

- An app runs on one server. It can be moved later with [server-to-server migration](/docs/guides/server-to-server-migration).
- Declared minimums are checked on the **first** deploy only. After that, a shortfall is a warning, so a
  redeploy is never blocked.
- The catalog bundled with your Synq version decides which apps you see. New apps arrive with
  [updates](/docs/guides/updating).

## Related

<Cards>
  <Card title="Templates catalog" href="/docs/reference/templates-catalog" description="Every app in the catalog, grouped by category." />
  <Card title="Box" href="/docs/guides/dev-box" description="A dev environment app: VS Code in the browser, runtimes and a domain for any dev server." />
  <Card title="Custom templates" href="/docs/guides/custom-templates" description="Turn your own stack into a one-click app for your organization." />
  <Card title="Add an app" href="/docs/guides/add-an-app" description="Contribute an app to the curated catalog." />
</Cards>