search

valeriansaliou / raider

🐎 Affiliates dashboard. Used by affiliates to generate tracking codes and review their balance.
https://crates.io/crates/raider-server
Mozilla Public License 2.0
146 stars 31 forks source link
affiliates dashboard sales tracker web

readme

Raider

Test and Build Build and Release dependency status Buy Me A Coffee

Affiliates dashboard. Used by affiliates to generate tracking codes and review their balance.

Raider is easy to integrate in your existing system. You can also customize the dashboard look & feel with templates and styles. It can be used as a self-service affiliates system, for your affiliate users to manage their account, create tracking URLs, review their balance and request for payouts.

Tested at Rust version: rustc 1.51.0-nightly (c8915eebe 2021-01-07)

🇭🇺 Crafted in Budapest, Hungary.

Raider

Who uses it?

Crisp

👋 You use Raider and you want to be listed there? Contact me.

Features

How does it work?

Raider provides a self-service affiliates dashboard on which users can sign up, login, and manage their account (eg. create tracking codes, request for payouts, etc.). Your backend can report referred customer payments to Raider, so that the affiliates can cash out their commission and request for a payout at any point.

Raider provides two services:

How to use it?

Installation

Install from releases:

The best way to install Raider is to pull the latest release from the Raider releases page.

Make sure to pick the correct server architecture (eg. Intel 32 bits).

👉 Each release binary comes with an .asc signature file, which can be verified using @valeriansaliou GPG public key: :key:valeriansaliou.gpg.pub.asc.

Install from packages:

Raider provides pre-built packages for Debian-based systems (Debian, Ubuntu, etc.).

Important: Raider only provides 64 bits packages targeting Debian 12 for now (codename: bookworm). You might still be able to use them on other Debian versions, as well as Ubuntu (although they rely on a specific glibc version that might not be available on older or newer systems).

First, add the Raider APT repository (eg. for Debian bookworm):

echo "deb [signed-by=/usr/share/keyrings/valeriansaliou_raider.gpg] https://packagecloud.io/valeriansaliou/raider/debian/ bookworm main" > /etc/apt/sources.list.d/valeriansaliou_raider.list
curl -fsSL https://packagecloud.io/valeriansaliou/raider/gpgkey | gpg --dearmor -o /usr/share/keyrings/valeriansaliou_raider.gpg
apt-get update

Then, install the Raider package:

apt-get install raider

Then, edit the pre-filled Raider configuration file:

nano /etc/raider/raider.cfg

Finally, restart Raider:

service raider restart

Install from Cargo:

If you prefer managing raider via Rust's Cargo, install it directly via cargo install:

cargo install raider-server

Ensure that your $PATH is properly configured to source the Crates binaries, and then run Raider using the raider command.

Install from source:

The last option is to pull the source code from Git and compile Raider via cargo:

cargo build --release

You can find the built binaries in the ./target/release directory.

Install the libssl-dev (ie. OpenSSL headers) and libmysqlclient-dev (ie. MySQL client headers) before you compile Raider. SSL dependencies are required for email notifications, and MySQL dependencies are required to connect to your database.

Install from Docker Hub:

You might find it convenient to run Raider via Docker. You can find the pre-built Raider image on Docker Hub as valeriansaliou/raider.

First, pull the valeriansaliou/raider image:

docker pull valeriansaliou/raider:v1.2.3

Then, seed it a configuration file and run it (replace /path/to/your/raider/config.cfg with the path to your configuration file):

docker run -p 8080:8080 -v /path/to/your/raider/config.cfg:/etc/raider.cfg valeriansaliou/raider:v1.2.3

In the configuration file, ensure that:

Raider will be reachable from http://localhost:8080.

Database

Raider requires a MySQL to be running on your host (it is unfortunately not compatible with PostgreSQL and others, at the moment).

The Raider SQL schema should be imported in the Raider database you created, which you can find at raider.sql.

Configuration

Use the sample config.cfg configuration file and adjust it to your own environment.

⚠️ Important: Make sure to change the default server.secret_key, server.track_token and server.management_token configuration values with secret keys you generated. Also, generate a random arbitrary length string for database.password_salt. Failing to change any of those values will make your Raider instance insecure. You can easily create these tokens by running openssl rand -base64 32.

Available configuration options are commented below, with allowed values:

[server]

[database]

[exchange]

[exchange.fixer]

[email]

[assets]

[branding]

[tracker]

[[tracker.banner]]

[payout]

Run Raider

Raider can be run as such:

./raider -c /path/to/config.cfg

How can I integrate Raider reporting in my code?

When a payment for which you have a tracking_id is made on your platform (ie. a payment for a customer that was referred by an affiliate); your backend needs to submit this payment to the Raider tracking API. The full payment amount needs to be submitted, as the commission percentage is applied by Raider itself.

Raider reporting libraries

👉 Cannot find the library for your programming language? Build your own and be referenced here! (contact me)

How can I use Raider HTTP APIs?

1️⃣ Track API

Payment tracking

In case you need to manually report tracked payments to the Raider endpoint, use the following HTTP configuration (adjust it to yours):

Endpoint URL:

HTTP POST https://affiliates.example.com/track/payment/<tracking_id>/

Where:

Request headers:

Request data:

Adjust the request data to your payment context and send it as HTTP POST:

{
  "amount": 95.00,
  "currency": "EUR",
  "trace": "Plan: Unlimited; Customer: valerian@crisp.chat; Website: crisp.chat"
}

Where:

Signup tracking

In case you need to manually report tracked signups to the Raider endpoint, use the following HTTP configuration (adjust it to yours):

Endpoint URL:

HTTP POST https://affiliates.example.com/track/signup/<tracking_id>/

Where:

Request headers:

2️⃣ Management API

Account creation

In case you need to create accounts in Raider database from a third-party system in your infrastructure (eg. if regular signups are disabled), you may us create new accounts via the Raider endpoint, use the following HTTP configuration (adjust it to yours):

Endpoint URL:

HTTP POST https://affiliates.example.com/management/account/

Request headers:

Request data:

Adjust the request data to your payment context and send it as HTTP POST:

{
  "email": "john.doe@gmail.com",
  "full_name": "John Doe",
  "address": "1 Market Street, San Francisco, CA",
  "country": "US"
}

Where:

:fire: Report A Vulnerability

If you find a vulnerability in Raider, you are more than welcome to report it directly to @valeriansaliou by sending an encrypted email to valerian@valeriansaliou.name. Do not report vulnerabilities in public GitHub issues, as they may be exploited by malicious people to target production servers running an unpatched Raider server.

:warning: You must encrypt your email using @valeriansaliou GPG public key: :key:valeriansaliou.gpg.pub.asc.