docs: correct the Administrator documentation and restructure getting started - #13
docs: correct the Administrator documentation and restructure getting started#13pacmano1 wants to merge 2 commits into
Conversation
… started The Administrator documentation describes a UI that does not match the product, and getting started never covered running the server. Plugin guide ------------ Extensions was documented as Settings > Extensions with an Uninstall button beside each plugin and an Enabled toggle. None of that exists. Extensions is a task in the Engine pane (Frame.java:1020-1030), the Status column is read-only (ExtensionManagerPanel.java:43, and the two tables at :514 and :572), and Enable, Disable and Uninstall are menu items under Extension Tasks (Frame.java:1235-1243). f0f8788 corrected two of the navigation references and missed five. Startup troubleshooting pointed at logs/oie-server.log, which does not exist. log4j2.properties:17 writes logs/mirth.log. The guide never said where a plugin's own configuration appears. An extension implementing SettingsPanelPlugin adds a tab under Engine > Settings (SettingsPane.java:54 and :68), which is likely how Settings and Extensions were conflated in the first place. Getting started --------------- Split into Installation, Server Process Management and Accessing the Administrator, which is the order these happen in. The old page gave a foreground "sudo oieserver" command, macOS-only, and never mentioned the service. It also implied a fresh install is running. The installer registers the service with automatic startup but does not start it, so nothing listens until someone starts it or reboots. Server Process Management covers all three platforms. The registered name differs on each: "Open Integration Engine Service" on Windows, the oieservice unit on Linux, com.oie.oieservice on macOS (oie-installer-config.install4j:427). oieserver stays as the foreground option, which also writes logs/mirth.log rather than replacing it. Also on those pages: the with-JRE and without-JRE builds explained rather than listed, the tar.gz and zip archives named up front, the headless console install documented, the unsigned installers set against the signed jars (signSetupJars in server/build.gradle), the privileged service account recorded, and the fact that every authenticated account is an administrator (DefaultAuthorizationController.isUserAuthorized returns true at :45, doesUserHaveChannelRestrictions returns false at :53). MariaDB was listed as a backend in its own right. mirth.properties:77 accepts derby, mysql, postgres, oracle and sqlserver, and MariaDB appears nowhere in the engine source, so it is folded into the MySQL line item. Version numbers are out of the startup log sample, which showed 4.5.2. Ten of the fourteen screenshots were pictures of the installer wizard, a Spotlight search, a login form and a progress bar. An eleventh file was already orphaned. A meta-refresh stub with noindex keeps /engine/getting_started.html alive, since it is published. Site ---- Links to index pages built to .html files that do not exist, so /engine.html and /examples.html both return 404. The SPA hides it from a browser, but crawlers and link checkers see the status code. Index pages need a trailing slash. Launchers is in the top nav, Launchers and Examples were single-entry collapsible groups and are now plain links, outline is [2, 3], and sidebarFromRemote() is removed; it read a docs.json that does not exist and was never called. Added Launcher after Ballista. The JNLP Launcher Project was described as cross-platform and has never shipped a macOS build, so its entry now says what it ships; the same unearned rating came off Ballista. Signed-off-by: Finnegan's Owner <44065187+pacmano1@users.noreply.github.com>
mgaffigan
left a comment
mgaffigan
left a comment
There was a problem hiding this comment.
I think it moves us in the right direction with/without further edits.
| ::: info | ||
| If you use a new instance, the default credentials are: | ||
|
|
||
| * login: **admin** | ||
| * password: **admin** | ||
| ::: |
There was a problem hiding this comment.
Should be updated to reflect generated password.
| ::: warning Every account is an administrator | ||
| The engine ships with an authorization controller that approves every operation for any authenticated user. `DefaultAuthorizationController.isUserAuthorized` returns `true` unconditionally and `doesUserHaveChannelRestrictions` returns `false`, so there are no roles and no per-channel restrictions out of the box. Any account you create can edit and deploy channels, read message content, and change server settings. |
There was a problem hiding this comment.
This is a bit densely worded. Maybe:
All users are administrators by default, with privilege to write and execute channel scripts on the server. Grant access only to users who should be able to author and execute scripts, or install a RBAC plugin to create low-privileged roles. [Link to RBAC plugin page]
The RBAC link to diridium seems fine as written
|
|
||
| The release also publishes `oie_unix_<version>.tar.gz` and `oie_windows-<arch>_<version>.zip` for a manual install. Unpack the archive wherever you want it and run `oieserver` from the extracted directory. | ||
|
|
||
| Nothing is registered with the service manager and nothing starts on boot, so you have to wire it into systemd, launchd or the Windows service manager yourself. Take this route when you want that control, or when you cannot give an installer administrative rights. |
There was a problem hiding this comment.
This might have a comment on directory permissions - configs, secrets, and appdata need to be configured for secrets. Plugins and other executable bins have to be secured for escalation of privilege.
|
|
||
| # Server Process Management | ||
|
|
||
| The installer registers OIE as a native service and sets it to start on boot, but it does not start it during installation. After a fresh install, start it once by hand or reboot the machine. |
There was a problem hiding this comment.
But why though? This sounds like a bug in the installer.
| The installer registers OIE as a native service and sets it to start on boot, but it does not start it during installation. After a fresh install, start it once by hand or reboot the machine. | ||
|
|
||
| ::: warning The service runs as a privileged account | ||
| No dedicated service account is created. The service runs as root on Linux and macOS, and as the local system account on Windows. |
There was a problem hiding this comment.
Yikes! We should change that default. NT Service\Open Intengration Engine is trivial on windows.
There was a problem hiding this comment.
There is a typo in Mitch's comment, but the important bit is that the part that follows NT Service\ needs to match the name of the service exactly.
| ``` | ||
| ```powershell [Windows] | ||
| cd <installation directory> | ||
| .\oieserver.ps1 |
There was a problem hiding this comment.
I think @tonygermano is arguing for this to be removed. Is there an install4j shim to start from instead?
There was a problem hiding this comment.
It should be oieserver.exe to match the Linux command calling the install4j launcher.
The confusion of there being two launchers for Windows is why I was arguing for the powershell script to be removed.
Pin the default credentials to 4.6.0 and note that a future release generates the password on first boot. That change is on main but not in any release, so an installer today still ships admin/admin. Rewrite the administrator warning in mgaffigan's words. Mine led with two method names and a return value, which proves the claim without explaining why it matters. Widen the promised securing-the-install guide to cover permissions on conf, appdata and the executable directories, not just the service account. Signed-off-by: Finnegan's Owner <44065187+pacmano1@users.noreply.github.com>
|
Generated password. Pinned to 4.6.0 with a note that a future release generates it. Density. Used your wording. Directory permissions. Out of scope here. The guide the page promises now covers Service not started. You and I are discussing this out of band. Local system. We have to sort out network access permission with whatever becomes the standard here, perhaps a named local or domain account. Worth more discussion for future releases.
|
mgaffigan
left a comment
mgaffigan
left a comment
There was a problem hiding this comment.
Still looks better than before, but much of this speaks to installer bugs. Also: setting privileges on directories for a .tar.gz manual install is required.
3 participants
This is the first of two PRs. The second ports my unofficial OIE wiki into this site, around 37 pages.
Rendered preview of this branch: https://pacmano1.github.io/docs-website/
The Administrator documentation does not match the product, and getting started never covered running the server.
Plugin guide. The Extensions section described a screen that does not exist. f0f8788 fixed two of the navigation references and missed the rest. The guide also now says where a plugin's configuration appears.
Getting started. Split into Installation, Server Process Management and Accessing the Administrator. The page said a fresh install is already running. The installer registers the service with automatic startup but does not start it, so nothing is listening until someone starts it or reboots. Server Process Management covers all three platforms and keeps
oieserveras the foreground option. Ten of the fourteen screenshots were pictures of the installer wizard and are gone. A meta-refresh stub keeps/engine/getting_started.htmlalive, since it is published.Site. Links to index pages build to
.htmlfiles that do not exist, so/engine.htmland/examples.htmlboth 404 today. The SPA hides this from a browser, but crawlers and link checkers see the status code.I added my Launcher after Ballista. The JNLP entry claimed cross-platform and that project has never shipped a macOS build.
bun run docs:buildpasses, every internal link resolves.