Local Setup

Full control over your development environment. Run Node.js and PostgreSQL directly on your machine.

Prerequisites

Installing PostgreSQL

macOS (Homebrew):

brew install postgresql@15
brew services start postgresql@15
createdb straktur

Ubuntu/Debian:

sudo apt install postgresql-15
sudo systemctl start postgresql
sudo -u postgres createdb straktur

Windows: Download from postgresql.org and run the installer.

Setup Steps

1. Clone and install

git clone <repo-url> my-app
cd my-app
npm install

2. Configure environment

cp .env.example .env.local

Open .env.local and set these values:

# Database
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/straktur"

# Auth secret - generate with: openssl rand -base64 32
BETTER_AUTH_SECRET="your-generated-secret-here"

# App URL
NEXT_PUBLIC_APP_URL="http://localhost:3000"

# Enable seeding
ALLOW_DB_SEED="true"

# Seed user credentials (required for db:seed)
SEED_USER_EMAIL="[email protected]"
SEED_USER_PASSWORD="testingpassword"

Generate the auth secret:

openssl rand -base64 32

3. Setup database

npm run dev:setup  # Create tables + bootstrap user & organization

Or step by step:

npm run db:push       # Create tables
npm run db:bootstrap  # Create user + organization (minimum to run the app)

4. Start the app

npm run dev

Open http://localhost:3000

Seed Options

Bootstrap (used by dev:setup)

Creates the minimum required to run the app:

npm run db:bootstrap

This creates:

• 1 user (from SEED_USER_* env vars)
• 1 organization (from SEED_ORG_* env vars)
• Owner membership

Idempotent and production-safe — skips anything that already exists.

Full seed (adds dictionaries)

Adds dictionary values on top of bootstrap:

npm run db:seed

This creates everything from bootstrap, plus:

• Dictionary values (statuses, industries, regions)

Requires ALLOW_DB_SEED=true in .env.local. Blocked in production.

Demo seed (optional)

Creates a fully populated demo environment:

npm run db:seed:demo

This adds:

• 44 companies with logos
• 70+ contacts
• Activities and files

Note: Demo seed requires S3 storage configured for company logos. Without it, companies are created but logos are skipped.

Customizing Seed Data

You can customize the seed user and organization via environment variables:

# .env.local
SEED_USER_EMAIL="[email protected]"
SEED_USER_PASSWORD="mysecurepassword"
SEED_USER_NAME="My Name"
SEED_ORG_NAME="My Company"
SEED_ORG_SLUG="my-company"

Troubleshooting

# macOS
brew services start postgresql@15

# Linux
sudo systemctl start postgresql

# macOS/Linux
createdb straktur

# Or via psql
psql -c "CREATE DATABASE straktur"

openssl rand -base64 32

ALLOW_DB_SEED="true"

# Edit pg_hba.conf (location varies)
sudo nano /etc/postgresql/15/main/pg_hba.conf

# Change "peer" to "md5" for local connections
# Then restart PostgreSQL
sudo systemctl restart postgresql

Adding Storage and Email (Optional)

For file uploads and email functionality, see:

• Cloud Setup - Configure Cloudflare R2 and Resend
• Environment Variables - All config options

Next Steps

• Project Structure - Understand the codebase
• Add Your First Feature - Build something