Skip to content

What's Next?

🎉 Congratulations on reaching this point — it's definitely a reason to celebrate!
There are several topics to cover. First, explore and familiarize yourself with the components and their concepts. Next, experiment with the system and customize it to your needs. Then, try automating your day-to-day Mio operations. Finally, Take on Maintenance Tasks and enable continuous integration by tuning the toolkit to your needs.

If you need support or want to help us improve our Security, don't hesitate to reach out.

This is the end of our tour, so we're sending you one last 🎉! Thank you for your patience. You have all the available options.
The following topics cover how to get to the bottom of things.

Things to Grok#

  • Explore Mio tools such as mio-files, which is used for file management, and mio-pass, which serves as an interface for the standard Unix password manager pass.
  • Get into mio-backup and mio-backupctl to manage your backups on top of BorgBackup, an end-to-end encrypted and deduplicable backup system.
  • Familiarizing yourself with shell scripting will make it easier to integrate applications and develop your own modules.
  • Use woo as a command runner and component revision tracker.
  • Gain a deep understanding of identity management by studying GnuPG Subkeys. For more information, please refer to the manual.

Multi-Repo Setup#

A multi-repo setup is often used for projects consisting of multiple components/services. With woo, you can track all components and their revisions, as well as your glue code, in a top-level repository.

Example of setting up a multi-repo with woo

First, visit the woo documentation page to see how to install it.

# create a top level project workspace
mkdir ~/my-multi-repo-project && cd ~/my-multi-repo-project

# create a top-level repository in your forge
# and initialize the project
woo boot <MY-MULTI-REPO-PROJECT-REPO.git>

# add all components
git clone <fe.git> ./frontend && echo /frontend >> .gitignore
git clone <be.git> ./backend && echo /backend >> .gitignore
git clone <my-porject-mio.git> ./mio && echo /mio >> .gitignore

# your glue code to assemble the payload
cat <<"EOF">Makefile
dist:
    @mkdir -p $@
    @$(MAKE) -C frontend build DIST=../dist/frontend
    @$(MAKE) -C backend build DIST=../dist/backend
    @tar -cvzf mio/conf/app/files/app.tgz -C $@

snapshot:
    woo snapshot
    @-git commit -a -m 'snapshot' && git push

clean:
    @rm -rf -- dist

EOF

# create the manifest
woo snappshot
git add manifest && git commit -m 'init my-multi-repo-project' && git push -u origin master

# next time
# update all components
woo pull
# create payload
make snapshot dist
# deploy
cd mio && ./activate && make app

Add Your Own Module#

Each module is a directory that contains a Makefile and a script. It may also contain subdirectories named files[-INSTANCE] with content/payload files.

General Module Writing Guidance

  • For now, the module name must start with my-.
  • Write your module script so that it can be run multiple times in a row.
  • Verify your input data.
  • Use capital letters for file-based variables.
  • Ensure that the content of all your variable files ends with a newline character (ASCII 10).
Setting Up Own Modules

Let's add a my-data module that transfers assets.

# register module
cat <<"EOF">>${MIO_OVERLAY}/mio.mk
SETUP_APPS_POST :=\
    my-data
EOF

# create module
mkdir -p ${MIO_OVERLAY}/my-data

# create the module Makefile
cat <<"EOF">${MIO_OVERLAY}/my-data/Makefile
include $(MIO_ROOT)/module.mk
EOF

# create the script
cat <<"EOF">${MIO_OVERLAY}/my-data/script
#!/bin/sh

mkdir -p /var/www/assets

if [ -d ./assets ]; then
    rsync -av --chown root:www-data \
        --chmod D2750,F640 \
        --delete \
        ./assets/ /var/www/assets/
fi
EOF
chmod 755 -- ${MIO_OVERLAY}/my-data/script

# you may want to exclude generated payloads from Git
printf -- '/conf/my-data/files*/assets' >> .gitignore

# as always, commit and push your changes
mio-git add . && mio-git commit -m 'add my-data module' && mio-git push

That's it. Now, add your assets and deploy them across all instances using make my-data.

Take on Maintenance Tasks#

Mio itself aims to be maintenance-free. For now, though, your instances and identities require attention.

Backups#

Mio configures all BorgBackups in append-only mode. This separates the responsibilities of creating and maintaining backups. It also prevents destructive operations on the repository. Although all data and archives are retained, additional maintenance work is required for cleaning and freeing up space.

This means that you need to set up jobs to check, prune, and compact repositories. Depending on the backup frequency and storage size, this process may take a while. These tasks should be performed at least once a month using the mio-backup tool.

In addition to ensuring the integrity of the repository and archives, you should also verify your backups manually.

Identities#

Take care of your identities.

  • Import them from trusted sources.
  • Verify new identities by their SHA256 hash.
  • Monitor expiration dates and extend or revoke keys as necessary.
  • For the time being, manually deallocating all related resources is necessary when revoking an identity.
  • The instances must be unlocked in order to function properly.

Collaborators#

If your project collaborators want to modify the project configuration, they must first create their own identity using the mio-wizard. Then, they must hand over their key.pub file, which you can import into the project using the mio-wizard id-add ./key.pub command.

If they only need SSH access to instances, you can grant it to them on a class or instance basis using the accounts module. Use Ed25519 keys!
To do so, put their SSH keys into one of the following locations:

  • ${MIO_OVERLAY}/accounts/files[-INSTANCE]/root/.ssh/authorized_keys
  • ${MIO_OVERLAY}/accounts/files[-INSTANCE]/home/<USER>/.ssh/authorized_keys

Don't forget to commit, push, and roll out your module changes.

System Updates#

Mio comes with the autoupgrades module installed, which applies daily security updates. However, automatic reboots are disabled due to the lack of automatic identity unlocking and unexpected service interruptions.

Therefore, you should schedule system audits and maintenance routines once a month. Your mileage may vary. The mio-tools will help you automate these tasks.

Unlock After Reboot

To restore full functionality, unlock the instance identity after rebooting the system.
If the reboot was unintentional, perform a security audit or bootstrap from a fresh image first.

make do-unlock HOSTS="instance-to-unlock"

Subscribe to Security Mailing Lists

It's also a good idea to subscribe to security mailing lists that cover your application stack.

How to Upgrade#

Mio comes with all batteries included! The mio-upgrade tool fetches a new version, if available, and displays all updated modules and their changes.
Without arguments, it runs in dry-run mode and does not perform any actions.

Currently, you must review the CHANGELOG and, if necessary, manually migrate modules to account for any breaking changes.

General Upgrade Instructions — May the Force be with you

  1. Use the make do-backup command to trigger a backup.
  2. Perform the upgrade by running the mio-updgrade do tool.
  3. Verify your overwrites and consider using mio-files and the CHANGELOG to migrate them.
  4. Execute MIO_SCM_PUSH=0 mio-wizard init to commit your changes.
  5. Reinstall any of the listed modules that are part of your setup.
  6. Push your configuration changes upstream.
Upgrading Offline Installations

The Mio Wizard can also be used for offline installations. Make sure you picked the matching upstream channel. After activating the project, delete the ${MIO_ROOT} directory. Then, rerun the MIO_SCM_PUSH=0 mio-wizard init tool from the new binary without any arguments. Proceed to step 3.