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. Copy the following command to your clipboard (use the copy button)

   Copy@"%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.

First steps

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:

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

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:

CopyGet-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

More complex catlets

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

A simple example:

Copy# 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:

Copy# 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.

Getting Help

Reset to Initial State

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

Copy
# 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.

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!