Skip to main content
This guide will help you go from zero to a working application in less than 10 minutes. For detailed setup instructions, see the Installation page.

​
Prerequisites

Before you begin, ensure you have:
  • Node.js 20 or higher
  • pnpm 10.18.0 or higher
  • Docker and Docker Compose (for database services)
1

Create Your Project

Use the AdonisJS CLI to scaffold a new project from the starter kit template:
pnpm create adonisjs@latest -K="filipebraida/adonisjs-starter-kit"
This command clones the starter kit repository and sets up your project structure with all necessary dependencies.
You’ll be prompted to:
  • Enter your project name
  • Choose your preferred package manager (select pnpm)
  • Configure additional options
Navigate to your project directory:
cd your-project-name
2

Configure Environment Variables

Copy the example environment file and configure your application:
cp apps/web/.env.example apps/web/.env
Generate a secure application key:
node apps/web/ace generate:key
The generate:key command creates a cryptographically secure key and automatically updates your .env file.
Your .env file will contain essential configuration:
TZ=UTC
PORT=3333
HOST=localhost
LOG_LEVEL=info
DRIVE_DISK=fs
APP_KEY=your-generated-key-here
NODE_ENV=development
SESSION_DRIVER=cookie

# Database Configuration
DB_HOST=127.0.0.1
DB_PORT=5432
DB_USER=root
DB_PASSWORD=root
DB_DATABASE=app

# Email Configuration (Mailpit for local development)
SMTP_HOST=localhost
SMTP_PORT=1025

# API URL
VITE_API_URL=http://localhost:3333
Don’t commit your .env file to version control. The starter kit includes it in .gitignore by default.
3

Start Database Services

Launch PostgreSQL, PgAdmin, and Mailpit using Docker Compose:
docker compose up -d
This command starts three essential services:

PostgreSQL

Database server on port 5432

PgAdmin

Database admin UI on port 5050

Mailpit

Email testing on port 8025
The PostgreSQL container automatically initializes with a development database named adonis_app using the script at .github/postgres/dev-init.sql.
Verify services are running:
docker compose ps
You should see all three services with status “Up”.
4

Initialize Database

Run migrations to create the database schema:
pnpm --filter web exec node ace migration:run
This creates all necessary tables including:
  • roles - User roles and permissions
  • users - User accounts
  • access_tokens - API authentication tokens
  • reset_password_tokens - Password recovery tokens
  • rate_limits - API rate limiting
Seed the database with initial data:
pnpm --filter web exec node ace db:seed
The seeder creates default users and roles. Check the seeder file at apps/web/app/users/database/seeders/user_seeder.ts to see what data is created.
5

Start Development Server

Launch the development server with hot module reloading:
pnpm run dev
TurboRepo orchestrates the build process, starting the AdonisJS server and Vite dev server simultaneously.
You should see output similar to:
• web:dev: [info] starting HTTP server on http://localhost:3333
• web:dev: [info] vite dev server started on http://localhost:5173
Open your browser and navigate to:
http://localhost:3333
The application uses Inertia.js, so requests go to port 3333 (AdonisJS), which serves React components bundled by Vite.

​
What You’ve Accomplished

Congratulations! You now have a fully functional AdonisJS Starter Kit application with:
  • ✅ Complete monorepo structure with TurboRepo
  • ✅ PostgreSQL database with migrations and seed data
  • ✅ Development environment with hot reloading
  • ✅ Email testing with Mailpit
  • ✅ Database administration with PgAdmin
  • ✅ Modern React frontend with Inertia.js
  • ✅ Tailwind CSS and ShadCN components

​
Access Your Services

Application

Main application interface

Mailpit

View test emails

PgAdmin

Database administrationLogin:

​
Default Credentials

Default credentials are for development only. Change them in production!
Check your seeder file to find the default user accounts created during the setup.

​
Next Steps

Explore the Codebase

Monorepo Structure:
  • apps/web/ - Main application
  • packages/ui/ - Shared components
  • apps/web/app/ - Feature modules (auth, users, analytics)

Add UI Components

Install ShadCN components:
pnpm dlx shadcn@latest add button -c apps/web

Create Modules

Generate a new feature module:
node ace make:module products

Configure Social Auth

Set up authentication providers:
  • Google OAuth
  • GitHub OAuth
  • More via @adonisjs/ally

​
Troubleshooting

Ensure Docker services are running:
docker compose ps
Check your database credentials in .env match the Docker Compose configuration.
If port 3333 is busy, change it in apps/web/.env:
PORT=3334
VITE_API_URL=http://localhost:3334
Reset your database and try again:
pnpm --filter web exec node ace migration:rollback
pnpm --filter web exec node ace migration:run
Clear your build cache and reinstall dependencies:
rm -rf node_modules apps/web/node_modules packages/*/node_modules
pnpm install
For detailed configuration options and advanced setup, see the Installation guide.

​
Learn More

Installation Guide

Detailed setup instructions and configuration options

AdonisJS Docs

Official AdonisJS documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us