Getting Started
RefearnApp is a lightweight, self-hosted affiliate tracking infrastructure. Ensure you have the following assets ready before proceeding.
Cloudflare
DNS & Worker management.
Domain
Dedicated root or subdomain.
VPS Server
Host your dashboard (Hetzner, GCE).
Upstash
Serverless Redis & QStash.
Zoho, Resend, or SMTP.
Cloudflare Configuration
Connecting your Domain
RefearnApp utilizes Cloudflare Workers. Your domain must be managed by Cloudflare to route traffic correctly.
Ensure your domain status is 'Active' in the Cloudflare dashboard.
- New Domains: Purchase via Cloudflare Registrar for instant setup.
- External Domains: If using Namecheap or others, update your Name Servers to the records provided in your Cloudflare DNS tab.
Preparing your VPS Bridge
1. Create your Origin DNS Record
Cloudflare SideBefore deploying, you need a "Direct Path" to your VPS. Point a subdomain to your VPS IP in Cloudflare. You can use any name you like.
Add an 'A' record pointing your subdomain to your VPS IPv4 address.
How will this be used?
The name you chose above creates your Origin URL. This URL will be your:NEXT_PUBLIC_REDIRECTION_URL
Future Env Var
NEXT_PUBLIC_REDIRECTION_URLExample Format
https://[your-name].domain.comSelf-Hosting with Coolify
1. Install Coolify on VPS
SSH into your VPS server and run the official command. Once finished, access the UI via your IP on port 8000.
2. Connect Forked Repository
Action Required: Fork the Repository
Fork this repository to maintain your own config:
https://github.com/ZAK123DSFDF/refearnapphttps://github.com/YOUR_USERNAME/refearnapp3. Configure Environment & Domain
Input All Variables
Add all keys from the Reference Section below.
Paste your environment variables into the 'Environment Variables' tab.
Link Redirection URL
Coolify Path: Configuration > General > Domains
1. Cloudflare Name
https://[ANY-NAME].yourdomain.com2. Paste into "Domains"
NEXT_PUBLIC_REDIRECTION_URL
Ensure the domain matches your NEXT_PUBLIC_REDIRECTION_URL exactly.
Set Dockerfile and Root Directory to /.
Select Dockerfile as the build pack in the 'General' settings.
4. Launch
Deploying the Tracking Worker
Prerequisite: Install Wrangler
Ensure Cloudflare's CLI tool is available globally on your VPS before starting.
1. Prepare SSH Tunnel (Your Local PC)
Run this in your Local Terminal to bridge your VPS to your browser for authentication:
2. Authenticate Cloudflare
Navigate to the worker directory to authenticate within the pnpm isolation:
cd apps/tracking-worker
npx wrangler login
cd ../..
3. Launch Tracker Setup
Follow the on-screen terminal instructions. Use the table below to map your variables correctly.
Script Prompt Reference
← Swipe table to see full variables →
5. Final Step: Connect Custom Domain
Link your domain in the Cloudflare Dashboard to make the worker public.
1. Go to Workers & Pages > Select your tracker worker.
2. Go to Settings > Domains & Routes > Add Custom Domain.
Add these two values:
- yourdomain.com (Bare Domain)
- www.yourdomain.com (WWW Catch-all)
Configure your Custom Domains within the Worker settings to enable public tracking.
Mistake during setup? Your configuration is saved in /apps/tracking-worker/.env.selfhost. To re-enter your details, run: pnpm launch:tracker --reset
Note: Cloudflare SSL issuance may take up to 10 minutes.
Database & Currency Setup
1. Initialize Database & Rates
Run the automated setup script from the project root. This will configure your .env, migrate your database, and fetch live exchange rates.
Script Prompt Reference
Apply Changes to Dashboard
The script has updated your .env file. To apply these settings, you must trigger a re-deployment.
Note: If the seeding fails, check that your CURRENCY_API_KEY is valid and has not reached its monthly limit.
Configure Email Delivery
RefearnApp requires an email provider to send alerts and system notifications. Choose one of the supported methods below and configure it in your environment variables.
Resend
Modern API-based sending. Easiest to setup.
ZeptoMail
Transactional email by Zoho. Great for high volume.
Custom SMTP
Use your own server (Zoho, Google, Amazon SES).
Implementation Steps
Choose your Provider
Sign up for an account on your preferred platform and get your API Key or SMTP credentials.
Set the Provider Key
In Coolify, set the EMAIL_PROVIDER variable to match your choice:
"resend""smtp""zeptomail"Fill Corresponding Credentials
Scroll down to the Env Variables section and fill only the keys related to your chosen provider (e.g., SMTP host vs Resend Key).
Finalizing Portal Routing
Initialize Your Organization
With your dashboard live, execute your first login. You’ll be prompted to define your Organization Workspace. This acts as the central hub for all affiliate tracking and payout logic.
Synchronize Domain Routing
To ensure the affiliate portal is reachable, you must bridge the active domain from your Refearn Dashboard back to your Coolify configuration.
Manage Domains → Copy
app.yourdomain.com
Copy the active domain prefix from your settings.
Configuration → General → Domains
Inform your VPS which URL to listen for.
Global DNS Propagation
Map your domain to your infrastructure by creating an A Record within Cloudflare. Ensure the "Name" field matches your chosen subdomain exactly.
The Record Name must be the prefix (e.g., 'app') of your full URL.
Deployment Successful!
Your affiliate infrastructure is now operational. Once DNS propagation completes, your portal will be accessible globally.
Environment Variables
Full configuration reference for your RefearnApp instance.