MC4Y Productivity Suite – Installation on the Mac
=================================================

Free software (GPL-3.0-or-later) from MY COACHING FOR YOU. German version: LIESMICH.txt
The complete guide for all systems is in INSTALL.txt (German: INSTALLATION.txt) in the main folder of the package.

Note: The single-workstation installation has been tried out on a real Mac (October 2026). Server operation
(--server) has not been tried yet. I would be glad to receive feedback.


FIRST CONSIDER: DO I NEED THE SUITE?
  If you only want to use the tools on your own and save your work as files, “Browser only” is the simpler
  way: download the file “mc4y-werkzeuge.zip”, double-click it, then double-click “index.html” in the new
  folder – done. No Terminal, no password, no PHP; this works on any Mac, even with an older macOS. This guide
  is for the whole suite (with sign-in, shared storage, calendar, wiki, tasks and daily backup).


WHAT YOU NEED
  - macOS 12 (Monterey) or later – an Intel Mac (for example MacBook Pro 2019) or a Mac with Apple silicon.
    To check: Apple menu (the apple symbol at the very top left) › “About This Mac”. It says, for example,
    “Version 14.7”; the first number must be 12 or higher. If it is 10.15 or 11: in the Apple menu, look under
    “System Preferences” › “Software Update” to see whether a newer version is available free of charge –
    otherwise use “Browser only”.
  - The password you use to sign in to the Mac (your account must be an administrator; for the first account
    on a Mac this is always the case).
  - Internet during the installation: It downloads PHP (about 15 MB). PHP is the programming language the suite
    runs in. You do NOT need Homebrew, Xcode or other developer tools.
  - About 15 minutes and 1 GB of free storage space.


THE TERMINAL IN TWO SENTENCES
  The Terminal is a window in which you type commands; you need only two, which you can copy below
  (select, cmd + C; click into the Terminal, cmd + V; then press the Return key ⏎).
  If it asks for a password, you see no characters while typing – that is intended; just type and press the
  Return key.
  The scripts write in English or German, like your Mac. The commands below end with “--lang en”, so the
  messages always appear in English, exactly as quoted here; without it, the language of your Mac applies.


STEP BY STEP

Part 1: Unpack the package
  1. Download “mc4y-suite.zip” (website of MY COACHING FOR YOU, area “Experimental”).
  2. Open the Finder and click “Downloads” on the left.
  3. If you see “mc4y-suite.zip”, double-click it.
     You now see a folder “MC4Y-Suite-” followed by the version, for example “MC4Y-Suite-0.4.15”.
     (Safari often unpacks by itself – then the folder is already there.) Leave the Finder window open.

Part 2: Open the Terminal
  4. Press cmd + Space, type “Terminal” and press the Return key.
     You now see a window with a line like “anna@MacBook-Pro ~ %”.

Part 3: Go to the package folder
  5. Type cd and a space. Do NOT press the Return key yet.
  6. Drag the folder “MC4Y-Suite-…” from the Finder into the Terminal window and let go.
     You now see, for example:  cd /Users/anna/Downloads/MC4Y-Suite-0.4.15
  7. Press the Return key. If macOS asks whether “Terminal” may access the “Downloads” folder:
     “OK”.

Part 4: Install
  8. Copy this command into the Terminal and press the Return key:

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

     You now see “The installation needs administrator rights. Please type the password …” and
     “Password:”.
  9. Type your Mac password (no characters appear) and press the Return key.
 10. At “Data folder [/Library/Application Support/MC4Y-Suite-Daten]:” simply press the Return key.
 11. At “Set up the desktop taskbar for … as well? [Y/n]” press the Return key (= yes).
     The desktop taskbar is a small program that keeps the tools of the suite at hand – even when no browser
     is open. It needs Python (see “Common problems”); if Python is missing, the suite still runs and the
     script explains how to add the taskbar later.
 12. At “Start the taskbar automatically when you sign in to your Mac? [Y/n]” press the Return key (= yes) –
     or type n if you prefer to start it yourself.
 13. At “Run the installation now? (Return = yes) [Y/n]” press the Return key.
 14. Wait (1 to 5 minutes). First PHP is downloaded and checked, then the suite is set up.
 15. You now see “Done. Address: http://127.0.0.1:8090/”, and the browser shows “Set up the suite”.
     Create your first account there (name, user name, password with at least 10 characters) and click
     “Set up and sign in”.
 16. Then start the taskbar: cmd + Space, type “MC4Y”, choose “MC4Y Taskbar”, press the Return key.
     It appears at the bottom left of the screen and asks for user name and password – the same as in step 15.
     If macOS asks about the keychain: “Always Allow”. From the next time you sign in to the Mac it starts by
     itself (if you answered step 12 with yes).
 17. Back in the Terminal (“Press Return to close …”): press the Return key, then close the Terminal with
     cmd + Q. The suite and the taskbar keep running.

From now on the suite starts by itself every time the Mac starts up and can only be reached on this Mac:
http://127.0.0.1:8090/.


HOW TO START THE SUITE AND THE TASKBAR LATER
  The installation creates two programs with an icon – like any other Mac program:
    “MC4Y Suite”     opens the suite in the browser          (folder “Applications”)
    “MC4Y Taskbar”   starts the desktop taskbar              (folder “Applications” in your home folder)
  How to find them:
    - Launchpad: click the icon with the coloured tiles in the Dock (on macOS 26 it is called “Apps”) and
      click “MC4Y Suite” or “MC4Y Taskbar”.
    - Spotlight: cmd + Space, type “MC4Y”, choose the entry and press the Return key.
    - Finder › Go › Applications (or Go › Home › Applications for the taskbar).
  Tip: drag the icons from Launchpad or the Finder into the Dock – then one click is enough.

  Important difference: In the suite, “Your account” › “Appearance” also offers a taskbar IN THE BROWSER. It
  belongs to the browser window and disappears when you close the window. The desktop taskbar (“MC4Y
  Taskbar”) is a program of its own and stays open – as on Windows. To quit it: ✕ at the end of the bar.

  Switching the start at sign-in on or off:
    - in the taskbar: click 🔍, at the bottom “Settings” › box “Start when signing in to the computer” ›
      “Save”;
    - from macOS 13 also: Apple menu › System Settings › General › Login Items, section “Allow in the
      Background” (it can be switched off there as well).
  The suite itself needs no start at sign-in – it always runs in the background.


HOW TO CHECK THAT IT WORKED
  1. Open http://127.0.0.1:8090/ in the browser: You see the suite’s sign-in page.
  2. Restart the Mac and open the address again: The sign-in page is back.
  3. In the suite, “Administration” › “System check”: Most rows are green.
  4. “Administration” › “Backup” › “Back up now”, then “Check” in the new row.


COMMON PROBLEMS
  - “No such file or directory” / “command not found”: You are not in the package folder – repeat steps 5 to
    7.
  - “Sorry, try again.”: Wrong password; type slowly once more (watch the Caps Lock key).
  - “… is not in the sudoers file”: Your account is not an administrator. Sign in with an administrator
    account or use “Browser only”.
  - “Operation not permitted”: Apple menu › “System Settings” › “Privacy & Security” › “Files and Folders” ›
    under “Terminal”, switch on the “Downloads Folder”; then repeat step 8.
  - “This Mac has macOS … The suite needs macOS 12 (Monterey) or newer”: Update macOS or use “Browser only”.
  - “PHP could not be downloaded”: Check your internet connection, repeat step 8. Without internet: download
    the file named in the message on another computer and put it in a new folder “voraussetzungen” (German
    for prerequisites – type the name exactly like that) in the package folder.
  - When you double-click a file of the package, macOS says “Apple could not verify …” or “… cannot be
    opened”: Do not start the files of the package by double-click, but in the Terminal with “bash …” as
    described above.
  - “… you do not have appropriate access privileges” / “permission denied”: This appears on double-click when
    the package came via Nextcloud, a cloud folder or a Windows computer. If you start it with “bash …” as
    above, it does no harm.
  - “Python (3.8 or newer, with tkinter) is missing on this Mac for the taskbar.”: The suite runs anyway.
    Install Python: open https://www.python.org/downloads/macos/ in the browser, download the latest “macOS
    64-bit universal2 installer”, double-click it in the “Downloads” folder and follow the steps. Then add the
    taskbar – as under “Updating”, but with:  bash install/macos/installieren.command --aktualisieren --taskleiste --lang en
  - The taskbar disappears when you close the browser: That is the taskbar IN THE BROWSER (see “How to start …
    later”). Start the program “MC4Y Taskbar” instead.


UPDATING
  Download the new “mc4y-suite.zip” and repeat steps 1 to 7, then instead of step 8:

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

  Type your password. If the desktop taskbar is not set up yet, the script asks about it (steps 11 and 12);
  if it is already there, it asks whether to update it as well. Then confirm “Run the update now? (Return =
  yes) [Y/n]” with the Return key. Content, accounts and settings are kept; the database is backed up
  beforehand (the last 10 backups stay in <data folder>/_update-sicherung). The update creates or renews the
  program “MC4Y Suite” in the “Applications” folder – also for installations that did not have it yet.


REMOVING
  Open the Terminal (step 4), copy this command and press the Return key:

       bash "/Library/Application Support/MC4Y-Suite/install/macos/deinstallieren.command" --lang en

  Type your password; at “Uninstall the MC4Y Productivity Suite? [y/N]” type y (for “yes”) and press the
  Return key. What is removed: the suite, the program “MC4Y Suite”, its own PHP, the services and the hidden
  system account. Your content stays in /Library/Application Support/MC4Y-Suite-Daten.
  If it should go too: append a space and --daten-loeschen to the command and, at “To delete it permanently,
  type LOESCHEN (German for DELETE):”, type LOESCHEN.
  The desktop taskbar belongs to your user account and stays. To remove it (no password needed):

       bash ~/"Library/Application Support/MC4Y/Taskleiste/deinstallieren-macos.command" --lang en

  This removes the program “MC4Y Taskbar”, the start at sign-in and the program files.


FOR EXPERTS

PHP
  The default is the suite’s own PHP: PHP 8.4 as a single, ready-compiled file from static-php-cli
  (https://static-php.dev, extension set “common” – among others pdo_sqlite with FTS5, mbstring, openssl,
  fileinfo, zip, curl, dom; without sodium, ldap and opcache). The script downloads the version whose SHA-256 is
  fixed in the script (Intel: x86_64, Apple silicon: aarch64; detected via hw.optional.arm64, also under
  Rosetta), checks it and places it in /Library/Application Support/MC4Y-Suite-PHP/<version>/bin/php (root:wheel,
  755; HERKUNFT.txt with source and checksum). If the file does not start, the script signs it ad hoc
  (codesign --sign -). The program requires at least macOS 12.0. Without internet: put the file
  php-<version>-cli-macos-<x86_64|aarch64>.tar.gz into the folder “voraussetzungen” of the package.
  Without sodium, the suite stores passwords with Argon2id from PHP itself or with bcrypt.
  --php-quelle homebrew takes PHP from Homebrew (offers “brew install php” as your user),
  --php <path> a specific PHP from 8.2. When updating, the existing PHP stays; the suite’s own PHP is brought
  to the version of the package (earlier versions are removed afterwards); with --php-quelle eigen or
  homebrew you can switch. Important when switching: If the new PHP does not know Argon2id, accounts with an
  Argon2id password can no longer sign in – the script points this out.

Call and options
  bash install/macos/installieren.command --probelauf     shows only what would happen (without password)
  bash install/macos/installieren.command --hilfe         all details (also --help)
  --daten <folder>  --programm <folder>  --port <number>  --auswahl <auswahl.txt>  --still  --ja  --ohne-browser
  --taskleiste | --ohne-taskleiste   also set up the desktop taskbar without asking, or do not offer it
  --ohne-autostart                   desktop taskbar without start at sign-in
  --lang de|en      language of the messages (also --sprache); default: the language of the signed-in user in
                    macOS (AppleLanguages), otherwise LC_ALL/LANG; the environment variable MC4Y_SPRACHE=en works too
  The option names are German (--probelauf = dry run, --daten = data folder, --still = no questions,
  --ja = answer “yes”); type them exactly as shown. The script obtains the administrator rights itself (sudo) and
  passes the language on; “sudo bash …” works as well. All scripts in install/macos (installieren.command,
  deinstallieren.command, wiederherstellen.command) know --lang.

What the script sets up (single workstation)
  1. System account mc4y-systemuser: hidden (IsHidden), without sign-in (UserShell /usr/bin/false), ID 400–499.
  2. Program  /Library/Application Support/MC4Y-Suite (owner root); konfig.php (root:mc4y-systemuser, 640)
     stays on updates. Tools that were not selected are listed in auswahl.txt and stay away on updates.
     Data       after asking, suggestion /Library/Application Support/MC4Y-Suite-Daten (mc4y-systemuser, 700)
     PHP        /Library/Application Support/MC4Y-Suite-PHP (own PHP, see above)
     Logs       /Library/Logs/MC4Y-Suite (server.log, sicherung.log; limited via /etc/newsyslog.d/mc4y-suite.conf)
     Details    /etc/mc4y-suite/installation.conf (PHP_BIN, PHP_QUELLE …)
  3. launchd service /Library/LaunchDaemons/de.my-coaching4you.mc4y-suite.plist: PHP’s own web server under
     mc4y-systemuser, only at http://127.0.0.1:8090/, starts at boot and restarts after crashes.
  4. Daily backup at 02:30 (…sicherung.plist, “php app/cli.php sicherung --auto”). If the Mac was asleep,
     macOS catches it up on waking; if it was switched off, it is skipped until the next night.
  5. Start, check, KURZANLEITUNG.txt (the quick guide) and installation log in the program folder – both in the
     language of the installation; the browser opens the setup (first account, without code, because it is on
     the same computer).
  6. Program /Applications/MC4Y-Suite.app (root:wheel; its launcher opens the address with /usr/bin/open,
     LSUIElement, icon mc4y-suite.icns, display name German/English via InfoPlist.strings); rewritten at every
     installation and update and registered with LaunchServices (lsregister).
  7. If wanted, the desktop taskbar for the user who started the script (SUDO_USER): taskbar package from
     public/client/mc4y-taskleiste.zip with voreinstellung.json (address of this suite), then its
     installieren-macos.command as this user (sudo -u … -H) with --autostart or --ohne-autostart.
     Result: ~/Applications/MC4Y Taskleiste.app, program in ~/Library/Application Support/MC4Y/Taskleiste,
     LaunchAgent ~/Library/LaunchAgents/de.my-coaching4you.mc4y-taskleiste.plist (RunAtLoad, Aqua). The
     graphical installer passes --ohne-taskleiste and sets up the taskbar itself if it was chosen.

Server operation (--server) – basic framework, not yet tried
  Needs Homebrew (nginx, PHP-FPM). Writes a PHP-FPM pool (etc/php/<version>/php-fpm.d/mc4y-suite.conf),
  an nginx entry (etc/nginx/servers/mc4y-suite.conf) and a self-signed certificate
  (/etc/mc4y-suite/tls). You start the services yourself as root:
    sudo brew services restart php
    sudo brew services restart nginx
  For several users on a network, a Windows or Linux server is the better-tried choice.

Restoring a backup
  bash "/Library/Application Support/MC4Y-Suite/install/macos/wiederherstellen.command" [<name or path>]
  Without an argument it shows the existing backups and asks “Name or path of the backup:”; before restoring
  it asks “Restore now? [y/N]”. The previous content moves to <data folder>/_vor-wiederherstellung_<time>.

Moving the data folder (there is no script of its own for this on macOS yet)
  Stop the suite (sudo launchctl bootout system/de.my-coaching4you.mc4y-suite), copy the folder with
  “sudo ditto <old> <new>”, change the entry 'daten' in konfig.php and run, from an unpacked package,
  “bash install/macos/installieren.command --aktualisieren” – this rewrites the service and starts the suite.
  Delete the old folder yourself afterwards.

Uninstalling for experts
  … deinstallieren.command [--konto-behalten] [--daten-loeschen] [--probelauf] [--ja]
  Removes services, program, the suite’s own PHP, logs, /etc/mc4y-suite and the account; Homebrew stays.
