Skip to content

Quick Start

Get started with Vibetuner in 5 minutes.

Prerequisites

That's it! Vibetuner handles the rest.

Create Your First Project

No installation needed:

uvx vibetuner scaffold new my-app

Install Globally

uv tool install vibetuner
vibetuner scaffold new my-app

Interactive Setup

The scaffold command will ask you:

  • Project name: my-app
  • Company name: Your company/organization
  • Author details: Name and email
  • Features: OAuth providers, background jobs, etc.

Skip Prompts

Use defaults for everything:

uvx vibetuner scaffold new my-app --defaults

Start Development

cd my-app
just dev

This starts:

  • Database (MongoDB or SQL, if configured)
  • Redis (if background jobs enabled)
  • FastAPI application with hot reload
  • Frontend asset compilation

Visit http://localhost:8000 - your app is running!

Project Structure

my-app/
├── src/vibetuner/          # Core framework (don't edit)
│   ├── frontend/           # FastAPI app, auth, middleware
│   ├── models/             # User, OAuth models
│   └── services/           # Email, storage services
├── src/app/                # Your code (edit freely)
│   ├── frontend/routes/    # Your HTTP routes
│   ├── models/             # Your database models
│   └── services/           # Your business logic
├── templates/              # Jinja2 templates
├── assets/                 # Static files
└── Dockerfile              # Production deployment

Next Steps

  • Add routes: Create files in src/app/frontend/routes/
  • Define models: Create models in src/app/models/ (Beanie for MongoDB, SQLModel for SQL)
  • Customize templates: Edit files in templates/
  • Configure environment: Copy .env.local to .env and customize

Common Commands

just dev              # Docker development with hot reload
just local-dev        # Local development (no Docker)
just sync             # Sync dependencies
just format           # Format code
just build-prod       # Test production build

Development Modes

just dev

Everything runs in containers with hot reload. Changes to code, templates, and assets automatically reload.

Local Development

# Terminal 1: Frontend assets
bun dev
# Terminal 2: Backend server
just local-dev

Useful when you want more control or Docker is slow on your system.

What's Next?