update readme
This commit is contained in:
Raven Scott
parent
526ef0ca84
commit
5e96160b7c
183
README.md
183
README.md
@ -2,7 +2,7 @@
|
||||
|
||||
## 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.
|
||||
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, viewing logs, deploying from templates, 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.
|
||||
|
||||
@ -25,15 +25,25 @@ pear run pear://7to8bzrk53ab5ufwauqcw57s1kxmuykc9b8cdnjicaqcgoefa4wo
|
||||
|
||||
- **Real-Time Docker Management**:
|
||||
- List all containers across peers with statuses.
|
||||
- Start, stop, and remove containers remotely.
|
||||
- Start, stop, restart, and remove containers remotely.
|
||||
|
||||
- **Dynamic Terminal Sessions**:
|
||||
- Open and manage multiple terminals for running containers.
|
||||
- Real-time shell sessions streamed to connected peers.
|
||||
|
||||
- **Docker CLI Terminal**:
|
||||
- Access a Docker CLI terminal to run Docker commands on the remote peer.
|
||||
|
||||
- **Container Duplication**:
|
||||
- Clone containers with custom configurations for CPUs, memory, network mode, and hostname.
|
||||
|
||||
- **Template Deployment**:
|
||||
- Deploy containers using templates fetched from a remote repository.
|
||||
- Customize deployment parameters such as ports, volumes, and environment variables.
|
||||
|
||||
- **Container Logs**:
|
||||
- View real-time and historical logs of containers.
|
||||
|
||||
- **Live Statistics Streaming**:
|
||||
- Broadcast CPU, memory, and network stats in real-time to connected peers.
|
||||
|
||||
@ -47,11 +57,13 @@ pear run pear://7to8bzrk53ab5ufwauqcw57s1kxmuykc9b8cdnjicaqcgoefa4wo
|
||||
- Modern, responsive UI built with **Bootstrap**.
|
||||
- Integrated terminal viewer powered by **Xterm.js**.
|
||||
- Real-time container stats displayed for each container.
|
||||
- View container logs directly from the UI.
|
||||
- Deploy containers using templates with a user-friendly wizard.
|
||||
|
||||
- **Production Deployment**:
|
||||
- Ready-to-use client app available via Pear runtime:
|
||||
```bash
|
||||
pear run pear://7to8bzrk53ab5ufwauqcw57s1kxmuykc9b8cdnjicaqcgoefa4wo
|
||||
pear run pear://7to8bzrk53ab5ufwauqcw57s1kxmuykcgoefa4wo
|
||||
```
|
||||
|
||||
---
|
||||
@ -102,15 +114,15 @@ Peers connect to the server using the unique topic derived from the `SERVER_KEY`
|
||||
|
||||
The server interacts with Docker using **Dockerode**:
|
||||
|
||||
- List containers:
|
||||
- **List Containers**:
|
||||
```javascript
|
||||
const containers = await docker.listContainers({ all: true });
|
||||
```
|
||||
- Start a container:
|
||||
- **Start a Container**:
|
||||
```javascript
|
||||
await docker.getContainer(containerId).start();
|
||||
```
|
||||
- Stream statistics:
|
||||
- **Stream Statistics**:
|
||||
```javascript
|
||||
container.stats({ stream: true }, (err, stream) => {
|
||||
stream.on('data', (data) => {
|
||||
@ -119,6 +131,8 @@ The server interacts with Docker using **Dockerode**:
|
||||
});
|
||||
});
|
||||
```
|
||||
- **Docker CLI Commands**:
|
||||
- Execute Docker commands received from the client within controlled parameters to ensure security.
|
||||
|
||||
---
|
||||
|
||||
@ -150,36 +164,37 @@ The server interacts with Docker using **Dockerode**:
|
||||
|
||||
### Server Setup
|
||||
|
||||
1. Clone the repository:
|
||||
1. **Clone the Repository**:
|
||||
```bash
|
||||
git clone https://git.ssh.surf/snxraven/peartainer.git
|
||||
cd peartainer
|
||||
```
|
||||
|
||||
2. Change to server Dir:
|
||||
2. **Change to Server Directory**:
|
||||
```bash
|
||||
cd server
|
||||
```
|
||||
|
||||
3. npm install:
|
||||
3. **Install Dependencies**:
|
||||
```bash
|
||||
npm install hyperswarm dockerode hypercore-crypto stream dotenv
|
||||
```
|
||||
|
||||
4. Run Server:
|
||||
4. **Run the Server**:
|
||||
```bash
|
||||
node server.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Client Setup
|
||||
|
||||
1. For development, run:
|
||||
1. **For Development**, run:
|
||||
```bash
|
||||
pear run --dev .
|
||||
```
|
||||
|
||||
2. For production, use the pre-deployed Pear app:
|
||||
2. **For Production**, use the pre-deployed Pear app:
|
||||
```bash
|
||||
pear run pear://7to8bzrk53ab5ufwauqcw57s1kxmuykc9b8cdnjicaqcgoefa4wo
|
||||
```
|
||||
@ -198,19 +213,85 @@ The server interacts with Docker using **Dockerode**:
|
||||
- **Listing Containers**:
|
||||
- View all containers (running and stopped) with their statuses.
|
||||
|
||||
- **Starting/Stopping Containers**:
|
||||
- Use the action buttons in the container list.
|
||||
- **Starting/Stopping/Restarting Containers**:
|
||||
- Use the action buttons (play, stop, restart icons) in the container list.
|
||||
|
||||
- **Removing Containers**:
|
||||
- Click the trash icon to delete a container.
|
||||
|
||||
- **Viewing Container Logs**:
|
||||
- Click the logs icon to view real-time and historical logs of 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.
|
||||
- **Container Terminal**:
|
||||
- Open terminals for running containers by clicking the terminal icon.
|
||||
- Switch between sessions using the tray at the bottom.
|
||||
|
||||
- **Docker CLI Terminal**:
|
||||
- Access a Docker CLI terminal to execute Docker commands on the remote peer.
|
||||
- Click the Docker terminal icon in the connection list.
|
||||
|
||||
### Template Deployment
|
||||
|
||||
- **Deploying from Templates**:
|
||||
- Open the template deployment modal by clicking the deploy template icon.
|
||||
- Search and select templates from the list.
|
||||
- Customize deployment parameters such as container name, image, ports, volumes, and environment variables.
|
||||
- Deploy the container with the specified settings.
|
||||
|
||||
---
|
||||
|
||||
## Screenshots
|
||||
|
||||
### Welcome Screen
|
||||
|
||||
|
||||
|
||||
*The initial welcome screen guiding users to add a connection.*
|
||||
|
||||
---
|
||||
|
||||
### Container List
|
||||
|
||||
|
||||
|
||||
*Displaying all Docker containers with real-time stats and action buttons.*
|
||||
|
||||
---
|
||||
|
||||
### Template Deployments
|
||||
|
||||
|
||||
|
||||
*Browsing and selecting templates for deployment from a remote repository.*
|
||||
|
||||
---
|
||||
|
||||
### Final Deploy Modal
|
||||
|
||||
|
||||
|
||||
*Customizing deployment parameters before launching a new container.*
|
||||
|
||||
---
|
||||
|
||||
### Duplicate Container Form
|
||||
|
||||
|
||||
|
||||
*Duplicating an existing container with options to modify configurations.*
|
||||
|
||||
---
|
||||
|
||||
### Container Logs
|
||||
|
||||
|
||||
|
||||
*Viewing real-time logs of a container directly from the UI.*
|
||||
|
||||
---
|
||||
|
||||
@ -232,7 +313,15 @@ The server interacts with Docker using **Dockerode**:
|
||||
|
||||
### Docker Commands
|
||||
|
||||
Add new commands in `server/server.js` under the `switch` statement for additional Docker functionalities.
|
||||
- Add new commands in `server/server.js` under the `switch` statement for additional Docker functionalities:
|
||||
```javascript
|
||||
switch (parsedData.command) {
|
||||
case 'newCommand':
|
||||
// Implement your command logic here
|
||||
break;
|
||||
// Existing cases...
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@ -240,6 +329,8 @@ Add new commands in `server/server.js` under the `switch` statement for addition
|
||||
|
||||
- The `SERVER_KEY` is sensitive and should be stored securely.
|
||||
- Refresh the key periodically to enhance security, especially in untrusted environments.
|
||||
- Peartainer uses encrypted peer-to-peer connections, but it's recommended to run it within secure networks.
|
||||
- Limit access to the server by controlling who has the `SERVER_KEY`.
|
||||
|
||||
---
|
||||
|
||||
@ -250,16 +341,72 @@ Add new commands in `server/server.js` under the `switch` statement for addition
|
||||
1. **Unable to Connect**:
|
||||
- Verify the `SERVER_KEY` matches on both server and client.
|
||||
- Ensure the server is running and accessible.
|
||||
- Check network configurations and firewall settings.
|
||||
|
||||
2. **Docker Errors**:
|
||||
- Ensure Docker is running and properly configured.
|
||||
- Check permissions to manage Docker.
|
||||
- Verify that the user running the server has access to the Docker daemon.
|
||||
|
||||
3. **Terminal Issues**:
|
||||
- Verify the container has a valid shell (e.g., `/bin/bash`).
|
||||
- Ensure that the container is running before opening a terminal.
|
||||
- Check for network latency that might affect terminal responsiveness.
|
||||
|
||||
4. **Template Deployment Failures**:
|
||||
- Ensure the Docker image specified in the template is valid and accessible.
|
||||
- Check network connectivity if pulling images from remote repositories.
|
||||
- Validate all required parameters in the deployment form.
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome! Fork the repository, make your changes, and submit a pull request.
|
||||
Contributions are welcome! Fork the repository, make your changes, and submit a pull request.
|
||||
|
||||
1. **Fork the Repository**:
|
||||
- Click the "Fork" button at the top of the repository page.
|
||||
|
||||
2. **Clone Your Fork**:
|
||||
```bash
|
||||
git clone https://github.com/your-username/peartainer.git
|
||||
```
|
||||
|
||||
3. **Create a Branch for Your Feature**:
|
||||
```bash
|
||||
git checkout -b feature/your-feature-name
|
||||
```
|
||||
|
||||
4. **Make Changes and Commit**:
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Add your feature"
|
||||
```
|
||||
|
||||
5. **Push to Your Fork**:
|
||||
```bash
|
||||
git push origin feature/your-feature-name
|
||||
```
|
||||
|
||||
6. **Submit a Pull Request**:
|
||||
- Go to your fork on GitHub and click the "New pull request" button.
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
Peartainer is released under the [MIT License](LICENSE).
|
||||
|
||||
---
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
- **Portainer**: For inspiring the creation of a powerful Docker management tool.
|
||||
- **Hyperswarm**: Providing the peer-to-peer networking backbone.
|
||||
- **Dockerode**: Facilitating Docker API interactions in Node.js.
|
||||
|
||||
---
|
||||
|
||||
## Contact
|
||||
|
||||
For questions, issues, or suggestions, please open an issue on the [GitHub repository](https://git.ssh.surf/snxraven/peartainer).
|
||||
Loading…
Reference in New Issue
Block a user