Service: Open Ad Server - EyevinnOSC/community GitHub Wiki

Open Ad Server

Open Ad Server (serviceId seanzhang414-openadserver) is an open source ad serving platform. It provides campaign management, ad targeting, impression tracking and delivery APIs for web and video advertising workflows, with ML-powered CTR predictions. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance.

What it can do

  • Manage advertising campaigns and ad targeting.
  • Track impressions and deliver ads through delivery APIs for web and video advertising.
  • Predict click-through rate with machine learning.
  • Provide an ad server dashboard at the instance URL.

Creating an instance

Open Ad Server depends on PostgreSQL (primary database) and Valkey (session and cache storage). Create both first and confirm they are running with wait-for-service-ready or get-instance-status.

  1. Create a PostgreSQL instance (birme-osc-postgresql, see PostgreSQL) with a name and a PostgresPassword. Use describe-service-instance to read the internal TCP address, user and password. Build the URL postgres://username:password@host:5432/postgres.
  2. Store that URL as a service secret with create-service-secret (serviceId: "seanzhang414-openadserver", for example name openads-dburl).
  3. Create a Valkey instance (valkey-io-valkey, see Valkey) and note its internal TCP URL, for example redis://host:6379.
  4. Create the instance with create-service-instance using serviceId: "seanzhang414-openadserver". The instance name must be alphanumeric and at most 20 characters.
{
  "name": "myopenadserver",
  "DatabaseUrl": "{{secrets.openads-dburl}}",
  "RedisUrl": "redis://<valkey-host>:6379"
}

The service runs database migrations on first start. Once running, open the instance URL (from describe-service-instance) to reach the ad server dashboard.

OSC CLI example:

# Create dependencies first
osc create birme-osc-postgresql myadsdb \
  -o PostgresPassword="{{secrets.ads-dbpass}}"

osc create valkey-io-valkey myadsvalkey

# Then create the ad server
osc create seanzhang414-openadserver myopenadserver \
  -o DatabaseUrl="{{secrets.openads-dburl}}" \
  -o RedisUrl="<valkey-internal-url>"

Options

Option Required Type Meaning
name Yes string Name of the instance. Letters, digits and underscore only; on OSC at most 20 characters.
DatabaseUrl Yes string, sensitive Full PostgreSQL connection URL, postgres://<user>:<password>@<host>:<port>/<db>. Store as a service secret and pass as {{secrets.NAME}}.
RedisUrl Yes string, sensitive URL of your Valkey (Redis-compatible) instance, for example redis://<host>:6379. If you set a Valkey password, include it in the URL and store the whole URL as a secret.

A {{secrets.NAME}} reference must be the whole field value. Overwriting a secret does not restart a running instance.

PostgreSQL options (birme-osc-postgresql)

Option Required Type Meaning
name Yes string Instance name, at most 20 characters.
PostgresPassword Yes string, sensitive Password for the PostgreSQL superuser. Example: {{secrets.postgrespwd}}.
PostgresUser No string Superuser name; postgres if not provided.
PostgresDb No string Name of the default database created at first start; the user name if not specified.
PostgresInitDbArgs No string Extra arguments passed to initdb when the cluster is initialized.
PostgresInitDbSql No string SQL executed during database initialization.

Valkey options (valkey-io-valkey)

Option Required Type Meaning
name Yes string Instance name, at most 20 characters.
Password No string, sensitive Password clients must supply. If empty, OSC generates one. See the Valkey page.

Resources

⚠️ **GitHub.com Fallback** ⚠️