Quick Start

Prerequisites

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.

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.

Once it finishes, your Openinary instance is running at http://localhost:3000.

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

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)

Open http://localhost:3000, you’ll be redirected to /setup.
Create your admin account.
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:

GET http://localhost:3000/t/w_400,h_400,c_fill/example-loan.jpg

Manual setup

Run with raw Docker commands (no CLI)

docker pull openinary/openinary:latest

Full stack
With S3 storage
API only

Starts the API and web dashboard together.

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

Replaces local file storage with a cloud bucket.

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

Headless mode, no web dashboard. An API key is auto-generated on first run.

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

The API key appears once in the container logs. Retrieve it immediately:

docker logs <container-id>

Run from source

Prefer running from source? See Local Development.

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 instead of local volumes.

Next steps

Image Transformations

Resize, crop, convert format, and optimize images via URL.

Video Transformations

Resize, trim, and extract thumbnails from videos.

Storage

Connect AWS S3, Cloudflare R2, or any S3-compatible provider.

File Uploader

Build a drag-and-drop file uploader with direct-to-storage uploads.

Getting Started

Configuration

Media Transformations

Resources

Prerequisites

Install

CLI reference

Initial setup (full stack)

Sample files

Manual setup

Next steps

Image Transformations

Video Transformations

Storage

File Uploader

​Prerequisites

​Install

​CLI reference

​Initial setup (full stack)

​Sample files

​Manual setup

​Next steps

Image Transformations

Video Transformations

Storage

File Uploader

Prerequisites

Install

CLI reference

Initial setup (full stack)

Sample files

Manual setup

Next steps