accounttechnologies / ring

ring! service launcher and monitor.

This repository is no longer maintained. All further development moves to queil/ring.

Ring

Meta-orchestrator for developers (cross-platform)

Ring brings order into the messy world of developing and debugging a cloud-ready microservice system side by side with maintaining and migrating legacy ones where you may have many different types of services (ASP.NET Core, Topshelf, WCF, ...) hosted in many different ways (Kubernetes, Docker, IIS Express, WindowsService, Exe) and scattered across many solutions and repositories.

What is it?

Ring consists of the following parts:

• the meta-orchestrator (a dotnet CLI tool)
• Visual Studio Extension (2022, also versions pre 4.0 support 2017, and 2019)
• Visual Studio Code Extension (WIP)

How it works

Ring groups apps into workspaces. Workspaces are defined in TOML files. Workspaces are composed from apps and other workspaces. A workspace can be loaded and started. Ring periodically runs a health check for every app, tries restarting the unhealthy ones, and reports the dead ones. Ring also exposes a web socket interface. Visual Studio extensions use it mainly for visualizing workspace/apps states, turning services off/on for build/debugging if they're a part of the currently loaded project/solution.

Basic facts

• You can run multiple instances of ring (serving different independent workspaces)
• There can be multiple clients (VS/VS Code extensions) interacting with a Ring instance at a time although mostly you'd have just one
• Ring is meant to keep your workspace running even if you quit Visual Studio
• You can also run Ring in a stand-alone mode which just keeps your workspace running
• Ring exposes a web socket interface on port 7999

Supported runnables

• kustomize - Kubernetes apps managed by Kustomize
• dockercompose - docker-compose files
• aspnetcore - .NET Core apps running in console (like ASP.NET Core in Kestrel)
• proc - arbitrary native processes

Windows-only:

• iisxcore - ASP.NET Core apps in IIS Express
• iisexpress - WCF and other .NET Framework services hosted in IIS Express
• netexe - full .NET Framework console apps (like TopShelf)

Installation

Ring dotnet tool

dotnet tool install --global ATech.Ring.DotNet.Cli --version '4.0.0-alpha.*'

Visual Studio Extension

Make sure you installed the dotnet tool first.

Download here ring! for Visual Studio

Visual Studio Code Extension

Download an early preview

Troubleshooting

If ring does not work as expected you can use --debug or -d switch to enable a debug level output.

ring run -w .\path\to\your\workspace.toml -d

CLI commands

• run - runs a specified workspace in a stand-alone mode.
• headless - starts and awaits clients (VS Code / VS extension) connections. Once connected a client can load a workspace and interact with it.
• clone - loads a workspace and clones configured repos for each runnable. The runnables must have the sshRepoUrl parameter configured otherwise they'll be skipped.
• config-* commands - more info here - configuration files.

Vocabulary

• app (aka runnable - an application/service/process ring manages.
• workspace - a logical grouping of apps defined in TOML file(s). Workspaces can be composed of other workspaces using the import tag. Ring can only run a single workspace at a time.

Example workspace

# your workspace.toml
[[kustomize]]
path = "your/app"

[[dockercompose]]
path = "app/2"

[[import]]
path = "relative/path/to/your/workspace.toml"

Authoring workspaces

Authoring workspaces docs

Release notes

Here

Working with the docs

Serve locally:

docker run -p 8089:8089 --rm -it -v ~/.ssh:/root/.ssh -v ${PWD}:/docs squidfunk/mkdocs-material serve -a 0.0.0.0:8089

Publish

docker run --rm -it -v ~/.ssh:/root/.ssh -v ${PWD}:/docs squidfunk/mkdocs-material gh-deploy 

ring's Issues

Multiple instances of ring fail cloning the same repo

Running Ring as a local tool highlighted an issue with running multiple instances with workspaces containing the same git repo. At present both instances try to clone into the same dir resulting with fatal: shallow file has changed since we read it. A possible solution would be to have a workspace hash and use it in the clone path (i.e. provide unique clone location per workspace). There is still a possibility someone could run the same workspace twice but this is not a valid use case.

Feature: expect ring.toml file in the working directory if no workspace file specified

At present ring requires passing workspace path like: dotnet ring run -w ring.toml. It would be handy if it could check for existence of ring.toml in the current working directory and run it.

Expose Service Startup Spread as a Configurable Value

When running a larger workspace (with 30+ services), the startup process can cause MacOS to freeze and even experience application crashes whilst the CPU is maxing out at 100%.

If possible it would be a good idea to expose the startup spread configuration so that the startup impact can be throttled according to OS/user needs.

Streaming logs

Ring should stream logs of the controlled runnables via websockets so they can be filtered and displayed in the clients.

Can fail to pull from sshRepo

Sometimes Ring fails to pull from an sshRepoUrl that it previously had no problem pulling from earlier in the same day. This error occurs when running Ring with the Visual Studio 2019 extension - so I run a toml file, then stop running it, and then next time I try to run it, this error might occur.

Problem seems intermittent but I have noticed it occurring after a change in VPN connection and I can get around the issue by closing Ring and trying again ... at which point it works.

The following error appears in Rings log files (not that xx is redacted code):

System.InvalidOperationException: If sshRepoUrl is used csProj must be a relative path but it is C:\Users\xx\AppData\Local\Temp\ring\repos\core\third-party\ob\provider\./source/xx.WebApi/xx.ProviderService.WebApi.csproj
   at ATech.Ring.DotNet.Cli.Windows.Runnables.Dotnet.DotnetContext.Create[T,C](C config) in C:\Dev\dev\tools\atech-ring\source\ATech.Ring.DotNet.Cli\Windows\Runnables\Dotnet\DotnetContext.cs:line 32
   at ATech.Ring.DotNet.Cli.Windows.Runnables.Dotnet.DotnetRunnableBase`2.InitAsync(CancellationToken token) in C:\Dev\dev\tools\atech-ring\source\ATech.Ring.DotNet.Cli\Windows\Runnables\Dotnet\DotnetRunnable.cs:line 34
   at ATech.Ring.DotNet.Cli.Windows.Runnables.Dotnet.AspNetCoreRunnable.InitAsync(CancellationToken token) in C:\Dev\dev\tools\atech-ring\source\ATech.Ring.DotNet.Cli\Windows\Runnables\Dotnet\AspNetCoreRunnable.cs:line 22
   at ATech.Ring.DotNet.Cli.Abstractions.Runnable`2.InitCoreAsync(CancellationToken token) in C:\Dev\dev\tools\atech-ring\source\ATech.Ring.DotNet.Cli\Abstractions\Runnable.cs:line 187

Kustomize runnables destroy is not awaited

What is happening

When ring terminates (CTRL+C) it starts the destroy command for Kustomize runnables but the child processes get terminated before completion. It results with orphaned applications.

Expected behaviour

Ring should wait for the destroy processes to finish. No orphaned apps should be left.

Details

Ring version: 2.4.0

Ring fails to start as a local tool

Repro:

1. Install ring as a local dotnet tool: dotnet tool install ATech.Ring.Dotnet.Cli --version 3.0.0-alpha.1
2. Create an example workspace and save as ring.toml in the repo root:

   [[aspnetcore]]
   csproj = "src/server/App.fsproj"

3. Run ring: dotnet ring run -w ring.toml
4. Observe the following exception:

Unhandled exception: System.IO.FileNotFoundException: The configuration file 'appsettings.json' was not found and is not optional. The expected physical path was '/home/user/path/to/not/found/appsettings.json'.
   at Microsoft.Extensions.Configuration.FileConfigurationProvider.HandleException(ExceptionDispatchInfo info)
   at Microsoft.Extensions.Configuration.FileConfigurationProvider.Load(Boolean reload)
   at Microsoft.Extensions.Configuration.FileConfigurationProvider.Load()
   at Microsoft.Extensions.Configuration.ConfigurationManager.AddSource(IConfigurationSource source)
   at Microsoft.Extensions.Configuration.ConfigurationManager.Microsoft.Extensions.Configuration.IConfigurationBuilder.Add(IConfigurationSource source)
   at Microsoft.Extensions.Configuration.ConfigurationExtensions.Add[TSource](IConfigurationBuilder builder, Action`1 configureSource)
   at Microsoft.Extensions.Configuration.JsonConfigurationExtensions.AddJsonFile(IConfigurationBuilder builder, IFileProvider provider, String path, Boolean optional, Boolean reloadOnChange)
   at Microsoft.Extensions.Configuration.JsonConfigurationExtensions.AddJsonFile(IConfigurationBuilder builder, String path, Boolean optional)
   at Program.<>c__DisplayClass0_0.<<Main>$>b__8(HostBuilderContext c, IConfigurationBuilder b) in /home/vsts/work/1/s/src/source/ATech.Ring.DotNet.Cli/Program.cs:line 131
   at Program.<Main>$(String[] args) in /home/vsts/work/1/s/src/source/ATech.Ring.DotNet.Cli/Program.cs:line 129

Migrate from Nett to Tomlyn

The Nett TOML library seems to no longer be maintained. Tomlyn seems to have a lot of traction instead. Let's migrate to it.

Runnables with git source code cannot recover if local clone gets corrupted

Problem

At present git clone/pull logic doesn't take into consideration a corrupted state of the local clone when git clone gets interrupted.

Solution

When initiating a runnable it should check the state of the clone. If it's corrupted delete it and try cloning again.