docs: split configuration and development references
This commit is contained in:
Daniel Volz
GitHub
@@ -0,0 +1,113 @@
|
||||
# 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 |
|
||||
| `TZ` | `Europe/Berlin` | Server default timezone for scheduled reminders |
|
||||
| `PUBLIC_APP_URL` | — | Public base URL for notification action links |
|
||||
| `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.
|
||||
|
||||
## 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:
|
||||
|
||||
```text
|
||||
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.
|
||||
|
||||
## Push Notifications
|
||||
|
||||
Push notification setup, provider support, and URL examples are documented in [PUSH_NOTIFICATIONS.md](PUSH_NOTIFICATIONS.md).
|
||||
|
||||
Recommended provider: `ntfy`, especially for intake reminders with direct actions.
|
||||
|
||||
## Default User Settings
|
||||
|
||||
Default values for newly created users are documented in [DEFAULT_USER_SETTINGS.md](DEFAULT_USER_SETTINGS.md).
|
||||
@@ -6,6 +6,9 @@ Scope and behavior:
|
||||
|
||||
- These values are applied only when a user's settings are created for the first time.
|
||||
- After that, values stored in the database are used and take precedence.
|
||||
- This document only covers settings that have an environment-backed default.
|
||||
- It is not intended to be a full inventory of every setting shown in the UI.
|
||||
- UI-only settings without a `DEFAULT_*` variable, for example the dashboard section order toggle, are intentionally excluded.
|
||||
|
||||
## Email Defaults
|
||||
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
# Development
|
||||
|
||||
## Start the Development Stack
|
||||
|
||||
```bash
|
||||
docker compose -p medassist-dev -f docker-compose.dev.yml up
|
||||
```
|
||||
|
||||
## Service Endpoints
|
||||
|
||||
- Frontend: `http://localhost:5173`
|
||||
- Backend: `http://localhost:3000`
|
||||
- API docs UI: `http://localhost:3000/docs` when docs are enabled
|
||||
- OpenAPI JSON: `http://localhost:3000/docs/json` when docs are enabled
|
||||
|
||||
## Frontend Dev Server Behind a Proxy
|
||||
|
||||
If the frontend dev server runs behind a reverse proxy or on a remote host, set these frontend-only environment variables before starting Vite:
|
||||
|
||||
These development overrides are documented here intentionally and are not part of the standard operator-focused `.env.example` surface.
|
||||
|
||||
- `BACKEND_URL`: backend target used by the Vite `/api` proxy; default `http://localhost:3000` outside Docker and `http://backend-dev:3000` in Docker
|
||||
- `VITE_ALLOWED_HOSTS`: comma-separated hostnames allowed to connect to the dev server; default `localhost,127.0.0.1`
|
||||
- `VITE_HMR_HOST`: public hostname for HMR websocket connections
|
||||
- `VITE_HMR_PROTOCOL`: websocket protocol override (`ws` or `wss`)
|
||||
- `VITE_HMR_CLIENT_PORT`: public websocket port exposed to the browser
|
||||
- `VITE_HMR_PORT`: server-side websocket port for the Vite process
|
||||
|
||||
## Useful Commands
|
||||
|
||||
```bash
|
||||
npm run lint
|
||||
cd backend && npm run test:run
|
||||
cd frontend && npm run test:run
|
||||
```
|
||||
@@ -0,0 +1,71 @@
|
||||
# Push Notifications
|
||||
|
||||
MedAssist uses [Shoutrrr](https://containrrr.dev/shoutrrr/) for push notifications.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Recommended provider: `ntfy`.
|
||||
|
||||
Use `ntfy` when you want the best-supported MedAssist notification flow, especially for intake reminders with direct actions such as `Take`, `Skip`, and `View`.
|
||||
|
||||
## Supported URL Schemes
|
||||
|
||||
- `ntfy://`
|
||||
- `discord://`
|
||||
- `pushover://`
|
||||
- `gotify://`
|
||||
- `telegram://`
|
||||
- direct `https://` webhooks
|
||||
|
||||
## Configuration
|
||||
|
||||
Configure push notifications in the app under `Settings -> Push`, or set defaults for new users with environment variables.
|
||||
|
||||
Push-related default variables:
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `DEFAULT_SHOUTRRR_ENABLED` | `false` | Enable push notifications by default |
|
||||
| `DEFAULT_SHOUTRRR_URL` | — | Default Shoutrrr URL |
|
||||
| `DEFAULT_SHOUTRRR_STOCK_REMINDERS` | `true` | Send stock reminders via push |
|
||||
| `DEFAULT_SHOUTRRR_INTAKE_REMINDERS` | `true` | Send intake reminders via push |
|
||||
| `DEFAULT_SHOUTRRR_PRESCRIPTION_REMINDERS` | `true` | Send prescription reminders via push |
|
||||
|
||||
For the full default-user-settings reference, see [DEFAULT_USER_SETTINGS.md](DEFAULT_USER_SETTINGS.md).
|
||||
|
||||
## URL Examples
|
||||
|
||||
### ntfy
|
||||
|
||||
```text
|
||||
ntfy://ntfy.sh/your-topic
|
||||
ntfy://user:password@your-server.com/topic
|
||||
```
|
||||
|
||||
### Pushover
|
||||
|
||||
```text
|
||||
pushover://shoutrrr:API_TOKEN@USER_KEY/
|
||||
```
|
||||
|
||||
### Gotify
|
||||
|
||||
```text
|
||||
gotify://your-server.com/TOKEN
|
||||
gotify://your-server.com:443/path/to/gotify/TOKEN?priority=1
|
||||
```
|
||||
|
||||
### Discord
|
||||
|
||||
```text
|
||||
discord://TOKEN@WEBHOOK_ID
|
||||
```
|
||||
|
||||
### Telegram
|
||||
|
||||
```text
|
||||
telegram://TOKEN@telegram?chats=CHAT_ID
|
||||
telegram://TOKEN@telegram?chats=@your_channel,-1001234567890
|
||||
```
|
||||
|
||||
For all supported services and options, see the [Shoutrrr documentation](https://containrrr.dev/shoutrrr/v0.8/services/overview/).
|
||||
Reference in New Issue
Block a user