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

# Self-Hosting

> Run the Open Animate platform on your own infrastructure

Open Animate is fully open source (Apache 2.0). You can run the entire platform on your own infrastructure.

## Prerequisites

* Node.js 18+
* PostgreSQL 15+
* A [fal.ai](https://fal.ai) API key (for asset generation)
* AWS credentials with S3 + Lambda access (for cloud rendering)
* A [Stripe](https://stripe.com) account (for billing, optional)
* A [Clerk](https://clerk.com) application (for authentication)

## Quick start with Docker

<Steps>
  ### Start the database

  ```bash theme={null}
  git clone https://github.com/jacobcwright/open-animate.git
  cd open-animate/packages/api

  docker-compose up -d
  ```

  This starts PostgreSQL 15 on port 5432.

  ### Configure environment

  Create `.env` from the example:

  ```bash theme={null}
  cp .env.example .env
  ```

  Edit `.env` with your values:

  ```bash theme={null}
  # Database
  DATABASE_URL=postgres://oanim:oanim@localhost:5432/oanim

  # Authentication (Clerk)
  CLERK_DOMAIN=your-app.clerk.accounts.dev
  CLERK_PUBLISHABLE_KEY=pk_test_...

  # Media Gateway (fal.ai)
  FAL_KEY=your-fal-ai-key

  # Storage (S3-compatible)
  AWS_ACCESS_KEY_ID=your-key
  AWS_SECRET_ACCESS_KEY=your-secret
  AWS_REGION=us-east-1
  S3_BUCKET=oanim-renders

  # Cloud rendering (Remotion Lambda)
  REMOTION_FUNCTION_NAME=remotion-render-xxx

  # Billing (Stripe) — optional
  STRIPE_SECRET_KEY=sk_live_...
  STRIPE_WEBHOOK_SECRET=whsec_...

  # Server
  PORT=8000
  ```

  ### Start the API

  ```bash theme={null}
  pnpm install
  pnpm build
  pnpm start
  ```

  ### Point the CLI at your instance

  ```bash theme={null}
  # Via environment variable
  export ANIMATE_API_URL=http://localhost:8000

  # Or via config file
  # ~/.oanim/config.yaml
  # api_url: http://localhost:8000
  ```

  Then use the CLI normally:

  ```bash theme={null}
  oanim login
  oanim assets gen-image --prompt "gradient" --out public/bg.png
  ```
</Steps>

## Environment variables

| Variable                 | Required         | Description                              |
| ------------------------ | ---------------- | ---------------------------------------- |
| `DATABASE_URL`           | Yes              | PostgreSQL connection string             |
| `CLERK_DOMAIN`           | Yes              | Clerk OAuth domain                       |
| `CLERK_PUBLISHABLE_KEY`  | Yes              | Clerk publishable key for browser auth   |
| `FAL_KEY`                | Yes              | fal.ai API key for media gateway         |
| `AWS_ACCESS_KEY_ID`      | For cloud render | AWS access key                           |
| `AWS_SECRET_ACCESS_KEY`  | For cloud render | AWS secret key                           |
| `AWS_REGION`             | For cloud render | AWS region (default: `us-east-1`)        |
| `S3_BUCKET`              | For cloud render | S3 bucket for render bundles and outputs |
| `REMOTION_FUNCTION_NAME` | For cloud render | Remotion Lambda function name            |
| `STRIPE_SECRET_KEY`      | For billing      | Stripe secret key                        |
| `STRIPE_WEBHOOK_SECRET`  | For billing      | Stripe webhook signing secret            |
| `PORT`                   | No               | Server port (default: `8000`)            |

<Note>
  New users receive a \$5.00 credit balance on signup. Without Stripe configured, users won't be able to purchase additional credits, but existing balances still work.
</Note>

## Direct provider keys

For asset generation without running the platform API, users can set `ANIMATE_FAL_KEY` to go directly to fal.ai:

```bash theme={null}
export ANIMATE_FAL_KEY=your-fal-key
oanim assets gen-image --prompt "gradient" --out bg.png
```

This bypasses the platform entirely — no API server, database, or auth required.

## docker-compose.yml

The included `docker-compose.yml` runs PostgreSQL:

```yaml theme={null}
services:
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: oanim
      POSTGRES_PASSWORD: oanim
      POSTGRES_DB: oanim
    ports:
      - '5432:5432'
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:
```

## Production considerations

For production deployments:

* **Database**: Use strong passwords, enable SSL, and set up regular backups
* **Stripe webhooks**: Configure the webhook endpoint at `https://your-domain/api/v1/billing/webhook`
* **Rate limiting**: The API includes in-memory rate limiting (60 req/min for media, 10 req/min for auth). For multi-instance deployments, consider adding a Redis-backed rate limiter
* **HTTPS**: Place the API behind a reverse proxy (nginx, Caddy) with TLS