Comprehensive installation and setup guide for the BISO Sites monorepo including prerequisites, environment configuration, and Appwrite setup.

Installation Guide

This guide covers everything you need to install and configure the BISO Sites monorepo for development, from system prerequisites to full Appwrite integration.

ℹ️

Already set up?

If you just want to get running quickly, see the Quickstart Guide.

Prerequisites

Required Software

Before installing BISO SItes, ensure you have these tools installed:

Tool	Version	Purpose	Install Link
Node.js	>= 18.0	JavaScript runtime	nodejs.org
Bun	>= 1.3.1	Package manager & runtime	bun.sh
Git	Latest	Version control	git-scm.com

Optional Tools

These are optional but recommended for the full development experience:

Tool	Purpose
Docker	For running Appwrite locally
VS Code	Recommended IDE with great TypeScript support
Appwrite Cloud Account	Alternative to self-hosting Appwrite

Verify Installation

Check your installations:

# Check Node.js
node --version  # Should be >= 18.0

# Check Bun
bun --version   # Should be >= 1.3

# Check Git
git --version   # Any modern version

Installation Steps

Clone the Repository

Get the code from your repository:

git clone https://github.com/biso-no/biso-sites.git
cd biso-sites

Install Dependencies

Use Bun to install all workspace dependencies:

bun install

This installs dependencies for:

All 3 applications (web, admin, docs)
All 5 packages (api, ui, editor, payment, configs)
Root workspace tools

What's happening?

Bun reads package.json in the root
Identifies all workspaces in apps/* and packages/*
Installs dependencies for each workspace
Creates a single node_modules at the root
Generates bun.lock lockfile

✅

Fast Installation

Bun is significantly faster than npm/yarn. A full install typically takes 10-30 seconds.

Verify Installation

Ensure everything installed correctly:

# Check workspace structure
bun run --help

# Verify TypeScript setup
bun run check-types

# Run linters
bun run lint

All commands should complete without errors.

Environment Setup

Each application requires environment variables for full functionality.

Web Application Environment

Create apps/web/.env.local:

# Appwrite Configuration
NEXT_PUBLIC_APPWRITE_ENDPOINT=https://your-appwrite-endpoint.com/v1
NEXT_PUBLIC_APPWRITE_PROJECT_ID=your-project-id

# Optional: For server-side operations
APPWRITE_API_KEY=your-api-key

# Payment Integration (Vipps)
NEXT_PUBLIC_VIPPS_CLIENT_ID=your-vipps-client-id
VIPPS_CLIENT_SECRET=your-vipps-secret
VIPPS_SUBSCRIPTION_KEY=your-subscription-key
VIPPS_TEST_MODE=true

# Optional: Analytics & Monitoring
NEXT_PUBLIC_GA_ID=your-google-analytics-id

Admin Application Environment

Create apps/admin/.env.local:

# Appwrite Configuration
NEXT_PUBLIC_APPWRITE_ENDPOINT=https://your-appwrite-endpoint.com/v1
NEXT_PUBLIC_APPWRITE_PROJECT_ID=your-project-id
APPWRITE_API_KEY=your-api-key

# AI Features (optional)
OPENAI_API_KEY=your-openai-key

# Admin-specific
NEXT_PUBLIC_ADMIN_URL=http://localhost:3001

Docs Application Environment

The docs app typically doesn't need environment variables for local development.

⚠️

Never Commit Secrets

.env.local files are gitignored. Never commit secrets to the repository!

Appwrite Setup

BISO SItes uses Appwrite as its backend. You have two options:

Option 1: Appwrite Cloud (Recommended for Beginners)

Create Appwrite Account

Create a New Project

Click "Create Project"
Name it (e.g., "BISO SItes Development")
Copy the Project ID

Create an API Key

Go to Settings → API Keys
Create new key with necessary permissions
Copy the API key (you won't see it again!)

Configure Applications

Add platform (Web) for your domains
For localhost: http://localhost:3000, http://localhost:3001

Update Environment Variables

Update your .env.local files with:

Appwrite endpoint (from cloud)
Project ID
API key

Option 2: Self-Hosted Appwrite

Install Docker

Ensure Docker and Docker Compose are installed.

Install Appwrite

# Create directory for Appwrite
mkdir appwrite
cd appwrite

# Download docker-compose.yml
curl -o docker-compose.yml https://appwrite.io/install/compose

# Start Appwrite
docker compose up -d

Access Appwrite Console

Open http://localhost:80 and complete setup wizard.

Configure Environment

Use http://localhost:80/v1 as your NEXT_PUBLIC_APPWRITE_ENDPOINT.

ℹ️

Detailed Appwrite Setup

For complete Appwrite database schema and configuration, see Appwrite Setup.

Database Schema

Once Appwrite is set up, you need to create the database schema. This can be done via:

Appwrite Console - Manually create collections and attributes
Appwrite CLI - Import from database.json files
Migration Scripts - Run provided migration scripts

Example using Appwrite CLI:

# Install Appwrite CLI
npm install -g appwrite-cli

# Login to your Appwrite instance
appwrite login

# Deploy database schema (from apps/web or apps/admin)
cd apps/web
appwrite deploy collection

📝

Database schema files are located in apps/web/database.json and apps/admin/database.json.

Running the Applications

After installation and configuration:

Start All Applications

# From root directory
bun run dev

This starts:

Start Individual Applications

# Web only
bun run dev --filter=web

# Admin only
bun run dev --filter=admin

# Docs only
bun run dev --filter=docs

Build for Production

# Build all applications
bun run build

# Build specific application
bun run build --filter=web

Development Tools Setup

VS Code Extensions (Recommended)

Install these extensions for the best development experience:

{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "bradlc.vscode-tailwindcss",
    "ms-vscode.vscode-typescript-next",
    "unifiedjs.vscode-mdx"
  ]
}

Git Hooks

Set up Git hooks for automatic linting and formatting:

# Install husky (if not already in package.json)
bun add -D husky

# Enable Git hooks
bunx husky install

Verification Checklist

After installation, verify everything works:

All dependencies installed without errors
bun run check-types passes
bun run lint passes
bun run dev starts all applications
Can access all three applications in browser
Appwrite connection working (check browser console)
Hot reload working (make a change and see it update)

Troubleshooting

Bun Installation Issues

If Bun fails to install:

# On macOS/Linux
curl -fsSL https://bun.sh/install | bash

# On Windows (use WSL)
wsl --install
# Then install Bun in WSL

Dependency Installation Failures

# Clear all node_modules and reinstall
rm -rf node_modules apps/*/node_modules packages/*/node_modules
rm bun.lock
bun install

Port Conflicts

If ports 3000, 3001, or 3002 are already in use:

Find and kill the process:

# macOS/Linux
lsof -ti:3000 | xargs kill -9

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

Change the port in apps/*/package.json:

{
  "scripts": {
    "dev": "next dev -p 3050"
  }
}

Appwrite Connection Issues

Verify environment variables are correct
Check Appwrite console is accessible
Verify platform is added in Appwrite project settings
Check browser console for specific error messages
Ensure CORS is configured correctly in Appwrite

TypeScript Errors

# Generate Next.js types
cd apps/web
bunx next build --typegen-only

# Check types across workspace
bun run check-types

Module Resolution Issues

If imports aren't working:

Check tsconfig.json has correct paths
Restart TypeScript server in VS Code: Cmd+Shift+P → "TypeScript: Restart TS Server"
Ensure package names in package.json match imports

Next Steps

Now that you're set up:

Learn the Architecture - Architecture Overview
Explore the Code - Project Structure
Start Developing - Development Workflow
Build a Feature - Creating Features

✅

Successfully Installed!

You're all set! Head to the Development Workflow to learn about day-to-day development.

Installation Guide

Clone the Repository

Install Dependencies

Verify Installation

Create Appwrite Account

Create a New Project

Create an API Key

Configure Applications

Update Environment Variables

Install Docker

Install Appwrite

Access Appwrite Console

Configure Environment

On this page