felice-n-franz

README

Felice & Franz

A generic, web-based producer and consumer for Apache Kafka.

Contents

• Requirements
• Installation
  • Docker
• Usage
  • Logging Flags
• Configuration
• TODO

Requirements

• Go version 1.19 or higher. You can probably install it through your system's package manager (apt, brew, etc.). For general instructions, go here --no pun intended.

• librdkafka v2.0.2 or higher. You can probably install it through your system's package manager (apt, brew, etc.). If you installed kcat through your package manager, then you're already set.

• Any web browser with decent support for ES2020 (e.g., Mozilla Firefox or any Chromium-based browser).

Installation

To install, open a terminal and execute the following

go install github.com/jwmwalrus/felice-n-franz@latest

The same command can be used for subsequent updates.

Docker

If you prefer so, you can clone this repository and run docker-compose, passing UID and GID as environment variavles:

env UID=${UID} GID=$(id -g) docker-compose up -d

The XDG_RUNTIME_DIR variable must exist in your host's shell environment before running docker-compose.

For Linux it is usually defined by your login session, but can otherwise be defined right before running the above command:

export XDG_RUNTIME_DIR=/run/user/${UID}
env UID=${UID} GID=$(id -g) docker-compose up -d

Similarly, for macOS:

export XDG_RUNTIME_DIR="${HOME}/Library/Application Support"
env UID=${UID} GID=$(id -g) docker-compose up -d

To stop the container, execute

docker-compose down

Usage

Assuming $GOBIN is in your PATH, open a terminal and execute the following

felice-n-franz

Then click on the displayed URL (which by default should be http://localhost:9191).

The web interface is pretty self-explanatory (select environment, consume or produce messages by topic, filter, etc.).

Logging Flags

Passing -h upon executing the felice-n-franz command, will display options related to logging.

The application's logs can be found at ${XDG_DATA_HOME}/felice-n-franz/.

Configuration

In order to operate properly (or at all), a config.json file is required.

Upon first run, one is generated at ${XDG_CONFIG_HOME}/felice-n-franz/. The expected contents are as follows:

Path	Type	Description	Default	Required
version	int	Configuration file version	1	required
firstRun	bool	If true, overwrite the ${XDG_CONFIG_HOME}/felice-n-franz/config.json file with in-memory values	false	optional
port	int	Application's port	9191	required
envs	array	Configured environments	[]	required
env.name	string	Environment's name		required
env.active	bool	If false, this environent's configuration will be ignored	false	optional
env.configuration	object	librdkafka configuration for this environment. See here for further details	{}	required
env.vars	object	Environment variables used for topic values	{"env": ""}	{}
env.headerPrefix	string	Common prefix for topic's headers		optional
env.topicsFrom	string	Copy env.schemas, env.topics and env.groups from the given environment		optional
env.schemas	object	TBD	{}	optional
env.topics	array	Configured topics for this environment	[]	required
env.topic.description	string	Topic description		optional
env.topic.key	string	Topic key. Must be a unique identifier for this environment		required
env.topic.value	string	Topic value. Actual topic definition. Shall be unique for this environment.		required
env.topic.headers	array	Array of key-value objects defining the headers associated to this topic	[{"key": "Content-Type","value": "application/json"}]	[]
env.topic.schema	object	TBD	{}	optional
env.groups	type	description	default	required/optional
env.group.name	string	Group's display name		optional
env.group.description	array	Group'ss description		optional
env.group.category	string	Group's category		optional
env.group.id	string	Group's identifier. Must be unique for this environment and not to collide with topic keys		required
env.group.keys	array	List of topic keys that belong to this group. Must not be empty		required

TODO

• Add a way of reordering consumer cards.
• Add topic schema validation.