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

# Quick Start

> Install Openinary with one command, create an admin account, and make your first image transformation.

<Note>
  This page covers the **self-hosted** version. For the hosted one, see the
  [Cloud Quickstart](/cloud/quickstart).
</Note>

## Prerequisites

* [Docker](https://docs.docker.com/get-docker/) 20.x or higher
* Node.js 20+ (only needed to run the CLI)

## Install

Scaffold a project with a single command, no install required. It generates your
configuration and starts the docker image for you.

```bash theme={null}
npx create-openinary
```

Follow the prompts to choose full stack vs. API-only and, optionally, S3-compatible
storage. By default it scaffolds into an `openinary/` directory, writes a
`docker-compose.yml` and `.env` with a generated `BETTER_AUTH_SECRET`, and starts
the containers.

<Check>
  Once it finishes, your Openinary instance is running at
  **[http://localhost:3000](http://localhost:3000)**.
</Check>

To get the full `openinary` command suite (start, stop, upgrade, …), install the
CLI globally:

```bash theme={null}
npm i -g create-openinary
```

## CLI reference

With the global install, the `openinary` command manages the project you just created:

| Command   | Description                                                                                                |
| --------- | ---------------------------------------------------------------------------------------------------------- |
| `create`  | Scaffold a new Openinary project                                                                           |
| `start`   | Start Openinary services                                                                                   |
| `stop`    | Stop services (data preserved)                                                                             |
| `restart` | Restart services                                                                                           |
| `upgrade` | Update to the latest compatible version, syncing env vars and showing the changelog                        |
| `reset`   | Delete local data (database, uploads, cache) and recreate the instance, destructive, requires confirmation |

Every command also works without the global install, e.g. `npx create-openinary start`
or `pnpm create openinary start`.

## Initial setup (full stack)

1. Open **[http://localhost:3000](http://localhost:3000)**, you'll be redirected to `/setup`.
2. Create your admin account.
3. Click your profile in the bottom-left of the dashboard → **API Keys** → create your first key.

## Sample files

The container ships with two files for testing, available at `/app/apps/api/public/`:

* `example-loan.jpg`, for image transformation tests
* `example-rahime-gul.mp4`, for video transformation tests

Try a transformation immediately:

```http theme={null}
GET http://localhost:3000/t/w_400,h_400,c_fill/example-loan.jpg
```

## Manual setup

<AccordionGroup>
  <Accordion title="Run with raw Docker commands (no CLI)">
    ```bash theme={null}
    docker pull openinary/openinary:latest
    ```

    <Tabs>
      <Tab title="Full stack">
        Starts the API and web dashboard together.

        ```bash theme={null}
        docker run --platform linux/amd64 -d -p 3000:3000 \
          -v openinary-cache:/app/apps/api/cache \
          -v openinary-public:/app/apps/api/public \
          -v openinary-db:/app/data \
          openinary/openinary:latest
        ```
      </Tab>

      <Tab title="With S3 storage">
        Replaces local file storage with a cloud bucket.

        ```bash theme={null}
        docker run --platform linux/amd64 -d -p 3000:3000 \
          -v openinary-db:/app/data \
          -e STORAGE_REGION=us-east-1 \
          -e STORAGE_ACCESS_KEY_ID=XXXXXXXXXXXXXXXXXXXX \
          -e STORAGE_SECRET_ACCESS_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
          -e STORAGE_BUCKET_NAME=your-bucket \
          -e STORAGE_ENDPOINT=https://s3.filebase.com/ \
          openinary/openinary:latest
        ```
      </Tab>

      <Tab title="API only">
        Headless mode, no web dashboard. An API key is auto-generated on first run.

        ```bash theme={null}
        docker pull openinary/openinary-api:latest

        docker run --platform linux/amd64 -d -p 3000:3000 \
          -v openinary-cache:/app/apps/api/cache \
          -v openinary-public:/app/apps/api/public \
          -v openinary-db:/app/data \
          -e MODE=api \
          openinary/openinary-api:latest
        ```

        <Warning>
          The API key appears **once** in the container logs. Retrieve it immediately:

          ```bash theme={null}
          docker logs <container-id>
          ```
        </Warning>
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Run from source">
    Prefer running from source? See [Local Development](/local-development).
  </Accordion>
</AccordionGroup>

<Warning>
  **Volume persistence**, in production, always mount all three volumes to durable storage. Losing a volume means losing that data.

  | Volume             | Path in container      | Contains                      |
  | ------------------ | ---------------------- | ----------------------------- |
  | `openinary-db`     | `/app/data`            | Database (accounts, API keys) |
  | `openinary-public` | `/app/apps/api/public` | Uploaded files                |
  | `openinary-cache`  | `/app/apps/api/cache`  | Cached transformations        |

  For better durability, use [S3-compatible storage](/configuration/storage) instead of local volumes.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Image Transformations" icon="image" href="/media-transformations/image-transformations">
    Resize, crop, convert format, and optimize images via URL.
  </Card>

  <Card title="Video Transformations" icon="video" href="/media-transformations/video-transformations">
    Resize, trim, and extract thumbnails from videos.
  </Card>

  <Card title="Storage" icon="cloud" href="/configuration/storage">
    Connect AWS S3, Cloudflare R2, or any S3-compatible provider.
  </Card>

  <Card title="File Uploader" icon="upload" href="/guides/file-uploader">
    Build a drag-and-drop file uploader with direct-to-storage uploads.
  </Card>
</CardGroup>