env.example

# The bundled database's own administrator. MySQL bakes this into its data
# directory the first time the container starts and ignores it after, so setup
# generates it once and leaves it alone --- nobody types this one. The account that
# administers the study is DB_ADMIN_USER / DB_ADMIN_PASSWORD below.
MYSQL_ROOT_PASSWORD=

# Password for the participant accounts devices use to insert data. Set it here
# or in the setup wizard's Database step before deploying; left blank, one is
# generated during deployment. Every deployment applies this value to the MySQL
# accounts, and it is embedded in the study config unless config_without_password
# is enabled — in which case participants type it when joining the study.
PARTICIPANT_DB_PASSWORD=

# Password for the Android micro-server's own MySQL account. On the webservice
# dataflow the server performs every write, so this is the credential ingest
# authenticates with; no device ever holds it. Left blank, one is generated during
# deployment. Its own secret rather than the participant one above, because that one
# is published to every phone on the direct dataflow and this account may read the
# enrolment registry a phone's account may not.
ANDROID_SERVER_DB_PASSWORD=
# The account the dashboard dumps and restores the study with, generated during
# deployment if left blank. It holds the two study schemas and nothing else,
# because a restore runs every statement in the archive it is handed.
BACKUP_DB_PASSWORD=
# Maximum simultaneous authenticated sessions allowed per MySQL account.
# This is a capacity guard, not a limit on enrolled study participants.
MYSQL_MAX_USER_CONNECTIONS_PER_ACCOUNT=100

# Django secret key — generate with: python -c "import secrets; print(secrets.token_hex(50))"
DJANGO_SECRET_KEY=replace_with_a_long_random_string

# Signs the researcher's dashboard session cookie. Generated during deployment if
# left blank. Keep it stable: changing it signs everyone out, and leaving it empty
# means every API restart does the same.
DASHBOARD_SESSION_SECRET=

# What the next deploy should mint again, as a list: `study-key`, `broker`, or
# both. Each one is generated on the first deploy that needs it and kept
# afterwards, so this is how a credential that has been exposed is replaced.
# Cleared once it has been acted on, so a rotation happens on the deploy that
# asked for it rather than on every deploy after.
#
# Both live on phones that are out in the field. A new study key changes the
# address a phone uploads to, so every participant rejoins by scanning the QR
# code again; a new broker password stops prompts reaching a phone until it has
# read its configuration.
ROTATE=

# How often the record counts the dashboard shows are refreshed, in seconds.
COUNTS_REFRESH_INTERVAL_SECONDS=60

# Set to 1 to log every SQL statement the API and the refresher run.
SQL_ECHO=

# Public host used by the reverse proxy and generated study URLs
PUBLIC_HOST=localhost
PUBLIC_PORT=80

# The account that creates the schema and this study's own accounts. Written by
# setup, which reads it from the wizard and falls back to what the host says about
# its provider: `avnadmin` for
# Aiven, `doadmin` for DigitalOcean, `root` for a database this deployment runs or
# a server you administer yourself. Set it by hand only when your provider named
# it something else.
DB_ADMIN_USER=root

# Its password. The administrator of whichever database this study names --- the
# provider's account on a server you name, and on the bundled database an account
# setup creates with that name and these privileges. Kept apart from
# MYSQL_ROOT_PASSWORD above, which belongs to the bundled container alone: MySQL
# bakes that one into its data directory at first start, so a field serving both
# overwrote the value the bundled server still needed the moment a study named
# somebody else's.
DB_ADMIN_PASSWORD=

# Where the setup wizard listens while it runs. Every address by default, because a
# server you are not sitting at has no other way in. Set it to 127.0.0.1 to keep the
# wizard on the machine and reach it through `ssh -L 9999:localhost:9999` instead --
# worth doing on a shared network, since the page it serves holds this deployment's
# database password and the researcher's own, over plain HTTP.
# SETUP_BIND=127.0.0.1

# Optional AWARE Micro database override. In Docker, the default is the internal
# MySQL service name `mysql`.
# MICRO_DATABASE_HOST=mysql

# Optional Android database override. Leave blank to reuse PUBLIC_HOST.
# ANDROID_DATABASE_HOST=your-public-hostname

# Protocol: "http" or "https"
PROTOCOL=http

# SSL certificates (only needed if PROTOCOL=https)
SSL_CERTIFICATE_PATH=./certs/fullchain.pem
SSL_CERTIFICATE_KEY_PATH=./certs/privkey.pem

# UID:GID the Configurator container runs as, so files it writes into bind-mounted
# host directories (studies/, aware-micro-server/esm/) are owned by you rather than
# root. setup.sh sets this automatically to your `id -u`/`id -g`, and the deploy
# fills it in from the project directory's own owner where nothing else has --- on
# Docker Desktop that is root, the only user that can write into the directories the
# deploy creates in the mount. Only set it by hand if you're deploying without
# either. The compose default of 1000:1000 owns nothing on Windows: the Configurator
# then answers every Save with a 500.
HOST_UID=1000
HOST_GID=1000

# Derived by setup from the study model's single database declaration, so the API,
# its refresher and the backup job follow a changed address instead of each holding
# their own copy. A service inside the deployment reaches the bundled database as
# `mysql` on the compose network; a declared external host is used as given.
DB_SERVICE_HOST=mysql
ANDROID_DATABASE_URL=mysql+aiomysql://aware_analytics:analyticspass@mysql:3306/aware_android
IOS_DATABASE_URL=mysql+aiomysql://aware_analytics:analyticspass@mysql:3306/aware_ios

# Whether this deployment's own reads of the study database are encrypted, derived
# from the same declaration the phones and the micro-server read. A database this
# deployment runs is always encrypted; a database you name may be a server that
# cannot offer TLS, and a client insisting on it there would fail every query.
DB_REQUIRE_TLS=1

# Whether the scheduled backup job follows a study that moved to a database this
# deployment does not run. Off: the job was written for the bundled database and is
# removed along with it, leaving copies of the named server to whoever administers
# it. On: the job stays, dumping into the same folder as `aware_analytics`, which may
# only read. Answered in setup, and kept across a redeploy that does not open it.
DB_KEEP_BACKUPS=0

# Who may reach MySQL's published port. The direct dataflow needs participant
# phones to open it themselves, so it is published to every interface; on the
# webservice dataflow only this host has any business there. Setup derives it from
# the chosen dataflow.
MYSQL_BIND_ADDRESS=0.0.0.0