Node CLI¶

lfgnode is a command-line interface (CLI) tool for managing workloads and clusters in the LFG network. This document provides an overview of the commands, folder structure, and CI/CD pipeline used in this repository.

Prerequisites¶

For MacOS & Windows, Docker Desktop is required.
After installing Docker Desktop. Open Docker Desktop -> Setting -> General -> Select Use WSL 2 Based Engine -> Select dd the *.docker.internal names to the host's /etc/hosts file -> Apply & Restart.
For Linux, Docker Engine is required.
Go 1.23 or later is required to build the CLI from source.

Installation and Deployment¶

Install Binary (Linux)¶

Stable channel:

curl -sL https://lfgnode-cli.s3.ap-southeast-1.amazonaws.com/releases/install.sh | bash

Beta channel:

curl -O https://lfgnode-cli.s3.ap-southeast-1.amazonaws.com/releases/install.sh && bash install.sh -c beta

Release Deployment Pipeline¶

node-cli deployment is automated by GitHub Actions (.github/workflows/release.yml):

A git tag triggers the release workflow.
Release channel is determined from the tag:
Tags containing -rc publish to the unstable channel metadata (unstable.txt).
Other tags publish to the stable channel metadata (stable.txt).
GoReleaser builds multi-platform binaries (linux, darwin, windows; amd64, arm64).
Build metadata is injected at compile time:
VERSION (LFGNODE_VERSION)
API_ENDPOINT (NODE_SYSTEM_API_ENDPOINT)
Artifacts are uploaded to S3 under:
s3://lfgnode-cli/releases/<tag>/...
The latest channel pointer file (stable.txt or unstable.txt) is updated in S3.

How to run¶

Download packages
```
go get
go mod tidy
```
Build the CLI
```
go build -o lfgnode main.go
```

Commands¶

The lfgnode CLI supports the following commands:

Core Commands¶

start: Start the LFG cluster.
stop: Stop the LFG cluster.
status: Check the status of the LFG cluster.
update: Update the CLI or cluster components.
info: Display information about the node.
version: Print the version of the CLI.
config: Manage configuration settings.

Workload Management¶

workload add: Add a new workload to the cluster.
workload list: List all workloads in the cluster.
workload remove: Remove a workload from the cluster.
workload restart: Restart a workload.
workload status: Check the status of a workload.

Version Management¶

Check Current CLI Version¶

lfgnode version

Update CLI to Latest Channel Version¶

lfgnode update

lfgnode update:

Resolves latest version from https://lfgnode-cli.s3.ap-southeast-1.amazonaws.com/releases/<channel-file>.
Downloads the matching binary archive for the current OS/architecture.
Replaces the installed lfgnode binary.
Stops the running cluster before update and starts it again after update.

Channel Behavior¶

Production builds use stable.txt.
Development and release-candidate (-rc) builds use unstable.txt.

Folder Structure¶

The repository is organized as follows:

.
├── cmd/                # CLI commands
│   ├── cmd.go          # Root command definition
│   ├── start.go        # Start command
│   ├── stop.go         # Stop command
│   ├── update.go       # Update command
│   ├── workload/       # Workload-related commands
│   │   ├── add.go
│   │   ├── list.go
│   │   ├── remove.go
│   │   └── status.go
│   └── config/         # Configuration-related commands
│       ├── config.go
│       └── privateKey.go
├── internal/           # Internal logic and utilities
│   ├── api/            # API integrations
│   ├── cluster/        # Cluster management (e.g., k3d)
│   ├── hooks/          # Pre-run hooks for commands
│   └── workload/       # Workload management logic
├── pkg/                # Shared packages
│   ├── config/         # Configuration utilities
│   ├── logger/         # Logging utilities
│   ├── constants/      # Constants used across the project
│   └── util/           # Helper functions
├── scripts/            # Shell scripts for installation and setup
│   ├── install.sh      # Linux installation script
│   └── install_macos.sh # MacOS installation script
├── docs/               # Documentation
│   └── design.md       # Design document
├── .github/            # GitHub workflows
│   └── workflows/
│       └── release.yml # CI/CD pipeline configuration
├── main.go             # Entry point for the CLI
├── go.mod              # Go module definition
├── go.sum              # Go module dependencies
└── README.md           # Project overview and installation guide

Underlying Technology¶

The lfgnode CLI is developed using the Go programming language and is designed to simplify workload and cluster management by leveraging Kubernetes technologies. Specifically, it utilizes k3s, a lightweight Kubernetes distribution optimized for edge computing, and k3d, a tool that enables running Kubernetes clusters within Docker containers.

By integrating these technologies and Node System Backend's APIs, lfgnode provides an intuitive command-line interface that abstracts the complexities of Kubernetes, allowing users to efficiently manage workloads and clusters on their nodes. This approach ensures a seamless experience for deploying and maintaining applications in a containerized environment.