Installation

Detailed installation instructions for different environments.

System Requirements

Requirement	Minimum	Recommended
Node.js	20.x	22.x
pnpm	9.x	Latest
Docker	20.x	Latest
RAM	4GB	8GB+
Disk	2GB free	10GB+

Installing Node.js

macOS

# Using Homebrew
brew install node@22
 
# Or using nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
nvm use 22

Linux (Ubuntu/Debian)

# Using NodeSource
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

Windows

Download the installer from nodejs.org or use:

# Using winget
winget install OpenJS.NodeJS.LTS
 
# Or using Chocolatey
choco install nodejs-lts

Installing pnpm

# Using npm
npm install -g pnpm
 
# Or using Corepack (Node.js 16.13+)
corepack enable
corepack prepare pnpm@latest --activate

Installing Docker

macOS

# Using Homebrew
brew install --cask docker
 
# Then start Docker Desktop from Applications

Linux

# Ubuntu/Debian
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Log out and back in

Windows

Download Docker Desktop for Windows.

Installing Postbase

Option 1: npm Global Install

npm install -g postbase

Option 2: pnpm Global Install

pnpm add -g postbase

Option 3: From Source

# Clone repository
git clone https://github.com/zeroexcore/postbase.git
cd postbase
 
# Install dependencies
pnpm install
 
# Build all packages
pnpm build
 
# Link CLI globally
cd packages/cli
pnpm link --global

Option 4: npx (No Install)

# Run without installing
npx postbase start
npx postbase db create myapp

Verify Installation

# Check CLI version
postbase --version
 
# Check Docker is running
docker info
 
# Start Postbase
postbase start
 
# Check status
postbase status

Expected output:

Postbase Status
 
Daemon:     Running (PID: 12345)
API:        http://localhost:9432
PostgreSQL: Running (Port: 5432)
Databases:  2
 
Databases:
  - myapp (12.5 MB)
  - demo (3.2 MB)

Uninstalling

npm

npm uninstall -g postbase

pnpm

pnpm remove -g postbase

Complete Cleanup

# Stop daemon
postbase stop
 
# Remove Docker container
docker rm -f postbase-postgres
 
# Remove data directory
rm -rf ~/.postbase

Troubleshooting Installation

Docker not found

Ensure Docker is installed and the daemon is running:

docker info

If not running, start Docker Desktop or:

# Linux
sudo systemctl start docker

Permission denied

On Linux, add your user to the docker group:

sudo usermod -aG docker $USER
# Log out and back in

Port already in use

If port 5432 is already in use:

# Check what's using the port
lsof -i :5432
 
# Or use a different port
POSTBASE_PORT=9433 postbase start

Node.js version mismatch

Ensure you're using Node.js 20+:

node --version
# Should show v20.x.x or later