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

# Scaffold a Deployment Project

> One-command starter projects for Fly.io, Railway, Render, Docker Compose

Scaffold a ready-to-edit deployment project — provider config plus `agents.yaml` — with one command.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "deploy create"
        T[💻 --template name] --> Pick{🔀 Which target?}
        Pick --> Local[🐳 docker-compose]
        Pick --> Cloud[☁️ fly / railway / render]
    end

    classDef cli fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef pick fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef out fill:#10B981,stroke:#7C90A0,color:#fff

    class T cli
    class Pick pick
    class Local,Cloud out
```

<Warning>
  Starter templates ship in the git checkout, **not** in the PyPI wheel (`MANIFEST.in` excludes `infra/`). Run from a monorepo checkout, or set `PRAISONAI_STARTERS_ROOT` / `PRAISONAI_INFRA_ROOT`.
</Warning>

## Quick Start

<Steps>
  <Step title="Scaffold a project">
    Pick a template and drop its files into the current directory.

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai deploy create --template fly
    ```
  </Step>

  <Step title="Edit and deploy">
    Adjust the generated config, then deploy with the matching command.

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai deploy fly
    ```
  </Step>
</Steps>

***

## How It Works

`create` copies the named template's files into your target directory, refusing to clobber existing files unless you pass `--force`.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant CLI as deploy create
    participant Dir as Target dir

    User->>CLI: --template fly --dir .
    CLI->>Dir: Check for conflicts
    alt File exists and no --force
        CLI-->>User: Refuse (use --force or empty dir)
    else Clear
        CLI->>Dir: Write fly.toml + agents.yaml
        CLI-->>User: Next steps
    end
```

***

## Choosing a Template

Match the template to where you want to run.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Start{Where do I deploy?} --> L[Local, with a database]
    Start --> B[Bare Docker API]
    Start --> C[A cloud PaaS]
    L --> DC[docker-compose]
    B --> DA[docker-api]
    C --> F[fly]
    C --> R[railway]
    C --> RE[render]

    classDef q fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef opt fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef res fill:#10B981,stroke:#7C90A0,color:#fff

    class Start,L,B,C q
    class DC,DA,F,R,RE res
```

***

## Templates

Five templates ship today.

| `--template`     | Files shipped                  | Purpose                                                                                                                              |
| ---------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `docker-api`     | `agents.yaml`                  | Bare Docker API scaffold.                                                                                                            |
| `docker-compose` | `agents.yaml`                  | For the `deploy compose` stack (API + Postgres).                                                                                     |
| `fly`            | `fly.toml` + `agents.yaml`     | Fly.io — pins the image, `internal_port=8005`, `PRAISONAI_API_AUTH=enabled`, HTTP `/health` check.                                   |
| `railway`        | `railway.json` + `agents.yaml` | Railway — `healthcheckPath: /health`, `restartPolicyType: ON_FAILURE`.                                                               |
| `render`         | `render.yaml` + `agents.yaml`  | Render — `runtime: image`, `healthCheckPath: /health`, requires `OPENAI_API_KEY` (`sync: false`), sets `PRAISONAI_API_AUTH=enabled`. |

***

## Command Options

| Flag                | Default      | Description                                      |
| ------------------- | ------------ | ------------------------------------------------ |
| `--template` / `-t` | *(required)* | Starter template name.                           |
| `--dir` / `-d`      | `.`          | Target directory (created if missing).           |
| `--force`           | `False`      | Overwrite conflicting files instead of refusing. |
| `--json`            | `False`      | Machine-readable output.                         |

The starters directory can be overridden with `PRAISONAI_STARTERS_ROOT`.

***

## Best Practices

<AccordionGroup>
  <Accordion title="Scaffold into an empty directory">
    Without `--force`, `create` refuses to overwrite an existing `agents.yaml` — protecting hand-edited files. Use a fresh directory, or pass `--force` when you intend to replace.
  </Accordion>

  <Accordion title="Chain create with the deploy command">
    The fastest path to a running deployment is a one-liner:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai deploy create --template fly && praisonai deploy fly
    ```
  </Accordion>

  <Accordion title="Pin the image tag in the generated config">
    Starters use `latest`. Swap in a released tag before deploying to production.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Docker Compose Stack" icon="docker" href="/docs/docs/features/compose-stack">
    Run the docker-compose template locally.
  </Card>

  <Card title="Deploy to Fly.io" icon="plane" href="/docs/docs/features/fly">
    Deploy the fly template in one command.
  </Card>
</CardGroup>