holesail-docker/README.md

# Holesail-docker

Holesail-docker is a Docker container that facilitates proxying traffic between containers or to external hosts, supporting server, client, and file manager modes.

## Overview

This project provides a Dockerized version of the Holesail tool, enabling seamless network tunneling and file sharing. It supports three operational modes:
- **Server**: Proxies traffic to another container or service.
- **Client**: Connects to a remote server for tunneling.
- **Filemanager**: Serves a web-based file management interface.

## Environment Variables

Customize the container's behavior using the following environment variables:

| Variable   | Description                                                                 | Applicable Modes            | Default       |
|------------|-----------------------------------------------------------------------------|-----------------------------|---------------|
| `MODE`     | Operation mode: `server`, `client`, or `filemanager`.                        | All                         | `server`      |
| `HOST`     | Hostname or IP address for connection.                                      | All                         | `0.0.0.0`     |
| `PORT`     | Port number for the connection.                                             | `server`, `client`          | `8989`        |
| `PUBLIC`   | Enable public connector string (boolean: `true` or `false`).                 | `server`, `filemanager`     | `true`        |
| `FORCE`    | Force a short connector string (<32 chars, boolean: `true` or `false`).      | `server`, `filemanager`     | `""` (false)  |
| `CONNECTOR`| Connector string for identifying the connection.                            | All                         | `""` (empty)  |
| `USERNAME` | Username for authentication.                                                | `filemanager`               | `admin`       |
| `PASSWORD` | Password for authentication.                                                | `filemanager`               | `admin`       |
| `ROLE`     | User role: `admin` or `user`.                                               | `filemanager`               | `user`        |
| `UDP`      | Enable UDP protocol (boolean: `true` or `false`).                            | `server`, `client`          | `false`       |

## Setup

### Prerequisites

- Docker and Docker Compose installed.
- A Docker network for container communication.

### Create a Docker Network

```bash
docker network create holesail
```

### Build the Image

1. Clone the repository or create the following files:
   - `Dockerfile` (as provided in your query).
   - `run.sh` (as provided in your query).

2. Build the Docker image:

```bash
docker build -t holesail:latest .
```

## Usage Examples

### Server Mode

Proxies traffic to another container, e.g., a Minecraft server. Example `docker-compose.yml`:

```yaml
services:
  holesail:
    container_name: holesail
    build: .
    restart: unless-stopped
    environment:
      MODE: server
      PORT: 25565
      HOST: minecraft
      PUBLIC: false
      CONNECTOR: very-super-secret
    networks:
      - holesail

  minecraft:
    image: itzg/minecraft-server
    container_name: minecraft
    restart: unless-stopped
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE"
    volumes:
      - ./minecraft-data:/data
    networks:
      - holesail

networks:
  holesail:
    external: true
```

Run with:

```bash
docker compose up --build -d
```

### Client Mode

Connects to a remote server. Requires host network mode and is Linux-only. Example `docker-compose.yml`:

```yaml
services:
  holesail:
    container_name: holesail
    build: .
    restart: unless-stopped
    network_mode: "host"
    environment:
      MODE: client
      PORT: 8989
      HOST: 0.0.0.0
      CONNECTOR: very-super-secret
```

**Note**: Client mode is incompatible with Windows and macOS due to host network requirements.

### Filemanager Mode

Serves a web-based file manager. Example `docker-compose.yml`:

```yaml
services:
  holesail:
    container_name: holesail
    build: .
    restart: unless-stopped
    environment:
      MODE: filemanager
      PORT: 8989
      HOST: 0.0.0.0
      PUBLIC: true
      USERNAME: admin
      PASSWORD: admin
      ROLE: user
      CONNECTOR: very-super-secret
    volumes:
      - /path/to/share:/data
```

Replace `/path/to/share` with the host directory to share. Access the file manager at `http://<host>:8989`.

## Development

To develop and test locally:

1. Clone the repository or ensure `Dockerfile` and `run.sh` are in your working directory.
2. Create a `docker-compose.yml` (e.g., use the Server Mode example above).
3. Run:

```bash
docker compose up --build
```

This rebuilds the image and starts the containers.

## Notes

- Ensure the Docker network (`holesail`) exists before running containers.
- In `filemanager` mode, the `/data` directory in the container maps to the shared host directory.
- The `EXPOSE 8989` line in the Dockerfile is commented out, so explicitly map ports in `docker run` or `docker-compose.yml` if needed.
- The image is built with `holesail@2.1.0` installed via npm.

## Troubleshooting

- **Invalid Mode Error**: Ensure `MODE` is set to `server`, `client`, or `filemanager`.
- **Connection Issues**: Verify `HOST`, `PORT`, and `CONNECTOR` values match between client and server.
- **Filemanager Access**: Check `USERNAME`, `PASSWORD`, and `ROLE` settings, and ensure the correct port is mapped.
- **Build Errors**: Ensure `node:lts-slim` is available and you have internet access for npm install.

For further assistance, check the Holesail documentation or open an issue on the repository.