Quickstart

VibeAny is delivered as a source archive that you customize into your own SaaS. This guide takes you from the delivered files to a working local application using the supported setup path.

Prerequisites

Install the following before you begin:

• Node.js 24.0.1 or newer
• npm 11.3.0 or newer
• Docker Desktop or another Docker-compatible runtime if you want the included local PostgreSQL and Mailpit services
• A standard PostgreSQL connection URL if you prefer a hosted database

The starter is locked with package-lock.json and supports npm only.

1. Verify and extract the archive

Keep the source archive and its .sha256 sidecar together. Verify the transport checksum before extracting it:

shasum -a 256 -c vibeany-starter-<version>.tar.gz.sha256
tar -xzf vibeany-starter-<version>.tar.gz
cd vibeany-starter-<version>

The extracted root also contains release-manifest.json and SHA256SUMS. The sidecar verifies the compressed archive, while SHA256SUMS describes the delivered source inventory.

Do not publish the extracted starter source in a public repository. Your order and the included commercial license define who may access and use it.

2. Install exact dependencies

npm ci

Use npm ci for a clean, reproducible install from the supplied lockfile. Do not replace the lockfile or switch package managers during initial activation.

3. Run the setup wizard

npm run setup

The wizard guides you through the supported local setup:

1. Choose the included Docker PostgreSQL service or provide an external PostgreSQL URL.
2. Test the database connection before continuing.
3. Generate BETTER_AUTH_SECRET when it is not already configured.
4. Enable email and password authentication.
5. Optionally configure Google OAuth.
6. Optionally configure one payment provider: Stripe or Creem.
7. Write or update .env.local without committing it.
8. Optionally apply the committed database migrations.

When you choose the Docker database, the wizard starts both PostgreSQL and Mailpit. If you choose an external database but still want local email capture, start Mailpit separately:

docker compose up -d mailpit

You can run the wizard again later to add optional integrations. Review existing values when it asks whether to keep or replace them.

4. Start the application

npm run dev

Open http://localhost:3000. The root route redirects to the default locale, currently /en.

5. Verify the local baseline

Use these routes to check the core application:

For local email authentication, open http://localhost:8025 after signing up. Mailpit captures verification and password-reset emails without sending them to the public internet.

Manual setup

If you do not want to use the wizard, copy the documented environment template and start the local services:

cp .env.example .env.local
docker compose up -d db mailpit
openssl rand -base64 32

Add the generated secret and the local values to .env.local:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/vibeany
BETTER_AUTH_SECRET=<generated-secret>
NEXT_PUBLIC_SITE_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_ENABLE_EMAIL_AUTH=true
NEXT_PUBLIC_ENABLE_PAYMENTS=false

Apply the committed migrations, then start Next.js:

npm run db:migrate
npm run dev

Never use db:push or drizzle-kit push. VibeAny deliberately requires reviewed, committed migrations in every environment.

If port 5432 is already in use, let the wizard configure a different host port:

VIBEANY_POSTGRES_PORT=55432 npm run setup

Stop the included services when you are done:

docker compose down

Next steps

• Understand the code ownership boundaries in Project structure.
• Review every supported variable in Environment configuration.
• Replace the example product identity in Branding and internationalization.
• Configure sign-in and delivery in Authentication and email.
• Learn the migration-only workflow in Database.