Bidder
The OpenRTB 2.0 compliant bidder for RTB4FREE, the open source bidder / DSP.
Install / Use
/learn @RTB4FREE/BidderREADME
Bidder - RTB4FREE Bidder
This is the bidder component to the RTB4Free open source DSP. The bidder is a JAVA 1.8 based openRTB bidding system, scalable to 25K+ QPS per node.
An image of this repo is available directly from Docker Hub
Getting Help
User documentation can be found on Read The Docs
Source Code
To start working with code, first make sure you have the following installed on your computer:
Next, get the code from this Github repo:
git clone git@github.com:RTB4FREE/bidder.git
cd bidder
Make a sample database, and use default settings:
cp database-sample.json database.json
cp Campaigns/payday-default.json payday.json
Install using Maven:
mvn assembly:assembly -DdescriptorId=jar-with-dependencies -Dmaven.test.skip=true
Run the tests:
mvn test
Start the bidder:
./tools/rtb4free
Note: Remember to submit changes back to this project via a pull request!
Docker Image
RTB4Free bidder can be deployed using Docker.
Build the Docker image:
docker build -t rtb4free/bidder:latest -t rtb4free/bidder:1 -t rtb4free/bidder:1.0 .
To push to the image to the RTB4Free repo in Docker:
docker push rtb4free/bidder:1.0
docker push rtb4free/bidder:1
docker push rtb4free/bidder:latest
Note: Dockerhub automatically builds this container when code gets pushed to this Github repo
Docker Deployment
The bidder can be deployed using Docker Compose. The default docker-compose.yml is included in the root directory, and it can be modified to suit your needs. To deploy the bidder using Docker Compose, run this from the root directory of this repo:
docker-compose up -d
This will run a Docker container, initialize the database and expose the service on port 8080.
To stop the container, run the command:
docker-compose down
Using Bidder
To configure the bidder locally, open a browser to the host:
Username: demo@rtb4free.com
Password: rtb4free
For information about the campaign manager functionality:
Getting Support
There are various ways of getting support:
- Email us at support@rtb4free.com
- Add a Github issue: github.com/rtb4free/bidder/issues
- Join the RTB4Free Slack Channel
Deployment Using Docker Swarm
Use Docker Swarm to run Crosstalk, Bidder, Zerospike, Kafka and Zookeeper
Step 1: Copy docker-compose.yml from Project's docker/ directory
cp docker/docker-compose.yml .
Step 2: Start the swarm
$docker swarm init
Step 3: Start the network
$docker network create --driver overlay rtb_net --subnet=10.0.9.0/24
Step 4: Deploy
$docker stack deploy -c docker-compose.yml bidder
Changing Operational Parameters
The bidder uses a container based file in Campaigns/payday.json. If you need to change the parameters within it, do it in your own copy and use volumes command to mount into it.
For example, suppose you made your own copy of payday.json, modified it and called it
./myconfig.json. In this case, modify the bidder services section in docker-compose.yml to
mount. Note the volumes directive:
bidder:
image: "jacamars/rtb4free:v1"
environment:
BROKERLIST: "kafka:9092"
PUBSUB: "zerospike"
EXTERNAL: "http://localhost:8080"
ports:
- "8080:8080"
- "8100:8100"
- "7379:7379"
volumes:
- ./myconfig.json:Campaigns/payday.json
networks:
- rtb_net
depends_on:
- kafka
- crosstalk
- zerospike
command: bash -c "./wait-for-it.sh kafka:9092 -t 120 && ./wait-for-it.sh zerospike:6000 -t 120 && sleep 1; ./rtb4free"
Zerospike uses a cache.db file located within the container. For operational use, the real cache.db must be mounted using the volumes command. For example, suppose you wanted to use the file mycache.db in your current working directory. The docker-compose.yml file would be modified as follows:
zerospike:
image: "jacamars/zerospike"
environment:
BROKERLIST: "kafka:9092"
ports:
- "6000:6000"
- "6001:6001"
- "6002:6002"
volumes:
- "./mycache.db:/cache.db"
networks:
- rtb_net
depends_on:
- kafka
command: bash -c "./wait-for-it.sh kafka:9092 -t 120 && sleep 1; ./zerospike"
Changing port assignments is not encouraged. Stick to the defaults to keep from losing your mind. There are a lot of interdependencies.
Connect Intellij Debugger to Bidder, Crosstalk or Zerospike
Bidder: In the service for the bidder in docker-compose.yml, use ./rtb4free-jmx instead of ./rtbf4free Then in your Intellij system, create a remote debug and connect using port 9000.
Zerospike In the service for the zerospike in docker-compose.yml, use ./zerospike-jmx instead of ./zerospike Then in your Intellij system, create a remote debug and connect using port 9000.
Crosstalk: In the service for the crosstalk in docker-compose.yml, use ./crosstalk-jmx instead of ./crosstalk Then in your Intellij system, create a remote debug and connect using port 9000.
CONFIGURING THE BIDDER
In order to run the bidder, you will need to load a campaign into the bidders memory and setup some operational parameters. These parameters are stored in a JSON file the bidder uses when it starts. There is a sample initialization file called "./Campaigns/payday.json' you can use to get started. The file describes the operational parameters of the bidder. Look in http://rtb4free.com/details_new.html for an in depth analysis of the configuration file. Also, once you get the bidder running, you can use the System Consolse to change the parameters using the web interface, described here: http://rtb4free.com/admin-mgmt.html
However, here is an example file, and a brief overview
{
"app" : {
"concurrency" : "1",
"deadmanswitch":"accountingsystem",
"threads": "128",
"stopped" : false,
"ttl" : 300,
"pixel-tracking-url" : "$EXTERNAL/pixel",
"clickurl" : "$EXTERNAL/click",
"winurl" : "$EXTERNAL/rtb/win",
"redirect-url" : "$EXTERNAL/redirect",
"vasturl" : "$EXTERNAL/vast",
"eventurl" : "$EXTERNAL/track",
"postbackurl" : "$EXTERNAL/postback",
"adminPort" : "0",
"adminSSL" : false,
"password" : "startrekisbetterthanstarwars",
"verbosity" : {
"level" : -3,
"nobid-reason" : false
},
"geotags" : {
"states" : "",
"zipcodes" : ""
},
"zeromq" : {
"bidchannel" : "kafka://[$BROKERLIST]&topic=bids",
"winchannel" : "kafka://[$BROKERLIST]&topic=wins",
"requests" : "kafka://[$BROKERLIST]&topic=requests",
"clicks" : "kafka://[$BROKERLIST]&topic=clicks",
"pixels" : "kafka://[$BROKERLIST]&topic=pixels",
"videoevents": "kafka://[$BROKERLIST]&topic=videoevents",
"postbackevents": "kafka://[$BROKERLIST]&topic=postbackevents",
"status" : "kafka://[$BROKERLIST]&topic=status",
"reasons" : "kafka://[$BROKERLIST]&topic=reasons",
"commands": "tcp://$PUBSUB:6001&commands",
"responses": "tcp://$PUBSUB:6000&responses",
"xfrport": "6002",
"requeststrategy" : "100"
},
"template" : {
"default" : "{creative_forward_url}",
"exchange" : {
"adx" : "<a href='$BID:8080/rtb/win/{pub_id}/%%WINNING_PRICE%%/{lat}/{lon}/{ad_id}/{creative_id}/{bid_id}'}'></a><a href='%%CLICK_URL_UNESC%%{redirect_url}></a>{creative_forward_url}",
"mopub" : "<a href='mopub template here' </a>",
"mobclix" : "<a href='mobclix template here' </a>",
"nexage" : "<a href='{redirect_url}/exchange={pub}/ad_id={ad_id}/creative_id={creative_id}/price=${AUCTION_PRICE}/lat={lat}/lon={lon}/bid_id={bid_id}?url={creative_forward_url}'><img src='{creative_image_url}' height='{creative_ad_height}' width='{creative_ad_width}'></a><img src='{pixel_url}/exchange={pub}/ad_id={ad_id}/creative_id={creative_id}/{bid_id}/price=${AUCTION_PRICE}/lat={lat}/lon={lon}/bid_id={bid_id}' height='1' width='1'>",
"smartyads" : "{creative_forward_url}",
"atomx" : "{creative_forward_url}",
"adventurefeeds" : "{creative_forward_url}",
"gotham" : "{creative_forward_url}",
"epomx" : "{creative_forward_url}",
"citenko" : "{creative_forward_url}",
"kadam" : "{creative_forward_url}",
"taggify" : "{creative_forward_url}",
"cappture" : "cappture/{creative_forward_url}",
"republer" : "{creative_forward_url}",
"admedia" : "{creative_f
