Skip to main content
Self-hosting Iris gives you complete control over your OSINT environment, ensuring maximum privacy and customization. This guide covers installation, deployment, and best practices.

​
Prerequisites

Before you begin, ensure you have the following installed:

Node.js

Version 18 or higher required

Package Manager

npm, yarn, or pnpm

Git

For cloning the repository

API Keys

Optional but recommended for full functionality

​
Quick Start Installation

1

Clone the Repository

Clone the Iris repository from GitHub:
git clone https://github.com/chinmay505/iris.git
cd iris
2

Install Dependencies

Install required packages using your preferred package manager:
npm install
Or with yarn:
yarn install
Or with pnpm:
pnpm install
3

Configure Environment Variables

Create a .env file in the root directory:
cp .env.example .env
Edit the .env file with your configuration:
# Logging (0 = off, 1 = basic, 2 = debug)
NEXT_PUBLIC_LOG_LEVEL=1
NODE_ENV=production

# ImgBB - for temporary image hosting during reverse search
IMGBB_API_KEY=your_imgbb_api_key
MAX_IMAGE_SIZE=32000
IMAGE_EXPIRY=600

# IPQualityScore - for email analysis
IPQS_API_KEY=your_ipqs_api_key

# Companies House - for UK company lookups
COMPANIESHOUSE_API_KEY=your_companies_house_api_key
See the API Keys Configuration guide for detailed instructions on obtaining these keys.
4

Run the Application

Development mode:
npm run dev
Production build:
npm run build
npm start
The application will be available at http://localhost:3000

​
Deployment Options

The easiest way to deploy Iris is using Vercel’s platform:
1

Connect Repository

  1. Create a Vercel account
  2. Import your Iris repository
  3. Vercel will automatically detect Next.js configuration
2

Configure Environment Variables

In your Vercel project settings:
  1. Navigate to Settings → Environment Variables
  2. Add each variable from your .env file
  3. Set variables for Production, Preview, and Development as needed
3

Deploy

Click Deploy and Vercel will build and deploy your application automatically.

​
Docker

Create a Dockerfile in your project root: 
FROM node:18-alpine AS base

# Install dependencies
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app

COPY package.json package-lock.json* ./
RUN npm ci

# Build application
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

RUN npm run build

# Production image
FROM base AS runner
WORKDIR /app

ENV NODE_ENV=production

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000

ENV PORT=3000

CMD ["node", "server.js"]
Build and run with Docker: 
# Build the image
docker build -t iris-osint .

# Run the container
docker run -p 3000:3000 \
  -e IMGBB_API_KEY=your_key \
  -e IPQS_API_KEY=your_key \
  -e COMPANIESHOUSE_API_KEY=your_key \
  iris-osint

​
Docker Compose

Create a docker-compose.yml file: 
version: '3.8'

services:
  iris:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - NEXT_PUBLIC_LOG_LEVEL=1
      - IMGBB_API_KEY=${IMGBB_API_KEY}
      - IPQS_API_KEY=${IPQS_API_KEY}
      - COMPANIESHOUSE_API_KEY=${COMPANIESHOUSE_API_KEY}
      - MAX_IMAGE_SIZE=32000
      - IMAGE_EXPIRY=600
    restart: unless-stopped
Run with: 
docker-compose up -d

​
Traditional VPS/Server

For deployment on a traditional server (Ubuntu/Debian):
1

Install Node.js

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
2

Clone and Install

git clone https://github.com/chinmay505/iris.git
cd iris
npm install
npm run build
3

Use Process Manager

Install PM2 for process management:
npm install -g pm2
pm2 start npm --name "iris" -- start
pm2 save
pm2 startup
4

Configure Reverse Proxy

Set up Nginx as a reverse proxy:
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

​
Tech Stack

Iris is built with modern web technologies:
TechnologyVersionPurpose
Next.js15+React framework with server-side rendering
React19+UI library
TypeScript5+Type-safe JavaScript
Tailwind CSS4+Utility-first CSS framework
Framer Motion12+Animation library
Radix UILatestAccessible component primitives

​
Configuration

​
Port Configuration

By default, Iris runs on port 3000. To change this: 
# Development
PORT=8080 npm run dev

# Production
PORT=8080 npm start

​
Logging Levels

Control application logging via NEXT_PUBLIC_LOG_LEVEL:
  • 0 - Disabled (recommended for production)
  • 1 - Basic logging (errors and important events)
  • 2 - Debug mode (verbose logging)

​
Image Upload Customization

If you modify MAX_IMAGE_SIZE beyond 32000 KB (32MB), ensure your ImgBB account supports larger files or implement your own image hosting solution.
MAX_IMAGE_SIZE=32000  # 32MB - free tier limit
IMAGE_EXPIRY=600      # 10 minutes - adjust as needed

​
Security Considerations

1

Environment Variables

  • Never commit .env files to version control
  • Use .env.local for local development
  • Set environment variables directly in production hosting
2

API Key Security

  • Rotate API keys periodically
  • Use different keys for development and production
  • Monitor API usage for anomalies
3

Server Hardening

  • Keep Node.js and dependencies updated
  • Use HTTPS with valid SSL certificates
  • Configure firewall rules appropriately
  • Regular security audits with npm audit

​
Maintenance

​
Updating Iris

To update your self-hosted instance: 
# Pull latest changes
git pull origin main

# Install new dependencies
npm install

# Rebuild application
npm run build

# Restart (PM2 example)
pm2 restart iris

​
Monitoring

Monitor your application health: 
# View PM2 logs
pm2 logs iris

# Monitor with PM2
pm2 monit

# Check application status
pm2 status

​
Troubleshooting

Increase Node.js memory limit:
NODE_OPTIONS="--max-old-space-size=4096" npm run build
Change the port or kill the process using it:
# Find process
lsof -i :3000

# Kill process
kill -9 <PID>

# Or use different port
PORT=3001 npm start
  1. Ensure .env file is in the project root
  2. Restart the application after changing .env
  3. Check that variable names match exactly
  4. For Next.js, prefix client-side variables with NEXT_PUBLIC_

​
Next Steps

API Keys Configuration

Set up your API keys for full functionality

Privacy & Security

Understand data handling and privacy features

Build docs developers (and LLMs) love

Get started for freeTalk to us