New protocol version released: This page may contain outdated information.

Installation

The HAIP Server can be installed and deployed in multiple ways. Choose the method that best fits your environment and requirements.

Prerequisites

Node.js

Version 18.0.0 or higher

npm

Version 8.0.0 or higher

Git

For cloning the repository

Method 1: From Source

Clone the Repository

git clone https://github.com/haiprotocol/haip cd haip/haip-server

Install Dependencies

bash npm install

Build the Project

bash npm run build

Start the Server

bash # Development mode npm run dev # Production mode npm start

Method 2: Docker

Pull the Image

docker pull haip-protocol/server:latest

Run the Container

docker run -p 8080:8080 haip-protocol/server:latest

Using Docker Compose

Create a docker-compose.yml file:

version: "3.8"
services:
  haip-server:
    image: haip-protocol/server:latest
    ports:
      - "8080:8080"
    environment:
      - JWT_SECRET=your-secret-key
      - PORT=8080
      - NODE_ENV=production
    restart: unless-stopped

Run with:

docker-compose up -d

Method 3: NPM Package

Available Now: The HAIP Server is available on npm as @haip/server.

npm install @haip/server

import { HAIPServer } from "@haip/server";

const server = new HAIPServer();
server.start();

Environment Configuration

The server can be configured using environment variables:

Required Environment Variables

# JWT secret for token validation
JWT_SECRET=your-secret-key-here

# Server port (default: 8080)
PORT=8080

# Server host (default: 0.0.0.0)
HOST=0.0.0.0

Optional Environment Variables

# JWT expiration time (default: 24h)
JWT_EXPIRES_IN=24h

# Maximum connections (default: 1000)
MAX_CONNECTIONS=1000

# Heartbeat interval in ms (default: 30000)
HEARTBEAT_INTERVAL=30000

# Heartbeat timeout in ms (default: 5000)
HEARTBEAT_TIMEOUT=5000

# Enable CORS (default: true)
ENABLE_CORS=true

# Enable compression (default: true)
ENABLE_COMPRESSION=true

# Enable logging (default: true)
ENABLE_LOGGING=true

# Node environment (default: development)
NODE_ENV=production

Flow Control Configuration

# Enable flow control (default: true)
FLOW_CONTROL_ENABLED=true

# Initial message credits (default: 1000)
FLOW_CONTROL_INITIAL_CREDITS=1000

# Minimum credits (default: 100)
FLOW_CONTROL_MIN_CREDITS=100

# Maximum credits (default: 10000)
FLOW_CONTROL_MAX_CREDITS=10000

# Credit threshold (default: 200)
FLOW_CONTROL_CREDIT_THRESHOLD=200

# Back-pressure threshold (default: 0.8)
FLOW_CONTROL_BACK_PRESSURE_THRESHOLD=0.8

# Adaptive adjustment (default: true)
FLOW_CONTROL_ADAPTIVE_ADJUSTMENT=true

# Initial credit bytes (default: 1048576)
FLOW_CONTROL_INITIAL_CREDIT_BYTES=1048576

Development Setup

Install Development Dependencies

npm install --include=dev

Run Tests

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:websocket

# Run tests with open handle detection
npm run test:detect-open-handles

Development Scripts

# Start in development mode with hot reload
npm run dev

# Build the project
npm run build

# Lint the code
npm run lint

# Format the code
npm run format

# Type check
npm run type-check

Production Setup

Security Considerations

JWT Secret: Use a strong, unique secret key
Environment: Set NODE_ENV=production
HTTPS: Use HTTPS in production with proper certificates
Firewall: Configure firewall rules appropriately
Rate Limiting: Consider additional rate limiting for production

Example Production Configuration

# Production environment variables
NODE_ENV=production
JWT_SECRET=your-very-secure-secret-key-here
PORT=8080
HOST=0.0.0.0
MAX_CONNECTIONS=1000
ENABLE_CORS=false
ENABLE_COMPRESSION=true
ENABLE_LOGGING=true
FLOW_CONTROL_ENABLED=true

Docker Production Setup

version: "3.8"
services:
  haip-server:
    image: haip-protocol/server:latest
    ports:
      - "8080:8080"
    environment:
      - NODE_ENV=production
      - JWT_SECRET=${JWT_SECRET}
      - PORT=8080
      - MAX_CONNECTIONS=1000
      - ENABLE_CORS=false
      - ENABLE_COMPRESSION=true
      - ENABLE_LOGGING=true
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    volumes:
      - ./logs:/app/logs

Verification

After installation, verify the server is running correctly:

Health Check

curl http://localhost:8080/health

Expected response:

{
  "status": "ok",
  "uptime": 12345,
  "activeConnections": 0,
  "totalConnections": 0
}

Statistics

curl http://localhost:8080/stats

Expected response:

{
  "totalConnections": 0,
  "activeConnections": 0,
  "totalMessages": 0,
  "messagesPerSecond": 0,
  "averageLatency": 0,
  "errorRate": 0,
  "uptime": 12345
}

WebSocket Connection

# Test WebSocket connection
wscat -c "ws://localhost:8080/haip/websocket?token=your-jwt-token"

Troubleshooting

Common Issues

Port Already in Use

# Check what's using the port
lsof -i :8080

# Kill the process or change the port
PORT=8081 npm start

JWT Secret Not Set

# Set the JWT secret
export JWT_SECRET=your-secret-key
npm start

Permission Denied

# Fix permissions
sudo chown -R $USER:$USER .

Docker Issues

# Check Docker logs
docker logs haip-server

# Restart the container
docker-compose restart

Logs

Check the server logs for debugging:

# Development logs
npm run dev

# Docker logs
docker logs haip-server

# Production logs
tail -f logs/haip-server.log

Next Steps

Quick Start - Get up and running quickly
Configuration - Configure the server
Deployment - Deploy to production
API Reference - Complete API documentation

​Installation

​Prerequisites

Node.js

npm

Git

​Method 1: From Source

​Method 2: Docker

​Pull the Image

​Run the Container

​Using Docker Compose

​Method 3: NPM Package

​Environment Configuration

​Required Environment Variables

​Optional Environment Variables

​Flow Control Configuration

​Development Setup

​Install Development Dependencies

​Run Tests

​Development Scripts

​Production Setup

​Security Considerations

​Example Production Configuration

​Docker Production Setup

​Verification

​Health Check

​Statistics

​WebSocket Connection

​Troubleshooting

​Common Issues

​Logs

​Next Steps

Installation

Prerequisites

Method 1: From Source

Method 2: Docker

Pull the Image

Run the Container

Using Docker Compose

Method 3: NPM Package

Environment Configuration

Required Environment Variables

Optional Environment Variables

Flow Control Configuration

Development Setup

Install Development Dependencies

Run Tests

Development Scripts

Production Setup

Security Considerations

Example Production Configuration

Docker Production Setup

Verification

Health Check

Statistics

WebSocket Connection

Troubleshooting

Common Issues

Logs

Next Steps