> ## Documentation Index
> Fetch the complete documentation index at: https://getfloo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Golden Path

> The shortest path from repo to live app, plus the commands you will keep using afterward.

<Note>
  Still evaluating floo? Start with [the introduction](/docs/introduction). This page assumes you've decided to build.
</Note>

## Before you start

You need a project directory with source code, a `Dockerfile`, and a GitHub repository. App names must be lowercase and hyphenated (e.g., `my-saas-app`). In examples below, replace `owner/repo` with your GitHub org and repo name.

The `--app` flag is optional when you're inside a directory with `floo.app.toml`. Use it when running commands from elsewhere.

## First-time setup

Sign in once, then three commands put you on a live URL.

```bash theme={null}
floo auth login                          # one-time: opens browser to sign up or log in
cd my-project

floo init my-app                         # writes floo.app.toml into the repo
floo apps github connect owner/my-project # wires the repo and triggers the first deploy
git push origin main                     # ships the committed config and kicks off the build
```

`floo auth login` opens a browser. New users create an account automatically. In headless/CI environments, use `floo auth login --api-key <key>`.

floo installs a GitHub webhook when you connect. After that, every `git push` triggers a build and deploy automatically.

Check your deploy succeeded:

```bash theme={null}
floo apps status my-app
```

<Check>
  **Your app is live.**

  * Dev URL: `https://my-app-dev.on.getfloo.com`
  * Every `git push` deploys to dev. When it's ready, run `floo releases promote --app my-app` to publish to `https://my-app.on.getfloo.com`.
  * Watch live logs with `floo logs --app my-app --follow`.
</Check>

<Tip>
  **Don't bind a route to `/healthz`.** Cloud Run's serving edge reserves that exact path and returns a 404 before the request reaches your container. Use `/health` or `/livez` instead — those reach your app normally. If your framework registers `/healthz` by default, rename it. floo's preflight emits a `cloud_run_reserved_healthz` warning when it detects this in your source.
</Tip>

## Ship Changes

Commit and push to GitHub. The deploy triggers automatically.

```bash theme={null}
git add . && git commit -m "feat: my change"
git push origin main
floo deploys watch --app my-app
```

## Decision Table

| I want to...                      | Run this                                                   |
| --------------------------------- | ---------------------------------------------------------- |
| Create an account or log in       | `floo auth login`                                          |
| Deploy for the first time         | `floo apps github connect owner/repo`                      |
| Ship a code change                | `git push origin main`                                     |
| Validate my config before pushing | `floo preflight` (local only, no auth needed)              |
| Redeploy after env var change     | `floo redeploy --app my-app`                               |
| Restart without rebuilding        | `floo redeploy --restart --app my-app`                     |
| Watch a deploy in progress        | `floo deploys watch --app my-app`                          |
| See deploy history                | `floo deploys list --app my-app`                           |
| Roll back to a previous version   | `floo deploys rollback my-app <id>`                        |
| Set an env var                    | `floo env set KEY=val --app my-app`                        |
| Add a custom domain               | `floo domains add example.com --app my-app`                |
| View logs                         | `floo logs --app my-app`                                   |
| Run locally with prod credentials | `floo dev --app my-app` (requires `dev_command` in config) |

## Common Workflows

### Add env vars and redeploy

```bash theme={null}
floo env set API_KEY=secret --app my-app
floo redeploy --app my-app
```

### Add a database

```bash theme={null}
floo services add postgres --app my-app
```

The command provisions the database, injects `DATABASE_URL` plus standard `PG*` component vars into your app's environment, and writes `.floo/services.lock`. Commit the lock file:

```bash theme={null}
git add .floo/services.lock && git commit -m "feat: add postgres"
git push origin main
```

The next deploy uses the new standard PostgreSQL `DATABASE_URL`. Postgres is fully isolated between dev and prod (separate schemas, separate credentials, both provisioned up front). For Redis (`floo services add redis`) and Storage (`floo services add storage`), see [Managed Services → Dev and prod isolation](/docs/guides/managed-services#dev-and-prod-isolation) for how environments share state.

### Add a custom domain

```bash theme={null}
floo domains add app.example.com --app my-app
```

Follow the DNS instructions in the output.

### Roll back a bad deploy

```bash theme={null}
floo deploys list --app my-app
floo deploys rollback my-app <deploy-id>
```

### Debug a failing deploy

```bash theme={null}
floo deploys logs <deploy-id> --app my-app
floo logs --app my-app --since 1h --error
```

<CardGroup cols={2}>
  <Card title="How floo works" href="/docs/how-floo-works">
    The mental model. Config in the repo, GitHub-backed deploys, CLI-first.
  </Card>

  <Card title="Configuration" href="/docs/guides/configuration">
    Understand floo.app.toml and how services are declared.
  </Card>
</CardGroup>