Introduction

Getting started with eryph

Eryph is a comprehensive suite of tools and concepts that transforms Windows desktops and servers into a local cloud environment. It introduces catlets, a new approach to virtual machine management.

Introduction

Introduction on what eryph is and how to use it for virtual machine management.

Working with the powershell

A deeper dive into using eryph with powershell commands.

The eryph genepool

A description of the eryph genepool and how you can use it to share your machines and configuration.

References

References of specification files, configuration files and commands.

Introduction

Catlets are virtual machines that are automatically managed by eryph. They are created from reusable specification files, making them easy to share and deploy.
Eryph acts as an abstraction layer between the OS/hypervisor - handling storage management, virtual networking and machine configuration. This functionality mirrors that of a cloud provider, but is available in any environment - whether on your local machine, on the local or corporate network, or even on cloud-managed hosts.

In addition, eryph enables standardization of machine builds and configurations, allowing the same base configuration to be reused for multiple purposes, similar to tools such as Vagrant or containerization platforms.
This is built around the concept of genesets, which are like packages for your virtual machine artifacts (we call them genes) such as volumes and configurations.

Note

Eryph is not intended to replace tools like Vagrant or containers, which are excellent for many scenarios. Instead, eryph complements these tools by addressing use cases where traditional virtual machines are still valuable. It helps you maximize standardization and efficiency while continuing to run on virtual machines.

Installation

Currently, eryph comes in one flavor - eryph-zero - which is our standalone version for managing a single Hyper-V host. Eryph-zero is free and the source code is available on github ( BSL license ).

You can install eryph-zero with the eryph App (recommended) or with an installation script on all Windows versions that support Hyper-V. See downloads for both installation options.

Note

A complete description of eryph-zero requirements and installation options can be found in the eryph-zero description.

Install from eryph App

Get started by installing the eryph App first.
When the eryph App is started, you have the option to either install eryph-zero locally or to connect to an existing eryph-zero installation.
Continue with the local installation of eryph-zero. During the installation, the eryph App will automatically make sure that all requirements are met.

First steps

After installing eryph-zero with the eryph App you can create your first virtual machines as catlets.

Your first catlet

You can create a new catlet quickly from the catlets page. When you click on "Create a new catlet" you will enter a wizard to build the catlet specification from a parent catlet.

Parent catlets are stored in genesets on the eryph genepool (something like the Docker Hub). The genesets have a address with following syntax: <Org>/<Geneset>.

  • Org: Name of organization on genepool, e.g. dbosoft
  • Geneset: Name of geneset

To get started enter the following geneset as parent and click on Next:

dbosoft/ubuntu-22.04

Now you are asked which tag you want to use. The tag is used to fully qualify a particular geneset version. For the first steps you should leave the default "starter". Click on Next.

You now have to enter a name for the catlet. Optionally, you can change the default settings.

Enter "firstcatlet" as catlet name and click on Review YAML to see the generated catlet specification.
On the right side you can see which attributes the catlet inherits from its parent.

Click Deploy to run a PowerShell command that will build the catlet.

Note

Eryph is command line first. So even if you use the eryph App, it will end up using the same powershell commands that you can also use directly in the powershell. If you have followed the steps above, the command generated is equivalent to running

New-Catlet -Name firstcatlet -Parent dbosoft/ubuntu-22.04/starter

from the Powershell.

How catlets are deployed

The eryph genepool contains artifacts that can be shared within eryph - these artifacts are called genes. Genes of same purpose can be grouped in a geneset.

The catlet parent genes will be downloaded from the eryph genepool if it isn't already available locally. It may take up to GB (for example for a Windows parent). Don't run this on your mobile device!

You can see your catlet now in Hyper-V Manager and can start it like any other VM, or you can use the Start-Catlet cmdlet to run it:

Get-Catlet  | Start-Catlet -Force

If you go back to the catlets page in the eryph App you will also see (after deployment) a entry for the catlet where it can also be started/stopped or deleted.

Accessing the catlet

When the catlet is started, it automatically configures itself. In the case of the starter catlet, the configuration already contains a configuration that creates a user admin with a password admin.

We call this kind of configuration fodder, because it is fed into the catlet the first time it is started.
Fodder is also stored in the genepool and is used to separate configuration (fodder) and settings (catlets) of virtual machines.

To access the catlet from the eryph app, simply click Connect on the Catlets page. This will open the VM console for the selected catlet.
Since you have deployed a Linux VM, you can also connect to it via ssh. So if you have ssh or putty installed, you can connect to it using its access IP and user admin, password admin.

Note

The access IP is a virtual IP that is accessible by default only from the host eryph-zero. This guarantees that connect will work in any kind of network environment (wifi/corporate networks). The disadvantage of the default network is that other network devices cannot reach the catlet. If you want other devices to access the catlet, see Advanced networking.

Next

We recommend that you next take a look at our sample repository on github:

  • Tutorial
    A step-by-step tutorial on the basic usage of eryph-zero from the powershell.

  • Ubuntu-pwsh
    A more complex example of how to use fodder and variables to configure a catlet to your needs.

  • SQL Server
    An example showing how to use variable content in catlets and how to inject content from ISO files.

  • cinc-automated
    A complex sample that sets up an entire landscape to demonstrate the use of features like projects, networks, and how to use eryph with configuration management tools like chef.

eryph-zero

A more detailed description of eryph-zero and its features and options.

Working with the powershell

A deeper dive into using eryph with powershell commands.

The eryph Genepool

A description of the eryph genepool and how you can use it to share your machines and configuration.

References

References of specification files, configuration files and commands.

Getting Help

Reset to Initial State

If you ever get stuck, you can simply remove all catlets, projects (if any) and (optional) genes.


# remove all projects except default project (which cannot be deleted)
Get-EryphProject | where Name -ne "default" | Remove-EryphProject

# remove all catlets
Get-Catlet | Remove-Catlet

#optional: remove genes (this will cause them to be downloaded again)
Remove-CatletGene -Unused

Reinstalling / Uninstalling

If something completely breaks and you can no longer use eryph, you can reinstall it. However, we encourage you to post your problem on either Github, Reddit, or our support site - see the next topic for support options.

You can uninstall eryph-zero using the Windows Add/Remove Programs control panel applet. The uninstaller gives you the option to remove the entire configuration, which is recommended if something is not working.

Feedback

Any feedback provided in the uninstaller is very valuable and we monitor the feedback from the uninstaller carefully. Feel free to add your email contact to the feedback in case we are allowed to contact you.

Support

Eryph-zero is free and our sources are available on github. Support should be provided by public communities (at least for eryph-zero, in the long run). However, since it is new, the community still needs to grow up. So if you post in one of the communities below, you can be pretty sure that a maintainer will answer you.

Communities:
GitHub: https://github.com/orgs/eryph-org/discussions
Reddit: https://www.reddit.com/r/eryph/

Support ticket:
In addition, while still in early beta, we also offer the option to submit support requests directly to our support website https://support.dbosoft.eu or via email support@dbosoft.eu.
Please use this option only if you do not want to disclose your support request, as issues posted in the communities may help others to solve their problems.

Contributing

If you are a developer and have identified a issue in our code or have a feature request - feel free to contribute to the project. See https://github.com/eryph-org for eryph repositories.

Our main programming language is C# on .NET Core and almost all repositories are MIT licensed (except the main repository which is Business Source licensed which restricts also forks to non-clustered usage!). Feel free to fork and create your own clients, add-ons, or whatever!

Next
eryph-zero