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

docker network create holesail

Build the Image

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

docker build -t holesail:latest .

Usage Examples

Server Mode

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

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:

docker compose up --build -d

Client Mode

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

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:

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:

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

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.