README.md

This is the Java version of Prebid Server. See the Prebid Server Feature List and FAQ entry to understand the differences between PBS-Java and PBS-Go.

Prebid Server (Java)

Prebid Server is an open source implementation of Server-Side Header Bidding. It is managed by Prebid.org, and upholds the principles from the Prebid Code of Conduct.

This project does not support the same set of Bidders as Prebid.js, although there is overlap. The current set can be found in the adapters package. If you don't see the one you want, feel free to contribute it.

For more information, see:

• What is Prebid?
• Getting started with Prebid Server
• Current Bidders

Please consider registering your Prebid Server to get on the mailing list for updates, etc.

Getting Started

The server makes the following assumptions:

• No ranking or decisioning is performed by this server. It just proxies requests.
• No ad quality management (e.g., malware, viruses, deceptive creatives) is performed by this server.
• This server does no fraud scanning and does nothing to prevent bad traffic.
• This server logs errors but not requests.
• This server has no user profiling or user data collection capabilities.

This project is built upon Vert.x to achieve high request throughput. We use Maven and attempt to introduce minimal dependencies.

When running, the server responds to several HTTP endpoints.

Building

Follow next steps to create JAR file which can be deployed locally.

• Install prerequsites

  • Java SDK: Oracle's or Corretto. Let us know if there's a distribution PBS-Java doesn't work with.
  • Maven

• Clone the project:

git clone https://github.com/prebid/prebid-server-java.git

• Move to project directory:

cd prebid-server-java

And from this step there are two common use cases, which can be chosen depending on your goals

1. Create prebid-server JAR only

• First, make sure nothing's running on your local port 8080 or 8090
• Run below command to build project:

mvn clean package

2. Create prebid-server JAR with modules

• Run below command to build project:

mvn clean package --file extra/pom.xml

For more information how to build the server follow documentation.

Configuration

The source code includes an example configuration file sample/configs/prebid-config.yaml. Also, check the account settings file sample/configs/sample-app-settings.yaml.

For more information how to configure the server follow documentation. There are many settings you'll want to consider such as which bidders you're going to enable, privacy defaults, admin endpoints, etc.

Running

Run your local server with the command:

java -jar target/prebid-server.jar --spring.config.additional-location=sample/configs/prebid-config.yaml

For more options how to start the server, please follow documentation.

Running prebuilt .jar

Starting from PBS Java v2.9, you can download prebuilt .jar packages from Release Notes page, instead of building them by yourself. This prebuilt packages are delivered with or without extra modules.

Verifying

To check the server is started go to http://localhost:8080/status and verify response status is 200 OK.

There are a couple of 'hello world' test requests described in sample/requests/README.txt

Running Docker image

Starting from PBS Java v3.11.0, you can download prebuilt Docker images from GitHub Packages page, and use them instead of plain .jar files. These prebuilt images are delivered in 2 flavors:

• https://github.com/prebid/prebid-server-java/pkgs/container/prebid-server-java is a bare PBS and doesn't contain modules.
• https://github.com/prebid/prebid-server-java/pkgs/container/prebid-server-java-bundle is a "bundle" that contains PBS and all the modules.

To run PBS from image correctly, you should provide the PBS config file. The easiest way is to mount the config file into the container, using --mount or --volume (-v) Docker CLI arguments. Keep in mind that the config file should be mounted into a specific location: /app/prebid-server/conf/ or /app/prebid-server/.

PBS follows the regular Spring Boot config load hierarchy and type. For simple configuration, a single application.yaml mounted to /app/prebid-server/conf/ will be enough. Please consult Spring Externalized Configuration for all possible ways to configure PBS.

You can also supply command-line parameters through JAVA_OPTS environment variable which will be appended to the java command before the -jar ... parameter. Please pay attention to line breaks and escape them if needed.

Example execution using sample configuration:

docker run --rm -v ./sample:/app/prebid-server/sample:ro -p 8060:8060 -p 8080:8080 ghcr.io/prebid/prebid-server-java:latest --spring.config.additional-location=sample/configs/prebid-config.yaml

or

docker run --rm -v ./sample:/app/prebid-server/sample:ro -p 8060:8060 -p 8080:8080 -e JAVA_OPTS=-Dspring.config.additional-location=sample/configs/prebid-config.yaml ghcr.io/prebid/prebid-server-java:latest

Documentation

Development

• Endpoints
• Adding new bidder
• Adding new analytics module
• Adding viewability support
• Auction result post-processing
• Cookie Syncs
• Stored Requests
• Unit Tests
• Functional Tests
• GDPR

Maintenance

• Build for local
• Build for AWS
• Configure application
  • Full list of configuration options
  • Application settings
• Run with optimizations
• Metrics

Contributing

• Contributing
• Code Style
• Code Review
• Versioning