refref

RefRef is an open source referral management platform that ships with a web portal and a robust set of tools for tracking referrals, managing rewards, and analyzing engagement. This MCP-enabled server setup focuses on deploying RefRef via Docker Compose, which automatically provisions the PostgreSQL database, runs migrations, seeds initial data, and exposes the webapp portal. You can use the docker-compose flow to spin up the full stack quickly, then access the web interface at the provided URL (the README indicates the webapp is accessible after startup). The key capabilities you can expect to leverage include referral attribution tracking via the JS snippet, customizable rewards, referrer and partner portals, personalized landing pages, fraud monitoring, and both manual and automatic reward handling with dispersal and timing controls. For development or local testing, you can run the stack in a Docker environment or follow the local development path if you choose to run components individually, keeping in mind you’ll need a PostgreSQL instance and proper environment variables for authentication and database access.

Prerequisites:

• Docker and Docker Compose installed on your system
• Optional: Node.js and pnpm if you plan to work with web assets locally

Installation steps:

1. Clone the repository git clone https://github.com/refrefhq/refref.git cd refref

2. Start the stack with Docker Compose (recommended for quick setup) docker-compose up -d

   This will:

   • Spin up PostgreSQL
   • Run migrations
   • Seed initial data
   • Serve the webapp portal

3. If you prefer local development without Docker:

   • Ensure Node.js 20+ is installed
   • Install dependencies and run the app using the project’s dev script as described in the README (pnpm is used in this project)

4. Configure environment variables Create and populate environment files as needed (per the README):

   • DATABASE_URL: PostgreSQL connection string
   • BETTER_AUTH_SECRET: Authentication secret key
   • Optional OAuth or email provider keys (e.g., GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, RESEND_API_KEY)

5. Access the webapp After startup, open http://localhost:3000 in your browser (or the port configured by your environment).

Tips and common issues:

• Docker Compose will handle database setup, migrations, and seeding automatically; if you encounter schema issues, rerun migrations using the project’s database commands.
• Ensure DATABASE_URL is reachable from the docker containers; networking between the container and the database host must be configured (use a Docker network or a separate PostgreSQL container in the same compose file).
• Generate BETTER_AUTH_SECRET securely (openssl rand -base64 32) and keep it confidential.
• For Google OAuth, provide GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET if you plan to enable Google login.
• If you modify environment variables, restart the Docker Compose stack to apply changes.
• The project relies on a TypeScript/Next.js stack; for local debugging, you may start the webapp in development mode as documented in the Getting Started section of the README.
• If you run into port conflicts, adjust ports in the docker-compose configuration or set environment-specific override files.
• Review the Licensing and contribution guidelines in the repo's LICENSE and CONTRIBUTING.md for collaboration.