Installation

Set up your BrewHoard development environment with all required dependencies and configurations.

This guide walks you through setting up a complete BrewHoard development environment from scratch.

Prerequisites

Before you begin, ensure you have the following installed:

Required Software

Software	Version	Purpose
Node.js	20.x or later	JavaScript runtime
npm	10.x or later	Package manager
PostgreSQL	15.x or later	Database
Git	2.x	Version control

Optional Software

Software	Purpose
Docker	Containerized PostgreSQL
VS Code	Recommended editor with Svelte extension

System Check

Verify your installations:

Bash

# Check Node.js version
node --version
# Should output: v20.x.x or higher

# Check npm version
npm --version
# Should output: 10.x.x or higher

# Check PostgreSQL
psql --version
# Should output: psql (PostgreSQL) 15.x or higher

# Check Git
git --version
# Should output: git version 2.x.x

Clone the Repository

Bash

# Clone via HTTPS
git clone https://github.com/Skediaio/beer-vault.git

# Or via SSH
git clone git@github.com:Skediaio/beer-vault.git

# Navigate to project directory
cd beer-vault

Install Dependencies

Bash

# Install all npm packages
npm install

This installs:

SvelteKit - Application framework
Svelte 5 - UI library with runes
postgres - PostgreSQL client
postgres-shift - Migration tool
@inlang/paraglide-sveltekit - i18n
tailwindcss - Styling
shadcn-svelte - Component library
stripe - Payment processing

Database Setup

Option 1: Local PostgreSQL

Bash

# Create the database
createdb brewhoard_dev

# Verify connection
psql -d brewhoard_dev -c "SELECT version();"

Option 2: Docker PostgreSQL

Bash

# Start PostgreSQL container
docker run -d 
  --name brewhoard-postgres 
  -e POSTGRES_DB=brewhoard_dev 
  -e POSTGRES_USER=postgres 
  -e POSTGRES_PASSWORD=postgres 
  -p 5432:5432 
  postgres:15-alpine

# Verify it's running
docker ps | grep brewhoard-postgres

Environment Configuration

Create your local environment file:

Bash

# Copy the example environment file
cp .env.example .env

Edit .env with your configuration:

Bash

# Database connection
DATABASE_URL="postgres://postgres:postgres@localhost:5432/brewhoard_dev"

# Session secret (generate a random string)
SESSION_SECRET="your-random-secret-at-least-32-characters"

# Stripe keys (for marketplace payments)
STRIPE_SECRET_KEY="sk_test_..."
STRIPE_PUBLISHABLE_KEY="pk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."

# Vision API (for beer scanner)
VISION_API_KEY="your-vision-api-key"

# File storage
STORAGE_PATH="./uploads"

# Email (optional)
SMTP_HOST="smtp.example.com"
SMTP_PORT="587"
SMTP_USER="user@example.com"
SMTP_PASS="password"

Generating a Session Secret

Bash

# Using Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Or using openssl
openssl rand -hex 32

Run Migrations

Apply the database schema:

Bash

# Run all pending migrations
npm run migrate

This creates all required tables:

users - User accounts
sessions - Authentication sessions
api_keys - API key authentication
beers - Beer catalog
breweries - Brewery information
user_collection - User’s beer collection
collection_history - Consumption history
marketplace_listings - Items for sale
transactions - Purchase records
ratings - User reviews
And more…

Verify Installation

Start the development server:

Bash

npm run dev

You should see:

Text

  VITE v5.x.x  ready in xxx ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: http://192.168.x.x:5173/
  ➜  press h + enter to show help

Open http://localhost:5173 in your browser. You should see the BrewHoard homepage.

Seed Data (Optional)

For development, you may want sample data:

Bash

# Run the seed script
npm run seed

# This creates:
# - Sample beers and breweries
# - Test user accounts
# - Example collection items
# - Marketplace listings

IDE Setup

VS Code Extensions

Install these recommended extensions:

Svelte for VS Code - Syntax highlighting and IntelliSense
ESLint - Code linting
Prettier - Code formatting
Tailwind CSS IntelliSense - Tailwind autocomplete
PostgreSQL - Database browser

VS Code Settings

Add to .vscode/settings.json:

JSON

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[svelte]": {
    "editor.defaultFormatter": "svelte.svelte-vscode"
  },
  "svelte.enable-ts-plugin": true,
  "tailwindCSS.includeLanguages": {
    "svelte": "html"
  }
}

Troubleshooting

Port Already in Use

Bash

# Find process using port 5173
lsof -i :5173

# Kill the process
kill -9 <PID>

Database Connection Failed

Verify PostgreSQL is running:
Bash
```
pg_isready -h localhost -p 5432
```
Check your DATABASE_URL in .env
Ensure the database exists:
Bash
```
psql -l | grep brewhoard
```

Migration Errors

Bash

# Reset and re-run migrations (DESTRUCTIVE!)
npm run migrate:reset

# Or check migration status
npm run migrate:status

Node Module Issues

Bash

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

Next Steps

With installation complete, you’re ready to:

Quick Start - Build your first feature
Architecture - Understand the codebase
Database - Explore the schema

Having issues? Check our GitHub Issues or open a new one.