MC4Y Productivity Suite – Installation on Linux
===============================================

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.

These scripts were written from the documentation but have NOT YET BEEN TRIED ON REAL SYSTEMS. Please first
look with --probelauf (dry run) at what they would do, and make the first installation on a test system.


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 simpler:
  in the file manager, right-click “mc4y-werkzeuge.zip” › “Extract Here” and double-click “index.html” in the
  new folder. No installation, no password.


STEP BY STEP: THE SUITE FOR THIS COMPUTER ONLY (Ubuntu, Debian, Fedora …)
You need: a computer with one of the Linux versions named below, your password (your account must be allowed
to install programs, “sudo”), internet and about 15 minutes.

  1. Download “mc4y-suite.zip”. The browser puts it in “Downloads”.
  2. Open the file manager, click “Downloads” on the left, then right-click “mc4y-suite.zip” and click
     “Extract Here”.
     You now see a folder “mc4y-suite” or “MC4Y-Suite-…”. Open it until you see the file
     “installer-starten.sh” and the folders “app”, “install” and “public”.
  3. Right-click an empty spot in this folder and then click “Open in Terminal”.
     You now see a Terminal window. This is a window in which you type commands. To paste there, use
     Ctrl + Shift + V; a command is run with the Enter key.
  4. Type the following and press Enter:

       sudo bash install/linux/installieren.sh --einzelplatz --lang en

     (--einzelplatz is German for “single workstation”. The scripts write in English or German, like your
     system; with --lang en the messages always appear in English, exactly as quoted here.)
  5. The system asks for your password (“[sudo] password for …”). Type it and press Enter. No characters
     appear while you type – that is intended.
  6. If the script asks “Install these packages now? [Y/n]” or “Install the recommended packages? [Y/n]”:
     press Enter each time (this means “yes”).
  7. At “Data folder [/var/lib/mc4y-suite-daten]:”, simply press Enter (accept the suggestion), and likewise
     at “Run the installation now? [Y/n]”.
  8. At the end it says “Done. The suite is running at http://127.0.0.1:8090/”. Open this address in the
     browser and, on the page “Set up the suite”, create your first account (name, user name, password with
     at least 10 characters, then “Set up and sign in”).

  Prefer the graphical installer: in step 4, type  bash installer-starten.sh  instead (without sudo) and
  choose “Linux” in the browser.

  How to check that it worked: http://127.0.0.1:8090/ shows the sign-in page – also after a restart.
  In the suite, under “Administration” › “System check”, most rows are green.

  Common problems: “… is not in the sudoers file” – your account is not allowed to install programs; use an
  administrator account. “PHP 8.1 is too old – the suite needs PHP 8.2 or newer.” (for example Ubuntu 22.04):
  The script names ways to newer packages; a newer version of the system or “Browser only” is simpler.

  Removing:  sudo bash /opt/mc4y-suite/install/linux/deinstallieren.sh --lang en
             At “Uninstall the MC4Y Productivity Suite? [y/N]”, type y and press Enter. Your content stays in
             the data folder.


FOR EXPERTS

Language: All scripts in install/linux write in English or German – by default in the language of the system
(LANGUAGE, LC_ALL, LC_MESSAGES, LANG; C and POSIX do not count; anything other than German gives English).
--lang de|en (also --sprache) or the environment variable MC4Y_SPRACHE chooses it; if a script restarts itself
with sudo, it passes the language on. The quick guide KURZANLEITUNG.txt and the log are written in the same
language. The command line of the suite (app/cli.php) writes German unless --lang en is given.
Placeholders such as <name>, <time> and <version> stand for your own values. Real names of files, folders and
options stay German, because that is what they are called (for example _update-sicherung, KURZANLEITUNG.txt,
--probelauf = dry run, --aktualisieren = update, --daten-loeschen = also delete the data folder).


PREREQUISITES

- Debian 12/13, Ubuntu 22.04/24.04 (apt) or RHEL/Rocky/AlmaLinux 8/9/10, Fedora (dnf); bash 4.4 or later, systemd.
  The script also sets up single-workstation operation on other systems with systemd if PHP is already installed.
- PHP 8.2 or later (8.4 recommended) with pdo_sqlite, mbstring, openssl, fileinfo, sodium and zip; opcache
  recommended, ldap for sign-in via Active Directory. The script installs missing packages on request.
  PHP that is too old (e.g. Ubuntu 22.04 with 8.1): The script names ways to newer packages but does not set up
  third-party sources.
- Server operation: Apache (default) or nginx, PHP-FPM, openssl, curl. A name under which the users reach the
  server (DNS entry), and preferably a certificate of your own; otherwise the script creates a self-signed one.


CALL

Unpack the package; after unpacking, the execute permission is often missing, so put “bash” in front:

  sudo bash install/linux/installieren.sh --probelauf          shows only what would happen (also works without sudo)
  sudo bash install/linux/installieren.sh                      server operation 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 --still --ja --daten /srv/mc4y-daten   without questions
  sudo bash install/linux/installieren.sh --lang en            messages in English (de = German)

All options: bash install/linux/installieren.sh --help (also --hilfe)


WHAT HAPPENS

1. Check: root rights, system, package, PHP and extensions; missing packages are installed after asking.
2. System account mc4y-systemuser: system account without login shell, without home directory, password locked.
   PHP runs under this account (own PHP-FPM pool or single-workstation service) – not under the web server’s account.
3. Folders:
     Program      /opt/mc4y-suite (app, public, install, LIESMICH; owner root, readable by everyone)
     Settings     /opt/mc4y-suite/konfig.php (root:mc4y-systemuser, 640) – stays on updates
     Data         after asking, suggestion /var/lib/mc4y-suite-daten (owner mc4y-systemuser, permissions 700);
                  must be empty or the data folder of an earlier installation (with system/suite.sqlite)
     Details      /etc/mc4y-suite/installation.conf (for the other scripts), certificate in /etc/mc4y-suite/tls,
                  older versions of changed files in /etc/mc4y-suite/alt
4. Server operation:
     - PHP-FPM pool “mc4y-suite” (Debian/Ubuntu: /etc/php/<version>/fpm/pool.d/mc4y-suite.conf, RHEL: /etc/php-fpm.d/)
       with its own socket, uploads up to 100 MB (request 110 MB), 512 MB memory, 600 s run time, display_errors off,
       temporary files in the data folder; plus expose_php = Off (99-mc4y-suite.ini).
     - Apache (sites-available/mc4y-suite.conf or conf.d/) or nginx: serves only public/, passes .php to the pool,
       blocks hidden files, leaves the suite’s error responses (JSON) unchanged, HTTP on port 80 redirects to HTTPS.
     - SELinux (RHEL): program httpd_sys_content_t, data httpd_sys_rw_content_t (semanage fcontext + restorecon).
       For sign-in via Active Directory additionally: setsebool -P httpd_can_connect_ldap 1
     - Firewall: only a hint or a question; with --firewall the script opens the ports in ufw or firewalld.
   Single workstation: systemd service mc4y-suite (php -S 127.0.0.1:8090, several requests at the same time), menu entry.
5. Daily backup at 02:30: systemd timer mc4y-suite-sicherung.timer (without systemd: /etc/cron.d/mc4y-suite),
   command “php app/cli.php sicherung --auto” under mc4y-systemuser. Backups: <data folder>/sicherungen or
   --sicherungsordner or Administration › Backup. Please copy them to another storage medium regularly.
6. Start and check via https://<name>/api.php?a=status (on this computer, but under the server name). Then the
   script shows “Setup code for the first administrator (only needed from another computer):” with the code
   below it (on screen only, not in the log) and writes /opt/mc4y-suite/KURZANLEITUNG.txt (the quick guide) as
   well as the log /opt/mc4y-suite/installation_<time>.log.

The suite sets its security headers itself and enforces HTTPS for requests from the network (konfig.php: 'https' =>
'erzwingen', German for “enforce”; behind a proxy that terminates TLS: --https proxy).


UPDATES

Unpack the new package, then from the NEW package:

  sudo bash install/linux/installieren.sh --aktualisieren

It asks “Run the update now? [Y/n]”. The script stops the suite (the single-workstation service, or only its own
PHP-FPM pool – other websites keep running), backs up the database to
<data folder>/_update-sicherung/<time>_vor-<version> (the last 10 stay;
--update-sicherungen <n>), replaces app, public and install and starts again. Account, data and konfig.php stay.
Pool, web server entry and services stay unchanged – with --konfiguration-erneuern the script writes them anew
(the previous version goes to /etc/mc4y-suite/alt).


RESTORING A BACKUP, MOVING THE DATA FOLDER

  sudo /opt/mc4y-suite/install/linux/wiederherstellen.sh <name or path of the backup>
       checks the backup, stops the suite, restores it (the previous content moves to
       <data folder>/_vor-wiederherstellung_<time>) and starts again. Existing backups:
       sudo runuser -u mc4y-systemuser -- php /opt/mc4y-suite/app/cli.php sicherungen --lang en
  sudo /opt/mc4y-suite/install/linux/datenordner-verschieben.sh <new folder>
       copies, compares (number, size, checksum of the database), switches konfig.php and the pool or service
       over. The old folder stays until you delete it yourself after checking.


UNINSTALLING

  sudo /opt/mc4y-suite/install/linux/deinstallieren.sh [--konto-behalten] [--daten-loeschen] [--probelauf]

Removes services, pool, web server entry, backup timer, program, account and /etc/mc4y-suite. The data folder
stays – except with --daten-loeschen and typing LOESCHEN at “To delete it permanently, type LOESCHEN (German for
DELETE):”. PHP, web server and firewall rules stay.


BY HAND (other systems)

Point the web server at <program>/public, hand .php to a PHP-FPM pool under an account of its own, block hidden
paths (/.), allow uploads up to 110 MB and 600 s run time, do not lay the web server’s error pages over PHP
responses; create konfig.php from konfig.beispiel.php next to app/ and public/; data folder outside the web
directory (permissions 700 for the PHP account); daily “php <program>/app/cli.php sicherung --auto” under this
account. The file gemeinsam.sh contains the building blocks (pool, services) that installieren.sh writes for this.
