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

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

But for a quick start, follow these steps:

  1. Copy the following command to your clipboard (use the copy button)

    @"%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'))"

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

  3. Paste the code from the clipboard (e.g. Ctrl-V or right click to paste) and run it.

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

Beta invitation code

eryph-zero is currently available by invitation only, so you will need an invitation code to download. Please join the eryph-zero waitlist to receive an invitation code.

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)

Powershell client

If you have not already done so, open a powershell prompt (as admin), as we will be using the powershell client for the following examples.

If you get a "Could not find credentials for eryph" error when running commands, make sure you actually started the powershell as an administrator.

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!

Eryph genepool availability

The eryph-genepool API services are fully available, but like eryph - in a beta state.
We are still working on the UI for browsing and managing the genepool.

In the meantime, please see The eryph genepool for a list of all the genesets we have already published to the genepool.

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.

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.

Next
eryph-zero