docs: correct the Administrator documentation and restructure getting started (#13)

* docs: correct the Administrator documentation and restructure getting 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>

* docs: address review feedback

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>

* docs: show both Windows foreground launchers

The foreground section listed only oieserver.ps1, under a tab labelled
PowerShell, so a reader at a command prompt had no working instruction.
Windows installs also carry oieserver.exe, the install4j console launcher
(tools/install4j/oie-installer-config.install4j, launcher id 39, included
in every Windows media set). Show both, each under the prompt it belongs
to.

Signed-off-by: Finnegan's Owner <44065187+pacmano1@users.noreply.github.com>

---------

Signed-off-by: Finnegan's Owner <44065187+pacmano1@users.noreply.github.com>

Author: pacmano1

.vitepress/config.mts

@@ -1,15 +1,4 @@
 import {defineConfig} from 'vitepress'
-import fs from 'node:fs'
-import path from 'node:path'
-
-const SUBMODULES_ROOT = path.resolve(__dirname, '../docs')
-
-// Generate sidebar items from /engine
-function sidebarFromRemote(remote: string) {
-  const filePath = path.join(SUBMODULES_ROOT, remote, 'docs.json')
-  const data = fs.readFileSync(filePath, 'utf-8')
-  return JSON.parse(data)
-}
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
@@ -21,8 +10,9 @@ export default defineConfig({
     // https://vitepress.dev/reference/default-theme-config
     nav: [
       { text: 'Home', link: '/' },
-      { text: 'Documentation', link: '/engine' },
-      { text: 'Examples', link: '/examples' },
+      { text: 'Documentation', link: '/engine/' },
+      { text: 'Launchers', link: '/launchers/' },
+      { text: 'Examples', link: '/examples/' },
     ],
 
     logo: 'https://raw.githubusercontent.com/OpenIntegrationEngine/governance/refs/heads/main/branding/logos/oie_logo_only_white_background.svg',
@@ -38,31 +28,23 @@ export default defineConfig({
 
     lastUpdated: true,
 
+    outline: [2, 3],
+
     sidebar: [
       {
         text: 'Engine',
         collapsed: false,
         items: [
-          { text: 'Overview', link: 'engine' },
-          { text: 'Getting started', link: 'engine/getting_started' },
-          { text: 'Plugin Guide', link: 'engine/plugins' },
-          { text: 'Contributing', link: 'engine/contributing' },
-        ]
-      },
-      {
-        text: 'Launchers',
-        collapsed: false,
-        items: [
-          { text: 'Overview', link: 'launchers' },
-        ]
-      },
-      {
-        text: 'Examples',
-        collapsed: false,
-        items: [
-          { text: 'Overview', link: 'examples' },
+          { text: 'Overview', link: '/engine/' },
+          { text: 'Installation', link: '/engine/installation' },
+          { text: 'Server Process Management', link: '/engine/server_process_management' },
+          { text: 'Accessing the Administrator', link: '/engine/accessing_the_administrator' },
+          { text: 'Plugin Guide', link: '/engine/plugins' },
+          { text: 'Contributing', link: '/engine/contributing' },
         ]
       },
+      { text: 'Launchers', link: '/launchers/' },
+      { text: 'Examples', link: '/examples/' },
     ],
 
     socialLinks: [

docs/engine/accessing_the_administrator.md

@@ -0,0 +1,77 @@
+---
+title: Accessing the Administrator
+description: Reaching a running OIE server, choosing between the web and desktop administrators, and logging in
+---
+
+# Accessing the Administrator
+
+To verify that the OIE server is available, open a browser and enter the URL from the startup output, `https://<host>:8443/`. See [Server Process Management](./server_process_management.md) if it is not up yet.
+
+After accepting the self-signed certificate in your browser, you will see this page:
+
+![Open Integration Engine Server home Page indicating the service is available with launcher target url and button to explore the Client API](images/gs_web_browser_step_1.png)
+
+From here there are two ways to administer the engine: a browser, or the desktop Administrator.
+
+## Web administrator
+
+[Web Support](https://github.com/gibson9583/oie-web-support-plugin) is a community extension by Chris Gibson that installs a browser-based administrator into the engine's own web server. It works read/write against the same REST API as the desktop client, covering channel editing, deployment, and the message browser. It requires OIE 4.6.0.
+
+Install it as you would any other extension, described in the [plugin guide](./plugins.md), then restart the engine and open `https://<host>:8443/oie-webadmin/`. No launcher is involved.
+
+## Desktop Administrator
+
+The desktop Administrator is a Java application and needs a launcher to start it. Copy the Administrator Launcher URL from the page above, then use one of the launchers below. See [Launchers](/launchers/) for the full list.
+
+### Ballista
+
+[Ballista](https://github.com/kayyagari/ballista/releases) is an open-source Administrator launcher for Open Integration Engine built on Tauri.
+
+### Launcher
+
+[Launcher](https://github.com/diridium-com/launcher/releases) is a fork of Ballista, also built on Tauri and open source under MPL-2.0.
+
+### MCAL
+
+The original Mirth® Connect Administrator Launcher by NextGen Healthcare (MCAL) works with OIE. Here is how you can use it to launch the OIE Administrator client GUI application.
+
+Open MCAL. If it's the first launch, the left panel with connections is empty.
+
+![MCAL application window showing "no saved connections" in left panel](images/gs_mcal_step_1.png)
+
+To work better with OIE, choose `Bundled Java 17`
+
+And just click on `Launch` at the top right screen.
+
+You should see a progress bar that will load the files necessary to launch the Open Integration Engine client.
+
+## Logging in
+
+::: info
+On 4.6.0 a new instance starts with:
+
+* login: **admin**
+* password: **admin**
+
+A future release replaces this with a password generated on first boot.
+:::
+
+Enter your credentials and click `Login` when the login screen appears. After a brief loading screen, you will see the OIE dashboard.
+
+If this is your first login, you are prompted to change the default password.
+
+![Edit User screen requesting username, password, and optional demographic information](images/gs_oie_credential_update_step_1.png)
+
+Fill the information, and don't forget to set the `New Password` (2 times)
+
+And click on `Finish`
+
+![Application ready to use at the Dashboard screen showing no deployed channels and the server startup messages in the log section](images/gs_oie_dashboard.png)
+
+It's finished. Now you can start to use your OIE server.
+
+::: warning Every account is an administrator
+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 an RBAC plugin to create low-privileged roles.
+
+[Role Based Access Control](https://github.com/diridium-com/role-based-access-control) is a community extension that replaces the default authorization controller with roles and per-channel grants, and it works in both administrators.
+:::

docs/engine/getting_started.md

@@ -1,168 +1,13 @@
 ---
-title: Open Integration Engine getting started
-description: First step to install on Windows and macOS and proceed to the first launch
+title: Installation
+search: false
+head:
+  - - meta
+    - http-equiv: refresh
+      content: 0; url=/engine/installation.html
+  - - meta
+    - name: robots
+      content: noindex
 ---
 
-# Getting started
-
-To quickly start with Open Integration Engine™️, also called OIE™️ in this documentation, 
-you can use the different installers available on Windows, macOS, and Linux platforms.
-
-::: info
-
-All installers are available at the releases page on GitHub, see [GitHub Releases](https://github.com/OpenIntegrationEngine/engine/releases)
-
-The installers are available in 2 flavors:
-
-* With Java Runtime Environment (JRE) 
-* Without JRE
-:::
-
-## System requirements
-
-The OIE Server operates as a completely self-contained application and does not depend on any external application server.
-
-### Java requirements
-
-The Open Integration Engine requires Java 17+ to work.
-
-### Database requirements
-
-OIE uses an embedded Apache Derby database by default, which allows you to store configuration and messages, for the purpose of rapid deployment, development and testing.
-
-For production deployments, it is recommended to use only database versions currently receiving official security and maintenance support from their respective vendors. The following database engines are supported as backends:
-
-* PostgreSQL
-* MySQL
-* MariaDB
-* Oracle
-* SQL Server
-
-## Download and installation
-
-You can download the latest version of Open Integration Engine for your platform at this 
-[address](https://github.com/OpenIntegrationEngine/engine/releases/latest).
-
-### Windows
-
-::: info
-Add Screenshots for windows Installation
-
-Wizard screenshots are similar to macOS part
-:::
-
-### macOS
-
-Locate the downloaded .dmg file and double-click the file to mount it.
-
-A window will open showing the Open Integration Engine Installer. Double-click to launch the Installer Wizard.
-
-![Mac Finder window with arrow indicating Open Integration Engine Installer](images/gs_macos_installer-package.png)
-
-Click `Next` on the initial Setup screen to move to the License Screen.
-![Open Integration Engine Installer Setup window displaying welcome message with Next button highlighted](images/gs_macos_install_step_1.png)
-
-To continue you must accept this license by selecting `I accept the agreement` and then click on `Next`.
-
-![License Screen requesting the user read and accept the Mozilla Public License version 2.0](images/gs_macos_install_step_2.png)
-
-The next screen presents information about the current release. Click on `Next` to continue.
-
-![Information screen showing details of Open Integration Engine 4.5.2 Release](images/gs_macos_install_step_3.png)
-
-Choose a destination directory for the installation and click `Next` to start the installation. You can choose another folder if you do not want to install as a global package.
-
-::: warning
-If you use the default application folder, you will need to use the `sudo` command to launch the OIE server.
-:::
-
-![Select Destination Directory screen showing value of /Applications/OpenIntegrationEngine](images/gs_macos_install_step_4.png)
-
-![Installation screen showing progress extracting files and a cancel button](images/gs_macos_install_step_5.png)
-
-The last screen informs you that installation is complete. Click `Finish` to close the installer.
-
-![Completion screen prompting user to click Finish to exit Setup](images/gs_macos_install_step_6.png)
-
-Now, open a Terminal and start the OIE server
-
-```shell
-sudo /Applications/OpenIntegrationEngine/oieserver
-```
-
-During the first launch, the server initializes the database. If the server is launched correctly, you should see the following lines:
-
-```log
-INFO  2026-01-15 20:07:38.773 [Main Server Thread] com.mirth.connect.server.Mirth: Open Integration Engine 4.5.2 (Built on July 8, 2025) server successfully started.
-INFO  2026-01-15 20:07:38.776 [Main Server Thread] com.mirth.connect.server.Mirth: This product was developed by NextGen Healthcare (https://www.nextgen.com) and its contributors (c)2005-2024.
-INFO  2026-01-15 20:07:38.776 [Main Server Thread] com.mirth.connect.server.Mirth: Open Integration Engine contributors (c)2025.
-INFO  2026-01-15 20:07:38.777 [Main Server Thread] com.mirth.connect.server.Mirth: Running OpenJDK 64-Bit Server VM 17.0.15 on Mac OS X (15.7.3, aarch64), derby, with charset UTF-8.
-INFO  2026-01-15 20:07:38.778 [Main Server Thread] com.mirth.connect.server.Mirth: Web server running at http://192.168.1.X:8080/ and https://192.168.1.X:8443/
-```
-
-::: tip
-Please note these URLs, as we will need them later.
-:::
-
-## First launch
-
-To verify if the OIE server is available, open your web browser and enter the URL previously noted.
-
-After accepting the self-signed certificate in your browser, you will see this page:
-
-![Open Integration Engine Server home Page indicating the service is available with launcher target url and button to explore the Client API](images/gs_web_browser_step_1.png)
-
-Copy the Administrator Launcher URL.
-
-### Ballista
-
-[Ballista](https://github.com/kayyagari/ballista/releases) is an open-source Administrator launcher for Open Integration Engine built on Tauri.
-
-### MCAL
-
-The original Mirth® Connect Administrator Launcher by NextGen Healthcare (MCAL) works with OIE. Here is how you can use it to launch the OIE Administrator client GUI application.
-
-Go to the macOS Launcher and search Mirth, you will see this icon.
-
-![Search bar populated with "mirth" with result displaying Mirth Connect Administrator Launcher icon](images/gs_launcher_mcal.png)
-
-If it's the first launch, the left panel with connections is empty.
-
-![MCAL application window showing "no saved connections" in left panel](images/gs_mcal_step_1.png)
-
-To work better with OIE, choose `Bundled Java 17`
-
-And just click on `Launch` at the top right screen.
-
-You should see a progress bar that will load the files necessary to launch the Open Integration Engine client.
-
-## Logging in
-
-::: info
-If you use a new instance, the default credentials are:
-
-* login: **admin**
-* password: **admin**
-:::
-
-Enter your credentials and click `Login` when the login screen appears.
-
-![Open Integration Engine Login screen with server field pre-populated and blank username and password](images/gs_oie_login_step_1.png)
-
-Upon successful login, a brief loading screen will display.
-
-![An indeterminate progress bar with the caption, Please wait: Loading Extensions](images/gs_oie_login_step_2.png)
-
-After some time, you will see the OIE dashboard.
-
-Now it asks to change the default password if this is your first time logging in.
-
-![Edit User screen requesting username, password, and optional demographic information](images/gs_oie_credential_update_step_1.png)
-
-Fill the information, and don't forget to set the `New Password` (2 times)
-
-And click on `Finish`
-
-![Application ready to use at the Dashboard screen showing no deployed channels and the server startup messages in the log section](images/gs_oie_dashboard.png)
-
-It's finished. Now you can start to use your OIE server.
+This page is now [Installation](/engine/installation).