Installation & Local Development
Step-by-step guide to installing Vibestacks locally. Learn how to set up Docker, install dependencies with pnpm, and launch your development server in minutes.
This guide will walk you through setting up Vibestacks on your local machine. By the end, you'll have a fully running development environment ready for building your SaaS.
Prerequisites
Before you begin, make sure you have the following installed on your system.
Node.js
Node.js is the runtime environment that executes JavaScript code outside of a browser.
node --version
# Required: v18.0.0 or higherIf Node.js is not installed or outdated, download it from the official Node.js website. We recommend using the LTS version.
Pro Tip
Use nvm (Node Version Manager) to easily switch between Node.js versions across different projects.
Git
Git is the version control system used to track changes and collaborate on code.
git --versionIf Git is not installed, download it from the official Git website.
Docker
Docker is required to run the local PostgreSQL database and other services. Vibestacks uses Docker Compose to orchestrate your local development environment.
docker --version
docker compose versionIf Docker is not installed, download Docker Desktop for your operating system.
New to Docker?
Not sure what Docker is or why we use it? Read our guide on What is Docker and why does Vibestacks use it? for a beginner-friendly explanation.
Package Manager (pnpm)
We strongly recommend using pnpm for Vibestacks. It's significantly faster and handles dependencies more efficiently than npm or yarn.
npm install -g pnpmpnpm --versionWhy pnpm?
Curious about the benefits? Read our detailed breakdown on Why pnpm is the industry standard compared to npm and yarn.
Quick Installation
Follow these steps to get Vibestacks running on your machine in under 5 minutes.
Download the Source Code
Choose how you want to download Vibestacks. We recommend Forking the repository so you can easily pull future updates and improvements.
Forking creates your own copy of the repository that stays linked to the original, making it easy to sync updates.
- Visit the Vibestacks GitHub Repository.
- Click the Fork button in the top-right corner.
- Important: Set the visibility to Private.
Once forked, clone your copy to your machine:
git clone https://github.com/YOUR_USERNAME/vibestacks.git my-saas
cd my-saasIf you have direct access to the repository or are just testing locally:
git clone https://github.com/your-username/vibestacks-shipfast.git my-saas
cd my-saasIf you prefer not to use Git:
- Go to the Vibestacks Repository.
- Click Code → Download ZIP.
- Extract the ZIP file to your preferred location.
- Open the extracted folder in your terminal.
cd path/to/vibestacksKeep It Private
Per your license agreement, Vibestacks source code must remain in a private repository and cannot be redistributed. Violations may result in license termination and legal action. See full terms.
Install Dependencies
Install all project dependencies using pnpm. This will also set up any required tooling.
pnpm installThis process typically takes 30-60 seconds depending on your internet connection.
Run the Setup Script
Vibestacks includes an interactive setup script that handles everything for you - environment variables, Docker containers, and database initialization.
pnpm setupThe setup script will:
- Create your
.env.localfile from the template - Guide you through configuring required environment variables
- Start the Docker containers (PostgreSQL database)
- Push the database schema using Drizzle ORM
- Optionally seed the database with sample data
What's happening under the hood?
The setup script runs tsx scripts/init.ts, which orchestrates your local environment. It uses T3 Env for type-safe environment variable validation - if any required variables are missing or invalid, you'll get clear error messages telling you exactly what to fix.
Start the Development Server
Once setup is complete, start the local development server:
pnpm devOpen http://localhost:3000 in your browser to see your app running.
Success!
If you see the Vibestacks landing page, congratulations - your setup is complete!
Manual Setup (Alternative)
If you prefer to configure everything manually instead of using the setup script, follow these steps.
Configure Environment Variables
Copy the example environment file to create your local configuration:
cp .env.example .env.localOpen .env.local in your editor and fill in the required values. For a detailed explanation of each variable, see the Environment Setup guide.
Type-Safe Environment Variables
Vibestacks uses T3 Env for runtime validation of environment variables. If a required variable is missing or has an invalid format, the app will fail to start with a descriptive error message - no more silent failures from typos.
Start Docker Containers
Spin up the local PostgreSQL database and any other required services:
docker compose up -dThis starts the containers in detached mode. To view logs:
docker compose logs -fPush the Database Schema
Once the database container is running, push the Drizzle schema:
pnpm db:pushSeed the Database (Optional)
Populate the database with sample data for development:
pnpm db:seedAvailable Scripts
Here's a quick reference of the most useful commands:
| Command | Description |
|---|---|
pnpm dev | Start the development server on port 3000 |
pnpm build | Create a production build |
pnpm start | Run the production build locally |
pnpm setup | Interactive setup script for first-time configuration |
pnpm db:push | Push schema changes to the database |
pnpm db:generate | Generate migration files from schema changes |
pnpm db:migrate | Run pending database migrations |
pnpm db:studio | Open Drizzle Studio to browse your database |
pnpm db:seed | Seed the database with sample data |
pnpm email | Preview email templates on port 3001 |
pnpm lint | Run ESLint to check for code issues |
Troubleshooting
Having issues? Here are solutions to common problems.
Port 3000 is already in use
Another application is using port 3000. Either stop that application or run Vibestacks on a different port:
pnpm dev --port 3001Docker containers won't start
Ensure Docker Desktop is running, then try restarting the containers:
docker compose down
docker compose up -dIf issues persist, check for port conflicts (PostgreSQL uses port 5432 by default).
Database connection errors
Verify your DATABASE_URL in .env.local matches the Docker container configuration. The default local connection string is:
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/vibestacks"Environment variable validation errors
T3 Env will show you exactly which variables are missing or invalid. Check the error message and update your .env.local file accordingly.
Module not found errors
Try clearing the cache and reinstalling dependencies:
rm -rf node_modules .next
pnpm installNext Steps
Now that Vibestacks is running, continue with the setup:
- Environment Setup - Deep dive into all environment variables
- Database Setup - Learn more about Drizzle ORM and migrations
- IDE Setup - Optimize your editor for the best experience
Vibestacks Introduction
Get started with Vibestacks, the complete SaaS starter kit featuring Next.js 16, React 19, Tailwind CSS v4, and Better Auth. Build and ship production-ready apps faster.
Environment Variables & Configuration
Configure type-safe environment variables with T3 Env. Learn how to securely manage database credentials, authentication secrets, and API keys for local and production environments.