Home / Docs / Installation

Installation Guide

Deploy FeedbackLoop AI on your own infrastructure. Choose between the automated installer, Docker Compose, or manual setup.

Hardware Requirements

Resource Minimum Recommended
CPU 2 vCPU 4 vCPU
RAM 4 GB 8 GB
Disk 20 GB SSD 50 GB SSD
OS Ubuntu 22.04+ or Debian 12+ (amd64)

The render worker (Puppeteer + FFmpeg) is the most resource-intensive component. If you do not need MP4 session renders, you can run comfortably on 2 vCPU / 2 GB RAM.

Tip

For production use with multiple tenants and heavy AI workloads, aim for 4+ vCPU and 8 GB RAM. MinIO storage grows with session count — plan disk accordingly.

Automated Install

The automated installer is the recommended approach for single-server deployments. It handles all dependencies and configuration in one command.

  1. Clone the repository
    bash 
    git clone https://github.com/QuentinAdt/FeedbackLoopAIOSS.git
cd FeedbackLoopAIOSS
  2. Run the install script
    bash 
    sudo bash install.sh

    The script will prompt you for your domain name and then install and configure:

    • Node.js 20 LTS via NodeSource
    • PostgreSQL 16 with a dedicated database and user
    • Docker & Docker Compose for containerized services
    • Redis (Docker container, port 6379)
    • MinIO (Docker container, API port 9000, console port 9001)
    • Caddy reverse proxy with automatic HTTPS
    • PM2 process manager for the API and worker
    • npm dependencies for all components
    • Prisma database migrations
  3. Verify the installation
    bash 
    # Check all services are running
pm2 status

# Check API health
curl http://localhost:3500/health

# Check Docker containers
docker compose ps
Warning

The install script must be run as root (or with sudo). It modifies system packages and creates systemd services. Review the script contents before running on a production server.

Docker Deployment

For fully containerized deployments, use Docker Compose to run all services including the API, worker, PostgreSQL, Redis, and MinIO:

bash 
git clone https://github.com/QuentinAdt/FeedbackLoopAIOSS.git
cd FeedbackLoopAIOSS

# Copy and edit the environment file
cp api/.env.example api/.env
nano api/.env

# Start all services
docker compose up -d

The Docker Compose file defines all required services with appropriate networking, volumes, and health checks. Edit api/.env before starting to configure your JWT secret, database URL, and OpenRouter API key.

Note

The Docker deployment uses a single docker-compose.yml file. Redis and MinIO are always containerized; the API and worker can optionally run on bare metal with PM2 if you prefer more control.

Manual Install

If you prefer to install components individually or are running on a non-Debian system:

1. Install dependencies

2. Set up the API

bash 
cd api
cp .env.example .env
# Edit .env with your database URL, JWT secret, etc.
nano .env

npm install
npx prisma generate
npx prisma db push
npm run seed   # Optional: seed initial data

3. Set up the Worker

bash 
cd worker
npm install
# Worker reads config from api/.env via symlink

4. Start services

bash 
# Start Redis and MinIO
docker compose up -d

# Start API and Worker with PM2
pm2 start api/ecosystem.config.cjs
pm2 start worker/ecosystem.config.cjs
pm2 save

Post-Install: Setup Wizard

After the install completes, navigate to https://your-domain.com/setup to run the setup wizard. The wizard guides you through the following steps:

  1. Verify setup token

    Enter the one-time setup token displayed in the install script output. This prevents unauthorized access to the wizard.

  2. Create admin account

    Set your admin email and password. This account has full access to all tenants and settings.

  3. Configure API keys

    Enter your OpenRouter API key to enable AI qualification and deep analysis. You can also configure SendGrid for email notifications.

  4. Set public domain

    Confirm the public URL where FeedbackLoop AI is accessible (e.g., https://feedback.yoursite.com).

  5. Create your first tenant

    A tenant represents one tracked website or application. The wizard generates an API key and secret for the embed snippet.

  6. Embed the widget

    Copy the generated <script> tag and add it to your site. Session replay and the feedback widget activate immediately.

Troubleshooting

Port conflicts

If the API fails to start, check whether another process is using the configured port:

bash 
lsof -ti:3500
# Kill if needed:
kill -9 $(lsof -ti:3500)
Warning

PM2 ecosystem config env vars override .env file values. If your API starts on the wrong port, check ecosystem.config.cjs for a PORT override.

Prisma migration errors

If Prisma reports migration conflicts, resolve them manually rather than resetting:

bash 
# Safe: apply additive schema changes
npx prisma db push

# Generate the client after schema changes
npx prisma generate
Danger

Never run prisma db push --force-reset on a production database. This drops all tables and destroys all data. Use prisma db push (without the flag) for additive changes, or prisma migrate dev for controlled migrations.

Bun runtime issues

On some systems, ~/.bun/bin/node is a Bun shim that replaces the system Node.js. FeedbackLoop AI's OSS edition uses this shim. If you see errors related to bun:sqlite, this is expected behavior — do not replace it with better-sqlite3.

Docker containers not starting

bash 
# Check container logs
docker compose logs redis
docker compose logs minio

# Restart containers
docker compose restart

ESM + PM2 issues

FeedbackLoop AI uses "type": "module" in package.json. PM2 ecosystem config files must use the .cjs extension to work correctly with ES modules. If PM2 fails to start the app, verify the ecosystem config file has a .cjs extension.