medassist-ng/docs/CONFIGURATION.md

Configuration

Configure MedAssist with environment variables in .env. Start from .env.example.

General

Variable	Default	Description
PUID	1000	User ID for container file permissions
PGID	1000	Group ID for container file permissions
PORT	3000	Backend API port
CORS_ORIGINS	http://localhost:4174	Allowed origins for CORS in the Docker Compose quickstart; local Vite development commonly uses http://localhost:5173 or http://localhost:4173
TZ	Europe/Berlin	Server default timezone for scheduled reminders
PUBLIC_APP_URL	—	Public base URL for notification action and share links. Strongly recommended for any deployment used from another device; do not point this to localhost or an internal Docker hostname. Local Vite development also allows this hostname automatically.
LOG_LEVEL	info	Log level: debug, info, warn, error, or silent
RATE_LIMIT_MAX	100	Maximum requests per minute per IP
OPENAPI_DOCS_ENABLED	auto	Explicitly enable or disable /docs and /docs/json

API docs behavior:

• If OPENAPI_DOCS_ENABLED is unset, docs are enabled outside production and disabled in production.
• OPENAPI_DOCS_ENABLED=true enables /docs and /docs/json.
• OPENAPI_DOCS_ENABLED=false disables the docs only.

CORS_ORIGINS note:

• The .env.example file is optimized for the Docker Compose quickstart, where the frontend runs on http://localhost:4174.
• Local frontend development uses the Vite dev server instead, so the backend schema defaults cover http://localhost:5173 and http://localhost:4173.
• If you use a custom hostname or reverse proxy, include that origin in CORS_ORIGINS.

Authentication

Variable	Default	Description
AUTH_ENABLED	false	Enable user authentication
REGISTRATION_ENABLED	false	Allow new user registrations
FORM_LOGIN_ENABLED	true	Enable username/password login
JWT_SECRET	—	Access token signing key; required when auth is enabled
REFRESH_SECRET	—	Refresh token signing key; required when auth is enabled
COOKIE_SECRET	—	Cookie signing key; required when auth is enabled
ACCESS_TOKEN_TTL_MINUTES	15	Access token lifetime
REFRESH_TOKEN_TTL_DAYS	7	Refresh token lifetime

Generate secrets with openssl rand -hex 32.

API Keys

When AUTH_ENABLED=true, authenticated users can create API keys and call protected endpoints with:

Authorization: Bearer ma_...

Available scopes:

• read: read-only access (GET, HEAD, OPTIONS)
• write: read and write access

Notes:

• The token is shown only once after creation.
• Creating a new key deactivates previously active keys for the same user.
• API keys are stored hashed in the database.

API reference:

• Interactive docs: /docs
• OpenAPI JSON: /docs/json
• Key management endpoints:
  • GET /auth/api-keys
  • POST /auth/api-keys
  • DELETE /auth/api-keys/:id

OIDC / SSO

Variable	Default	Description
OIDC_ENABLED	false	Enable OIDC authentication
OIDC_ISSUER_URL	—	OIDC provider URL
OIDC_CLIENT_ID	—	OIDC client ID
OIDC_CLIENT_SECRET	—	OIDC client secret
OIDC_REDIRECT_URI	—	OIDC callback URL
OIDC_SCOPES	openid profile email	Requested scopes
OIDC_USERNAME_CLAIM	preferred_username	Username claim
OIDC_AUTO_CREATE_USERS	true	Auto-create users on first SSO login
OIDC_PROVIDER_NAME	SSO	Login button label

Email (SMTP)

Variable	Default	Description
SMTP_HOST	—	SMTP server hostname
SMTP_PORT	587	SMTP server port
SMTP_USER	—	SMTP username
SMTP_PASS	—	SMTP password
SMTP_TOKEN	—	OAuth2 or app token; takes precedence over SMTP_PASS
SMTP_FROM	—	Sender email address
SMTP_SECURE	false	Use TLS

Reminders

Variable	Default	Description
REMINDER_DAYS_BEFORE	7	Days before stock runs out to send reminder
REMINDER_HOUR	6	Hour to send daily reminders (24h format)
REMINDER_MINUTES_BEFORE	15	Minutes before intake to send reminder
EXPIRY_WARNING_DAYS	30	Days before expiry warning

Reminder timing uses IANA timezones. TZ is the server default. Users can override it in Settings.

These values are runtime defaults. User-specific settings can override reminder behavior after first save.

Push Notifications

Push notification setup, provider support, and URL examples are documented in PUSH_NOTIFICATIONS.md.

Recommended provider: ntfy, especially for intake reminders with direct actions.

Notification action and share links should use PUBLIC_APP_URL as their reachable base URL. For self-hosted setups, this should normally be your externally reachable HTTPS address, for example https://med.example.com.

If PUBLIC_APP_URL is missing in a remote deployment, reminder links can still be generated from local origins that are unreachable from phones or external browsers.

Default User Settings

Default values for newly created users are documented in DEFAULT_USER_SETTINGS.md.