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

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.

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 ).

A full description of the installation options can be found in the eryph-zero description.

But for a quick start, follow these steps:

1. Open a elevated command prompt (as admin)
   e.g. by typing cmd.exe in the Windows Start menu.

2. Run the following command:
   @"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command "[System.Net.ServicePointManager]::SecurityProtocol = 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/eryph-org/eryph/main/src/apps/src/Eryph-zero/install.ps1'))"

This will download the eryph-zero installation script (see also security notice ) and installs eryph-zero and the powershell clients.

Your first catlet

You can create a new catlet quickly from a parent with the New-Catlet powershell command:

New-Catlet -Parent <Org>/<Geneset>/<Tag>

Catlets are stored in genesets on the eryph genepool (something like the Docker Hub). The <Org>/<Geneset>/<Tag> syntax is the address of a geneset.

• Org: Name of organization on genepool, e.g. dbosoft
• Geneset: Name of geneset
• a geneset tag, optional (default is latest)

Example:

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

or

New-Catlet -Parent dbosoft/ubuntu-22.04

for latest geneset.
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

When the catlet is started, it automatically configures itself. In case of the starter catlet the configuration already contains a configurations that creates a user admin with password admin.
We call this kind of configuration fodder, as it will be fed into the catlet on first boot.

Other useful powershell commands:

• Get-Catlet:
  Shows a list or a single catlet if you add the catlet id. Catlets are always identifed by an id. The name of a catlet is only unique within a project (we will come later to projects).
• Remove-Catlet:
  To remove a catlet by its id

To remove all catlets simple use a powershell pipeline:

Get-Catlet | Remove-Catlet -Force

More complex catlets

Instead of writing always everything on the command line you will write more complex catlet specs in files.

A simple example:

# file: catlet.yaml
name: catlet2
parent: dbosoft/ubuntu-22.04/starter
memory: 4096
cpu: 2

Such a spec file can then be passed to New-Catlet via powershell pipeline:

# if you saved it as catlet.yaml
gc ./catlet.yaml | New-Catlet

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

• 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.