Operations Manual

This manual is intended for the person who installs and looks after the suite. How to use the tools and modules is explained by the help pages in the portal and in the tools themselves. It applies to version 0.4 (Stage 4). All scripts are located in the program folder under install.

Language of the scripts: The installation scripts write in English or German – by default in the language of the system (Windows: display language; macOS: preferred language of the signed-in user; Linux: LANGUAGE, LC_ALL, LC_MESSAGES, LANG). For one call, --lang en or --lang de (macOS, Linux) or -Sprache en (Windows) chooses the language; scripts that obtain administrator rights themselves pass it on. The command line of the suite, app/cli.php, writes German unless you add --lang en. The option names of all scripts are German (for example --probelauf = dry run, --aktualisieren = update) – type them exactly as shown.

This is an English translation of the German manual (handbuch.html); in case of doubt, the German version applies.

Quick start for beginners

Every step has a number and exactly one action. What you click or type is shown in “quotation marks” – exactly as it appears on the screen.

Which route is right for me?

What you need

• A current browser (Edge, Chrome, Firefox or Safari) and, for routes B and C, internet access during the installation – it downloads PHP, the programming language the suite runs on.
• Check your Windows version: Windows key + R, type “winver”, press Enter – the window “About Windows” shows the version. For route B you need the password of an administrator account.
• Check your macOS version: Apple menu (the apple symbol at the top left of the screen) › “About This Mac” – it shows, for example, “Version 14.7”; for route C the first number must be 12 or higher (Intel Mac or Apple silicon). With 10.15 or 11: under “System Preferences” › “Software Update”, check whether a newer version is available free of charge – otherwise use route A. (On macOS 13 and later: “System Settings” › “General” › “Software Update”.) For route C you need the password you use to sign in to your Mac. You do not need Homebrew or Xcode.
• Time: route A about 5 minutes, route B or C about 15 minutes.

Route A – Browser only

1. Download “mc4y-werkzeuge.zip”.
2. Unpack it: on Windows, right-click › “Extract All…” › “Extract”; on a Mac, double-click it in Finder (Safari often unpacks it by itself).
3. In the folder “MC4Y-Werkzeuge-…”, double-click “index.html”. You now see the page “MC4Y tools”.
4. Add a bookmark (Windows: Ctrl + D, Mac: cmd + D) and click a tool. “Save” (German: “Speichern”) stores your work as a file, “Open” (“Öffnen”) loads it again.

Route B – The suite on this Windows computer

1. Download “mc4y-suite.zip”. In Explorer (Windows key + E) › “Downloads”, right-click the file › “Properties”. If “Security” at the bottom says “This file came from another computer …”: tick “Unblock”, then “OK”.
2. Right-click the file › “Extract All…” › “Extract” and open the folder “MC4Y-Suite-…”.
3. Double-click “Installer-starten”. (Blue window “Windows protected your PC”: “More info” › “Run anyway”.) A black window opens – leave it open – and then, in the browser, “What would you like to set up?”.
4. Click “The suite on this Windows computer”, then “Next →”; at “New or update”, click “Next →” again.
5. “Storage locations”: next to “All locations on”, click a drive (if there is only one: “Drive C”), then “Next →”. “Tools”: leave everything selected, “Next →”.
6. “Prerequisites”: tick “I agree that these prerequisites will be downloaded and installed.”, then click “Install”. Answer the Windows prompt “Do you want to allow this app to make changes to your device?” with “Yes”.
7. Wait until “Installation complete.” appears (2 to 10 minutes), then click “Open suite” and create the first account. Finally, click “Close installer”.

Route C – The suite on this Mac

On a Mac, the safest way is with Terminal, a window for commands. You need only two commands. Copy: select and press cmd + C; paste: click into Terminal and press cmd + V; run: Return key. If Terminal asks for a password, no characters appear while you type – that is intended.

1. Download “mc4y-suite.zip” and double-click it in Finder › “Downloads” (unless Safari has already unpacked it). You now see the folder “MC4Y-Suite-…”. Leave the Finder window open.
2. Open Terminal: cmd + Space, type “Terminal”, press Return.
3. Type cd and a space, drag the folder “MC4Y-Suite-…” from Finder into the Terminal window, press Return. (If macOS asks for access to “Downloads”: “OK”.)
4. Paste this command and press Return:

   bash install/macos/installieren.command --lang en

   With --lang en, the script always writes in English, exactly as quoted here; without it, it uses the language of your Mac.
5. At “Password:”, type your Mac password (no characters are shown), then press Return.
6. At the data folder prompt (“Data folder [/Library/Application Support/MC4Y-Suite-Daten]:”), at “Set up the desktop taskbar for … as well? [Y/n]”, at “Start the taskbar automatically when you sign in to your Mac? [Y/n]” and at “Run the installation now? (Return = yes) [Y/n]”, just press Return each time (= yes).
7. Wait (1 to 5 minutes; PHP is downloaded and checked). At “Done. Address: http://127.0.0.1:8090/”, the browser opens – create the first account.
8. Then start the taskbar: cmd + Space, type “MC4Y”, choose “MC4Y Taskbar”, press Return – and sign it in with the same user name and password. Finally, at “Press Return to close …”, press Return in Terminal and close it with cmd + Q; the suite and the taskbar keep running.

Please do not start the files in the package by double-clicking them in Finder – macOS blocks that for files from the internet. Starting them in Terminal with “bash …” does not have this problem.

How to start the suite and the taskbar later

• Windows: Start menu › “MC4Y Productivity Suite” (opens the suite; on a computer set to German “MC4Y-Produktivitaetssuite”) or “MC4Y Taskleiste”; the suite is also on the desktop as a shortcut.
• Mac: The installation creates the programs “MC4Y Suite” (opens the suite in the browser) and “MC4Y Taskbar” with an icon. You find them in Launchpad (the icon with the coloured tiles in the Dock; on macOS 26 it is called “Apps”), via Spotlight (cmd + Space, type “MC4Y”, Return) and in the Finder under “Applications”. Tip: drag the icons into the Dock.
• Linux: applications menu or overview › “MC4Y Productivity Suite” or “MC4Y Taskbar”.
• Start at sign-in (taskbar): in the taskbar click 🔍, at the bottom “Settings” › box “Start when signing in to the computer” › “Save”. Windows: Windows Settings › Apps › Startup. Mac from macOS 13 also: System Settings › General › Login Items, section “Allow in the Background”. The suite itself always runs in the background.
• Do not confuse: the taskbar you switch on in the suite under “Your account” › “Appearance” belongs to the browser window and closes with it. The desktop taskbar (“MC4Y Taskbar”) is a program of its own and stays open until you quit it with ✕.

Creating the first account

1. On the page “Set up the suite”, enter “Organisation” (may stay empty), “Your name” and a “User name” without spaces.
2. Enter a “Password” of at least 10 characters and repeat it below it (“Repeat password”); keep it safe. On a server, also enter the “Setup code” that the installer showed.
3. Leave the tick box “Also add me to the group ‘All tools – full access’” ticked and click “Set up and sign in”.

How to check that it worked

1. Open http://127.0.0.1:8090/ in the browser: you see the sign-in page – also after restarting the computer.
2. In the suite, go to “Administration” › “System check”: most lines are green (yellow = recommendation, red = please fix).
3. “Administration” › “Backup” › “Back up now”, then click “Check” in the new row.

Common problems

Updating: download the new package and follow the same route again (Mac: bash install/macos/installieren.command --aktualisieren --lang en, then confirm “Run the update now? (Return = yes) [Y/n]” with Return – it also offers the desktop taskbar and creates the program “MC4Y Suite”); content, accounts and settings are kept. Removing: see section 16.

1. Structure and storage locations

The suite consists of three separate parts. Only the first is delivered over the network.

CMDB: The IT components of the “CMDB” module are stored in a separate database cmdb/cmdb.sqlite in the data folder – for the single-user suite on this computer, for the server suite on the server. They are recorded by hand, by importing existing lists (Excel/CSV, Active Directory, DHCP, Wireshark exports) or – on request – automatically via agents and a crawler (section “CMDB discovery”). The permission groups determine who may edit and import (module “CMDB”: Read, Read and write, Full access = may also delete permanently). The ITSM tool assigns incidents, problems and changes to components in the CMDB if the person has at least read access to the “CMDB” module; it only creates new components there with “Read and write”. The detail view of a component lists the associated tickets. Each component shows its origin (by hand, recorded in the ITSM tool, imported from Excel, CSV, Active Directory, DHCP or Wireshark, from a CMDB export) as well as when it was created and last changed. In addition, every component carries a classification (physical, software or abstract): components recorded by hand are pre-set from the category (e.g. Server → physical, “Software / service” → software, “Application / IT system” → abstract) and can be changed freely, while devices reported by agents or the crawler are automatically set to “physical” (software to “software”). The overview and the list can be filtered by origin and classification. For software, services and applications there are dedicated fields: version (each major version as its own component), deployment (local, on a server, internal or external cloud) as well as licence and maintenance costs; the list can also be filtered by deployment.

CMDB and 8EM Modeller: When an enterprise model is saved to the storage in the 8EM Modeller, the Modeller transfers its IT systems, technical architecture plans, platforms and IT components to the CMDB (origin “transferred from the 8EM Modeller”, status = phase of the life cycle). For this, the person saving needs at least “Read and write” in the “CMDB” module; the transfer can be switched off per model in the Modeller's input form (section “CMDB”) or per entry with “do not transfer this entry to the CMDB”. Details maintained in the CMDB are retained; the Modeller does not recreate components that have been moved to the recycle bin.

CMDB discovery (agents and crawler): Optionally, visibly installed programs fill the CMDB automatically – an agent on a device (Windows, Linux, Raspberry Pi, macOS, Android/Termux, Home Assistant) reports its inventory, a crawler scans the networks entered in the suite (IPv4/IPv6) and reports reachable devices – inventory only, no login attempts. You set this up in the “CMDB” module under the Discovery tab (full access): there you create a setup key and a setup file (mc4y-erkennung.json), enter the networks and see the connected agents, their last reports and runs; “Collect now” requests an immediate report. The easiest way to set up a single computer is the graphical installer (package mc4y-suite.zip; on Windows double-click Installer-starten.bat – no terminal needed –, on Linux/macOS installer-starten.sh or installer-starten.command): there you choose the target “Report this device to the CMDB (agent/crawler)”, enter the address and setup key (or place mc4y-erkennung.json next to it) and tick “Agent” and/or “Crawler”. By hand it works with the discovery packages (step by step in their README). The packages (mc4y-erkennung.zip for Windows/Linux/Raspberry Pi/macOS/Android, mc4y-cmdb-homeassistant.zip) are located under public/client and in the website's download area. The agents send encrypted over HTTPS only to this suite (endpoint agent.php) and deliver only inventory data – no user names or file contents; the server stores their identifier only as a check value. For a self-signed certificate, provide the suite certificate to the installer. The data belongs to the CMDB database and is backed up with it.

Several computers at once (deployer): Instead of setting up each computer individually, roll out the agent or crawler via Discovery › “Connect devices” from your workstation – Windows over WinRM, Linux/Raspberry Pi/macOS over SSH. There you download the small deploy helper (mc4y-verteiler.zip), put the setup file (verteiler.json) next to it and start Verteiler-starten.bat; it opens the view connected. Then choose the operating system, enter the computers (one per line: name, FQDN or IP) and the account (Windows: an administrator account; SSH: the SSH user), check the connection and roll out – with progress per computer. On Windows targets WinRM must be enabled (usually already so in a domain; otherwise once winrm quickconfig); for SSH the login is key-based (OpenSSH client on your workstation) and the install needs root rights – log in as root, set up NOPASSWD sudo or provide a sudo password; python3 must be present on the target. Any password you enter stays only in the helper's memory and is not stored; the helper is reachable only on 127.0.0.1 with a random key. So the suite view may talk to this local helper, the suite's security policy (CSP) allows connections to 127.0.0.1/localhost – connections only, no foreign scripts. If you choose Home Assistant as the operating system, the view shows a step-by-step guide with a download instead of the rollout form: Home Assistant is not set up remotely but the integration is installed once on the device itself (package mc4y-cmdb-homeassistant.zip, full guide in its README).

In your network, under your responsibility: the IT staff install and operate agents and crawler in their own network. They set everything organisation-specific themselves – suite address, setup key, networks, schedule, SNMP community; the package downloaded from the website contains no preset address. There is no telemetry, no update check at my-coaching4you.de and no query to outside servers (the manufacturer lookup also comes from the locally stored list). The data stays in the company network.

Virus scanners and firewalls: an inventory agent reads installed software and sends it – some virus scanners flag this pattern as suspicious pre-emptively, or move a file to quarantine (even though it is not malware). Add the agent's folder, service or task as an exception (check the files beforehand, download them only from your own suite or the official source); if the agent does not appear in the discovery view, look in the quarantine; a remnant of an already-locked file can sometimes only be removed after a restart (the Windows agent is therefore split into two parts – network and inventory –, or use the Python agent instead). For the firewall: agents need only outbound HTTPS (port 443) to the suite – no port opened on the devices; the crawler needs outbound ping (ICMP), the checked TCP ports and, where used, SNMP (UDP 161) into the configured networks (IPv6 too), and the suite server only inbound HTTPS. Blocked ping makes devices invisible to the crawler; network protection systems (IDS/IPS) may flag a scan as suspicious – so agree it with those responsible for the network beforehand, schedule it outside working hours and run it throttled.

Solution database: Proven solutions (like a wiki, with categories, versions and attachments) are stored in a separate database loesungen/loesungen.sqlite, the attachments under loesungen/anhaenge. The user interface is the ITSM tool (module “Solution database” or the view “Solutions” in the tool); when a ticket is recorded, it suggests matching solutions and, on request, adopts solved tickets as drafts. Permissions (module “Solution database”): Read, Read and write, Full access = delete permanently and delete categories. Import and export of Word, PDF, PowerPoint and LibreOffice files run in the browser; the server only stores the results.

Administration › Storage locations shows exactly where everything is located – with size and free space. An update replaces only the program; content is never stored in the program folder.

konfig.php (next to app) contains:

2. Which deployment type is right?

All deployment types require PHP 8.2 or later (8.4 or newer recommended) with the extensions pdo_sqlite, mbstring, openssl, fileinfo and zip; sodium and opcache are recommended, and for domain sign-in ldap as well. Without sodium, the suite stores passwords using Argon2id from PHP itself or with bcrypt. No database software is needed (SQLite is included in PHP).

The graphical installer

The easiest way is to start, in the unpacked package, Installer-starten.bat (Windows 10/11 and Windows Server), installer-starten.sh (Linux, as a normal user) or installer-starten.command (macOS, in Terminal with bash installer-starten.command; it needs Python there, e.g. from python.org – without Python, the route via bash install/macos/installieren.command is simpler, see macOS). At the top right, “DE | EN” switches the installer to English. A small helper listens only on 127.0.0.1 with a random key in the address and opens installer.html in the browser. The installer asks in six steps: target system (including “Browser only (easiest)” – the individual tools as files, without the suite and without administrator rights; suite modules and the desktop taskbar are then greyed out), first installation or update (an existing installation is detected, even on another drive; configuration, database, documents, accounts and settings are carried over), locations with full paths for program, PHP, data storage and backups (each location is checked), tools and modules, prerequisites and result.

For a new installation, the installer does not suggest any location – choose all locations deliberately, for example with a drive next to “All locations on” and then individually (ideally put the backups on a different drive). When updating, the existing locations are shown and cannot be changed. “Update and move data storage or backups” updates the program files and then moves the data storage and/or the backups to new locations (Windows Server: on request also the program and PHP); empty fields stay at the previous location, and the previous folders remain in place.

The installer shows missing prerequisites – PHP (from windows.php.net, with checksum), Visual C++ runtime (from Microsoft, signature checked), IIS role services, system packages on Linux, Python with tkinter for the taskbar – with source and size, and only downloads them after you confirm. Beforehand, it runs the installation script once as a dry run and shows what the script will do. The installer passes its own language (“DE | EN”) on to the installation scripts, so their output in the log appears in the same language. The system only asks for administrator rights when installing (Windows: User Account Control; Linux: pkexec, otherwise sudo in the terminal; macOS: password prompt). Tools that were not selected are listed in auswahl.txt in the program folder and remain excluded with every update; their data is kept. Without internet access: place the PHP package with its .sha256 file and vc_redist.x64.exe in a folder voraussetzungen next to installer.html. Without the helper (file opened directly), the installer only plans and writes an answer file mc4y-installation.json, which the helper picks up on the target computer. On a Linux server without a graphical interface, the helper shows the address and a command for SSH port forwarding.

3. Single-user installation on Windows

The easiest way is the graphical installer – step by step in the Quick start (route B); it downloads PHP and, if needed, the Visual C++ runtime itself. Without the graphical installer:

1. Download PHP for Windows from windows.php.net: package “VS17 x64 Non Thread Safe”; the checksum (SHA256) is shown next to it.
2. Unpack the suite package and double-click install\windows\installieren.bat (Windows asks for administrator rights). With a PHP package:

   installieren.bat -PhpZip C:\Downloads\php-8.x.y-nts-Win32-vs17-x64.zip -PhpSha256 <checksum>

3. The script creates the account mc4y-systemuser (cannot sign in, only runs the PHP server), the program folder (suggested: C:\Program Files\MC4Y-Suite), the data folder (suggested: C:\ProgramData\MC4Y-Suite-Daten, or E:\MC4Y-Suite-Daten if the program is on E:) and the backup folder – it asks for all three; without prompts: -Programm E:\MC4Y-Suite -Daten E:\MC4Y-Suite-Daten -SicherungOrdner F:\MC4Y-Suite-Sicherungen – as well as the task “MC4Y-Suite”, which starts php -S 127.0.0.1:8090 at system startup.
4. The setup opens in the browser: create the first account (it becomes the administrator).

The single-user installation can only be reached on your own computer and therefore does not use HTTPS. For access from the network, choose a server installation.

4. Windows Server with IIS

What the installation script sets up

• IIS role services (web server, CGI/FastCGI, Windows Authentication, management tools), if they are missing. If IIS was newly installed in the process, the empty “Default Web Site” is stopped.
• PHP: existing PHP or the specified package (to C:\PHP), the Visual C++ runtime if needed. The suite uses its own php.ini under <program>\php\php.ini (other PHP applications are not affected).
• Application pool “MC4Y-Suite” with the virtual identity IIS AppPool\MC4Y-Suite – no user account is created and no policy is changed. This is also safe on a domain controller.
• Website “MC4Y-Suite” on port 443 with certificate (see HTTPS); the suite redirects requests to http://servername/ to HTTPS.
• Data folder only for administrators, SYSTEM and the application pool; konfig.php read-only for the application pool.
• Firewall rule “MC4Y-Suite (HTTPS)” for the Domain and Private profiles.
• Task “MC4Y-Suite-Sicherung”: daily backup at 02:30 as SYSTEM.
• Quick guide <program>\KURZANLEITUNG.txt and log installation_<time>.log.

On the server itself

Copy the package to the server, unpack it and run as administrator:

install\windows\installieren-server.bat -PhpZip C:\Pakete\php-8.x.y-nts-Win32-vs17-x64.zip -PhpSha256 <checksum> -VcRedist C:\Pakete\vc_redist.x64.exe

The script asks for the data folder (“Set up storage: where should the contents of the suite be kept …”, then “Data folder […]”) and shows the drives with their free space. Further switches: -Daten, -Sicherungen (different drive recommended), -HostName (address, default: full computer name), -Zertifikat <fingerprint>, -SicherungUhrzeit 02:30, -OhneWindowsAnmeldung, -Probelauf.

From a workstation (without signing in to the server)

On a computer in the domain, in the unpacked package:

powershell -ExecutionPolicy Bypass -File install\windows\auf-server-installieren.ps1 -Server server.firma.local -PhpZip … -PhpSha256 … -VcRedist …

A Windows sign-in window asks for an administrator account of the server. The password goes only to Windows (Kerberos via WinRM, port 5985 – enabled by default on Windows Server) and is neither stored nor logged. The script copies the packages, asks for the data folder, runs the installation and stores the log, quick guide and certificate under Dokumente\MC4Y-Suite-Installationen. At the end it shows the setup code for the first account.

First steps after installation

1. Register the certificate as trusted on the workstations (see HTTPS).
2. Open https://servername/ and create the first account with the setup code.
3. Administration › Sign-in (domain): switch on domain sign-in, map AD groups, run “Check connection”; see Active Directory.
4. Administration › Backup: “Back up now” and “Check”; then Administration › System check.

5. Linux (Apache or nginx)

For Debian 12/13, Ubuntu 22.04/24.04 (apt) as well as RHEL, Rocky, AlmaLinux 8–10 and Fedora (dnf); bash 4.4 or later, systemd. In the unpacked package:

sudo bash install/linux/installieren.sh --probelauf          dry run: only shows what would happen
sudo bash install/linux/installieren.sh                      server with Apache (asks for the data folder)
sudo bash install/linux/installieren.sh --webserver nginx --host suite.firma.local
sudo bash install/linux/installieren.sh --zertifikat /etc/ssl/suite.crt --schluessel /etc/ssl/suite.key
sudo bash install/linux/installieren.sh --einzelplatz        this computer only, http://127.0.0.1:8090/
sudo bash install/linux/installieren.sh --lang en            messages in English (otherwise: language of the system)
bash install/linux/installieren.sh --help                    all options

• The script installs missing PHP packages after asking (it does not set up third-party repositories; if PHP is too old, it says so and names ways to obtain newer packages).
• System account mc4y-systemuser without a login shell; a separate PHP-FPM pool “mc4y-suite” runs under it – not under the web server's account.
• Program /opt/mc4y-suite, data folder after asking (suggested: /var/lib/mc4y-suite-daten, permissions 700), settings and certificate under /etc/mc4y-suite.
• Apache or nginx delivers only public/, blocks hidden files and redirects port 80 to HTTPS (your own or a self-signed certificate). Under SELinux the script sets the file contexts; for domain sign-in, additionally setsebool -P httpd_can_connect_ldap 1.
• Firewall only after confirmation or with --firewall (ufw or firewalld).
• Daily backup at 02:30 as the systemd timer mc4y-suite-sicherung.timer (without systemd via cron), quick guide and log in the program folder, setup code only on screen.

Further commands: sudo bash /opt/mc4y-suite/install/linux/wiederherstellen.sh <backup>, …/datenordner-verschieben.sh <new folder>, …/deinstallieren.sh. Always run the suite's command line under its own account: sudo runuser -u mc4y-systemuser -- php /opt/mc4y-suite/app/cli.php sicherungen --lang en. Everything else, including manual setup: install/linux/README.txt.

6. macOS

Requirements: macOS 12 (Monterey) or later, an Intel Mac or a Mac with Apple silicon, a user account with administrator rights, internet access during the installation. Homebrew and Xcode are not needed. On older Macs (macOS 10.15 or 11), “Browser only” (mc4y-werkzeuge.zip) works; many of these Macs can be upgraded to a newer macOS free of charge.

Own PHP: The script downloads a single, ready-compiled PHP file (PHP 8.4 from static-php-cli, extension set “common”), checks it against the SHA-256 checksum hard-coded in the script and places it in /Library/Application Support/MC4Y-Suite-PHP/<version> (with HERKUNFT.txt, the file recording where it came from). If the file does not start, the script signs it ad hoc. Without internet access: put the file named in the error message into a folder voraussetzungen in the package. With --php-quelle homebrew, PHP from Homebrew is used instead; with --php <path>, a specific PHP 8.2 or later. When updating, the existing PHP is kept; the suite's own PHP is brought up to the version in the package.

Running it (step by step in the Quick start, route C): in Terminal, change into the unpacked package folder (cd, space, drag the folder into Terminal, Return) and enter

bash install/macos/installieren.command --probelauf    dry run: only shows what would happen
bash install/macos/installieren.command                single-user (asks for the password and the data folder)
bash install/macos/installieren.command --lang en      messages in English (otherwise: language of the Mac)
bash install/macos/installieren.command --help         all options

• Always start it with bash … in Terminal, not by double-clicking: When you double-click, macOS blocks files from the internet (“Apple could not verify …”), and packages that came via Nextcloud or a Windows computer often no longer have the execute permission (“you do not have appropriate access privileges”). With bash, neither matters.
• “Operation not permitted”: Terminal is not allowed to read the folder (Downloads, Desktop, Documents, cloud folders). Allow “Terminal” under “System Settings” › “Privacy & Security” › “Files and Folders”.
• “… is not in the sudoers file”: The account needs administrator rights. The password is not displayed while you type it in Terminal.
• “This Mac has macOS … The suite needs macOS 12 (Monterey) or newer”: Update macOS or use “Browser only”.

The script creates a hidden system account mc4y-systemuser that cannot sign in, copies the program to /Library/Application Support/MC4Y-Suite, creates the data folder after asking (suggested: /Library/Application Support/MC4Y-Suite-Daten) and sets up two launchd services: PHP's built-in web server at http://127.0.0.1:8090/ and the daily backup at 02:30 (if the Mac was asleep, the backup is caught up when it wakes). Logs are stored in /Library/Logs/MC4Y-Suite.

Programs with an icon: every installation and update creates /Applications/MC4Y-Suite.app (opens the address of the suite in the default browser; Launchpad, Spotlight, Applications folder) – also afterwards for older installations. If wanted, the script sets up the desktop taskbar for the user who started it: ~/Applications/MC4Y Taskleiste.app (shown as “MC4Y Taskbar”), start at sign-in as a LaunchAgent (~/Library/LaunchAgents/de.my-coaching4you.mc4y-taskleiste.plist, from macOS 13 visible under “Login Items” and can be switched off there). Without asking: --taskleiste, --ohne-taskleiste, --ohne-autostart. The uninstaller removes MC4Y-Suite.app; the taskbar belongs to the user account and has its own deinstallieren-macos.command.

--server only writes a basic framework (PHP-FPM pool and nginx entry for Homebrew, self-signed certificate); you start the services yourself. For several users on the network, a Linux or Windows server is the better-tested choice. There is not yet a script for moving the data folder on macOS – the manual steps are described in install/macos/README.txt.

7. Web hosting package

1. Set the PHP version of the hosting package to 8.2 or newer; check that pdo_sqlite and zip are active (sodium is recommended).
2. Upload the folders app, public and install as well as .htaccess and konfig.beispiel.php from the package root via SFTP – including the hidden files (.htaccess, public/.user.ini). Ideally the domain points to public and everything else lies one level higher. If the hosting package does not allow a separate document root, app and install lock themselves via their own .htaccess files, and the .htaccess in the package root locks konfig.php, setup codes and scripts.
3. PHP limits (upload 100 MB, run time 600 s, memory 512 MB, no error display) are set in public/.user.ini – with PHP as FastCGI/PHP-FPM (e.g. STRATO), entries in .htaccess have no effect. The system check shows what the provider fixes.
4. Open the address: the suite shows “Set up storage”. Enter the setup code from ablage-einrichtungscode.txt (read it via SFTP) and choose a data folder outside the web directory.
5. Then create the first account (the second code is in <data folder>/system/einrichtungscode.txt).
6. Daily backup: create a cron job php /path/to/app/cli.php sicherung --auto in the provider's customer menu (sicherung is German for “backup”); download the backups regularly (Administration › Backup › Download).

8. Setting up and moving the storage

The installation scripts ask for the data folder and write konfig.php themselves. If the entry is missing (web hosting, manual installation), the start page shows the “Set up storage” dialog: it checks PHP and the extensions, creates the folder, checks write permission and rejects locations inside the web directory. When accessed from another computer, the code from ablage-einrichtungscode.txt in the program folder is required.

Moving the data folder and/or the backup folder (e.g. to a larger drive) – the suite is briefly unavailable during this:

powershell -ExecutionPolicy Bypass -File "<program folder>\install\windows\datenordner-verschieben.ps1" -Ziel E:\MC4Y-Suite-Daten -Sicherungen F:\MC4Y-Suite-Sicherungen

Both options can be used on their own; the script finds the running installation itself, even if it is not under C:\Program Files. Together with an update: installieren.bat -Aktualisieren -DatenNeu … -SicherungenNeu … or, in the graphical installer, “Update and move data storage or backups”. After “Type YES to move (the suite is briefly unavailable meanwhile)” (YES or JA), the script stops the suite, copies with the existing access rights, compares the number and size of the files and the checksums of the databases (suite, CMDB, solution database), switches konfig.php over (the old version remains next to it) and restarts the suite. A new backup folder receives the access rights of the data folder, existing backups are copied into it and the location is registered in the suite; backups that were previously stored in the data folder move along. The new locations are then also recorded in installation.json. The previous folder remains in place unchanged until you delete it yourself. On Linux: sudo bash /opt/mc4y-suite/install/linux/datenordner-verschieben.sh <new folder> (also switches the pool or service over); on macOS manually, following install/macos/README.txt. The exact command for your installation is also shown under Administration › Storage locations.

9. HTTPS and certificate

Passwords and content may only travel across the network encrypted. That is why the suite requires HTTPS as soon as it is accessed other than via 127.0.0.1.

Self-signed certificate (default of the server installation)

Valid for five years for the full computer name, the short name and the IP address. It is kept in the server's “Web Hosting” certificate store – so that a domain controller does not use it for LDAPS by mistake. To stop browsers from showing warnings, add the public part once on each workstation:

• Single computer: download https://servername/zertifikat/mc4y-suite.cer (or take it from <program>\zertifikat), double-click › “Install Certificate” › “Local Machine” › store “Trusted Root Certification Authorities”.
• All computers in the domain: Group Policy › Computer Configuration › Policies › Windows Settings › Security Settings › Public Key Policies › “Trusted Root Certification Authorities” › Import.

Firefox uses the Windows certificates if security.enterprise_roots.enabled is switched on (default for managed installations).

Your own certificate

Import a certificate from your own certification authority (e.g. Active Directory Certificate Services) or from a public provider into “Local Computer › Personal” and specify -Zertifikat <fingerprint> during installation – or replace it later in IIS Manager under “Bindings”.

Behind a proxy

If HTTPS terminates at an upstream proxy or load balancer, in konfig.php set 'https' => 'proxy'; the proxy must send X-Forwarded-Proto: https, and the suite must be reachable only through it.

10. Sign-in via Active Directory

Staff sign in with their Windows account – using name, name@firma.local or FIRMA\name. The suite checks the password and account directly with the domain controller (LDAP bind with the account itself, no service account, no stored password) and reads the name, email address and groups.

Switching on: Administration › Sign-in (domain)

“Check connection” tests the connection without signing in or – with name and password – an account including its groups. Existing accounts can be linked to a domain account under Administration › Users; their own password in the suite then no longer applies. The account is recognised by its identifier (SID), even after it has been renamed.

LDAPS and signing

For ldaps, the domain controller needs a certificate (usually from Active Directory Certificate Services) that the suite server trusts. If the domain requires LDAP signing (message “requires a signed or encrypted connection”), use ldaps or starttls, or run the suite on the domain controller with 127.0.0.1.

Signing in with the signed-in Windows account

With the server installation on IIS, the sign-in page additionally shows “Sign in with the signed-in Windows account” (Kerberos via windows-anmeldung.php). This applies to accounts that are linked to a domain account in the suite or are created automatically. For the browser to sign in without prompting, add the suite's address to the “Local intranet” zone (Group Policy “Site to Zone Assignment List”, value 1); otherwise the browser asks once for name and password.

11. Backup and restore

A backup is a ZIP file mc4y-sicherung_<date>_<time>_<occasion>.zip containing the entire data folder, consistent snapshots of the database, the CMDB and the solution database (even while work is in progress), a description MC4Y-SICHERUNG.json and checksums (SHA-256) of all files. Older backups are removed according to the configured number (default 14).

• Daily: task “MC4Y-Suite-Sicherung” (Windows Server), cron job or systemd timer (Linux), launchd (macOS) or cron job on web hosting – in each case php app/cli.php sicherung --auto.
• Manually: Administration › Backup › “Back up now”; there also “Check”, “Download” (administrators only, logged) and “Delete”.
• Location: default <data folder>\sicherungen. It is better to enter a different drive or a network drive (Administration › Backup › Settings) and also to keep the files off-site (3-2-1 rule: three copies, two media, one off-site).

Weekly CMDB cleanup

For the CMDB the installation also sets up a weekly run (Windows: scheduled task “MC4Y-Suite-CMDB-Aufraeumen”, Sundays 03:30, as SYSTEM; Linux: systemd timer or cron job; macOS: launchd) – php app/cli.php cmdb-aufraeumen. It removes the installation links of silent devices (devices that have not reported for a configurable number of days – default 30, CMDB › Group rules) and records this in the history of the respective software component; the components themselves are kept, as are manually maintained devices. The run also happens automatically at most once a week as soon as someone opens the CMDB – the task only makes sure it also happens without anyone using it. Manually: CMDB › Group rules › “Run weekly cleanup now” (with a dry run). Uninstalling removes the task again.

Restoring

powershell -ExecutionPolicy Bypass -File "C:\Program Files\MC4Y-Suite\install\windows\wiederherstellen.ps1" -Sicherung mc4y-sicherung_2026-10-17_02-30-00_auto.zip

Without -Sicherung, the script lists the available backups and asks for the name. It first checks the backup against its checksums, asks “Type YES to restore” (YES or the German JA are accepted; -Ja skips the question), stops the suite, moves the previous content to <data folder>\_vor-wiederherstellung_<time> (nothing is deleted), restores the backup and starts the suite. On Linux: sudo bash /opt/mc4y-suite/install/linux/wiederherstellen.sh <backup>, on macOS: bash "/Library/Application Support/MC4Y-Suite/install/macos/wiederherstellen.command".

Practise restoring once, ideally on a test computer: only a tested restore makes a backup reliable.

Commands for the command line (in the program folder). The command names are German; the output is German unless you add --lang en (or set the environment variable MC4Y_SPRACHE=en):

php app/cli.php status --lang en              version, data folder, backup folder
php app/cli.php sicherung --lang en           create a backup
php app/cli.php sicherungen --lang en         list the existing backups
php app/cli.php pruefen <name> --lang en      check a backup against its checksums
php app/cli.php cmdb-aufraeumen --lang en     remove installations of silent devices (--probelauf = dry run, --tage N sets the period)
php app/cli.php system --lang en              system check as text
php app/cli.php --lang en                     short help with all commands

On Windows Server with the suite's php.ini: C:\PHP\php.exe -c "C:\Program Files\MC4Y-Suite\php\php.ini" app\cli.php …

11a. Forgotten password – making an account accessible again

There is deliberately no reset by e-mail. If someone can no longer sign in, the person who looks after the server creates a recovery code for the account there; with it, the account owner sets a new password themselves. An administrator can also set a password directly in Administration › Users (the “Password” section, checkbox “must change the password at the next sign-in”) – that is the way when an administrator can still sign in.

Create a recovery code on the server (visible window; the code appears only there, is stored nowhere and is not written to the log):

Windows:  Kennwort-zuruecksetzen.bat        (in the folder install\windows; or kennwort-zuruecksetzen.ps1)
Linux:    sudo bash /opt/mc4y-suite/install/linux/kennwort-zuruecksetzen.sh [login]
macOS:    bash "/Library/Application Support/MC4Y-Suite/install/macos/kennwort-zuruecksetzen.command" [login]
or:       php app/cli.php kennwort-code <login>

The script asks for the login name (if not given) and shows a code such as K7PX-QM4R-TV9H. Give it only to the account owner (not by unencrypted e-mail). The code is valid for 30 minutes, single use, and expires after five wrong entries.

Set a new password in the browser: on the sign-in page click “Forgot password?”, then enter login name, code and a new password. Afterwards failed attempts and any lock are cleared and all other sessions of the account are ended; the person signs in with the new password.

12. Updating

Unpack the new package and start the installation script with -Aktualisieren (server: installieren-server.bat -Aktualisieren, from a workstation: auf-server-installieren.ps1 … -Aktualisieren). Beforehand, the database and – if present – the CMDB and the solution database are backed up to <data folder>\_update-sicherung; only app, public and install are replaced. konfig.php, the data folder, certificate and settings are kept; the locations (including those on other drives) and the port are taken from the existing installation. With -DatenNeu/-SicherungenNeu, the data storage and/or the backups are moved afterwards (see Storage). The new version converts the database itself on first access. Linux: sudo bash install/linux/installieren.sh --aktualisieren (pool, web server entry and services are kept; rewritten with --konfiguration-erneuern), macOS: bash install/macos/installieren.command --aktualisieren – in each case from the new package.

If an update changes the structure of a database (e.g. version 0.4.5: wiki and solution database with a German and an English version), the suite additionally makes a copy itself on the first call: <data folder>\_update-sicherung\<time>_vor-datenbank-11\suite.sqlite or …_vor-loesungen-2\loesungen.sqlite. If this copy fails (e.g. disk full), the database remains unchanged and the portal reports the error. After the conversion, existing wiki pages and solutions count as German; their English version is a copy that changes along with them until someone translates it.

13. System check

Administration › System check checks three groups and shows green, yellow or red with a note for each item:

• Operation: PHP version and extensions, write permission and free space for the data folder, upload limits, size of the database, OPcache, error log.
• Backup: age of the last backup (yellow from two days), number, backup on a different storage medium from the data?
• Security: data folder outside the web directory, HTTPS and secure cookie, error display in the browser switched off, PHP version not disclosed, permissions of the data folder (Linux/macOS), number of administrators, minimum password length (12 recommended), setup code still present, domain sign-in.

Below that are the latest entries of the error log (<data folder>/system/fehler.log).

14. Checklist for a security review

For your own or an external review (e.g. before use with personal data). The suite is not a certified product; the list does not replace an expert review.

Operation and server

• Operating system, web server and PHP receive security updates; the PHP version is still supported.
• Only public is delivered; https://…/app/kern.php, …/konfig.php, …/install/ return no content.
• The data folder is outside the web directory; only administrators, the system and the web server account have permissions.
• HTTPS with a valid or distributed certificate; HTTP redirects or is blocked; switch on hsts once the roll-out is complete.
• Firewall: only port 443 (and, if applicable, 80 for the redirect) from the intended networks; no exposure to the internet without additional protection (VPN or upstream proxy).
• Web server logs: retention period defined and documented.

Accounts and permissions

• At least two, but only a few administrators; without groups, administrators have no permissions for content.
• Minimum password length of at least 12 (Administration › Settings); with domain sign-in, the domain's password rules apply.
• Permission groups follow the principle of least privilege; Full access only where necessary.
• People who have left are deactivated (or disabled in AD – the suite then rejects them).
• Setup codes removed (system check: no setup code still present).

Backup and emergency

• The daily backup is running; the last backup is at most one day old (system check green).
• Backups are also stored on a different drive or off-site, protected like the data.
• Restoring has been practised and documented.

Application

• Sign-in: lockout after 5 failed attempts, limit per address, same message for an unknown account and a wrong password.
• Session cookie HttpOnly, SameSite=Strict, with HTTPS Secure; protection against cross-site requests (CSRF token, origin check).
• Headers: Content-Security-Policy, X-Content-Type-Options: nosniff, X-Frame-Options: SAMEORIGIN, Referrer-Policy.
• Uploaded files are delivered only as a download or in a sandboxed view.
• The log (Administration › Log) is reviewed regularly; the error log is empty or explained.
• Tools do not call external servers (exception: company search in the Vertriebs-Navigator sales tool – blocked in the suite).

Data protection

• Record of processing activities extended to include the suite; notes for users (privacy page of the suite) adapted to your own organisation (Administration › Settings).
• Deletion periods for the log, recycle bin and backups defined.
• If operated by third parties (web hosting, data centre): data processing agreement.

15. Troubleshooting

16. Uninstalling

Single-user installation: install\windows\deinstallieren.bat. Server with IIS: install\windows\deinstallieren-server.bat (removes the website, application pool, FastCGI entry, backup task, firewall rule and program folder; with -ZertifikatLoeschen also the generated certificate). The data folder is always kept – except with -DatenLoeschen and entering LOESCHEN. PHP, IIS and the Visual C++ runtime remain installed. Linux: sudo bash /opt/mc4y-suite/install/linux/deinstallieren.sh [--konto-behalten] [--daten-loeschen], macOS: bash "/Library/Application Support/MC4Y-Suite/install/macos/deinstallieren.command" (also removes the suite's own PHP and the program “MC4Y Suite”; the desktop taskbar is removed with bash ~/"Library/Application Support/MC4Y/Taskleiste/deinstallieren-macos.command") – there, too, the data folder is kept, except with --daten-loeschen and entering LOESCHEN. “Browser only”: drag the tools folder to the Recycle Bin (Windows) or the Bin (Mac).

Step by step (single-user installation on Windows): in the unpacked package (or in the program folder), open install › windows, double-click “deinstallieren”, answer the Windows prompt with “Yes”, at “Uninstall the suite? (y/n)” type y and press Enter (on Windows set to German: “Suite deinstallieren? (j/n)”, j). Mac: open Terminal (cmd + Space, “Terminal”), paste the command above with --lang en added, press Return, type your password, at “Uninstall the MC4Y Productivity Suite? [y/N]” type y and press Return. With --daten-loeschen/-DatenLoeschen, the scripts then ask you to type LOESCHEN (German for DELETE) – this word is the same in both languages.