ADconsle/docs/configuration.md

Configuration

Two layers:

1. .env — deployment settings, read at boot, never written back. After any change run php artisan config:cache (or php artisan optimize), or the old cached values keep being used.
2. Database (/settings) — in-app settings via PanelSettingsService: general settings in panel_settings (one JSON row), the AD attribute / column definitions in panel_attributes (one row each).

.env reference

Application

Key	Default	Notes
APP_NAME	ADconsole	Shown in the header / page titles.
APP_ENV	production	local on a dev box only.
APP_KEY	—	php artisan key:generate. Also the fallback key for encrypted attributes (see below). Rotating it invalidates existing sessions and any attributes encrypted with it.
APP_DEBUG	false	Never true in production — stack traces leak DNs and query filters.
APP_URL	—	Exact public URL, scheme + host, no trailing slash.
APP_DOMAIN	—	Hostname the Docker/Traefik router matches. Ignored on bare metal.
APP_LOCALE	pl	pl or en.
APP_FALLBACK_LOCALE	en	Used for any missing translation key.
LOG_CHANNEL / LOG_LEVEL	stack / warning	Standard Laravel logging.

Database

ADconsole stores no directory data in SQL — only sessions, cache, queue, the panel's own config (panel_settings, panel_attributes) and the change log (panel_audit).

Key	Notes
DB_CONNECTION	mysql (MariaDB/MySQL), pgsql, or sqlite.
DB_HOST / DB_PORT / DB_DATABASE / DB_USERNAME / DB_PASSWORD	Connection.
DB_ROOT_PASSWORD	Only consumed by docker/compose.yaml when it first initialises docker/data/db.

Sessions / cache / queue

Key	Default	Notes
SESSION_DRIVER	file	database or redis if you run more than one app node.
SESSION_LIFETIME	120	Minutes.
CACHE_STORE	database	The app's own heavy caches (OU tree, dashboard, org chart) always use the file store regardless of this.
QUEUE_CONNECTION	database	No queued jobs ship today.

Active Directory — connection

Key	Default	Notes
LDAP_HOSTS	127.0.0.1	Comma-separated DC list, tried in order. LDAP_HOST (singular) also accepted.
LDAP_USERNAME	—	Service-account bind DN or user@domain.
LDAP_PASSWORD	—	Service-account password.
LDAP_PORT	636	636 LDAPS, 389 plain/STARTTLS.
LDAP_SSL	true	LDAPS.
LDAP_TLS	false	STARTTLS on 389. Use one of SSL/TLS.
LDAP_TLS_VERIFY	false	true = validate the DC certificate chain. Leave false for an internal-CA / self-signed cert the app host doesn't trust.
LDAP_TIMEOUT	5	Seconds.
LDAP_BASE_DN	—	Must cover users, computers and groups. If those OUs are siblings, use the domain root (DC=…,DC=…).
LDAP_LOGGING	true	Logs LDAP operations to the Laravel log.

Writes to AD (password reset, enable/disable, create, move, delete) require LDAP_SSL=true or LDAP_TLS=true. A clear connection can read but every write of unicodePwd etc. is refused by the DC.

Active Directory — defaults & access

Key	Notes
LDAP_DEFAULT_USER_OU	Where new users are created; also caps the Users OU tree.
LDAP_DEFAULT_COMPUTER_OU	Same for Computers.
LDAP_DEFAULT_GROUPS_OU	Same for Groups.
AD_DOMAIN_LABEL	Friendly domain name in the header (defaults to LDAP_BASE_DN).
AD_LOGIN_GROUP	AD group whose members may sign in. Full DN (recommended) or bare CN. Nested membership + primary group honoured. Empty = nobody can log in.

AD_LOGIN_GROUP controls who can open the panel. It does not grant directory permissions — what the service account may change is decided by AD delegation. See active-directory.md.

Mail

Not used by the app as shipped. Configure MAIL_* only if you add notifications.

In-app settings (/settings)

All read and written through App\Services\PanelSettingsService. Nothing here touches .env.

General tab

Stored as one JSON row in panel_settings (key panel). Absent → the built-in PanelSettingsService::defaults() apply.

Setting	Meaning
Reset password → must change at next logon	Default state of that checkbox in the reset dialog.
Reset password → unlock account	Default state of the "also unlock" checkbox.
Password policy → max age (days)	Drives the "password expires / expired" columns and dashboard tiles. 0 = no expiry. This is ADconsole's own figure — it does not read the domain's maxPwdAge.
Password generator → length / symbols	For the in-panel generator only; does not touch AD policy.
Attribute encryption key	Symmetric key used to encrypt/decrypt attributes whose type is encrypted (e.g. cloud extension attributes). Empty = feature off. base64:… (16/32 bytes) is used verbatim — paste APP_KEY here if values were encrypted with it; any other string is hashed to a 32-byte key. See App\Services\AttributeCipher.
Audit log → require a reason for destructive actions	When on, disable / delete / move-OU / offboard refuse to run without a reason. An audit row (panel_audit) is written either way — this only forces the operator to type why. Default: off.

Attributes tab

Defines the attribute set the Users module works with. One row per attribute in panel_attributes; row order (position) sets column / field order. Empty table → PanelSettingsService::defaultAttributes() apply.

Column	Meaning
key	internal id ([A-Za-z0-9_-])
label	column / field caption
ldap	the AD attribute name
category	profile-dialog tab: general / org / address / hr / account
type	text · number · date · encrypted (editable) or system · account_status · password_expiry (computed / read-only)
is_column	show it as a column on the user list
position	display order

Locked rows that can't be removed or retyped: login (sAMAccountName), distinguishedName, the computed status and password_expiry, and account_expiry (fixed date, accountExpires). If deleted directly in SQL they are re-created from the defaults on the next read.

Backup / restore

The General tab has a Configuration backup card:

• Export downloads a JSON file with the General-tab settings and the full attribute list (App\Services\ConfigBackupService::export()). Tick leave the encryption key out to blank encryption.key in the file.
• Import reads such a file back and overwrites panel_settings (key panel) and panel_attributes. Values are re-validated on the way in (ranges clamped, locked attribute rows re-asserted), so a hand-edited file can't push the panel into a bad state. A file that isn't a format: adconsole-config JSON, or that declares a newer schema version, is rejected with a form error.

Both actions write a panel_audit row (config.export / config.import). The backup never contains Active Directory data or the audit log itself.