MC4Y – all packages in one
==========================

Version 0.4.30 · free software (GPL-3.0-or-later, see LIZENZ.txt) · Deutsche Fassung: mc4y-alles.zip
MY COACHING FOR YOU, Peter Hoenig – https://www.my-coaching4you.de/

This bundle holds every MC4Y program package at once. You download ONE file and then have everything on
your computer – the suite, the tools for the browser, the taskbar, the agents and crawlers for the CMDB,
the Home Assistant integration, the roll-out helper and the HTML-PY editor.

Each package stays a ZIP file of its own in the subfolder “pakete” (German for “packages”). When you unpack
them, each one gets its own folder. There are two reasons for this: you can leave single parts out, and the
start scripts for Mac and Linux keep their execute permission (that is lost when files are repacked on
Windows).

Nothing is installed, nothing is started and nothing is downloaded unless you do it yourself. Unpacking
alone changes nothing on your computer.


CONTENTS

  pakete/mc4y-suite.zip                The full suite: server (PHP), all tools, modules (documents, wiki,
                                       notes, tasks, calendar, CMDB, solution database), installation for
                                       Windows, Linux and macOS, manual.
                                       → folder “MC4Y-Suite-0.4.30”

  pakete/mc4y-werkzeuge.zip            All tools in the browser only – no installation, no login, no PHP.
                                       The easiest way, and it works on older machines too.
                                       → folder “MC4Y-Werkzeuge-0.4.30” (Werkzeuge = tools)

  pakete/mc4y-taskleiste.zip           The taskbar for your desktop (Windows, Linux, macOS). It connects to
                                       a suite, but it also works on its own.
                                       → folder “MC4Y-Taskleiste” (Taskleiste = taskbar)

  pakete/mc4y-erkennung.zip            Agents and crawlers that report devices and installed software to the
                                       CMDB of the suite (Windows, Linux, Raspberry Pi, macOS, Android).
                                       → folder “MC4Y-CMDB-Erkennung” (Erkennung = discovery)

  pakete/mc4y-cmdb-homeassistant.zip   Integration for Home Assistant: reports the devices managed there to
                                       the CMDB.
                                       → folder “MC4Y-CMDB-HomeAssistant”

  pakete/mc4y-verteiler.zip            “Connect devices”: rolls the agents out to many computers at once
                                       (Windows via WinRM, Linux and macOS via SSH).
                                       → folder “MC4Y-CMDB-Verteiler” (Verteiler = distributor)

  pakete/html-py-editor.zip            HTML-PY editor: a builder for your own website, with upload over
                                       SFTP/FTPS. Not part of the suite; it needs Python.
                                       → folder “html-py-editor”

  Unpack-all.bat                       Windows: double-click to unpack all packages.
  auspacken.ps1                        Windows: the same as a PowerShell script (with options).
  auspacken.sh                         Linux and macOS: unpacks all packages.
  auspacken.command                    macOS: double-click starter for auspacken.sh.
  LIZENZ.txt                           Licence note.

  (“auspacken” is German for “unpack” – the scripts speak both languages.)


WHICH WAY SUITS ME?

  I just want to have a look
    → Unpack “mc4y-werkzeuge.zip” only and double-click “index.html” inside. Done, no server.

  I want the suite on my own computer (single workstation)
    → Unpack “mc4y-suite.zip” and read “INSTALL.txt” in that folder. The easiest way is the graphical
      installer (double-click “Installer-starten.bat” or “installer-starten.command”).
    → Then unpack “mc4y-taskleiste.zip” if you would like to start the tools from your desktop.

  I want the suite on a server for several people
    → Unpack “mc4y-suite.zip” and read the “Server” section of “INSTALL.txt”.

  I want to know which devices and programs run in my network
    → Set up the suite first, then create a setup key in the suite under “CMDB › Discovery” and continue
      with “mc4y-erkennung.zip” (and with “mc4y-verteiler.zip” if you have many computers).

  I want to build a website of my own
    → Unpack “html-py-editor.zip” and read the instructions inside.


WHAT YOU NEED

  - For unpacking: nothing but your operating system (Windows, macOS or Linux). About 2 minutes.
  - Disk space: around 60 MB for the bundle, around 90 MB unpacked.
  - For the suite itself: see its own instructions (it brings PHP along or downloads it during setup).
  - For the agents, the roll-out helper and the HTML-PY editor: Python 3.8 or newer.


STEP BY STEP – WINDOWS 10/11

  1. Open your “Downloads” folder (Windows key, type “Downloads”, Enter).
  2. Right-click “mc4y-all” and then “Extract All …”.
  3. Click “Extract”.
     You now see a folder “MC4Y-All-0.4.30” with this file inside.
     Tip: with “Browse …” you can choose a fixed place first, for example “Documents”.
  4. Open the folder “MC4Y-All-0.4.30”.
  5. Double-click “Unpack-all” (or “Unpack-all.bat”).
     A black window opens. It first shows what it is going to unpack and asks before it refreshes a folder
     that already exists.
     If Windows warns you (“Windows protected your PC”): click “More info” and then “Run anyway”. The
     script is unchanged, exactly as it comes in the bundle.
  6. At the end you read “Done.” with the list of folders. Close the window.
  7. Open the folder you need (see “Which way suits me?”) and read “README.txt” there.

  Prefer to do it without a script? Then unpack every ZIP file in the folder “pakete” one by one:
  right-click › “Extract All …” › “Extract”. The result is the same.


STEP BY STEP – MAC (macOS 12 or newer)

  1. Open Terminal: cmd + space, type “Terminal”, Enter.
  2. Unpack the bundle like this (not by double-click – the macOS archive utility sometimes loses the
     execute permission). Type:

        ditto -x -k ~/Downloads/mc4y-all.zip ~/mc4y

     You see no output – that is correct. Your home folder now holds “mc4y/MC4Y-All-0.4.30”.
  3. Remove the internet marker from the files:

        xattr -dr com.apple.quarantine ~/mc4y

  4. Change into the folder and unpack the packages:

        cd ~/mc4y/MC4Y-All-0.4.30
        bash auspacken.sh

     The script first shows what it is going to do and asks before it refreshes an existing folder.
  5. At the end you read “Done.” with the list of folders.
  6. Open the folder you need and read “README.txt” there.

  Note: “Operation not permitted” means macOS protects that folder (Desktop, Documents, Downloads, iCloud
  or Nextcloud folders). In that case work in your home folder (~) as shown above.


STEP BY STEP – LINUX (Raspberry Pi too)

  1. Open a terminal.
  2. Unpack the bundle and change into it:

        cd ~ && unzip -q ~/Downloads/mc4y-all.zip
        cd MC4Y-All-0.4.30

     If “unzip” is missing:  sudo apt-get install unzip   (or dnf, zypper, pacman)
  3. Unpack the packages:

        sh auspacken.sh

  4. At the end you read “Done.” with the list of folders.

  If the bundle sits on a network share, copy it into your home folder first – scripts often cannot be
  executed from a mounted share.


HOW TO CHECK THAT IT WORKED

  - Next to the folder “pakete” there are now seven more folders, one per package.
  - “MC4Y-Werkzeuge-0.4.30” contains “index.html”. Double-click it: your browser shows the page
    “MC4Y tools” with every tool. That tells you the unpacking was complete.
  - “MC4Y-Suite-0.4.30” contains the folders “app”, “public” and “install” plus “INSTALL.txt”.


OPTIONS OF THE UNPACK SCRIPTS (if you like)

  Windows:   powershell -ExecutionPolicy RemoteSigned -File .\auspacken.ps1 -Probelauf
  Linux/Mac: sh auspacken.sh --dry-run

    --dry-run / -Probelauf      only shows what would happen; changes nothing
    --target <folder> / -Ziel   unpacks into another folder (default: this folder)
    --yes / -Ja                 refreshes existing folders without asking
    --lang de|en / -Sprache     language of the messages


COMMON PROBLEMS

  - “The folder pakete is missing”: the downloaded ZIP file was not unpacked completely. Please unpack it
    again (Windows: right-click › “Extract All …”; Mac: the ditto command above).

  - Windows does not run “Unpack-all” (a message about the execution policy): open PowerShell (Windows key,
    type “PowerShell”), change into the folder with “cd” and start:
        powershell -ExecutionPolicy RemoteSigned -File .\auspacken.ps1
    The file is not modified; Windows simply marks everything that comes from the internet.

  - Your antivirus speaks up: the scripts only unpack ZIP files. They download nothing, start no program
    and write no autostart entry. If your antivirus removes them anyway, unpack the packages by hand (see
    above) – the result is the same.

  - “bash: ./auspacken.sh: Permission denied” (Linux/Mac): the bundle sits on a share, or the execute
    permission is gone. Start it with “sh auspacken.sh” or “bash auspacken.sh” – then no permission is
    needed.

  - Not enough space: you do not need everything. Unpack only the packages you really want and delete the
    folder “pakete” afterwards.


UPDATING

  There is no automatic update. Download a new bundle, unpack it and run the unpack script again:

      https://www.my-coaching4you.de/downloads/experimentell/software/mc4y-all.zip

  The folders are refreshed; your own files stay. For an INSTALLED suite its own instructions apply as well
  (“Updating”) – unpacking alone does not renew the installation. Your working data is kept separately and
  is not touched.


REMOVING

  Drag the unpacked folders to the bin. If you have INSTALLED the suite, the taskbar or an agent, use the
  matching uninstaller first (see the instructions in that folder) – otherwise a service, a scheduled task
  or a menu entry stays behind.


FOR PROFESSIONALS

  - The bundle contains the single packages unchanged, so checksums can be compared against the individual
    downloads (Windows: Get-FileHash, Linux/Mac: shasum -a 256).
  - The unpack scripts use built-in tools only: Expand-Archive or System.IO.Compression on Windows, unzip
    or “python3 -m zipfile” on Linux and macOS.
  - Every package has exactly one root folder; the scripts read it from the archive and skip packages
    without a unique root folder.
  - Existing folders are refreshed, not deleted: files with the same name are replaced, everything else
    stays.
  - The language of the messages is set in “sprache.txt” (one line, “de” or “en”); -Sprache or --lang take
    precedence, then the language of the system.

The programs are provided free of charge and without any warranty (see LIZENZ.txt).
