Installation

PulseDB can be deployed using Docker or run locally with Node.js.

Docker (recommended)

Docker is the recommended way to run PulseDB. It handles all dependencies and provides persistent storage.

Docker Compose

Create a docker-compose.yml file:

yaml

services:
  pulsedb:
    build: .
    ports:
      - "5433:3000"
    volumes:
      - pulsedb-data:/data
    restart: always

volumes:
  pulsedb-data:

Then start the service:

bash

docker compose up -d

Port configuration

The default port is 5433 (a nod to PostgreSQL's 5432). Change it in your docker-compose.yml:

yaml

ports:
  - "8080:3000"

Volumes

PulseDB stores encrypted connection configs and the encryption key in a Docker volume:

/data
├── connections.json      # Encrypted connection configurations
└── encryption.key        # Auto-generated AES-256 key

Local development

Prerequisites

Node.js 20+
npm

Setup

bash

git clone https://github.com/elmoziml/pulsedb.git
cd pulsedb
npm install
npm run dev

Available commands

Command	Description
`npm run dev`	Start development server
`npm run build`	Build for production
`npm start`	Start production server
`npm run lint`	Run ESLint

Production deployment

For production, build and start:

bash

npm run build
npm start

Or use the Docker setup:

bash

docker compose up -d --build

Updating

PulseDB is built from source, so updating to a new version means pulling the latest code and rebuilding the image.

Docker (recommended)

Run the two commands one after another, they are not a single command:

bash

cd pulsedb
# Step 1 — pull the latest code
git pull
# Step 2 — rebuild and restart the container
docker compose up -d --build

Your data is safe during an update — connection configs and the encryption key live in the pulsedb-data volume and are never touched by the rebuild.

Local development

bash

cd pulsedb
git pull
npm install
npm run dev

Version pinning

Currently docker-compose.yml builds from the latest commit on main, so updates pull whatever is newest. If you want a reproducible deployment, check out a specific tag or commit first:

bash

cd pulsedb
git pull
git checkout <tag-or-commit>
docker compose up -d --build

Troubleshooting

If the build fails after updating, check whether the new version changed the Docker setup or environment variables:

bash

git log --oneline -10
git show HEAD -- docker-compose.yml Dockerfile

You can always roll back to a previous working commit and redeploy.