There are two ways to get Oolvay running locally. The CLI handles the boilerplate for you. The manual path gives you full control.
The fastest way to get started. The CLI clones the repository, configures your brand, generates a secret, installs dependencies, and tells you exactly what to do next.
bunx oolvay new my-app0 / 2,000 characters
Replace my-app with the name of the directory you want Oolvay to create.
You will be prompted for four things:
| Prompt | Example | Notes |
|---|---|---|
| License key | xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx | Issued at purchase |
| Brand name | Acme | Populates your app name throughout the codebase |
| Domain | acme.com | Used in email addresses and metadata |
| Super-admin email | you@acme.com | Account created with this email is automatically promoted to super admin |
Once the CLI finishes, it will print a summary of the remaining steps. Continue from Step 3: Set up the database below.
Oolvay is developed and tested primarily with Bun. npm, pnpm, and Yarn are fully supported, but Bun is the recommended package manager for the best experience.
Sign in to your Oolvay account, click your profile picture in the top-right corner, and select Developer → License from the dropdown.
Enter your GitHub username in the Redeem License section and click Get Repository Access. Access is granted automatically.
Accept the GitHub repository invitation. GitHub sends it to the email address associated with your GitHub account.
Confirm you can open the repository at github.com/oolvay/starter-kit.
If you need to transfer access to a different GitHub account, return to the License page and submit a new username. Your previous account will lose access immediately. Contact support if you run into issues.
Clone the repository and enter the project directory. Replace my-app with whatever you want your project folder to be named.
git clone https://github.com/oolvay/starter.git my-app
cd my-appInstall dependencies.
bun installCopy the example environment file into your project root as .env.local.
cp .env.example .env.localOpen config/constants.ts and set your brand name, domain, and email sender name.
export const BRANDNAME = "Acme"
export const BRANDDOMAIN = "acme.com"
export const EMAILSENDERNAME = "Arnold"Open config/site.ts and set your super-admin email. The first account created with this email address is automatically promoted to super admin.
authAndSession: {
initialSuperAdminEmail: "you@acme.com",
},Generate a secure random secret and assign it to BETTER_AUTH_SECRET in .env.local.
openssl rand -base64 32Confirm your .env.local has at minimum these four variables set.
NEXT_PUBLIC_APP_URL="http://localhost:3000"
BETTER_AUTH_SECRET=
BETTER_AUTH_URL="http://localhost:3000"
DATABASE_URL=During local development, keep NEXT_PUBLIC_APP_URL and BETTER_AUTH_URL set to http://localhost:3000. Before deploying to production, replace them with your actual domain, such as https://acme.com.
Oolvay uses uses Drizzle ORM with PostgreSQL-compatible database. We recommend Neon for most projects because of its generous free tier, database branching, and excellent developer experience, but you may use any provider that exposes a standard PostgreSQL connection string.
Create a PostgreSQL database with your preferred provider.
Popular options include:
Copy your database connection string. It should follow this format:
postgresql://<user:password>@host:5432/<dbname>DATABASE_URL in .env.local.Run the bundled database migrations to create all required tables:
bun db:migrateOolvay ships with pre-generated migration files. You do not need to run
db:generate during installation.
Neon is the recommended provider for most projects because of its generous free tier, database branching, and excellent developer experience. However, Oolvay works with any PostgreSQL-compatible database.
bun devThe application starts at http://localhost:3000. If the landing page loads without errors, your core setup is working.
On first run, Next.js compiles all routes. This can take 10–20 seconds. Subsequent starts are significantly faster.
| Check | Expected result |
|---|---|
| Application starts | bun dev starts without errors |
| Database migrations | bun db:migrate completes successfully |
| App loads | Visiting http://localhost:3000 displays the landing page |
If the application fails to start, the most common causes are a missing environment variable or an incorrect DATABASE_URL.
A minimal local setup intentionally leaves several systems unconfigured. You do not need them to run the application, but you will need them before deploying to production.
| System | Configuration guide |
|---|---|
| Payment processing | Payments |
| Transactional email | |
| File storage and CDN | Storage |
| Error monitoring | Observability |
| Analytics | Analytics |
| OAuth providers | Authentication |
Oolvay’s environment validation runs at startup. If a required variable is missing, the process will print the offending variable name and exit. Add the missing variable to .env.local and restart.
Confirm your DATABASE_URL is correct and that your database server is reachable. If you are using Neon, free-tier projects may suspend after a period of inactivity and need to be resumed from the Neon dashboard.
Next.js will usually start on the next available port automatically.
If the application starts on a different port (for example, http://localhost:3001), update NEXT_PUBLIC_APP_URL and BETTER_AUTH_URL in .env.local to match before testing authentication features.
GitHub invitations expire after seven days. If yours has expired, contact support and provide your GitHub username and the email address associated with your Oolvay account.