diff --git a/README.md b/README.md index cb64ed9a3b1..3ede131e122 100644 --- a/README.md +++ b/README.md @@ -2,78 +2,106 @@ [![Go Report Card](https://goreportcard.com/badge/github.com/prebid/prebid-server?style=flat-square)](https://goreportcard.com/report/github.com/prebid/prebid-server) ![Go Version](https://img.shields.io/github/go-mod/go-version/prebid/prebid-server?style=flat-square) -# Prebid Server +
+
+

Prebid Server Logo

+
-Prebid Server is an open source implementation of Server-Side Header Bidding. -It is managed by [Prebid.org](https://prebid.org/about/), -and upholds the principles from the [Prebid Code of Conduct](https://prebid.org/code-of-conduct/). +Prebid Server is an open-source solution for running real-time advertising auctions in the cloud. This project is part of the Prebid ecosystem, seamlessly integrating with Prebid.js and the Prebid Mobile SDKs to deliver world-class header bidding for any ad format and for any type of digital media. -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](./adapters) package. If you don't see the one you want, feel free to [contribute it](https://docs.prebid.org/prebid-server/developers/add-new-bidder-go.html). +## Getting Started +- [What is Prebid Server](https://docs.prebid.org/prebid-server/overview/prebid-server-overview.html) +- [Intro to Header Bidding](https://docs.prebid.org/overview/intro-to-header-bidding.html) +- [Header Bidding with Prebid](https://docs.prebid.org/overview/intro.html#header-bidding-with-prebid) +- [API Endpoints](https://docs.prebid.org/prebid-server/endpoints/pbs-endpoint-overview.html) + +## Configuring -For more information, see: +When hosting Prebid Server or developing locally, **you must set a default GDPR value**. This configuration determines whether GDPR is enabled when no regulatory signal is available in the request, where a value of `"0"` disables it by default and a value of `"1"` enables it. This is required as there is no consensus on a good default. -- [What is Prebid?](https://docs.prebid.org/overview/intro.html) -- [Prebid Server Overview](https://docs.prebid.org/prebid-server/overview/prebid-server-overview.html) -- [Current Bidders](https://docs.prebid.org/dev-docs/pbs-bidders.html) +Refer to the [configuration guide](docs/developers/configuration.md) for additional information and a list of available configuration options. -Please consider [registering your Prebid Server](https://docs.prebid.org/prebid-server/hosting/pbs-hosting.html#optional-registration) to get on the mailing list for updates, etc. +## Hosting Prebid Server +> [!NOTE] +> Please consider [registering as a Prebid Server host](https://docs.prebid.org/prebid-server/hosting/pbs-hosting.html#optional-registration) to join the mailing list for updates and feedback. -## Installation +The quickest way to host Prebid Server is to deploy our [official Docker image](https://hub.docker.com/r/prebid/prebid-server). If you're hosting the container with Kubernetes, you can configure Prebid Server with environment variables [using a pod file](https://kubernetes.io/docs/tasks/inject-data-application/define-interdependent-environment-variables/) or [using a config map](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#configure-all-key-value-pairs-in-a-configmap-as-container-environment-variables). Alternatively, you can use a configuration file [embedded in a config map](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#populate-a-volume-with-data-stored-in-a-configmap) which Prebid Server will read from at the path `/etc/config`. -First install [Go](https://golang.org/doc/install) version 1.19 or newer. +For deploying a fork, you can create a custom Docker container using the command: +``` bash +docker build -t prebid-server . +``` +or compile a standalone binary using the command: +``` bash +go build . +``` +Ensure that you deploy the `/static` directory, as Prebid Server requires those files at startup. -Note that prebid-server is using [Go modules](https://blog.golang.org/using-go-modules). -We officially support the most recent two major versions of the Go runtime. However, if you'd like to use a version <1.13 and are inside GOPATH `GO111MODULE` needs to be set to `GO111MODULE=on`. +## Developing -Download and prepare Prebid Server: +Prebid Server requires [Go](https://go.dev) version 1.19 or newer. You can develop on any operating system that Go supports; however, please note that our helper scripts are written in bash. -```bash -cd YOUR_DIRECTORY -git clone https://github.com/prebid/prebid-server src/github.com/prebid/prebid-server -cd src/github.com/prebid/prebid-server +1. Clone The Repository +``` bash +git clone git@github.com:prebid/prebid-server.git +cd prebid-server ``` -Run the automated tests: +3. Download Dependencies +``` bash +go mod download +``` +3. Verify Tests Pass ```bash ./validate.sh ``` -Or just run the server locally: - +4. Run The Server ```bash -go build . -./prebid-server +go run . ``` -Run format: -``` -make format -``` -or -```bash -./scripts/format.sh -f true -``` +By default, Prebid Server will attach to port 8000. To confirm the server is running, visit `http://localhost:8000/` in your web browser. + +### Code Style +To maintain consistency in the project's code, please: + +- Follow the recommendations set by [Effective Go](https://go.dev/doc/effective_go). This article provides a comprehensive guide on how to write idiomatic Go code, covering topics such as naming and formatting. Many IDEs will automatically format your code upon save. If you need to manaully format your code, either run the bash script or execute the make step: + ``` + ./scripts/format.sh -f true + ``` + ``` + make format + ``` + +- Prefer small functions with descriptive names instead of complex functions with comments. This approach helps make the code more readable, maintainable, and testable. + +- Do not discard errors. You should implement appropriate error handling, such as gracefully falling back to a default behavior or bubbling up an error. + +### IDE Recommendation -Load the landing page in your browser at `http://localhost:8000/`. -For the full API reference, see [the endpoint documentation](https://docs.prebid.org/prebid-server/endpoints/pbs-endpoint-overview.html) +An option for developing Prebid Server in a reproducible environment isolated from your host OS is using Visual Studio Code with [Remote Container Setup](devcontainer.md). This is a recommendation, not a requirement. This approach is especially useful if you are developing on Windows, since the Remote Container runs within WSL providing you with the capability to execute bash scripts. -## Go Modules +## Importing Prebid Server -The packages within this repository are intended to be used as part of the Prebid Server compiled binary. If you -choose to import Prebid Server packages in other projects, please understand we make no promises on the stability -of exported types. +Prebid Server is not currently intended to be imported by other projects. Go Modules is used to manage dependencies, which also makes it possible to import Prebid Server packages. This is not supported. We offer no guarantees regarding the stability of packages and do not adhere to semantic versioning guidelines. ## Contributing +> [!IMPORTANT] +> All contributions must follow the [Prebid Code of Conduct](https://prebid.org/code-of-conduct/) and the [Prebid Module Rules](https://docs.prebid.org/dev-docs/module-rules.html). -Want to [add an adapter](https://docs.prebid.org/prebid-server/developers/add-new-bidder-go.html)? Found a bug? Great! +### Bid Adapter +Bid Adapters transform OpenRTB requests and responses for communicating with a bidding server. This may be as simple as a passthrough or as complex as mapping to a custom data model. We invite you to contribute an adapter for your company. Consult our guide on [building a bid adapter](https://docs.prebid.org/prebid-server/developers/add-new-bidder-go.html) for more information. -Report bugs, request features, and suggest improvements [on Github](https://github.com/prebid/prebid-server/issues). +### Analytics Module +Analytics Modules enable business intelligence tools to collect data from Prebid Server to provide publishers and hosts with valuable insights into their header bidding traffic. We welcome you to contribute a module for your platform. Refer to our guide on [building an analytics module](https://docs.prebid.org/prebid-server/developers/pbs-build-an-analytics-adapter.html) for further information. -Or better yet, [open a pull request](https://github.com/prebid/prebid-server/compare) with the changes you'd like to see. +### Auction Module +Auction Modules allow hosts to extend the behavior of Prebid Server at specfic spots in the auction pipeline using existing modules or by developing custom functionality. Auction Modules may provide creative validation, traffic optimization, and real time data services amoung many other potential uses. We welcome vendors and community members to contribute modules that publishers and hosts may find useful. Consult our guide on [building an auction module](https://docs.prebid.org/prebid-server/developers/add-a-module.html) for more information. -## IDE Recommendations +### Feature +We welcome everyone to contribute to this project by implementing a specification or by proposing a new feature. Please review the [prioritized project board](https://github.com/orgs/prebid/projects/4), where you can select an issue labeled "Ready For Dev". To avoid redundant effort, kindly leave a comment on the issue stating your intention to take it on. To propose a feature, [open a new issue](https://github.com/prebid/prebid-server/issues/new/choose) with as much detail as possible for consideration by the Prebid Server Committee. -The quickest way to start developing Prebid Server in a reproducible environment isolated from your host OS -is by using Visual Studio Code with [Remote Container Setup](devcontainer.md). +### Bug Fix +Bug reports may be submitted by [opening a new issue](https://github.com/prebid/prebid-server/issues/new/choose) and describing the error in detail with the steps to reproduce and example data. A member of the core development team will validate the bug and discuss next steps. You're encouraged to open an exploratory draft pull request to either demonstrate the bug by adding a test or offering a potential fix. diff --git a/docs/developers/configuration.md b/docs/developers/configuration.md index 9a22fd1ac7f..39789d49541 100644 --- a/docs/developers/configuration.md +++ b/docs/developers/configuration.md @@ -1,14 +1,160 @@ # Configuration -Configuration is handled by [Viper](https://github.com/spf13/viper), which supports [many ways](https://github.com/spf13/viper#why-viper) of setting config values. +Prebid Server is configured using environment variables, a `pbs.json` file, or a `pbs.yaml` file, in that order of precedence. Configuration files are read from either the application directory or `/etc/config`. -As a general rule, Prebid Server will log its resolved config values on startup and exit immediately if they're not valid. +Upon starting, Prebid Server logs the resolved configuration to standard out with passwords and secrets redacted. If there's an error with the configuration, the application will log the error and exit. -For development, it's easiest to define your config inside a `pbs.yaml` file in the project root. +# Sections +> [!IMPORTANT] +> As we are still developing this guide, please refer to the [configuration structures in code](../../config/config.go) for a complete definition of the options. -## Available options +- [General](#general) +- [Privacy](#privacy) + - [GDPR](#gdpr) -For now, see [the contract classes](../../config/config.go) in the code. -Also note that `Viper` will also read environment variables for config values. Prebid Server will look for the prefix `PBS_` on the environment variables, and map underscores (`_`) -to periods. For example, to set `host_cookie.ttl_days` via an environment variable, set `PBS_HOST_COOKIE_TTL_DAYS` to the desired value. +# General + +### `external_url` +String value that specifies the external url to reach your Prebid Server instance. It's used for event tracking and user sync callbacks, and is shared with bidders in outgoing requests at `req.ext.prebid.server.externalurl`. Defaults to empty. + +
+ Example +

+ + JSON: + ``` + { + "external_url": "https://your-pbs-server.com" + } + ``` + + YAML: + ``` + external_url: https://your-pbs-server.com + ``` + + Environment Variable: + ``` + PBS_EXTERNAL_URL: https://your-pbs-server.com + ``` + +

+
+ +### `host` +String value that specifies the address the server will listen to for connections. If the value is empty, Prebid Server will listen on all available addresses, which is a common configuration. This value is also used for the Prometheus endpoint, if enabled. Defaults to empty. + +
+ Example +

+ + JSON: + ``` + { + "host": "127.0.0.1" + } + ``` + + YAML: + ``` + host: 127.0.0.1 + ``` + + Environment Variable: + ``` + PBS_HOST: 127.0.0.1 + ``` + +

+
+ +### `port` +Integer value that specifies the port the server will listen to for connections. Defaults to `8000`. + +
+ Example +

+ + JSON: + ``` + { + "port": 8000 + } + ``` + + YAML: + ``` + port: 8000 + ``` + + Environment Variable: + ``` + PBS_PORT: 8000 + ``` + +

+
+ +# Privacy + +## GDPR + +### `gdpr.enabled` +Boolean value that determines if GDPR processing for TCF signals is enabled. Defaults to `true`. +
+ Example +

+ + JSON: + ``` + { + "gdpr": { + "enabled": true + } + } + ``` + + YAML: + ``` + gdpr: + enabled: true + ``` + + Environment Variable: + ``` + PBS_GDPR_ENABLED: true + ``` + +

+
+ + +### `gdpr.default_value` (required) +String value that determines whether GDPR is enabled when no regulatory signal is available in the request. A value of `"0"` disables it by default and a value of `"1"` enables it. This is a required configuration value with no default. +
+ Example +

+ + JSON: + ``` + { + "gdpr": { + "default_value": "0" + } + } + ``` + + YAML: + ``` + gdpr: + default_value: "0" + ``` + + Environment Variable: + ``` + PBS_GDPR_DEFAULT_VALUE: 0 + ``` + +

+
diff --git a/docs/developers/features.md b/docs/developers/features.md deleted file mode 100644 index b9bb9053ed5..00000000000 --- a/docs/developers/features.md +++ /dev/null @@ -1,12 +0,0 @@ -# Features - -Prebid Server documentation has been moved to the prebid.org website: - -- [Adding a new bidder](https://docs.prebid.org/prebid-server/developers/add-new-bidder-go.html) -- [Adding a new analytics module](https://docs.prebid.org/prebid-server/developers/pbs-build-an-analytics-adapter.html) -- [Currency](https://docs.prebid.org/prebid-server/features/pbs-currency.html) -- [Prebid Server and GDPR](https://docs.google.com/document/d/1g0zAYc_EfqyilKD8N2qQ47uz0hdahY-t8vfb-vxZL5w/edit#heading=h.8zebax5ncz0t) -- [Prebid and TCF2](https://docs.google.com/document/d/1fBRaodKifv1pYsWY3ia-9K96VHUjd8kKvxZlOsozm8E/edit#heading=h.hlpacpauqwkx) -- [Prebid Server User ID Sync](https://docs.prebid.org/prebid-server/developers/pbs-cookie-sync.html) -- [Cookie Sync](https://docs.prebid.org/prebid-server/developers/pbs-cookie-sync.html) -- [Default Request](https://docs.prebid.org/prebid-server/features/pbs-default-request.html) diff --git a/docs/endpoints.md b/docs/endpoints.md deleted file mode 100644 index 88116144a41..00000000000 --- a/docs/endpoints.md +++ /dev/null @@ -1 +0,0 @@ -Endpoint documentation has been moved to prebid.org: [https://docs.prebid.org/prebid-server/endpoints/pbs-endpoint-overview.html](https://docs.prebid.org/prebid-server/endpoints/pbs-endpoint-overview.html)