Configure the solution - Prebid Server Deployment on AWS
Opting out of using CloudFront and AWS WAFManaging configuration files for the solution

Configure the solution

This section provides instructions for configuring the Prebid Servcer Deployment on AWS solution.

Opting out of using CloudFront and AWS WAF

By default, this solution deploys CloudFront and AWS WAF.

Benefits of using CloudFront and AWS WAF

CloudFront helps reduce latency by delivering data through globally dispersed Points of Presence (PoPs) with automated network mapping and intelligent routing. It cuts costs with consolidated requests, customizable pricing options, and zero fees for data transfer out from AWS origins. CloudFront can cache objects and serve them directly to users (viewers), reducing the load on your Application Load Balancer.

The Application Load Balancer is configured to forward requests that contain a custom secret header value to enhance security. CloudFront automatically adds this custom HTTP header to the requests. This secret value is unique and is generated when you deploy the stack. For added protection, the Application Load Balancer security group is configured with the CloudFront managed prefix list. This contains the IP address ranges of all CloudFront globally distributed origin-facing servers. The CloudFront managed prefix list allows inbound traffic to your origin only from CloudFront origin-facing servers, preventing any non CloudFront traffic from reaching your origin.

AWS WAF provides additional security by preventing distributed denial of service (DDoS) and helps more easily monitor, block, or rate-limit common and pervasive bots. It improves web traffic visibility with granular control over how metrics are emitted.

How to opt out

For users who decide not to use CloudFront and AWS WAF with this solution, follow these steps:

  1. Obtain an SSL server certificate for your domain by requesting or importing it in AWS Certificate Manager in the same Region where you plan to launch your stack.

  2. When launching the stack, set the AWS CloudFormation template parameter CloudFrontWafDeployment to No.

  3. Enter the SSL certificate ARN in AWS CloudFormation template parameter SSLCertificate.

  4. After you deploy the stack, access the ALB DNS name from the AWS CloudFormation console, on the Outputs tab, from the value for PrebidALBDNSName.

  5. Update your domain’s DNS settings to route traffic to the Prebid Application Load Balancer.

Managing configuration files for the solution

This section provides detailed instructions for updating configuration files for the Prebid Server and restarting the cluster. It also covers file descriptions, recovery from configuration mistakes, and guidance on using the S3 bucket’s versioning feature for rollback.

Finding the S3 bucket for prebid configuration files

The S3 bucket used for Prebid Server configuration files is created automatically by the stack. To locate the bucket where the configuration files are stored, follow these steps:

  1. Access the CloudFormation stack outputs - Sign in to the AWS CloudFormation console.

  2. Select the Prebid Server stack - From the list of stacks, select the stack that is responsible for creating your Prebid Server environment.

  3. View the outputs - After selecting the stack, choose the Outputs tab.

  4. Locate the S3 bucket link - Find the Output entry that starts with ContainerImagePrebidSolutionConfigBucket. This output contains a direct link to the S3 bucket where the configuration files are stored.

  5. Navigate to the S3 bucket - Choose the link in the output to navigate to the root of the S3 bucket. From there, you see the folder structure containing the default/ and current/ configuration files.

After you locate the bucket, you can download, modify, and manage the Prebid Server configuration files as described in the following sections.

This S3 bucket is retained after the stack is deleted. To delete the bucket, see Deleting the Amazon S3 buckets

Making configuration changes

When working with the Prebid Server, maintain separation between default and custom configurations. Make updates to the configuration files in the /prebid-server/current/ folder in your S3 bucket, and never in the /prebid-server/default/ folder. After you update the files, redeploy your cluster to apply the changes.

Important folders:

  • default/ - Stores baseline configuration files for Prebid Server, which should not be modified.

  • current/ - Used for custom configuration files that override the defaults.

Updating configuration files and restarting the cluster

  1. Identify the configuration files to modify

    1. Check the /prebid-server/default/ folder in the S3 bucket for the baseline configuration files.

    2. Download the relevant file from the /prebid-server/default/ folder to your workstation. You cannot modify the files directly in the S3 bucket.

  2. Edit the configuration files

    1. After you download the file to your workstation, make the required changes.

    2. Upload the modified file back to the /prebid-server/current/ folder in your S3 bucket.

    Common configuration files include:

    • prebid-config.yaml - Contains the main configuration settings for the Prebid Server instance.

    • prebid-logging.xml - Manages logging levels and output formats for Prebid Server logs.

    • entrypoint.sh - Custom script that initializes and launches the Prebid Server containers.

    For detailed information about how to configure Prebid Server, refer to the Prebid Server Java Documentation.

  3. Document custom scripts

    If you need to modify or add a script such as entrypoint.sh (which is custom), ensure that the following details are documented:

    1. Purpose - What the script is used for (for example, starting services, managing environment variables).

    2. Usage - Specific configurations, dependencies, or parameters used.

    3. Modification - How to safely edit the script.

    Example: The entrypoint.sh script ensures that the necessary environment variables are set before starting the Prebid Server. It can be updated to handle different runtime configurations.

  4. Test your changes in a test stack

    Before applying changes to the production environment, test the configuration updates. Deploy a test stack in an AWS account to ensure that the changes work as expected, avoiding disruption to the production environment.

  5. Deploy the custom configuration

    After making and testing your changes, complete the following steps:

    1. Upload the updated files to the /prebid-server/current/ folder in the S3 bucket.

    2. Force a redeployment of your ECS cluster by following Amazon ECS documentation for initiating a redeployment.

  6. Verify the deployment

    After you complete the redeployment, verify that the new configuration has been applied and that the Prebid Server is functioning as expected. Check the logs and monitor key metrics to ensure that no errors are occurring.

Description of important files

  1. prebid-config.yaml

    Contains the core configuration for running Prebid Server. This file manages settings such as:

    • Bidder adapters

    • Server ports

    • Caching rules

    Refer to the Prebid Server Configuration Guide for detailed usage instructions.

  2. prebid-logging.xml

    Defines logging levels and output destinations for Prebid Server logs. Adjustments to this file control the verbosity and detail of logging, critical for debugging and auditing purposes.

    Example modification: Change the logging level from INFO to DEBUG for troubleshooting.

    Documentation: Prebid Server Logging.

  3. entrypoint.sh

    This is the script responsible for initializing the Prebid Server container. It sets up environment variables, runs prerequisite commands, and starts the Prebid Server.

    Document custom steps or configurations made to this script.

  4. Custom files

    Document the custom files added to the /current/ folder in terms of their purpose, usage, and changes that can be made.

Recovering from a mistake in the config files

Mistakes in configuration files can lead to failed deployments or runtime errors. Because S3 bucket versioning is enabled, you can revert to previous configurations. See How S3 Versioning works for more information.

  1. Identify the issue

    Review the logs or errors generated during deployment. You can access logs through several methods:

    • Navigate to the Logs tab under the Prebid Amazon ECS service in the AWS Management Console to review consolidated output from all containers.

    • Navigate to a specific Task in Amazon ECS, and view the Logs tab for output from that specific container.

    • Check CloudWatch Logs in the log group named <STACK-NAME>-PrebidContainerLogGroup<ID>. Use Log Insights or Live Tail to observe and search the logs.

      For more detailed instructions on how to access Amazon ECS and CloudWatch Logs, refer to the Amazon ECS Logs documentation.

  2. Check S3 version history

    Navigate to your S3 bucket and use versioning to locate the previous, stable version of the configuration file:

    1. Select the file from the /current/ folder and enable the Show versions switch.

    2. Locate the correct version of the file before the mistake was introduced.

  3. Restore the previous version

    After you’ve identified the correct file version, restore it by selecting it and replacing the current file. You can also remove the problematic file from the /current/ folder to allow the original file in the /default/ folder to take precedence.

  4. Redeploy the cluster

    After restoring the stable version, follow the redeployment steps to update your Amazon ECS cluster with the corrected configuration.

Best practices for recovery

  • Backup - Always create a backup of your current configuration before making any changes.

  • Testing - Test configurations in a test stack before applying changes to production.

  • Document - Keep detailed notes on the changes made, including the rationale behind the modifications, to simplify troubleshooting and rollback if needed.

By maintaining a clear separation between default and custom configurations and using S3 bucket versioning, you can safely and effectively update your Prebid Server setup. Always test thoroughly and document changes to ensure smooth deployments and easy recovery from any configuration issues.