super-utils

super-utils is a portable, web-based debugging and network toolkit built with Go (Fiber) and HTMX. It allows you to run a wide range of system, network, and diagnostic tools from any browser, with a modern UI and easy deployment via Docker or Helm.

Overview

This project serves dual purposes:

  1. Network Toolkit: A comprehensive web-based debugging and network diagnostic platform
  2. Microservices Emulator: A book shop microservices architecture emulator for testing and development

The toolkit provides instant access to essential system utilities through a browser interface, while the emulator allows developers to simulate and test microservices architectures without deploying full infrastructure.

Features

Network & System Diagnostics

Microservices Emulator

Deployment & Integration

Supported Tools

super-utils includes a comprehensive set of CLI/network utilities (all available in the Docker image and UI):

Network & Diagnostic Tools

apache2-utils, arping, bash, bind-tools, bird, bridge-utils, busybox, busybox-extras, calicoctl, conntrack-tools, ctop, curl, dhcping, drill, ethtool, file, fping, httpie, iftop, iperf, iperf3, iproute2, ipset, iptables, iptraf-ng, iputils, ipvsadm, liboping, mii-tool, mtr, net-snmp-tools, netcat-openbsd, netgen, nftables, ngrep, nmap, nmap-nping, scapy, socat, strace, tcpdump, tcptraceroute, termshark, tshark, websocat

File & Text Processing

awk, cut, diff, find, grep, sed, vi, vim, wc, gzip, cpio, tar, jq

System & Development

bash, git, libc6-compat, openssl, py-crypto, py2-virtualenv, python2, python3, util-linux

Web & Transfer Tools

curl, wget, dig, nslookup, telnet, ssh, lftp, rsync, scp, ab (ApacheBench)

Database Clients

mysql-client, postgresql-client, mongodb-tools, redis

Quick Start

Local Development

# Install dependencies
cd super-utils
go mod tidy
go run main.go
# Open http://localhost:8080 in your browser

Docker

docker run -p 8080:8080 super-utils
# All tools are available inside the container

docker pull quay.io/pepodev/super-utils

# mysqldump
docker run --rm quay.io/pepodev/super-utils "mysqldump --help"

# gsutil // copy local file to google cloud storage
# working directory is /opt/ mount folder in this path to easy use as volume
docker run --rm -v ./service-account:./service-account quay.io/pepodev/super-utils "gcloud activate ./service-account/gcp && gsutils -m copy -r ./dir/ gs://some-bucket"

Multi-Architecture Build (Local Testing)

To test multi-architecture builds locally, you need Docker Buildx:

# 1. Create a new builder instance (one-time setup)
docker buildx create --name multiarch --driver docker-container --use
docker buildx inspect --bootstrap

# 2. Build for multiple architectures
# Build and load for local testing (single platform at a time)
docker buildx build --platform linux/amd64 -t super-utils:amd64 --load .
docker buildx build --platform linux/arm64 -t super-utils:arm64 --load .

# 3. Test the built images
docker run --rm super-utils:amd64 /app/super-utils --version
docker run --rm super-utils:arm64 /app/super-utils --version

# 4. Build for multiple platforms and push to registry
docker buildx build --platform linux/amd64,linux/arm64 \
  -t quay.io/pepodev/super-utils:latest \
  --push .

# 5. Build without pushing (just verify it builds)
docker buildx build --platform linux/amd64,linux/arm64 \
  -t super-utils:multiarch .

Note:

Helm (Kubernetes)

cd super-utils/helm
helm install super-utils .
# Exposes service on port 8080

Book Shop Microservices Architecture

The service emulator provides a complete book shop microservices ecosystem for development and testing purposes. Each service is designed to handle a specific business domain with clear boundaries and responsibilities.

Core Services

1. User Service

2. Catalog Service

3. Shopping Cart Service

4. Order Service

5. Payment Service

6. Review Service

7. Notification Service

8. Inventory Service

Supporting Services

9. API Gateway

10. Service Registry

Service Interactions & Data Flow

The microservices interact in the following sequence:

  1. Authentication: Users interact with the User Service for authentication
  2. Browse Catalog: Authenticated users browse books via the Catalog Service
  3. Shopping Cart: Users add books to their cart using the Shopping Cart Service
  4. Order Creation: Users checkout, creating an order with the Order Service
  5. Payment Processing: Payment is processed through the Payment Service
  6. Inventory Update: Inventory is updated via the Inventory Service
  7. Notifications: Notifications are sent through the Notification Service
  8. Reviews: Users can submit reviews via the Review Service

Service Dependencies

graph TD
    A[API Gateway] --> B[User Service]
    A --> C[Catalog Service]
    A --> D[Cart Service]
    A --> E[Order Service]
    A --> F[Payment Service]
    A --> G[Review Service]
    A --> H[Notification Service]
    A --> I[Inventory Service]
    E --> F
    E --> I
    E --> H
    F --> H
    I --> H
    C --> G

Technology Stack for Emulator

Usage

Network Toolkit

  1. Open the Web UI: Visit http://localhost:8080 (or your server IP).
  2. Select a Tool: Use the dropdown to choose a tool (e.g., tcpdump, nmap, curl).
  3. Enter Arguments: Fill in the arguments field (see example hints for each tool).
  4. Run & View Output: Click “Run Tool” to execute. Output appears below.
  5. Other Features: Use the Curl/GraphQL and Network Info sections for specialized queries.

Service Emulator

  1. Access Service Emulator: Navigate to the “Service Emulator” section in the web UI.
  2. View Services: See all available book shop microservices with their status, port, and database information.
  3. Start Services: Select services and click “Start Selected” to simulate running microservices.
  4. Stop Services: Select running services and click “Stop Selected” to stop them.
  5. Reset All: Use “Reset All Services” to return all services to stopped state.
  6. Monitor Status: Service cards display real-time status (stopped/running) with color-coded indicators.
  7. Test Interactions: Use the emulator to test service dependencies and data flows in a microservices architecture.

API Endpoints

Network Toolkit Endpoints

Service Emulator Endpoints

Architecture

File Structure

super-utils/
├── main.go                      # Fiber backend & API server
├── go.mod                       # Go module dependencies
├── web/
│   └── index.html              # HTMX single-page UI (embedded)
├── documents/                   # Architecture documentation
│   ├── book-shop-architecture.md
│   ├── book-shop-services.md
│   └── book-shop-service-emulator-plan.md
├── Dockerfile                   # Multi-arch container build with all tools
├── helm/                        # Helm chart for Kubernetes
│   ├── Chart.yaml
│   ├── values.yaml
│   └── templates/
│       ├── deployment.yaml
│       └── service.yaml
├── AGENTS.md                    # Agent instructions for development
├── README.md                    # This file
└── _config.yml                  # Jekyll configuration

Security Notice

⚠️ Important Security Considerations:

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes:

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

Support

For issues, questions, or suggestions:

Roadmap

License

MIT