-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathgetting-started.html
More file actions
317 lines (297 loc) · 19.5 KB
/
Copy pathgetting-started.html
File metadata and controls
317 lines (297 loc) · 19.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Get started — MessageFoundry</title>
<meta name="description" content="Install MessageFoundry from PyPI with a single pip install, run the engine and localhost API, send a test HL7 message over MLLP, open the admin console, and author your first Connection / Router / Handler in Python.">
<link rel="canonical" href="https://messagefoundry.org/getting-started.html">
<link rel="icon" href="/assets/img/favicon.svg" type="image/svg+xml">
<meta name="theme-color" content="#0b1220">
<meta property="og:type" content="website">
<meta property="og:site_name" content="MessageFoundry">
<meta property="og:title" content="Get started — MessageFoundry">
<meta property="og:description" content="Install, run the engine, send a test HL7 message, and author your first route in Python.">
<meta property="og:url" content="https://messagefoundry.org/getting-started.html">
<meta property="og:image" content="https://messagefoundry.org/assets/img/og.png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:type" content="image/png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:image" content="https://messagefoundry.org/assets/img/og.png">
<link rel="stylesheet" href="/assets/css/styles.css">
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "HowTo",
"about": { "@id": "https://messagefoundry.org/#software" },
"name": "Get started with MessageFoundry",
"description": "Install MessageFoundry from PyPI, run the engine, send a test HL7 message over MLLP, open the admin console, and author your first route in Python.",
"tool": [{ "@type": "HowToTool", "name": "Python 3.14 or newer" }],
"supply": [{ "@type": "HowToSupply", "name": "messagefoundry (PyPI package)" }],
"step": [
{
"@type": "HowToStep",
"name": "Install",
"text": "Create a virtual environment and install MessageFoundry from PyPI with: pip install messagefoundry."
},
{
"@type": "HowToStep",
"name": "Run the engine",
"text": "Load the sample config, open the store, and serve the localhost API on 127.0.0.1:8765."
},
{
"@type": "HowToStep",
"name": "Send a test message",
"text": "Send an HL7 ADT message to the sample MLLP listener on port 2575 and watch it route."
},
{
"@type": "HowToStep",
"name": "Open the web console",
"text": "Install the web console package alongside the engine and browse to /ui for dashboards, message search, and one-click replay."
},
{
"@type": "HowToStep",
"name": "Author your own route",
"text": "Add a Python module to your config directory that names an inbound and outbound Connection, then wires a Router and Handler by name."
}
]
}
</script>
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{ "@type": "Question", "name": "What do I need to run MessageFoundry?", "acceptedAnswer": { "@type": "Answer", "text": "Python 3.14 or newer on Windows, Linux, or macOS. MessageFoundry installs from PyPI with pip and starts zero-config on a built-in SQLite store, so you can run it on a laptop; for production it also supports PostgreSQL and SQL Server." } },
{ "@type": "Question", "name": "How do I install MessageFoundry?", "acceptedAnswer": { "@type": "Answer", "text": "Create a virtual environment and run pip install messagefoundry, then start the engine pointed at a config directory and a store database. The quickstart walks through receiving your first HL7 v2 message over MLLP." } },
{ "@type": "Question", "name": "Do I have to write code to build an interface?", "acceptedAnswer": { "@type": "Answer", "text": "No. You can set interfaces up with guided wizards in the VS Code extension and drop into plain Python whenever you need full control — either way the result is readable configuration you version-control." } },
{ "@type": "Question", "name": "Which databases does MessageFoundry support?", "acceptedAnswer": { "@type": "Answer", "text": "SQLite out of the box for zero-config local runs, and PostgreSQL or SQL Server for production scale-out and high availability." } }
]
}
</script>
</head>
<body>
<a class="skip-link" href="#main">Skip to content</a>
<div class="eabar" role="region" aria-label="Project status">
<div class="container">
<p><strong>Early Access · beta.</strong> We're building toward 1.0 — and we want people involved now, while it can still be shaped. <a href="/status.html">Where the project stands →</a></p>
</div>
</div>
<header class="site-header">
<div class="container header-inner">
<a class="brand" href="/" aria-label="MessageFoundry home">
<img class="brand-mark" src="/assets/img/logo.svg" alt="" width="28" height="28">
<span class="brand-name">Message<span class="brand-accent">Foundry</span><span class="brand-tm">™</span></span>
</a>
<button class="nav-toggle" aria-expanded="false" aria-controls="site-nav" aria-label="Toggle navigation"><span></span><span></span><span></span></button>
<nav class="site-nav" id="site-nav">
<div class="nav-group">
<button type="button" class="nav-group__btn" aria-expanded="false" aria-haspopup="true" aria-controls="nav-product">Product</button>
<div class="nav-group__menu" id="nav-product">
<a href="/overview.html">Overview</a>
<a href="/features.html">Features</a>
<a href="/features-table.html">Feature list</a>
<a href="/architecture.html">Architecture</a>
<a href="/reliability.html">Reliability (CI)</a>
<a href="/tools.html">Tools</a>
<a href="/editor.html">Editor</a>
<a href="/console.html">Console</a>
<a href="/ai.html">AI assist</a>
</div>
</div>
<a href="/security.html">Security</a>
<a href="/comparison.html">Comparison</a>
<div class="nav-group">
<button type="button" class="nav-group__btn" aria-expanded="false" aria-haspopup="true" aria-controls="nav-getstarted">Get started</button>
<div class="nav-group__menu" id="nav-getstarted">
<a href="/getting-started.html" class="active" aria-current="page">Quickstart</a>
<a href="/guides/">Guides</a>
<a href="/documents.html">Documents</a>
</div>
</div>
<div class="nav-group">
<button type="button" class="nav-group__btn" aria-expanded="false" aria-haspopup="true" aria-controls="nav-company">About Us</button>
<div class="nav-group__menu" id="nav-company">
<a href="/about.html">About</a>
<a href="/status.html">Project status</a>
<a href="/licensing.html">Licensing</a>
<a href="/contact.html">Contact</a>
<a href="/sponsor.html">Sponsor</a>
</div>
</div>
<a class="btn btn-ghost" href="/pypi.html">PyPI<svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 3l8 4.5l0 9l-8 4.5l-8 -4.5l0 -9l8 -4.5"/><path d="M12 12l8 -4.5"/><path d="M12 12l0 9"/><path d="M12 12l-8 -4.5"/><path d="M16 5.25l-8 4.5"/></svg></a>
<a class="btn btn-ghost" href="https://github.com/MEFORORG/MessageFoundry" target="_blank" rel="noopener">GitHub ↗</a>
</nav>
</div>
</header>
<main id="main">
<section class="section section--dark section--tight">
<div class="container center">
<span class="eyebrow">Get started</span>
<h1 style="max-width:20ch;margin-inline:auto">From install to your first routed message</h1>
<p class="lead">MessageFoundry installs from <b>PyPI</b> with a single <code>pip install messagefoundry</code> — a signed, versioned release you can verify, not a moving source checkout — and runs locally on <b>Python 3.14+</b>. Once it's running, you can build interfaces two ways: with <b>guided wizards</b> in the VS Code extension and admin console, or in <b>plain Python</b> for full control. It starts zero-config on SQLite; point it at PostgreSQL or SQL Server for production.</p>
<div class="btn-row center" style="margin-top:24px">
<a class="btn btn-ghost" href="/documents.html">Browse the documents →</a>
<a class="btn btn-ghost" href="/guides/">All guides →</a>
<a class="btn btn-ghost" href="/hl7-over-mllp/">HL7 over MLLP →</a>
<a class="btn btn-ghost" href="/build-an-hl7-interface/">Build an interface →</a>
</div>
</div>
</section>
<section class="section">
<div class="container" style="max-width:860px">
<div class="callout" style="margin-bottom:22px;background:rgba(245,158,11,.07);border-color:rgba(245,158,11,.28)">
<p><strong>Start in a sandbox — and tell us what happens.</strong> MessageFoundry started in May 2026 and is Early Access, beta-level software under fast development. The best way to use it right now is in a <b>sandboxed, non-production environment</b> with synthetic data: install it, wire up the interface shapes you actually run, and push them until something breaks. That's exactly the feedback that steers the project — and we're actively looking for users and organizations willing to do it. <a href="/status.html">Where the project stands →</a></p>
<p style="margin-top:12px">Taking it further than a sandbox? The <a href="https://github.com/MEFORORG/MessageFoundry/blob/main/docs/EARLY-ADOPTER-GUIDE.md" target="_blank" rel="noopener">Early-Adopter Installation & Rollout Guide ↗</a> is the playbook for doing it safely — prerequisites, honest limitations, capacity testing on your own hardware, backup/restore, and a staged rollout with go/no-go gates.</p>
</div>
<h2 class="vh">Quickstart steps</h2>
<div class="steps">
<div class="step">
<h3>Install</h3>
<p>Create a virtual environment and install MessageFoundry from <a href="/pypi.html">PyPI</a> — a signed, versioned release. <a href="/security.html">How releases are signed & attested →</a></p>
<div class="code-card">
<div class="code-card__bar"><i></i><i></i><i></i><span class="code-card__name">terminal</span></div>
<pre class="code"><span class="c"># virtual environment</span>
python -m venv .venv
<span class="c"># macOS / Linux: . .venv/bin/activate</span>
<span class="c"># Windows (PS): .venv\Scripts\Activate.ps1</span>
<span class="c"># install from PyPI</span>
pip install messagefoundry</pre>
</div>
<p style="margin-top:14px">The sample-driven steps below use config and messages from the repository, so clone it alongside to follow along:</p>
<div class="code-card">
<div class="code-card__bar"><i></i><i></i><i></i><span class="code-card__name">terminal</span></div>
<pre class="code">git clone https://github.com/MEFORORG/MessageFoundry.git
<span class="k">cd</span> MessageFoundry</pre>
</div>
</div>
<div class="step">
<h3>Run the engine</h3>
<p>Load the sample config, open the store, and serve the localhost API on <code>127.0.0.1:8765</code>.</p>
<div class="code-card">
<div class="code-card__bar"><i></i><i></i><i></i><span class="code-card__name">terminal</span></div>
<pre class="code">python -m messagefoundry serve --config samples/config --db messagefoundry.db
<span class="c"># API on http://127.0.0.1:8765</span>
<span class="c"># GET /connections GET /messages GET /stats WS /ws/stats</span></pre>
</div>
</div>
<div class="step">
<h3>Send a test message</h3>
<p>The sample config's <code>IB_Test_ADT</code> listens for MLLP on port <code>2575</code>. Send it an ADT and watch it route.</p>
<div class="code-card">
<div class="code-card__bar"><i></i><i></i><i></i><span class="code-card__name">terminal</span></div>
<pre class="code">python samples/send_mllp.py samples/messages/adt_a01.hl7
<span class="c"># A01/A04/A08 → archived to ./out/adt/<MSH-10>.hl7</span>
<span class="c"># other events → logged FILTERED; non-ADT → logged UNROUTED</span></pre>
</div>
</div>
<div class="step">
<h3>Open the web console</h3>
<p>The operator GUI runs in your browser, served by the engine itself — dashboards, message search and browse, parse-tree viewer, and one-click replay. Nothing to install on each workstation, and it's on by default.</p>
<div class="code-card">
<div class="code-card__bar"><i></i><i></i><i></i><span class="code-card__name">terminal</span></div>
<pre class="code">pip install messagefoundry-webconsole
<span class="c"># restart the engine, then open http://127.0.0.1:8765/ui</span></pre>
</div>
</div>
<div class="step">
<h3>Author your own route</h3>
<p>Prefer wizards? The VS Code extension's <b>New Connection</b> and <b>New Route</b> flows generate this for you. Or, if you prefer code, drop a Python module into your config directory — name an inbound and outbound Connection, then wire a Router and Handler by name:</p>
<div class="code-card">
<div class="code-card__bar"><i></i><i></i><i></i><span class="code-card__name">config/IB_Lab_ORU.py</span></div>
<pre class="code"><span class="k">from</span> messagefoundry <span class="k">import</span> MLLP, Send, inbound, outbound, router, handler
<span class="f">inbound</span>(<span class="s">"IB_Lab_ORU"</span>, <span class="f">MLLP</span>(port=<span class="n">2580</span>), router=<span class="s">"oru_router"</span>)
<span class="f">outbound</span>(<span class="s">"OB_EHR_ORU"</span>, <span class="f">MLLP</span>(host=<span class="s">"10.0.0.21"</span>, port=<span class="n">6661</span>))
<span class="d">@router</span>(<span class="s">"oru_router"</span>)
<span class="k">def</span> <span class="f">route</span>(msg):
<span class="k">if</span> msg[<span class="s">"MSH-9.1"</span>] != <span class="s">"ORU"</span>:
<span class="k">return</span> [] <span class="c"># UNROUTED</span>
<span class="k">return</span> [<span class="s">"to_ehr"</span>]
<span class="d">@handler</span>(<span class="s">"to_ehr"</span>)
<span class="k">def</span> <span class="f">to_ehr</span>(msg):
<span class="k">if</span> msg[<span class="s">"OBR-25"</span>] == <span class="s">"X"</span>: <span class="c"># drop corrected-in-error</span>
<span class="k">return</span> <span class="n">None</span> <span class="c"># FILTERED</span>
<span class="k">return</span> <span class="f">Send</span>(<span class="s">"OB_EHR_ORU"</span>, msg)</pre>
</div>
<p style="margin-top:14px">Validate it before it ships with the commit gate:</p>
<div class="code-card">
<div class="code-card__bar"><i></i><i></i><i></i><span class="code-card__name">terminal</span></div>
<pre class="code">python -m messagefoundry check --config samples/config</pre>
</div>
</div>
</div>
</div>
</section>
<!-- faq -->
<section class="section">
<div class="container">
<div class="center" style="margin-bottom:28px"><span class="eyebrow">FAQ</span><h2>Frequently asked questions</h2></div>
<div class="faq">
<div class="faq-item"><h3>What do I need to run MessageFoundry?</h3><p>Python 3.14 or newer on Windows, Linux, or macOS. MessageFoundry installs from PyPI with pip and starts zero-config on a built-in SQLite store, so you can run it on a laptop; for production it also supports PostgreSQL and SQL Server.</p></div>
<div class="faq-item"><h3>How do I install MessageFoundry?</h3><p>Create a virtual environment and run pip install messagefoundry, then start the engine pointed at a config directory and a store database. The quickstart walks through receiving your first HL7 v2 message over MLLP.</p></div>
<div class="faq-item"><h3>Do I have to write code to build an interface?</h3><p>No. You can set interfaces up with guided wizards in the VS Code extension and drop into plain Python whenever you need full control — either way the result is readable configuration you version-control.</p></div>
<div class="faq-item"><h3>Which databases does MessageFoundry support?</h3><p>SQLite out of the box for zero-config local runs, and PostgreSQL or SQL Server for production scale-out and high availability.</p></div>
</div>
</div>
</section>
</main>
<footer class="site-footer">
<div class="container">
<div class="footer-grid">
<div class="footer-brand">
<a class="brand" href="/" aria-label="MessageFoundry home">
<img class="brand-mark" src="/assets/img/logo.svg" alt="" width="28" height="28">
<span class="brand-name">Message<span class="brand-accent">Foundry</span><span class="brand-tm">™</span></span>
</a>
<p class="footer-tagline"><b>More</b> Than an HL7 Interface Engine</p>
<p>Open-source healthcare interface engine — secure by default, built to recognized standards, connecting a wide range of protocols and message types.</p>
<div class="badge-row" style="margin-top:16px">
<span class="badge">Open source</span>
<span class="badge">No lock-in</span>
<span class="badge">Self-hosted</span>
</div>
</div>
<div class="footer-col">
<h4>Product</h4>
<a href="/overview.html">Overview</a>
<a href="/features.html">Features</a>
<a href="/architecture.html">Architecture</a>
<a href="/reliability.html">Reliability</a>
<a href="/dicom.html">DICOM</a>
<a href="/security.html">Security & PHI</a>
<a href="/documents.html">Documents</a>
</div>
<div class="footer-col">
<h4>Tools</h4>
<a href="/tools.html">Tools</a>
<a href="/editor.html">Editor</a>
<a href="/console.html">Console</a>
<a href="/ai.html">AI assist</a>
</div>
<div class="footer-col">
<h4>Get started</h4>
<a href="/getting-started.html">Quickstart</a>
<a href="/guides/">Guides</a>
<a href="/comparison.html">Comparison</a>
</div>
<div class="footer-col">
<h4>Project</h4>
<a href="/status.html">Project status</a>
<a href="https://github.com/MEFORORG/MessageFoundry" target="_blank" rel="noopener">GitHub</a>
<a href="https://github.com/MEFORORG/MessageFoundry/issues" target="_blank" rel="noopener">Issues</a>
<a href="/contact.html">Contact</a>
<a href="/licensing.html">License</a>
<a href="/about.html">About</a>
<a href="/sponsor.html">Sponsor</a>
</div>
</div>
<div class="footer-bottom">
<span>© 2026 MEFOR-ORG, a non-profit — this website and its content, all rights reserved. The MessageFoundry engine is separately open source, licensed under AGPL-3.0-or-later.</span>
<span>MessageFoundry and the MessageFoundry word mark are trademarks of MEFOR-ORG. Mirth Connect, Cloverleaf, Rhapsody, Corepoint, and Ensemble are trademarks of their respective owners; MessageFoundry is independent and unaffiliated.</span>
</div>
</div>
</footer>
<script src="/assets/js/nav.js" defer></script>
</body>
</html>