epos-opensource

EPOS Open Source CLI

A command-line tool for deploying the EPOS Platform locally using Docker Compose or K8s.

🚀 Quick Start

Run the CLI without arguments to launch the interactive TUI, or use subcommands for CLI operations.

Install the CLI (Linux/macOS/WSL):

curl -fsSL https://raw.githubusercontent.com/EPOS-ERIC/epos-opensource/main/install.sh | bash

Check installation:

epos-opensource --version

Terminal User Interface (TUI)

For an interactive experience, just run

epos-opensource

to launch the TUI. This provides a menu-driven interface for managing environments, equivalent to CLI commands but with intuitive navigation and visuals.

Deploy a local environment with Docker Compose:

epos-opensource docker deploy myenv

Populate it with your own data:

epos-opensource docker populate myenv /path/to/ttl/files

What is EPOS Open Source CLI?

A command-line tool to easily deploy and manage EPOS Platform environments on your computer or in the cloud, using either Docker Compose or K8s.

Usage Requirements

• Docker and Docker Compose (for Docker-based setups)
• kubectl and access to a K8s cluster (for K8s-based setups)

Installation

Easiest: Installation Script

curl -fsSL https://raw.githubusercontent.com/EPOS-ERIC/epos-opensource/main/install.sh | bash

This script works on Linux, macOS, and WSL. It will update the CLI if already installed.

[!IMPORTANT] ALWAYS REVIEW SCRIPTS YOURSELF BEFORE EXECUTING THEM ON YOUR SYSTEM!

Using Go

go install github.com/EPOS-ERIC/epos-opensource@latest

Make sure $GOPATH/bin or $HOME/go/bin is in your $PATH.

Pre-built Binaries

1. Download the appropriate archive from the releases.

2. Make the binary executable and move it to your $PATH:

   chmod +x epos-opensource-{your version}
   mv epos-opensource-{your version} /usr/local/bin/epos-opensource
   

3. Verify the installation:

   epos-opensource --version
   

Build from source

Build using make with Go 1.25.4 or later:

make build

Commands

The CLI is organized into two main commands: docker and k8s. Each has its own set of subcommands for managing environments. These commands work in both CLI and TUI modes.

Docker Commands

Example:

# Deploy a new Docker environment named "my-test"
epos-opensource docker deploy my-test

# Populate it with data
epos-opensource docker populate my-test /path/to/my/data

K8s Commands

Example:

# Deploy a new K8s environment named "my-cluster"
epos-opensource k8s deploy my-cluster

# Populate it with data
epos-opensource k8s populate my-cluster /path/to/my/data

Getting Help

For more details on any command, use the --help flag:

epos-opensource --help
epos-opensource docker --help
epos-opensource k8s deploy --help

Troubleshooting & Tips

• Docker/K8s not found: Make sure Docker and/or kubectl are installed and running.
• Environment/Directory already exists: Use a new name, or delete the old environment first.
• Problems with .ttl files: Make sure the directory exists and contains valid .ttl files and that their path are valid (no spaces, weird symbols, ...).
• Environment not found/Does not exists: Make sure to be running the commands as the same user, the cli uses an user level sqlite database to store the environment information.

If you get stuck, run with --help for more info, or feel free to open an issue.

Development

Follow these steps to set up your local development environment and enable the shared Git hooks.

Prerequisites

• Go 1.25.4+
• Make
• golangci‑lint

Clone & Enter the Repo

git clone https://github.com/EPOS-ERIC/epos-opensource.git
cd epos-opensource

Install the Shared Git Hooks

We include a set of pre‑commit hooks under .githooks/ that will automatically run your Makefile checks before each commit:

git config core.hooksPath .githooks

Makefile Targets

Our Makefile provides common commands for development like:

• make build Compile the CLI binary.

• make test Run all tests.

• make lint Execute linters (using golangci-lint).

Workflow

1. Edit code in your favorite editor.
2. Run your chosen make targets to verify everything passes.
3. Commit: the pre‑commit hook will automatically invoke make lint test.
4. Push your changes when you're ready.

Contributions Welcome

We welcome all contributions, including bug reports, feature ideas, documentation, or code changes.

If you have questions or are unsure how to get started, feel free to open an issue. We are happy to assist!

Contributing

1. Fork the repository and clone it locally.
2. Create a new branch from main or develop.
3. Make your changes and follow the existing code style.
4. Add or update tests and documentation as needed.
5. Commit your changes using clear, present-tense messages.
6. Push your branch and open a pull request.

Before submitting:

• Pull the latest changes from upstream.
• Squash commits if needed.
• Ensure all tests pass.

After submitting:

• Address any feedback on your pull request.
• Update your branch until it is approved and merged.

Thank you for your contribution!