Configuration Reference

All configuration is loaded from environment variables. The application reads .env files from the current directory and project root on startup.

Example .env File

ENVIRONMENT=development
APP_PORT=8080
AUTH_TOKEN_SECRET=replace-with-at-least-32-characters

DATABASE_HOST=mysql
DATABASE_PORT=3306
DATABASE_USERNAME=trackme
DATABASE_PASSWORD=trackme
DATABASE_NAME=tracker

ERP_INTEGRATION_ENABLED=false

Core / Application

Variable	Description	Default	Required
APP_PORT	HTTP server listen port	8080	No
ENVIRONMENT	Runtime environment (development, staging, production)	production	No
DEBUG	Enable debug mode	false	No
APP_LOCAL_TIMEZONE	Application timezone (IANA format, e.g. Europe/London)	UTC	No

Database

The application supports MySQL (primary) and SQLite engines.

Variable	Description	Default	Required
DATABASE_ENGINE	Database driver (mysql or sqlite)	mysql	No
DATABASE_URL	Full DSN (fallback if individual vars not set)	trackme:trackme@/tracker?parseTime=true	No
DATABASE_HOST	MySQL host	—	For MySQL
DATABASE_PORT	MySQL port	3306	No
DATABASE_USERNAME	MySQL user	—	For MySQL
DATABASE_PASSWORD	MySQL password	—	For MySQL
DATABASE_NAME	MySQL database name	—	For MySQL
DATABASE_PATH	SQLite file path	—	For SQLite

INFO

When DATABASE_HOST, DATABASE_USERNAME, DATABASE_PASSWORD, and DATABASE_NAME are all set, they take precedence over DATABASE_URL. The connection string is built as user:pass@tcp(host:port)/dbname?parseTime=true.

Authentication

Variable	Description	Default	Required
AUTH_TOKEN_SECRET	JWT signing secret for admin auth (HS256)	—	Yes (min 32 chars)

WARNING

The application validates this on startup and will not start if it is missing or shorter than 32 characters.

ERP / iSAMS Integration

These variables control the optional iSAMS integration. When disabled, all ERP-related features and cron jobs are skipped.

Variable	Description	Default	Required
ERP_INTEGRATION_ENABLED	Master toggle for iSAMS integration	false	No
ISAMS_BASE_URL	iSAMS API base URL	—	When ERP enabled
ISAMS_API_CLIENT_ID	OAuth2 client ID	—	When ERP enabled
ISAMS_API_CLIENT_SECRET	OAuth2 client secret	—	When ERP enabled
ERP_LOCAL_TIMEZONE	Timezone for ERP date calculations	System local	No
ERP_MAIN_REGISTRATION_PERIOD_TYPE	Registration period type code	AM	No
ERP_DEFAULT_LESSON_ABSENCE_CODE_NAME	Default absence code name	O	No
AUTO_REGISTRATION_YEAR_GROUPS	Comma-separated year groups for auto-absence marking	—	No
FORCE_ERP_SYNC_ON_START	Force a full student sync on application start	false	No

TIP

ERP integration is only active when all three conditions are met: ERP_INTEGRATION_ENABLED=true, ISAMS_BASE_URL is set, and both ISAMS_API_CLIENT_ID and ISAMS_API_CLIENT_SECRET are provided.

Cron Schedules

These cron expressions are only used when ERP integration is enabled. Format follows standard cron syntax.

Variable	Description	Default
CRON_STUDENT_SYNC	Student data sync from iSAMS	0 7-17/2 * * 1-5 (every 2h, 7–17, weekdays)
CRON_PHOTO_SYNC	Student photo sync	0 5 * * 1-5 (5:00 AM, weekdays)
CRON_REGISTRATION_CODES_SYNC	Registration code dictionary sync	0 7-17/1 * * 1-5 (hourly, 7–17, weekdays)
CRON_MARK_ABSENT	Mark unregistered students as absent	10 8-12/1 * * 1-5 (hourly, 8:10–12:10, weekdays)

Storage / Images

Variable	Description	Default
STUDENTS_IMAGE_PHOTO_DIR	Filesystem path for student photos	storage/img/students
STUDENTS_IMAGE_PHOTO_URL_PREFIX	URL prefix for student photo serving	/storage/img/students
VISITOR_IMAGE_DIR	Filesystem path for visitor images	storage/img/visitors
VISITOR_IMAGE_URL_PREFIX	URL prefix for visitor image serving	/storage/img/visitors

Docker-Only Variables

These are used only in the Docker Compose setup:

Variable	Description	Default
MYSQL_ROOT_PASSWORD	MySQL root password for the container	—