MONARC Local Builder

This repository packages a Docker-based local MONARC distribution that replaces the legacy VirtualBox OVA workflow with pre-built launchers for:

• Windows (.exe)
• macOS (.app packaging can wrap the built binary)
• Linux Ubuntu (native executable)

Goal

Ship each MONARC release with a lightweight local launcher that:

• validates Docker availability
• pulls the release images
• starts/stops a simplified Docker Compose stack
• stores user data in a dedicated local folder
• provides backup and restore commands
• runs update + migration flow for new releases

Repository Layout

• launcher/: Go-based monarc-local CLI launcher
• compose/: Docker Compose template consumed by launcher
• scripts/: release build scripts
• .github/workflows/: CI pipeline to build release artifacts
• docs/: architecture and rollout guidance

Distribution

For publishing, vm.monarc.lu is fine as a download host if it is treated as a versioned release repository rather than a single mutable download folder.

Recommended release layout:

• publish one directory per release, for example https://vm.monarc.lu/monarc-local/v1.2.3/
• keep direct download links for each platform artifact
• publish a SHA256SUMS file next to the packages
• keep old releases available instead of replacing files in place
• link the release page or release notes from the README
• publish notarized macOS artifacts only; unsigned macOS zips will trigger Gatekeeper warnings

If you already use GitHub, the cleanest setup is usually:

• GitHub Releases as the canonical release index and changelog
• vm.monarc.lu as the stable download mirror or public landing page
• the README pointing users to the current release and the per-OS install instructions below

Developer Quick Start

1. Install Docker Desktop (Windows/macOS) or Docker Engine + Compose plugin (Linux).
2. Copy compose/.env.example to compose/.env and set your MONARC image/version.
3. Adjust service definitions in compose/docker-compose.release.yml (or compose/docker-compose.stage.yml) as needed.
4. Build launcher (dist/ is created by this step):

make build

If local go is missing, the build script automatically falls back to a Dockerized Go toolchain.

To create distributable packages as well, run:

make package

5. Run:

./dist/linux-amd64/monarc-local doctor
./dist/linux-amd64/monarc-local up --version vX.Y.Z
./dist/linux-amd64/monarc-local logs --service monarc-frontoffice --follow
./dist/linux-amd64/monarc-local open

# Linux ARM64
./dist/linux-arm64/monarc-local doctor

# Stage stack (temporary)
MONARC_COMPOSE_FILE=./dist/linux-amd64/compose/docker-compose.stage.yml \
  ./dist/linux-amd64/monarc-local up --version stage

If your .env is not in the same directory as the selected compose file, set MONARC_ENV_FILE=/path/to/.env.

End-User Installation And Usage

These steps are for people using the packaged applications from dist/packages rather than building from source.

Before first run on any OS:

1. Install Docker and make sure it is running.
2. Download the package that matches your operating system and CPU architecture.
3. Start the launcher once.
4. Open Config and review the generated .env file.
5. Set at least MONARC_FO_VERSION and MONARC_STATS_VERSION to a real release tag instead of vX.Y.Z.
6. Adjust DB settings, language settings, and any MONARC-specific values you need.
7. Save the config, then use Start MONARC.

Default login after the stack is up:

• admin@admin.localhost
• admin

Windows

Before installing:

• Install Docker Desktop for Windows.
• Use the WSL 2 backend.
• Ensure WSL 2 is installed and updated; Docker currently recommends WSL version 2.1.5 or later, ideally the latest available version.
• Ensure hardware virtualization is enabled in BIOS/UEFI.
• Start Docker Desktop once and wait until Docker shows that the engine is running.

Recommended preparation:

wsl --install
wsl --update

Package install:

1. Download monarc-local-windows-amd64.zip.
2. Extract it to a normal writable folder such as C:\Users\<you>\Documents\monarc-local\.
3. Start Monarc Local.bat for the GUI, or run monarc-local.exe in a terminal for CLI usage.

Windows notes:

• The launcher stores editable config in %LOCALAPPDATA%\MonarcLocal\compose\.env.
• MONARC data is stored under %LOCALAPPDATA%\MonarcLocal\.
• If Docker Desktop is installed by an administrator for another account, the user may need access to the docker-users group.

macOS

Before installing:

• Install Docker Desktop for Mac for the correct CPU type: Apple silicon or Intel.
• Start Docker Desktop once and wait until it is fully running.
• Keep Docker Desktop updated; Docker supports the current macOS major release and the previous two major releases.

Package install:

1. Download the matching package: monarc-local-darwin-arm64.zip for Apple silicon, or monarc-local-darwin-amd64.zip for Intel.
2. Extract the archive.
3. Open Monarc Local.app.

macOS notes:

• The launcher stores editable config in ~/.monarc-local/compose/.env.
• MONARC data is stored under ~/.monarc-local/.
• Release artifacts should be signed and notarized; otherwise macOS may report the app as damaged or block it on first launch.

Avoiding the misleading macOS "app is damaged" error:

• Best fix for published releases: distribute a signed and notarized macOS package.
• If you are testing an internal or unsigned build downloaded from a browser, macOS may add the com.apple.quarantine attribute to the extracted app and show a misleading "is damaged and can't be opened" message.
• If the archive came from a trusted MONARC source, remove the quarantine attribute from the extracted app before opening it by running in the terminal app:

/usr/bin/xattr -dr com.apple.quarantine "/path/to/Monarc Local.app"

• After removing quarantine, start Monarc Local.app again.
• Do not recommend this workaround for untrusted downloads; for public releases, the proper fix is notarization.

Linux

Before installing:

• Install Docker Engine and the Docker Compose plugin.
• Add your user to the docker group if you want to run Docker without sudo.
• Install python3 with Tk support if you want the GUI launcher.

Typical Ubuntu preparation:

sudo apt-get update
sudo apt-get install -y python3 python3-tk
sudo usermod -aG docker "$USER"

Install Docker Engine and the Compose plugin from Docker's official Ubuntu repository instructions first, then log out and log back in after changing the docker group.

Package install:

• .deb:

sudo dpkg -i monarc-local-linux-amd64.deb

• portable archive:

tar -xzf monarc-local-linux-amd64.tar.gz
cd monarc-local-linux-amd64
./monarc-local-gui.sh

Linux notes:

• The .deb installs files under /opt/monarc-local and adds monarc-local and monarc-local-gui into /usr/bin.
• The launcher stores editable config in ~/.monarc-local/compose/.env.
• MONARC data is stored under ~/.monarc-local/.

Daily Usage

GUI actions:

• Start MONARC: pull images and start the stack
• Update MONARC: pull newer images, restart the stack, and run the migration command
• Open In Browser: open the configured MONARC URL
• Display Status: show container status
• Display Logs: show recent frontoffice logs
• Edit Config: open the user .env file
• Help: show CLI help text
• Stop MONARC: stop the stack

Equivalent CLI commands:

monarc-local doctor
monarc-local up
monarc-local status
monarc-local logs --service monarc-frontoffice --tail 200
monarc-local open
monarc-local update
monarc-local down

Updating Installed Packages

Updating MONARC itself:

monarc-local update

Updating the launcher package:

• Windows: download the new zip, extract it, and replace the previous extracted folder.
• macOS: download the new macOS artifact and replace the previous app bundle.
• Linux .deb: install the newer .deb over the existing one with sudo dpkg -i ....
• Linux .tar.gz: extract the new archive and start using the new extracted folder.

Reinstalling the launcher package does not remove the user config or MONARC data directories unless you delete them manually.

Launcher Commands

• doctor: validate docker + compose + compose file
• status: show stack status
• up: pull images and start stack
• down: stop stack
• update: pull new FrontOffice/stats versions, restart stack, run migration hook
• logs: show compose logs (all services or specific service)
• open: open MONARC URL in browser
• backup: archive local data folder into .tar.gz
• restore: restore archived data folder

Run monarc-local help for options.

Notes

• Default compose is compose/docker-compose.release.yml.
• Optional stage compose is compose/docker-compose.stage.yml.
• Configure image tags, DB settings, and language settings in .env (DB*, STATS_DB*, and MONARC_*LANGUAGE* variables).
• MONARC_LANGUAGES uses code:index:label entries separated by semicolons. The index controls translated DB fields such as label1 / name1, label2 / name2, and so on.
• MONARC_ACTIVE_LANGUAGES selects which configured language codes are available in the UI, and MONARC_DEFAULT_LANGUAGE_INDEX selects the default one written to config/autoload/languages.local.php.
• If you previously started an older stack definition, run monarc-local down and then docker compose ... down -v once to reset old DB volumes before first start with the new compose.
• macOS packaging now creates a CLI-oriented .app; signed and notarized release artifacts avoid the Gatekeeper "is damaged and can't be opened" warning that appears on downloaded unsigned .app bundles.
• Backup/restore currently archives the launcher data directory; production releases may switch to service-aware dumps if needed.

Packaging

make package first builds all launcher binaries, then creates distributable artifacts in dist/packages:

• monarc-local-linux-amd64.tar.gz
• monarc-local-linux-amd64.deb when dpkg-deb is available
• monarc-local-linux-arm64.tar.gz
• monarc-local-linux-arm64.deb when dpkg-deb is available
• monarc-local-darwin-amd64.zip
• monarc-local-darwin-arm64.zip
• monarc-local-windows-amd64.zip

The macOS package is a native .app wrapper around the launcher binary and bundled compose files. Double-clicking the app opens a centered control window, exposes the same actions in the macOS menu bar, and stores its editable config at ~/.monarc-local/compose/.env by default. Native macOS packaging is produced when scripts/package-macos.sh runs on macOS; CI builds those artifacts on a macOS runner.

If you run packaging on macOS, you can set:

• MONARC_CODESIGN_IDENTITY to sign the app bundle with a Developer ID Application certificate.
• MONARC_NOTARY_KEYCHAIN_PROFILE to submit the signed archive through xcrun notarytool, staple the accepted ticket onto the .app, and then build the final release zip.
• MONARC_NOTARY_KEYCHAIN when the notary profile is stored in a non-default keychain.
• MONARC_CREATE_DMG=1 to also emit a .dmg.

The GitHub Actions macOS release job now uses the same flow when these repository secrets are present: MONARC_MACOS_CERTIFICATE_P12_BASE64, MONARC_MACOS_CERTIFICATE_PASSWORD, MONARC_MACOS_CODESIGN_IDENTITY, MONARC_MACOS_KEYCHAIN_PASSWORD, MONARC_MACOS_NOTARY_APPLE_ID, MONARC_MACOS_NOTARY_TEAM_ID, and MONARC_MACOS_NOTARY_APP_PASSWORD. If those secrets are omitted, the workflow still produces unsigned macOS artifacts, and downloaded apps may still trigger Gatekeeper on first launch.

The Windows package now includes a GUI launcher alongside monarc-local.exe. Double-click Monarc Local.bat to start a WinForms control window plus tray menu, or run monarc-local.exe directly for CLI usage.

The Linux package now includes both amd64 and arm64 builds, each with a desktop/window wrapper as monarc-local-gui.sh plus Monarc Local.desktop in the portable archive and monarc-local.desktop in the .deb. The desktop launcher uses Python tkinter, so Linux systems need python3 with Tk support installed. CLI usage with monarc-local is still available in both the tarball and the .deb.

The packaged compose bundle also includes a local frontoffice entrypoint wrapper that keeps the upstream initialization flow but skips the initial admin seed when admin@admin.localhost already exists. This avoids repeated first-run crashes on partially initialized databases.

Use MONARC_PACKAGE_VERSION to override the package version metadata. The GitHub Actions release workflow sets this automatically from the pushed tag name and uploads both dist/packages and the raw dist/ output.