emc/README.md

emc

The minimal, declarative service catalog.

Background

In the last three jobs I've worked at, it's always been a hassle trying to locate the various dashboards, documentation, and support for a given project. I joined effx to try and help address just that. As I've been spinning up a new cluster, I found myself wanting a landing page for the systems that I use regularly.

Building your catalog

The emc service catalog is defined using a simple Golang script. This makes it easy for engineers to drop in their own functionality for rendering links, link groups, or services. For an example, see the provided grafana package which includes several of my personal dashboards for different systems.

// catalog.go

//go:build ignore
// +build ignore

package main

import (
	"code.pitz.tech/mya/emc/catalog"
	"code.pitz.tech/mya/emc/catalog/grafana"
	"code.pitz.tech/mya/emc/catalog/linkgroup"
	"code.pitz.tech/mya/emc/catalog/service"
)

func main() {
	catalog.Serve(
		catalog.Service(
			"Drone",
			service.LogoURL("https://path/to/drone-logo.png"),
			service.URL("https://drone.example.com"),
			service.Description("Drone is a self-service Continuous Integration platform for busy development teams."),
			service.Metadata("Contact", "drone@example.com"),
			service.LinkGroup(
				"Dashboards",
				linkgroup.Link("Drone", grafana.Drone("cicd", "drone")),
				linkgroup.Link("Golang", grafana.Golang("cicd", "drone")),
				linkgroup.Link("Litestream", grafana.Litestream("cicd", "drone")),
				linkgroup.Link("Redis Queue", grafana.Redis("cicd", "drone-redis-queue")),
			),
			service.LinkGroup(
				"Documentation",
				linkgroup.Link("docs.drone.io", "https://docs.drone.io/"),
			),
		),
		// ...
	)
}

Hosting your catalog

Once you've built your catalog, you can easily run a landing page by executing the catalog file.

$ go run ./catalog.go

This starts a web server for you to interact with on localhost:8080. If :8080 is already in use, you can configure the bind address by passing the -bind_address flag with the desired host and port.

Exporting your catalog

Instead of needing to compile a binary or host your catalog using go run, you can export your catalog to HTML or JSON. This makes it easy to drop into existing self-host platforms or leverage with other popular systems.

$ go run ./catalog.go -output html > index.html
$ go run ./catalog.go -output json > catalog.json

Protecting your catalog using oauth-proxy

Regardless of how you host your catalog, you'll likely want to protect access to it. An easy way to do this is using the oauth-proxy project. This project provides common OAuth2 client functionality to any project, making it easy to require authentication in order to access a system / project.

Until I have more of a concrete guide, you can follow my setup here. A simple analogy to this deployment would be a docker compose file with two services, one for the oauth-proxy and the other for the catalog (bound to 127.0.0.1). Using the new -output functionality, this deployment could definitely be simplified.