> ## Documentation Index
> Fetch the complete documentation index at: https://paper.brimble.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Deploy your first Brimble project from a Git repository in under 10 minutes.
Deploy your first Brimble project from a Git repository in under 10 minutes.
## Prerequisites
* A GitHub, GitLab, or Bitbucket account with a repository you want to deploy.
* A Brimble account. If you don't have one, go to [app.brimble.io/signup](https://app.brimble.io/signup) and sign up with email or one of the supported OAuth providers (GitHub, Google, GitLab, Bitbucket). The free plan needs no credit card.
If you don't have an app handy, any small Node, Python, or Go web server with a `Procfile` or standard start command will work.
## Step 1: Create a project
1. Sign in at [app.brimble.io](https://app.brimble.io).
2. Click **New project**.
3. Connect your Git provider if it isn't already linked, then pick the repository to deploy.
4. Choose the **branch** you want Brimble to track (usually `main`).
## Step 2: Configure the build
Brimble auto-detects most frameworks. Review the detected settings or override them:
| Setting | What it means |
| ------------------------- | ------------------------------------------------------------------------------ |
| **Framework** | Auto-detected from your repo. Override if it guessed wrong. |
| **Root directory** | Leave blank for the repo root. Set a sub-path for monorepos (e.g. `apps/web`). |
| **Build command** | What runs to produce the artifact (e.g. `npm run build`). |
| **Start command** | What runs to start your server (e.g. `npm start`). |
| **Environment variables** | Any values your app needs at build or runtime. |
| **Region** | The datacenter where your project runs. Pick one near your users. |
| **Compute size** | Memory and CPU. Start small, you can scale later. |
**Read `PORT` from the environment and bind to `0.0.0.0`.** Brimble assigns the port at runtime, so a hardcoded port returns 502. Binding to `localhost` or `127.0.0.1` returns 502 too, the gateway can't reach a loopback-only listener.
Your app must read its HTTP port from the `PORT` environment variable. Brimble assigns the port at runtime; if your server listens on a hardcoded port, requests will fail with a 502.
## Step 3: Deploy
Click **Deploy**. The dashboard opens a logs drawer where you can watch each phase of the build and deployment stream in real time, clone, framework detection, build, push, start.
When the deployment finishes, your project is live at `https://.brimble.app`.
## Troubleshooting
**Build fails with "framework not detected."** Brimble couldn't infer your build setup. Set the framework, build command, and start command manually in step 2.
**Deploy succeeds but the URL returns 502.** Your app isn't listening on the right port. Make sure your server reads the `PORT` environment variable instead of hardcoding a value.
**Build fails partway through.** Open the failed deployment in the dashboard and read the logs from the bottom up, the first error is usually the real one. Common causes: a missing dependency, a build script that needs an env var, or a Node/Python version mismatch.
**The deploy completes but the URL shows a default Brimble page.** Your project may still be starting. Wait 30 seconds and refresh. If it persists, check the runtime logs for a startup error.
## Next steps
* [Add a custom domain](../domains/custom-domains), point `app.example.com` at your project.
* Push a new commit to the tracked branch. Brimble will build and deploy it automatically.