# Quickstart

> Install the Falak control plane, connect your first server and deploy an app from GitHub to a generated HTTPS domain in about ten minutes.

Source: https://falak.sh/docs/getting-started/quickstart/

In this quickstart you install Falak on one host, connect a second machine as an app server, and deploy an app from a GitHub repository. At the end your app is live at an HTTPS URL like `https://shop.203-0-113-20.sslip.io`, with no DNS setup for the app.

## Before you begin

You need two Linux machines with public IPv4 addresses and root access:

| Machine | Purpose | Minimum | OS |
|---|---|---|---|
| **Control plane host** | Runs Falak itself (UI, API, builder) | 2 GB RAM (4 GB recommended), 10 GB free disk, ports 80 and 443 free | Ubuntu 22.04/24.04 or Debian 12, amd64 or arm64 |
| **App server** | Runs your app | 1 GB RAM (2 GB+ recommended) | Fresh Ubuntu 24.04 LTS, amd64 or arm64 |

You also need:

- A domain you control, for example `example.com`. The control plane lives at `falak.example.com`.
- A GitHub account with a repository to deploy. Any Laravel, Node.js, Bun, Deno or static-site repository works. See [Requirements](/docs/getting-started/requirements/) for details.

The two machines must be different. The control plane host runs only Falak; the servers Falak manages are separate machines.

## 1. Point DNS at the control plane host

Create two DNS records for the control plane host's public IP (replace `203.0.113.10`):

| Name | Type | Value |
|---|---|---|
| `falak.example.com` | A | `203.0.113.10` |
| `agents.falak.example.com` | A | `203.0.113.10` |

The first is the panel. The second is the API your servers' agents talk to over mutual TLS.

Set both records to **DNS only** (grey cloud). A proxy terminates TLS and breaks the agents' mutual TLS.

Check that they resolve before you continue:

```bash title="Your computer"
dig +short falak.example.com agents.falak.example.com
```

```text title="Expected output"
203.0.113.10
203.0.113.10
```

## 2. Install the control plane

SSH into the control plane host and run the installer. Use your own domain and e-mail address. The e-mail is used for Let's Encrypt and becomes the first admin login.

```bash title="Control plane host"
curl -fsSL https://falak.sh/install.sh \
  | sudo bash -s -- --domain falak.example.com --email you@example.com
```

The installer checks the host, installs Docker if needed, generates `/opt/falak/.env`, pulls the release images, starts the stack and creates your admin account. It ends with a summary like this:

```text title="Expected output (end)"
Falak v0.2.6 is running.

  Panel        https://falak.example.com
  Agent API    https://agents.falak.example.com/agent/v1  (mTLS, Fleet CA)

  Admin login  you@example.com
  Password     2kP7…
  (shown once — store it in a password manager)

  Next: falak-ctl status | falak-ctl doctor | falak-ctl backup
```

The password is printed **once**. Store it now. If you lose it, run `falak-ctl admin reset-password you@example.com` on the host.

Open `https://falak.example.com` and log in. You land on the **Projects** dashboard with a `Default` project.

![The Projects dashboard listing projects as cards, each with a preview of its services and the health of its production environment.](./_images/projects.png)

## 3. Connect your app server

1. Open **Servers → Create** (or press <kbd>⌘K</kbd> and type "server").

2. Fill in the form:
   - **Name**: `app-1`
   - **Type**: **App server** (PHP, Node, database and cache on one machine)
   - **Provider**: **Custom (bring your own server)**
   - **Software**: keep the defaults (FrankenPHP, PHP 8.4, Node 22). Add a database if your app needs one.

   ![The Create server form with sections for server name and type, infrastructure provider, software (PHP runtime and versions, Node.js, database, cache, Docker) and SSH access.](./_images/servers-create.png)

3. Click **Create server**. Falak shows a one-line install command:

   ```bash title="Install command (example)"
   curl -fsSL https://falak.example.com/install/Xy3…a9 | sudo sh
   ```

4. SSH into the **app server** as root (or a sudo user) and run that command.

   ```text title="Expected output"
   falak: downloading falak-agent (amd64)
   falak: enrolling with https://falak.example.com
   falak: falak-agent installed and running
   ```

5. Back in the UI, the server moves from **Creating** to **Provisioning** to **Active**. Provisioning installs FrankenPHP, PHP, Node.js, the firewall and SSH hardening. It takes a few minutes; you can watch the output on the server page.

The install token is single-use and expires after 24 hours. If it expires, regenerate the command on the server page.

## 4. Connect GitHub

1. Open **Settings → Source control** and click **Connect GitHub**.

2. Confirm the GitHub App on github.com. Falak registers a private app for your organization with **read-only** access to repository contents and metadata, plus `push` events.

3. On the installation page, pick the repositories Falak may deploy. GitHub sends you back to Falak.

Prefer a personal access token, or use GitLab or Bitbucket? See [Connect with a token](/docs/guides/connect-git-tokens/).

## 5. Deploy your app

1. Open the `Default` project. You see the **canvas** for the `production` environment.

2. Click **+ Create** and choose **Git repository**.

3. Pick the GitHub connection, your repository and the branch. Falak detects the framework and suggests a preset (for example **Laravel** or **Next.js**).

4. Select the server `app-1`. Keep the domain choice **Generate** (a free `sslip.io` name with a Let's Encrypt certificate).

5. Click **Deploy**. The new service appears on the canvas, and its panel opens on the **Deployments** tab with the first deployment streaming.

![The service panel's Deployments tab: a deployment in progress at 41%, a queued deployment, the active release and the deployment history.](./_images/canvas-panel-deployments.png)

A deployment runs these phases: **Build → Fetch → Prepare → Migrate → Activate → Restart → Health**. When the health check passes, the service shows **Active** and its domain, for example `https://shop.203-0-113-20.sslip.io`. Open it.

The Laravel preset creates `APP_KEY`, sets `LOG_CHANNEL=daily` and runs `php artisan migrate --force` on the leader server. If your app needs a database, create one first and reference it with `${{ my-db.DATABASE_URL }}` in the service's **Variables**. See [Deploy Laravel](/docs/deploy/laravel/).

## 6. Push to deploy

Push-to-deploy is on for sites created from a connected repository. Push a commit to the branch:

```bash title="Your computer"
git commit --allow-empty -m "Trigger a Falak deploy" && git push
```

A new deployment starts within seconds. The old release keeps serving until the new one is healthy.

Push-to-deploy needs GitHub to reach `https://falak.example.com`. Deploys from the UI, CLI and API work even when it cannot.

## 7. Control Falak from your terminal

Install the `falak` CLI on your computer and log in with a token from **Settings → API tokens**:

```bash title="Your computer"
curl -fsSL https://falak.sh/install-cli.sh | FALAK_URL=https://falak.example.com sh
falak deploy shop --wait
falak logs shop --follow
```

See [Install and log in](/docs/cli/install-and-login/) for options.

## If something goes wrong

| Symptom | Fix |
|---|---|
| Installer stops with `DNS does not point at this host` | Create the printed records, wait for propagation, run the installer again. It is safe to re-run. |
| The install command fails to enroll | The server must reach both `https://falak.example.com` and `https://agents.falak.example.com`. Run `falak-ctl doctor` on the control plane host. |
| The deployment fails in **Health** | Open **View logs**. The health check requests `/up` for Laravel and `/` for Node apps by default; change the path under **Settings → Deploy**. |
| The build stays queued | Run `falak-ctl logs builder` on the control plane host. |

More in [Troubleshooting](/docs/reference/troubleshooting/).

## Next steps