> For the complete documentation index, see [llms.txt](https://zcx.gitbook.io/fastapi-template/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zcx.gitbook.io/fastapi-template/developer-manual/quickstart.md).

# Quickstart

Get the whole stack (API and PostgreSQL) running with Docker. No local Python setup needed.

## Prerequisites

* [Docker](https://www.docker.com/) with Docker Compose. Docker Desktop includes it.
* [uv](https://docs.astral.sh/uv/) only if you want local virtualenv and package support. See [Local Development](/fastapi-template/developer-manual/local_development.md).

## Install dependencies with uv

This step is optional if you only plan to use Docker.

```bash
uv sync
```

This creates the project's `.venv` and installs the runtime and dev dependencies (Ruff, pytest, pre-commit).

## Create your `.env`

```bash
cp .env.example .env
```

Set `AUTH_SECRET_KEY` to a real value. It signs the JWT tokens.

```bash
openssl rand -hex 32
```

See [Configuration](/fastapi-template/developer-manual/configuration.md) for every variable.

## Run the stack with Docker

```bash
docker compose up -d
```

This builds and starts two containers:

| Container          | Role                     | Exposed port |
| ------------------ | ------------------------ | ------------ |
| `fastapi`          | The FastAPI application. | `8080`       |
| `fastapi-postgres` | PostgreSQL 16.           | `5432`       |

## Verify it runs

```bash
curl http://localhost:8080/healthz   # -> {"status":"ok"}
curl http://localhost:8080/readyz    # -> {"status":"ready"} (pings PostgreSQL)
```

Open the interactive API at <http://localhost:8080/docs> (Swagger UI) or <http://localhost:8080/redoc>.

## Stop the stack

```bash
docker compose down        # keeps the database volume
docker compose down -v     # also deletes the PostgreSQL data volume
```

Follow the logs while it runs:

```bash
docker compose logs --follow -t
```

## What's next

* Create a user and log in. See [Authentication](/fastapi-template/architecture/auth.md).
* Run the test suite. See [Testing](/fastapi-template/architecture/testing.md).
* Start building your own API. Read [Project Structure](/fastapi-template/architecture/project_structure.md) and [Conventions](/fastapi-template/architecture/conventions.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://zcx.gitbook.io/fastapi-template/developer-manual/quickstart.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.