Databases and Redis

The Full Stack Quick Start runs a MariaDB container for each service and one Redis container. This page covers replacing them with databases and Redis that you manage.

Settings on this page are given as environment variables, except where a setting is in another file. For other ways to configure the services, see Configuration Mechanics.

Requirements

Store	Used by	Supported versions
Relational database	one-core, one-frontend-backend (BFF), one-bridge, one-wallet-relying-party-registry	MariaDB 11.4, or PostgreSQL 18.3
Redis-compatible store	one-frontend-backend	Compatible with Redis 8.2

Each service needs its own database. The databases are independent of each other, so different services can use different supported engines or versions.

Databases

Preparing a database

For each service, create an empty database and a user for the service. The service creates and updates its own tables, so the user needs permission to create and change tables, not only to read and write data. For how to create databases and users, see your database vendor's documentation.

Connecting a service

Service	Settings	Quick start location
one-core	ONE_app__databaseUrl	env/.core.env
one-frontend-backend (BFF)	spring.datasource.url, spring.datasource.username, spring.datasource.password	env/.bff.env
one-bridge	spring.datasource.url, spring.datasource.username, spring.datasource.password	env/.bridge.env
one-wallet-relying-party-registry	spring.datasource.url, spring.datasource.username, spring.datasource.password	env/.wrpr.env

Core takes the credentials as part of ONE_app__databaseUrl. For MariaDB, the URL starts with mysql://. Core connects using the MySQL protocol, which MariaDB supports.

BFF, Bridge, and WRPR take the credentials as separate settings. In the starter setup, the images build the database URL from MYSQL_* variables, with a fixed port of 3306. Set the three settings above directly instead, and remove the MYSQL_* variables. The URL starts with jdbc:mariadb:// or jdbc:postgresql://.

Each service keeps a pool of connections to its database. The pool size applies to each instance of a service, so if you run several instances, your database must accept enough connections for all of them. For pool settings, see the Core, BFF, WRPR, and Bridge configuration references.

Schema migrations

Each service updates its database schema when it starts, by running the migrations included in its version. Note the following:

• Migrations cannot be undone. To return to an earlier version, restore a backup taken before the upgrade. Back up each database before you upgrade a service.
• Migrations are not designed to run from several instances at the same time. Do not start several instances of a service at once against a new or upgraded database.

Core can run migrations separately from the server. Add one of these flags to the command of the core service:

Flag	Effect
--only-migration	Migrates the database, then exits.
--skip-migration	Starts the server without migrating. The database must already be migrated.

For example, run Core once with --only-migration, then start your Core instances with --skip-migration.

Redis

The BFF require a Redis-compatible store. You can use Redis or any compatible service, such as Valkey or a managed service from your cloud provider.

In the starter setup, the auxiliary service oauth2_proxy stores operator sessions in the same Redis instance.

Service	Data	If the data is lost
one-frontend-backend (BFF)	Mappings of sessions to roles	The mappings are rebuilt. The first requests take longer.
oauth2_proxy	Operator sessions	Operators are signed out.

The services do not need this data to survive a restart, so persistence is not required.

Connecting to Redis

Service	Settings	Quick start location
one-frontend-backend (BFF)	REDIS_HOST, REDIS_PORT, REDIS_DB, REDIS_PASSWORD	env/.bff.env
oauth2_proxy	redis_connection_url	conf/oauth2_proxy/oauth2-proxy.cfg

Keep session_store_type = "redis" in oauth2-proxy.cfg. For the connection URL format, including credentials and TLS, see the oauth2-proxy session storage documentation.

Removing the starter containers

After a service connects to your own database or Redis, remove the starter container from docker-compose.yml: its service entry, its entries under depends_on, and its volume, if it has one.