Quick Start

Get Starterbase running in 5 minutes using Docker.

Prerequisites

Before you start, make sure you have installed:

That's it! Docker will handle everything else.

Step 1: Create Your Project

Use the CLI to scaffold a new project:

# One-command setup (recommended) - creates and starts everything
npx create-starterbase-app my-app -y

# Or interactive mode (prompts for options)
npx create-starterbase-app my-app
cd my-app

The -y flag enables non-interactive mode with sensible defaults and auto-starts Docker Compose.

CLI Options

Option Description
-y, --yes Non-interactive mode with defaults, auto-starts Docker
-d, --database <type> Database type: sqlite or postgresql (default: prompts)
--skip-install Skip dependency installation (npm/uv)
--no-start Don't auto-start Docker Compose after creation

Examples:

# SQLite database, non-interactive
npx create-starterbase-app my-app -d sqlite -y

# PostgreSQL with auto-start
npx create-starterbase-app my-app -d postgresql -y

# Skip dependency installation
npx create-starterbase-app my-app --skip-install

# Don't start Docker after creation
npx create-starterbase-app my-app -y --no-start

The CLI will:

For full CLI documentation, see the CLI Reference page.

💡 License Required

Starterbase requires a valid license. Use npx create-starterbase-app activate <license-key> to activate your license before creating a project.

Step 2: Configure Environment

The CLI has already created .env files for you in backend/.env and frontend/.env.local with sensible defaults.

Generate JWT Secret

Your backend needs a secure JWT secret for authentication. Generate one:

openssl rand -hex 32

Copy the output and update backend/.env:

JWT_SECRET=<paste the generated secret here>
💡 Optional Configuration

You can skip Stripe configuration for now. The app works without it, and you can add billing features later.

Environment Variables Explained

Backend (backend/.env):

Variable Description Required
APP_NAME Application name No (default: Starterbase)
ENVIRONMENT Environment mode: development or production No
DEBUG Enable debug mode No
TZ Timezone in IANA format (e.g., UTC, America/New_York) No
DB_URL PostgreSQL connection string Yes (auto-configured for Docker)
REDIS_URL Redis connection string Yes (auto-configured for Docker)
JWT_SECRET Secret key for JWT tokens Yes
JWT_ALGORITHM JWT algorithm (default: HS256) No
JWT_ACCESS_TOKEN_EXPIRE_MINUTES Access token expiry (default: 15) No
JWT_REFRESH_TOKEN_EXPIRE_DAYS Refresh token expiry (default: 7) No
CORS_ORIGINS Allowed CORS origins (JSON array) No
STRIPE_SECRET_KEY Stripe secret API key No (for billing)
STRIPE_PUBLISHABLE_KEY Stripe publishable key No (for billing)
STRIPE_WEBHOOK_SECRET Stripe webhook secret No (for billing)
RESEND_API_KEY Resend API key No (for emails)
EMAIL_FROM_ADDRESS Sender email address No (for emails)
EMAIL_FROM_NAME Sender display name No
GOOGLE_OAUTH_CLIENT_ID Google OAuth client ID No (for social login)
GOOGLE_OAUTH_CLIENT_SECRET Google OAuth client secret No (for social login)
MICROSOFT_OAUTH_CLIENT_ID Microsoft OAuth client ID No (for social login)
MICROSOFT_OAUTH_CLIENT_SECRET Microsoft OAuth client secret No (for social login)
MICROSOFT_OAUTH_TENANT_ID Microsoft tenant ID (default: common) No
APPLE_OAUTH_CLIENT_ID Apple OAuth service ID No (for social login)
APPLE_OAUTH_TEAM_ID Apple team ID No (for social login)
APPLE_OAUTH_KEY_ID Apple key ID No (for social login)
APPLE_OAUTH_PRIVATE_KEY Apple private key (.p8 contents) No (for social login)

Frontend (frontend/.env.local):

Variable Description Required
NEXT_PUBLIC_API_URL Backend API URL Yes
NEXT_PUBLIC_BACKEND_URL Backend base URL (for Swagger UI links) No
NEXT_PUBLIC_APP_NAME Application name for branding Yes
NEXT_PUBLIC_SITE_URL Site URL for SEO (sitemap, canonical URLs) No
NEXT_PUBLIC_GOOGLE_CLIENT_ID Google OAuth client ID No (for social login)
NEXT_PUBLIC_MICROSOFT_CLIENT_ID Microsoft OAuth client ID No (for social login)
NEXT_PUBLIC_APPLE_CLIENT_ID Apple OAuth client ID No (for social login)

Step 3: Start All Services

Start the entire stack with one command:

docker compose up

This will start:

The first run takes a few minutes as Docker downloads images and installs dependencies.

ℹī¸ First Run

The backend automatically runs database migrations on startup, so your database schema is ready to use immediately.

Step 4: Access Your App

Once all services are running, open your browser:

Service URL Description
Frontend http://localhost:3000 Main application interface
Backend API Docs http://localhost:8000/docs Interactive API documentation (Swagger UI)
Backend ReDoc http://localhost:8000/redoc Alternative API documentation

Step 5: Create Your First User

  1. Visit the registration page: http://localhost:3000/register

  2. Sign up with an email and password:

    • Email: admin@example.com
    • Password: SecurePass123!

  3. Email verification (not required in development):

    • Users are created with is_verified = false by default
    • In development, you can manually verify users if needed (see below)
    • Email verification endpoints are not yet implemented

  4. Login: http://localhost:3000/login

💡 First User = Superadmin

The first registered user automatically receives the superadmin role with full access to all features, including the admin panel.

Manual User Verification (Optional)

If you need to mark a user as verified for testing purposes:

# Access the database
docker compose exec postgres psql -U starterbase -d starterbase

# Mark user as verified
UPDATE users SET is_verified = true WHERE email = 'admin@example.com';

# Exit
\q

Step 6: Explore Features

Now that you're logged in, explore what Starterbase offers:

User Dashboard

Visit http://localhost:3000/dashboard to see:

Visit http://localhost:3000/settings to manage:

Admin Panel (Back Office)

As a superadmin, you have access to the complete back-office at http://localhost:3000/back-office:

Section URL Description
Dashboard /back-office Analytics charts (user growth, revenue, activity, plan distribution) and key metrics
Organizations /back-office/organizations Multi-tenant organization management
Users /back-office/users User management with role assignment and invitation system
Roles /back-office/roles Role and permission management (CRUD operations)
Plans /back-office/plans Subscription plan management
Products /back-office/products Product catalog management
Subscriptions /back-office/subscriptions Active subscription management
Settings /back-office/settings System configuration

API Documentation

The backend provides interactive API docs:

  1. Visit http://localhost:8000/docs (Swagger UI)
  2. Try the "Try it out" feature on any endpoint
  3. Authenticate using the "Authorize" button (paste your JWT access token)

Alternative documentation at http://localhost:8000/redoc (ReDoc)

What's Next?

You're up and running! Here's what to explore next:

Core Guides

Common Issues

Port Already in Use

If you see "port is already allocated", another service is using the port:

# Check what's using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or use different ports in docker-compose.yml

Database Connection Error

If the backend can't connect to PostgreSQL:

# Check if PostgreSQL container is running
docker compose ps

# View PostgreSQL logs
docker compose logs postgres

# Restart services
docker compose restart

Containers Won't Start

Clear Docker volumes and rebuild:

# Stop everything
docker compose down

# Remove volumes (WARNING: deletes all data)
docker compose down -v

# Rebuild and start fresh
docker compose up --build

Stopping the Services

To stop all services:

# Stop and keep containers (faster restart)
docker compose stop

# Stop and remove containers (clean shutdown)
docker compose down

# Stop and remove everything including volumes (clean slate)
docker compose down -v

Need Help?

Congratulations! 🎉 You now have a fully functional application running locally. Start building your product!