Getting Started

Get PulseGen up and running in minutes.

Table of contents

  1. Prerequisites
  2. One-Command Setup
    1. Linux / macOS
    2. Windows (PowerShell)
  3. Manual Setup
    1. 1. Clone the Repository
    2. 2. Configure Environment
    3. 3. Generate Secure Secrets
    4. 4. Start Services
    5. 5. Access the Application
  4. Default Credentials
  5. Docker Compose Profiles
  6. Verify Installation
  7. Creating Your First Survey
  8. Next Steps
  9. Troubleshooting
    1. Docker Compose fails to start
    2. Database connection errors
    3. Frontend shows “API Error”
  10. Getting Help

Prerequisites

Before you begin, ensure you have:

  • Docker (20.10+) and Docker Compose (2.0+)
  • At least 2GB RAM available
  • 10GB disk space

Don’t have Docker? Install Docker Desktop for the easiest setup.

One-Command Setup

The fastest way to get started is with our automated setup script.

Linux / macOS 

1
2
3

git clone https://github.com/genesis-nexus/pulsegen.git
cd pulsegen
./setup.sh

Windows (PowerShell) 

1
2
3

git clone https://github.com/genesis-nexus/pulsegen.git
cd pulsegen
.\setup.ps1

The script will:

  1. Check prerequisites (Docker & Docker Compose)
  2. Generate secure secrets automatically
  3. Configure your environment
  4. Start all services
  5. Provide access URLs and credentials

That’s it! Open http://localhost:3001 to access PulseGen.

Manual Setup

If you prefer manual configuration:

1. Clone the Repository 

1
2

git clone https://github.com/genesis-nexus/pulsegen.git
cd pulsegen

2. Configure Environment 

1

cp .env.example .env

Edit .env with your settings:

1

nano .env  # or use your preferred editor

At minimum, change these values:

POSTGRES_PASSWORD=your_secure_password_here
JWT_SECRET=your_jwt_secret_here
JWT_REFRESH_SECRET=your_refresh_secret_here
ENCRYPTION_KEY=your_64_char_hex_encryption_key_here

Never use default secrets in production. Generate secure values using the commands below.

3. Generate Secure Secrets 

1
2
3
4
5

# Generate JWT secrets (32 characters)
openssl rand -base64 32

# Generate encryption key (64 hex characters)
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

4. Start Services 

1

docker-compose up -d

5. Access the Application

Default Credentials

Change these immediately after first login!

Field Value
Email admin@example.com
Password admin123

Docker Compose Profiles

Choose the setup that fits your needs:

1
2
3
4
5
6
7
8
9
10
11

# Basic setup (Postgres + Backend + Frontend)
docker-compose up -d

# Production with Nginx reverse proxy
docker-compose --profile production up -d

# Production with Redis caching
docker-compose --profile production --profile with-redis up -d

# Development mode (hot-reload enabled)
docker-compose -f docker-compose.dev.yml up

Verify Installation

Check that all services are running:

1

docker-compose ps

Expected output:

1
2
3
4

NAME                STATUS
pulsegen_postgres   running (healthy)
pulsegen_backend    running
pulsegen_frontend   running

Check logs for any issues:

1

docker-compose logs -f

Creating Your First Survey

  1. Log in at http://localhost:3001
  2. Click “Surveys” in the navigation
  3. Click “Create Survey with AI” or “New Survey”
  4. Add questions using the drag-and-drop builder
  5. Click “Publish” to make it live
  6. Share the survey link with respondents

Next Steps

Troubleshooting

Docker Compose fails to start 

1
2
3
4
5
6
7
8
9

# Check docker-compose.yml syntax
docker-compose config

# Verify .env file exists
ls -la .env

# Ensure ports are not in use
lsof -i :3001
lsof -i :5001

Database connection errors 

1
2
3
4
5

# Check postgres container
docker-compose logs postgres

# Verify database is ready
docker-compose exec postgres pg_isready

Frontend shows “API Error”

  1. Check VITE_API_URL matches backend URL
  2. Verify CORS_ORIGIN in backend .env
  3. Ensure backend is running: docker-compose logs backend

Getting Help

  • Documentation: Browse these docs
  • Issues: GitHub Issues
  • Setup Help: Run ./setup.sh --help