Skip to content

Commit d3d18aa

Browse files
skylightis666skylightis666
committed
Split configuration reference docs
1 parent 0d16abc commit d3d18aa

4 files changed

Lines changed: 85 additions & 55 deletions

File tree

‎SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
* [MDMbox](README.md)
44
* [Getting started](getting-started.md)
5+
* [Configuration reference](config-reference.md)
56
* [Matching models](matching-models.md)
67
* [Find duplicates: $match](match-operation.md)
78
* [Bulk matching](bulk-match.md)

‎docs/config-reference.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
description: Environment variables and runtime configuration for MDMbox.
3+
---
4+
5+
# Configuration reference
6+
7+
MDMbox is configured through environment variables.
8+
9+
## License
10+
11+
MDMbox requires a license to start. There are two ways to activate it:
12+
13+
1. **Environment variable.** Sign in to the [Aidbox portal](https://aidbox.app/ui/portal), open the MDMbox project, copy the license JWT, and pass it to the MDMbox container as `MDMBOX_LICENSE`. Recommended for production and CI.
14+
2. **Browser activation.** Leave `MDMBOX_LICENSE` unset and start MDMbox. Open `http://localhost:3000`, click **Continue with Aidbox account**, sign in to the portal — a development MDMbox license is generated and stored in the database automatically. Useful for local development.
15+
16+
| Variable | Description | Required |
17+
| --- | --- | --- |
18+
| `MDMBOX_LICENSE` | License JWT copied from the Aidbox portal | No — falls back to browser activation |
19+
20+
## Authentication
21+
22+
Authentication is enabled by default. When enabled, MDMbox protects both API
23+
endpoints and the Admin UI:
24+
25+
- API endpoints require a valid `Authorization` header.
26+
- The Admin UI uses browser session authentication and redirects unauthenticated
27+
users to `/login`.
28+
- Health checks, Swagger UI, and the OpenAPI specification remain public.
29+
30+
| Variable | Description | Default |
31+
| --- | --- | --- |
32+
| `MDMBOX_AUTH_ENABLED` | Enable authentication for API endpoints and the Admin UI. Accepted values: `true` or `false`. | `true` |
33+
| `MDMBOX_ADMIN_ID` | Admin `User` id to bootstrap for browser login. Must be set together with `MDMBOX_ADMIN_PASSWORD`. | unset |
34+
| `MDMBOX_ADMIN_PASSWORD` | Password for the bootstrapped admin `User`. Must be set together with `MDMBOX_ADMIN_ID`. | unset |
35+
| `MDMBOX_API_CLIENT_ID` | API `Client` id to bootstrap for Basic auth. Must be set together with `MDMBOX_API_CLIENT_SECRET`. | unset |
36+
| `MDMBOX_API_CLIENT_SECRET` | Secret for the bootstrapped API `Client`. Must be set together with `MDMBOX_API_CLIENT_ID`. | unset |
37+
38+
## Match operation
39+
40+
| Variable | Description | Default |
41+
| --- | --- | --- |
42+
| `MDMBOX_MATCH_DEFAULT_COUNT` | Default maximum number of `$match` results when the request omits `count`. | `10` |
43+
44+
## Database
45+
46+
MDMbox uses the standard Aidbox database environment variables:
47+
48+
| Variable | Description | Required |
49+
| --- | --- | --- |
50+
| `BOX_DB_HOST` | PostgreSQL host | Yes |
51+
| `BOX_DB_PORT` | PostgreSQL port (default: 5432) | No |
52+
| `BOX_DB_DATABASE` | Database name | Yes |
53+
| `BOX_DB_USER` | Database user | Yes |
54+
| `BOX_DB_PASSWORD` | Database password | Yes |
55+
56+
## MDMbox Connection Pool
57+
58+
MDMbox maintains its own connection pool separate from the embedded FHIR engine. Both pools connect to the same database but are sized independently.
59+
60+
| Variable | Description | Default |
61+
| --- | --- | --- |
62+
| `MDMBOX_DB_MAX_POOL_SIZE` | Maximum pool connections | 10 |
63+
| `MDMBOX_DB_MIN_IDLE` | Minimum idle connections | 1 |
64+
65+
## HTTP Server
66+
67+
| Variable | Description | Default |
68+
| --- | --- | --- |
69+
| `MDMBOX_HTTP_PORT` | HTTP port | 3000 |
70+
71+
## Related Pages
72+
73+
- [Getting started](getting-started.md)
74+
- [Find duplicates: $match](match-operation.md)

‎docs/getting-started.md‎

Lines changed: 6 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -86,63 +86,14 @@ config:
8686

8787
The full list of values is in the [chart README](https://github.com/HealthSamurai/helm-charts/blob/main/mdmbox/README.md).
8888

89-
## License
89+
## Configuration
9090

91-
MDMbox requires a license to start. There are two ways to activate it:
91+
For production, pass `MDMBOX_LICENSE` as an environment variable. For local
92+
trial runs, you can leave it unset and activate MDMbox in the browser after
93+
startup.
9294

93-
1. **Environment variable.** Sign in to the [Aidbox portal](https://aidbox.app/ui/portal), open the MDMbox project, copy the license JWT, and pass it to the MDMbox container as `MDMBOX_LICENSE`. Recommended for production and CI.
94-
2. **Browser activation.** Leave `MDMBOX_LICENSE` unset and start MDMbox. Open `http://localhost:3000`, click **Continue with Aidbox account**, sign in to the portal — a development MDMbox license is generated and stored in the database automatically. Useful for local development.
95-
96-
| Variable | Description | Required |
97-
| --- | --- | --- |
98-
| `MDMBOX_LICENSE` | License JWT copied from the Aidbox portal | No — falls back to browser activation |
99-
100-
## Configuration reference
101-
102-
### Authentication
103-
104-
Authentication is enabled by default. When enabled, MDMbox protects both API
105-
endpoints and the Admin UI:
106-
107-
- API endpoints require a valid `Authorization` header.
108-
- The Admin UI uses browser session authentication and redirects unauthenticated
109-
users to `/login`.
110-
- Health checks, Swagger UI, and the OpenAPI specification remain public.
111-
112-
| Variable | Description | Default |
113-
| --- | --- | --- |
114-
| `MDMBOX_AUTH_ENABLED` | Enable authentication for API endpoints and the Admin UI. Accepted values: `true` or `false`. | `true` |
115-
| `MDMBOX_ADMIN_ID` | Admin `User` id to bootstrap for browser login. Must be set together with `MDMBOX_ADMIN_PASSWORD`. | unset |
116-
| `MDMBOX_ADMIN_PASSWORD` | Password for the bootstrapped admin `User`. Must be set together with `MDMBOX_ADMIN_ID`. | unset |
117-
| `MDMBOX_API_CLIENT_ID` | API `Client` id to bootstrap for Basic auth. Must be set together with `MDMBOX_API_CLIENT_SECRET`. | unset |
118-
| `MDMBOX_API_CLIENT_SECRET` | Secret for the bootstrapped API `Client`. Must be set together with `MDMBOX_API_CLIENT_ID`. | unset |
119-
120-
### Database
121-
122-
MDMbox uses the standard Aidbox database environment variables:
123-
124-
| Variable | Description | Required |
125-
| --- | --- | --- |
126-
| `BOX_DB_HOST` | PostgreSQL host | Yes |
127-
| `BOX_DB_PORT` | PostgreSQL port (default: 5432) | No |
128-
| `BOX_DB_DATABASE` | Database name | Yes |
129-
| `BOX_DB_USER` | Database user | Yes |
130-
| `BOX_DB_PASSWORD` | Database password | Yes |
131-
132-
### MDMbox connection pool
133-
134-
MDMbox maintains its own connection pool separate from the embedded FHIR engine. Both pools connect to the same database but are sized independently.
135-
136-
| Variable | Description | Default |
137-
| --- | --- | --- |
138-
| `MDMBOX_DB_MAX_POOL_SIZE` | Maximum pool connections | 10 |
139-
| `MDMBOX_DB_MIN_IDLE` | Minimum idle connections | 1 |
140-
141-
### HTTP server
142-
143-
| Variable | Description | Default |
144-
| --- | --- | --- |
145-
| `MDMBOX_HTTP_PORT` | HTTP port | 3000 |
95+
See [Configuration reference](config-reference.md) for all environment
96+
variables, authentication settings, and runtime defaults.
14697

14798
## Endpoints
14899

‎docs/match-operation.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,10 @@ No request body is needed — MDMbox retrieves the resource by ID and runs the m
5858
| `onlySingleMatch` | valueBoolean | No | Return at most one result (empty if ambiguous) |
5959
| `count` | valueInteger | No | Maximum number of results (default: 10) |
6060

61+
The default `count` is controlled by `MDMBOX_MATCH_DEFAULT_COUNT` and is `10`
62+
unless configured otherwise. When `onlyCertainMatches=false`, MDMbox returns no
63+
more than 100 potential matches.
64+
6165
### Query parameters (for by-ID match)
6266

6367
| Name | Type | Default | Description |

0 commit comments

Comments
 (0)