Sample

The Sample describes several demos of quickly spinning up different Prebid Server instances with various preset configurations. These samples are intended for audiences with little knowledge about Prebid Server and plan to play around with it locally and see how it works.

Installation

In the Sample, we use docker and docker-compose to instantiate examples; with docker providing a unified setup and interface, you can spin up a demo server instance locally with only one command without knowing all the complexities. The docker image used in docker-compose.yml is the Dockerfile residing in the root level of the repository.

Option 1 - Standard Docker Engine

Install docker and docker-compose via the official docker page. If you cannot use the official docker engine due to restrictions of its license, see the option below about using Podman instead of Docker.

Option 2 - Podman

From MacOS, you can use podman with these additional steps:

$ brew install podman docker-compose
$ podman machine init
$ podman machine set --rootful
$ podman machine start

Examples

Common File & Structures

All required files for each example are stored in a folder that follows the name pattern _. The <number> suggests its order and <name>` describes its title.

The following files will be present for every example and are exclusively catered to that example.

1. app.yaml - the prebid server app config.
2. pbjs.html - the HTML file with Prebid JS integration and communicates with the Prebid Server. It also provides a detailed explanation of the example.
3. *.json - additional files required to support the example. e.g. stored request and stored response.

Common steps

#1 - To get to the sample folder if you are on the root repository directory.
$ cd sample 

#2a - This command builds a new image, you should execute this command whenever the repository source code changes.
$ docker-compose build

#2b - Optionally you could run `docker-compose build --no-cache` if you want to build an completely new image without using cache but results in slower time to build it.
$ docker-compose build --no-cache

#3a - Spin up a corresponding sample in a container - see Steps for details 
$ docker-compose up <number>_<name>

#3b - Optionally you could use `--force-recreate` flag if you want to recreate the container every time you spin up the container.
$ docker-compose up <number>_<name> --force-recreate

Detailed Steps

1. To prevent app.yaml from being overwritten by other config files. Ensure that pbs.yaml or pbs.json config file MUST NOT be present in the root directory of the repository.

2. Bring up an instance by running docker-compose up <number>_<name> in the sample folder.

3. Wait patiently until you see Admin server starting on: :6060 and Main server starting on: :8000 in the command line output. This marks the Prebid Server instance finishing its initialization and is ready to serve the auction traffic.

4. you can copy the URL http://localhost:8000/status and paste it into your browser. You should see ok in the response which is another way to tell the Prebid Server that the main auction server is up and running.

5. Open a new tab in your browser and turn on the console UI. If you are using Chrome, you can right-click on the page and click inspect. Once the console UI is on, click on the Network tab to inspect the traffic later.

6. Copy the URL http://localhost:8000/static/pbjs.html?pbjs_debug=true into your browser. It starts the example immediately with debugging information from Prebid JS, and you can inspect the request and response between Prebid JS and Prebid Server.

7. After playing with the example, type docker-compose down. This is to shut down the existing Sample so you can start the next one you want to select.