TL;DR

MIO

All right then. You're so hot, and I'm going to make you mine.

This automated process generates a ready-to-use distribution with useful features for serving Mio's README via HTTPS.

Spin up a fresh Debian 12 / Bookworm machine.

Go wild, become root, then copy and paste the following example into the terminal.
The best way to do this is to blockwise verify the process, at least in three steps.
First, prepping sections 0 and 1. Then, bootstrapping sections 2-10. Finally, deploying.
Lean back and enjoy our show!

Serve mio's README via HTTPS

Known Bugs

Alertmanager UI is not opening using IPV6 literal

Identity passphrase

hotspoon

Copy / Paste Issues

You may achieve better results by copying and pasting each script block into a file. Then, you can source it. Follow these steps to do so:

cat > demo
Shift-Insert or CTRL-v
ENTER
CTRL-d
. ./demo

# 0. Prepare the host for demo purposes only
umask 077
apt update && apt -y -qq install bash curl openssh-server </dev/null
useradd --create-home --user-group --shell "$(which bash)" mio
if grep -sq -- "$(hostname)" /etc/hosts; then
    sed -i "s/$(hostname)/&.demo.mio.lan &/" /etc/hosts
else
    printf '127.0.1.1\t%s\n' "$(hostname).demo.mio.lan $(hostname)" >> /etc/hosts
fi
printf '::1\t\t%s %s\n' "$(hostname).demo.mio.lan" "$(hostname)" >> /etc/hosts
install -m 700 -d ~/.ssh
touch ~/.ssh/authorized_keys
chmod 640 ~/.ssh/authorized_keys
cat <<EOF_SUDO >/etc/sudoers.d/mio
mio ALL=(ALL:ALL) NOPASSWD: /usr/bin/cat /root/.ssh/authorized_keys
mio ALL=(ALL:ALL) NOPASSWD: /usr/bin/tee -a /root/.ssh/authorized_keys
EOF_SUDO
install -m 755 -d /etc/ssh/sshd_config.d
echo PermitRootLogin prohibit-password > /etc/ssh/sshd_config.d/000-mio.conf
systemctl restart ssh.service

# 1. Install mio
if [ ! -s /usr/local/bin/mio-wizard ]; then
    printf 'pulling mio-wizard OSE from next release channel\n'
    curl -Oj https://codeberg.org/api/packages/kosmonum/generic/mio-ose/next/mio-wizard
    install -m 755 mio-wizard /usr/local/bin/mio-wizard
fi
# install system dependencies (requires root)
mio-wizard install

# drop permission
runuser - mio

# continue as user

# checks
[ "$(id -u)" = "0" ] && { echo Error: drop permissions; return 1; }
HN=$(hostname)
DN=$(hostname -d)
PN=${DN%%.*}
DN=${DN#*.}
[ "${PN}" = "${DN}" ] && { echo Error: init issues; return 1; }
FQDN=${HN}.${PN}.${DN}
# EOF checks

# 2. Create a Super Project
mkdir ~/docs-mio && cd ~/docs-mio || return 1

# configure git
git config --global user.email "me@${DN}"
git config --global user.name "me"
git config --global init.defaultBranch "master"

export LC_ALL=C.UTF-8 || :
# identities expire after 1 day
export MIO_EXPIRE=1d


# 3. Create your identity
# Warning: leaks secrets!
echo hotspoon | mio-wizard id "me@${DN}"


# 4. Create a remote repository
git init --bare ~/docs-mio.git


# 5. Initialize the Super Project
mio-wizard init "file://${HOME}/docs-mio.git" "${PN}" "${DN}"
# source your project environment
. ./activate


# 6. Add backup controller
# skipped for demo purposes


# 7. Configure overlays
# configure modules
sed -i 's/^# MODULES.*/MODULES := $(filter-out backup postgresql msmtp sysstat, $(MODULES))/' conf/mio.mk
sed -i 's/^# TASKS .*/TASKS := $(filter-out do-backup, $(TASKS))/' conf/mio.mk
mio-git commit -a -m 'configure modules'
mio-git push --all


# 8. Integrate applications and payloads
# 8.1 Register app
mkdir -p -- conf/app/files

cat <<"EOF_MK" >> conf/mio.mk
SETUP_APPS := app
EOF_MK

# 8.2 System dependencies
mkdir -p -- conf/packages/files
echo python3-venv > conf/packages/files/app.conf

# 8.3 Prepare the source
mkdir -p ~/docs/app/docs/stylesheets

cat <<"EOF_DEPS" > ~/docs/app/requirements.txt
mkdocs-materialx
pymdownx_blocks
EOF_DEPS

cat <<"EOF_PAGE_HEADER" | tee ~/docs/app/docs/LICENSE.md ~/docs/app/docs/CHANGELOG.md > ~/docs/app/docs/index.md
---
hide:
  - navigation
  - path
---

![MIO](https://kosmonum.space/mio.png){ align=right width=33% loading=lazy }

EOF_PAGE_HEADER

sed 's/mio/mio&/' -i ~/docs/app/docs/index.md

sed 's/README\.md/index.md/g' "${MIO_ROOT}/CHANGELOG.md" >> ~/docs/app/docs/CHANGELOG.md
cat "${MIO_ROOT}/LICENSE" >> ~/docs/app/docs/LICENSE.md
sed -e '/^\[! For/d' "${MIO_ROOT}/README.md" >> ~/docs/app/docs/index.md

cat <<"EOF_STYLE" > ~/docs/app/docs/stylesheets/extra.css
.md-content .md-typeset h1 {
    display: none;
}
EOF_STYLE

cat <<"EOF_MKDOCS" > ~/docs/app/mkdocs.yml
site_name: MIO X MIO
site_author: coco von miconoco
copyright: "&copy; since 2021 <a href=https://kosmonum.space>kosmonum.space</a>"

repo_name: mio
repo_url: https://codeberg.org/kosmonum/mio-ose
edit_uri: ""

theme:
  name: materialx
  language: en
  font: false
  topbar_style: primary
  palette:
    primary: pink
    accent: indigo
  features:
    - navigation.tabs
    - navigation.top
    - header.autohide
    - search.highlight
    - search.suggest
    - toc.follow

extra:
  social:
    - icon: material/chat-plus
      link: https://web.libera.chat/gamja/#kosmonum
      name: 'Chat with us on #kosmonum @ irc.libera.chat'
    - icon: material/rss
      link: https://docs.kosmonum.space/rss.xml
      name: 'RSS Feed - Kosmonum Blog'
    - icon: fontawesome/brands/bluesky
      link: https://bsky.app/profile/miconoco.de
      name: 'Follow miconoco on bluesky'
    - icon: fontawesome/brands/mastodon
      link: https://fedifreu.de/@miconoco
      name: 'Follow miconoco on fedifreu.de'

extra_css:
  - stylesheets/extra.css

markdown_extensions:
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - meta
  - md_in_html
  - tables
  - toc:
      permalink: "#"
      baselevel: 2
      separator: "-"
  - pymdownx_blocks.dirtree
  - pymdownx.highlight
  - pymdownx.inlinehilite
  - pymdownx.details
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

nav:
  - Getting Started: index.md
  - License: LICENSE.md
  - Changelog: CHANGELOG.md
  - /alertmanager: /alertmanager/
  - /prometheus: /prometheus/
  - /kosmonum: https://kosmonum.space/
  - /miconoco: https://miconoco.de/
EOF_MKDOCS

# 8.4 Create the payload
tar cvzf conf/app/files/app.tgz -C ~/docs .

# 8.5 Payload installer
mkdir -p -- conf/app/files/home/bin
cat <<"EOF_DEPLOY_SCRIPT" > conf/app/files/home/bin/app.deploy
#!/bin/sh

set -euf

rm -rf -- ~/app
mv app ~/app
python3 -m venv ~/app/.venv
~/app/.venv/bin/pip install -r ~/app/requirements.txt
EOF_DEPLOY_SCRIPT

# 8.6 Service file
cat <<"EOF_SERVICE" > conf/app/files/app.service
[Unit]
Description={{ACCOUNT}}-App
StartLimitIntervalSec=1
RequiresMountsFor=/home

[Service]
Restart=always
RestartSec=30
ExecStart={{ACCOUNT_HOME_DIR}}/app/.venv/bin/mkdocs serve
WorkingDirectory={{ACCOUNT_HOME_DIR}}/app
PrivateTmp=1

[Install]
WantedBy=default.target
EOF_SERVICE

# 8.7 Configure features
# 8.7.1 Prometheus
cat <<"EOF_MK2" >> conf/mio.mk
SETUP_METRICS := node_exporter prometheus
EOF_MK2
printf 'https://%s/prometheus\n' "${FQDN}" | mio-files set prometheus WWW_URL

# 8.7.2 Alertmanager
sed 's/^SETUP_METRICS :=.*$/& alertmanager/' -i conf/mio.mk
printf 'https://%s/alertmanager\n' "${FQDN}" | mio-files set alertmanager WWW_URL
# email options direct setup or use msmtp module
printf -- 'YOUR.MAILBOX.HOST.LAN:587\n' | mio-files set alertmanager MAIL_HOST
printf -- 'alerts@%s\n' "${DN}" | mio-files set alertmanager MAIL_USER
printf -- 'alerts+%s@%s\n' "${PN}" "${DN}" | mio-files set alertmanager MAIL_FROM
printf -- 'me+alerts@%s\n' "${DN}" | mio-files set alertmanager MAIL_TO
# shared secret across instances
echo secret-passphrase | mio-pass insert -m instances/mail/default.pw
echo mail/default.pw > conf/alertmanager/files/mail.pw.pass

# 8.7.3 blackbox_exporter
sed 's/^SETUP_METRICS.*$/& blackbox_exporter/' -i conf/mio.mk
mkdir -p conf/prometheus/files/scrapes/probe.d

# 8.7.4 Domain
mkdir -p -- conf/domain/files
cat <<"EOF_SITE" > conf/domain/files/site.conf
server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name {{FQDN}};

    include snippets/ssl.conf;
    include snippets/sts.conf;

    ssl_certificate /etc/letsencrypt/signed/{{FQDN}}.crt;
    ssl_certificate_key /etc/letsencrypt/{{FQDN}}.key;

    include snippets/letsencrypt.conf;
    include snippets/gzip.conf;

    add_header Content-Security-Policy "default-src 'self' https: 'unsafe-inline' data: blob:;";

    location /alertmanager/ {
        proxy_pass http://127.0.0.1:9093/;
        proxy_set_header Host $host;
    }

    location /prometheus/api/v1/notifications/live {
        proxy_pass http://127.0.0.1:9090/api/v1/notifications/live;
        gzip off;
        proxy_buffering off;
        proxy_cache off;
        proxy_http_version 1.1;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
        proxy_set_header Accept "text/event-stream";
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /prometheus/ {
        proxy_pass http://127.0.0.1:9090/;
        proxy_set_header Host $host;
    }

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
    }
}

server {
    listen 80;
    listen [::]:80;
    server_name {{FQDN}};

    include snippets/letsencrypt.conf;

    location / {
        return 301 https://$host$request_uri;
    }
}
EOF_SITE

# 8.7.5 MY-TRUST-SELF-SIG
printf 'SETUP_APPS_POST := my-trustselfsig\n' >> conf/mio.mk

mkdir -p conf/my-trustselfsig/
cat <<"EOF_MOD">conf/my-trustselfsig/Makefile
include $(MIO_ROOT)/module.mk
EOF_MOD

cat <<"EOF_TRUST_SELFSIG_SCRIPT" > conf/my-trustselfsig/script
#!/bin/sh

echo ADR-0005 VIOLATIONS
echo hack to make blackbox probing work

# Yoda and Vader's powers merged.
find /etc/letsencrypt/signed/ -type f -print0 \
| xargs -0 -r -t ln -srf -t /usr/local/share/ca-certificates/

update-ca-certificates
EOF_TRUST_SELFSIG_SCRIPT


# 8.8 Commit changes
mio-git add conf
mio-git commit -m 'feat(app): serve mio one-shot-edition README over HTTP/S'
mio-git push --all


# 9. Add instances
# prepare instance - self-provisioning via SSH (requires root)
sudo cat /root/.ssh/authorized_keys | tee -a conf/accounts/files/root/.ssh/authorized_keys
sudo tee -a /root/.ssh/authorized_keys < .ssh/id.pub

# add our instance
mio-wizard add-instance "${HN}"
# instance-based module configuration
printf -- '%s\n' "${FQDN}" | mio-files set domain FQDN "${HN}"
# probe endpoint
cat <<EOF_BLACKBOX_PROBE > "conf/prometheus/files/scrapes/probe.d/${HN}.yml"
- targets: &targets
  - ${HN} https://${HN}.${PN}.${DN}
  labels:
    module: http_2xx
- targets: *targets
  labels:
    module: http_v6_2xx
EOF_BLACKBOX_PROBE

# commit instance configuration
mio-git add conf
mio-git commit -m "configure modules for ${HN}"

# fetch host keys from instance
ssh-keyscan -H -t ed25519 -4 "${FQDN}" | tee -a .ssh/known_hosts
mio-git commit -a -m "update known_hosts for ${HN}"
mio-git push --all


# 10. Roll out
make

cat <<"EOF_BOOT"


Project successfully bootstrapped!
Take over! Your demo time. Ahoy!
Deploy with:

    make install


EOF_BOOT

# bootstrap done

If you enjoyed the show, let's review What You Received.
If you encounter any problems or get stuck, please take a screenshot or the terminal log and submit an issue report.
Your feedback is appreciated.