Raven Scott 0e6f464d16 Add readme

2024-11-29 18:13:45 -05:00

7.0 KiB

Raw Blame History

Peartainer

Overview

Peartainer is a decentralized, peer-to-peer application designed to streamline Docker container management using Hyperswarm. The application connects multiple peers over a distributed hash table (DHT) network and provides full control over Docker containers, including starting, stopping, removing, duplicating, and monitoring real-time metrics. With its robust server key-based architecture, Peartainer ensures secure and persistent peer-to-peer communication.

The server key forms the foundation of the connection. It is automatically generated, saved, and reused unless explicitly refreshed, making it easy to maintain consistent access while allowing for manual key regeneration when needed.

In addition to a development environment, the client app can be run in production mode directly via Pear with the following command:

pear run pear://7to8bzrk53ab5ufwauqcw57s1kxmuykc9b8cdnjicaqcgoefa4wo

Key Features

Server-Side

Persistent Server Key:
- Generates a SERVER_KEY for each instance.
- The key is saved to .env for consistent re-use.
- Supports manual key regeneration by deleting .env.
Real-Time Docker Management:
- List all containers across peers with statuses.
- Start, stop, and remove containers remotely.
Dynamic Terminal Sessions:
- Open and manage multiple terminals for running containers.
- Real-time shell sessions streamed to connected peers.
Container Duplication:
- Clone containers with custom configurations for CPUs, memory, network mode, and hostname.
Live Statistics Streaming:
- Broadcast CPU, memory, and network stats in real-time to connected peers.

Client-Side

Peer-to-Peer Networking:
- Connects to servers using unique server keys via Hyperswarm.
- Fully decentralized; no central server is required.
Interactive User Interface:
- Modern, responsive UI built with Bootstrap.
- Integrated terminal viewer powered by Xterm.js.
- Real-time container stats displayed for each container.
Production Deployment:
- Ready-to-use client app available via Pear runtime:
```
pear run pear://7to8bzrk53ab5ufwauqcw57s1kxmuykc9b8cdnjicaqcgoefa4wo
```

How It Works

Server Key Architecture

The server is initialized with a SERVER_KEY that uniquely identifies the network. This key is essential for peers to connect and interact with the server.

Key Generation:

On the first run, the server checks for an existing SERVER_KEY in the .env file. If absent, a new key is generated:

function generateNewKey() {
  const newKey = crypto.randomBytes(32);
  fs.appendFileSync('.env', `SERVER_KEY=${newKey.toString('hex')}\n`, { flag: 'a' });
  return newKey;
}

The key is saved to .env for persistence.

Key Usage:

The server uses the key to generate a topic buffer for Hyperswarm:

const topic = Buffer.from(keyHex, 'hex');
swarm.join(topic, { server: true, client: false });

Key Refresh:
- To regenerate the key, delete the .env file and restart the server.

Peer Connections

Peers connect to the server using the unique topic derived from the SERVER_KEY. The Hyperswarm network ensures secure, low-latency connections.

Connecting:

Each client app connects to the server by joining the topic buffer:

const topicBuffer = b4a.from(topicHex, 'hex');
swarm.join(topicBuffer, { client: true, server: true });

Communication:
- Commands (e.g., listContainers, startContainer) are sent as JSON over the connection.
- Responses and real-time updates are broadcast back to peers.

Docker Integration

The server interacts with Docker using Dockerode:

List containers:

const containers = await docker.listContainers({ all: true });

Start a container:

await docker.getContainer(containerId).start();

Stream statistics:

container.stats({ stream: true }, (err, stream) => {
  stream.on('data', (data) => {
    const stats = JSON.parse(data.toString());
    broadcastToPeers({ type: 'stats', data: stats });
  });
});

Installation

Prerequisites

Docker:
- Install Docker and ensure it is running.
- For Linux, add your user to the Docker group:
```
sudo usermod -aG docker $USER
```
  Log out and back in for changes to take effect.
Node.js:
- Install Node.js v16 or higher:
```
sudo apt install nodejs npm
```
Pear:
- Install the Pear runtime for running the client and server:
```
npm install -g pear
```

Server Setup

Clone the repository:

git clone https://git.ssh.surf/snxraven/peartainer.git
cd peartainer

Change to server Dir:
```
cd server
```

npm install:

npm install hyperswarm dockerode hypercore-crypto stream dotenv

Run Server:
```
node server.js
```

Client Setup

For development, run:
```
pear run --dev .
```

For production, use the pre-deployed Pear app:

pear run pear://7to8bzrk53ab5ufwauqcw57s1kxmuykc9b8cdnjicaqcgoefa4wo

Usage

Connecting to a Server

Launch the client app.
Enter the server's SERVER_KEY in the connection form to join its topic.

Managing Containers

Listing Containers:
- View all containers (running and stopped) with their statuses.
Starting/Stopping Containers:
- Use the action buttons in the container list.
Removing Containers:
- Click the trash icon to delete a container.
Duplicating Containers:
- Click the clone icon and customize the duplication form.

Terminal Access

Open terminals for running containers.
Switch between sessions using the tray at the bottom.

Customization

UI Customization

Modify the layout and styling in index.html and the embedded CSS.

Terminal Behavior

Adjust terminal settings in libs/terminal.js:

const xterm = new Terminal({
  cursorBlink: true,
  theme: { background: '#1a1a1a', foreground: '#ffffff' },
});

Docker Commands

Add new commands in server/server.js under the switch statement for additional Docker functionalities.

Security

The SERVER_KEY is sensitive and should be stored securely.
Refresh the key periodically to enhance security, especially in untrusted environments.

Troubleshooting

Common Issues

Unable to Connect:
- Verify the SERVER_KEY matches on both server and client.
- Ensure the server is running and accessible.
Docker Errors:
- Ensure Docker is running and properly configured.
- Check permissions to manage Docker.
Terminal Issues:
- Verify the container has a valid shell (e.g., /bin/bash).

Contributing

Contributions are welcome! Fork the repository, make your changes, and submit a pull request.

7.0 KiB Raw Blame History