Minicluster is a library for setting up infrastructure.

It can be used in various ways:

• as a platform-engineering tool for developers
• to test processes like: upgrade paths, backup restoration
• for black-box testing and system testing (also in failure scenarios)
• to develop cloud-based Linux images
• for setting up and operating homelabs
• for safe deployment to production of provably working systems
• for testing dedicated hardware by giving control over the kernel and kernel drivers
• as the name suggests, all of the above in a cluster, including features like failover, backup, restore, observability (logging, monitoring, health-checks) and more

By combining these aspects within the same organization, it can cover the full needs, from development to deploying software into production.

Minicluster is optimized for

• developer experience
• gaining knowledge
• robust, reproducible environments
• promoting the infrastructure to production with peace of mind
• observability

Minicluster has commands to do basic things. However, to model complex pipelines/processes, you'll have to write python code.

WIP

• it's a library, so you write just code in python (more languages once the API is stable)
• it fosters knowledge by tackling the problems at the most fundamental level, instead of building abstractions on top (it doesn't use yaml or the like)

WIP

The project is currently in the bootstrapping phase, examples will be added here.

• ArchLinux, current release
• 8-12 GB RAM; minicluster adapts its ram usage based on what is freely available; still, at least 8 GB RAM is ideal
• 20 GB free disk space

pipx ensurepath
exit # then start up your shell again
pipx install --include-deps 'xontrib-ergopack[onepath,prompt,dev]'
xonsh
xpip install 'xonsh[full]' psutil python-dateutil pyzstd requests pygit2 bs4 lxml pytz
# optional, as root: chsh -s /home/[username]/.local/bin/xonsh [username] # replace [username] with your username

Now configure xonsh with the following ~/.config/xonsh/rc.xsh:

from xonsh.xontribs import xontribs_load
xontribs_load([
#        'whole_word_jumping',
        'ergopack',
#        'autoxsh',
#        'ssh_agent',
#        #'cmd_done',
])

Since we're in the early stages and we don't even have a release yet, the steps necessary are for tinkerers.

• clone the repository
• Execute as root the commands listed in bin/commands/bootstrap-host.sh; Please review and understand them first
• Start your shell, and if it's not xonsh, run xonsh
• cd minicluster # this executes the commands in .autoxsh if you've configured xonsh that way; the very first time you do this, you will be prompted to accept the commands
• if you don't use xonsh as a shell and autoxsh, then execute: export PATH=$PATH:``pwd``/bin/commands
• cd ~/.cache/; mkdir minicluster; cd minicluster
• build-base-image.xsh --handle d1 - this can take 20-40 minutes, depending also on your internet speed.

At the end of the process, you will have three artefacts:

• L2 image with the base arch installation; artefacts-nested-d1/nested-d1.qcow2 and the kernel and fstab files: artefacts-nested-d1/fstab (for debugging, not really used), artefacts-nested-d1/initramfs-linux.img, artefacts-nested-d1/vmlinuz-linux (the kernel image and initramfs are used on L0 by kvm/qemu to boot the VM, bypassing the VMs own boot loader)
• artefacts-nested-d1/nested-d1-repo/ the repository used to put together the L2 image
• tmp/d1-repo/ - the repository which could be used to construct a minicluster-capable VM on top of the L2 image

Not that d1 above is whatever you used as a handle for the command build-base-image.xsh above.

If build-base-image.xsh fails, see HACKING.md for diagnosing.

WIP

• why archlinux, isn't it too unstable?
• isn't it less secure to use a rolling release distro like archlinux?

Minicluster is licensed under the GNU AGPLv3, see LICENSE.txt for details.

For exceptions and/or business oportunities, contact me at Flavius Aspra <flavius.as+minicluster@gmail.com>.

    Minicluster - craft your clusters easily and reliably.
    Copyright (C) 2003  Flavius-Adrian ASPRA <flavius.as+minicluster@gmail.com>

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU Affero General Public License as published
    by the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Affero General Public License for more details.

    You should have received a copy of the GNU Affero General Public License
    along with this program.  If not, see <https://www.gnu.org/licenses/>.