dlinux-community/holesail-docker
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update readme
Some checks failed
Docker image CI for GHCR / build_and_publish (push) Has been cancelled
Details

Browse Source
This commit is contained in:
snxraven 2025-06-06 19:07:25 -04:00
parent 7697b5862e
commit f819bf904b
1 changed files with 72 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

158
README.md
View File

@ -1,66 +1,68 @@
# Holesail-docker
- [ ] TODO: Make README more clear.
Holesail-docker is a Docker container that facilitates proxying traffic between containers or to external hosts, supporting server, client, and file manager modes.
Holesail-docker is a Docker container that proxies traffic from or to other containers.
## Overview
Environment Variables
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.
The container uses several environment variables to customize its behavior. These variables can be set when running the container using the -e flag.
## Environment Variables
## Available Environment Variables
Customize the container's behavior using the following environment variables:
The following environment variables are available:
- MODE: The mode in which the container should run. Can be one of client, server, or filemanager.
- PORT: The port number to use for the client or server mode.
- HOST: The hostname or IP address to use for the client or server mode.
- PUBLIC: A boolean value indicating whether the server should use a public connetor string. Only applicable in server mode.
- FORCE: A boolean value indicating whether to force a short connector string of less than 32 chars. Only applicable in server and filemanager modes.
- CONNECTOR: A connector string used to identify the connection. Can be used in client, server, and filemanager modes.
- USERNAME: The username to use for authentication in filemanager mode.
- PASSWORD: The password to use for authentication in filemanager mode.
- ROLE: The role to assign to the user in filemanager mode. Can be either admin or user.
| 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
### Create a Docker Network
### Prerequisites
Create a Docker network to connect your containers:
- Docker and Docker Compose installed.
- A Docker network for container communication.
### Create a Docker Network
```bash
docker network create holesail
```
### Use the Image
### Build the Image
Use the latest Holesail-docker 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 run -d --name holesail \
-e MODE=server \
-e PORT=25565 \
-e HOST=minecraft \
-e CONNECTOR=very-super-secret \
-e PUBLIC=false \
--network holesail \
anaxios/holesail:latest
docker build -t holesail:latest .
```
## Modes
Holesail-docker can run in three modes: Server, Client, and Filemanager.
## Usage Examples
### Server Mode
In Server mode, Holesail-docker proxies traffic from one container to another. Example `docker-compose.yml` file:
Proxies traffic to another container, e.g., a Minecraft server. Example `docker-compose.yml`:
```yaml
services:
holesail:
container_name: holesail
build: .
restart: unless-stopped
image: anaxios/holesail:latest
environment:
MODE: server
PORT: 25565
@ -70,20 +72,16 @@ services:
networks:
- holesail
mc:
minecraft:
image: itzg/minecraft-server
container_name: minecraft
tty: true
stdin_open: true
restart: unless-stopped
ports:
- "25565:25565"
environment:
EULA: "TRUE"
volumes:
- ./data:/data
depends_on:
- holesail
- ./minecraft-data:/data
networks:
- holesail
@ -92,95 +90,83 @@ networks:
external: true
```
Run with:
```bash
docker compose up --build -d
```
### Client Mode
In Client mode, Holesail-docker connects to a remote host. Example `docker-compose.yml` file:
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"
image: anaxios/holesail:latest
environment:
MODE: client
PORT: 8989
HOST: 0.0.0.0
PUBLIC: false
CONNECTOR: very-super-secret
```
**Note:** Client mode only works on Linux, and is incompatible with Windows and Mac.
**Note**: Client mode is incompatible with Windows and macOS due to host network requirements.
### Filemanager Mode
In Filemanager mode, Holesail-docker serves a file manager interface. Example `docker-compose.yml` file:
Serves a web-based file manager. Example `docker-compose.yml`:
```yaml
services:
holesail:
container_name: holesail
build: .
restart: unless-stopped
image: anaxios/holesail:latest
environment:
MODE: filemanager
PORT: 8989
HOST: 0.0.0.0
PUBLIC: true
ROLE: user
USERNAME: admin
PASSWORD: admin
ROLE: user
CONNECTOR: very-super-secret
volumes:
- <host dir>:/data
- /path/to/share:/data
```
Replace `<host dir>` with the directory you wish to share.
Replace `/path/to/share` with the host directory to share. Access the file manager at `http://<host>:8989`.
## Development
To develop Holesail-docker, clone this repository, create docker-compose.yml and run:
To develop and test locally:
```yaml
services:
holesail:
container_name: holesail
restart: unless-stopped
build: .
environment:
MODE: server
PORT: 25565
HOST: minecraft
PUBLIC: false
CONNECTOR: very-super-secret
networks:
- holesail
mc:
image: itzg/minecraft-server
container_name: minecraft
tty: true
stdin_open: true
restart: unless-stopped
ports:
- "25565:25565"
environment:
EULA: "TRUE"
volumes:
- ./data:/data
depends_on:
- holesail
networks:
- holesail
networks:
holesail:
external: true
```
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 will start the containers and rebuild the image if necessary.
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.