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 # 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: | Variable | Description | Applicable Modes | Default |
|------------|-----------------------------------------------------------------------------|-----------------------------|---------------|
- MODE: The mode in which the container should run. Can be one of client, server, or filemanager. | `MODE` | Operation mode: `server`, `client`, or `filemanager`. | All | `server` |
- PORT: The port number to use for the client or server mode. | `HOST` | Hostname or IP address for connection. | All | `0.0.0.0` |
- HOST: The hostname or IP address to use for the client or server mode. | `PORT` | Port number for the connection. | `server`, `client` | `8989` |
- PUBLIC: A boolean value indicating whether the server should use a public connetor string. Only applicable in server mode. | `PUBLIC` | Enable public connector string (boolean: `true` or `false`). | `server`, `filemanager` | `true` |
- FORCE: A boolean value indicating whether to force a short connector string of less than 32 chars. Only applicable in server and filemanager modes. | `FORCE` | Force a short connector string (<32 chars, boolean: `true` or `false`). | `server`, `filemanager` | `""` (false) |
- CONNECTOR: A connector string used to identify the connection. Can be used in client, server, and filemanager modes. | `CONNECTOR`| Connector string for identifying the connection. | All | `""` (empty) |
- USERNAME: The username to use for authentication in filemanager mode. | `USERNAME` | Username for authentication. | `filemanager` | `admin` |
- PASSWORD: The password to use for authentication in filemanager mode. | `PASSWORD` | Password for authentication. | `filemanager` | `admin` |
- ROLE: The role to assign to the user in filemanager mode. Can be either admin or user. | `ROLE` | User role: `admin` or `user`. | `filemanager` | `user` |
| `UDP` | Enable UDP protocol (boolean: `true` or `false`). | `server`, `client` | `false` |
## Setup ## 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 ```bash
docker network create holesail 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 ```bash
docker run -d --name holesail \ docker build -t holesail:latest .
-e MODE=server \
-e PORT=25565 \
-e HOST=minecraft \
-e CONNECTOR=very-super-secret \
-e PUBLIC=false \
--network holesail \
anaxios/holesail:latest
``` ```
## Modes ## Usage Examples
Holesail-docker can run in three modes: Server, Client, and Filemanager.
### Server Mode ### 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 ```yaml
services: services:
holesail: holesail:
container_name: holesail container_name: holesail
build: .
restart: unless-stopped restart: unless-stopped
image: anaxios/holesail:latest
environment: environment:
MODE: server MODE: server
PORT: 25565 PORT: 25565
@ -70,20 +72,16 @@ services:
networks: networks:
- holesail - holesail
mc: minecraft:
image: itzg/minecraft-server image: itzg/minecraft-server
container_name: minecraft container_name: minecraft
tty: true
stdin_open: true
restart: unless-stopped restart: unless-stopped
ports: ports:
- "25565:25565" - "25565:25565"
environment: environment:
EULA: "TRUE" EULA: "TRUE"
volumes: volumes:
- ./data:/data - ./minecraft-data:/data
depends_on:
- holesail
networks: networks:
- holesail - holesail
@ -92,95 +90,83 @@ networks:
external: true external: true
``` ```
Run with:
```bash
docker compose up --build -d
```
### Client Mode ### 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 ```yaml
services: services:
holesail: holesail:
container_name: holesail container_name: holesail
build: .
restart: unless-stopped restart: unless-stopped
network_mode: "host" network_mode: "host"
image: anaxios/holesail:latest
environment: environment:
MODE: client MODE: client
PORT: 8989 PORT: 8989
HOST: 0.0.0.0 HOST: 0.0.0.0
PUBLIC: false
CONNECTOR: very-super-secret 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 ### 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 ```yaml
services: services:
holesail: holesail:
container_name: holesail container_name: holesail
build: .
restart: unless-stopped restart: unless-stopped
image: anaxios/holesail:latest
environment: environment:
MODE: filemanager MODE: filemanager
PORT: 8989 PORT: 8989
HOST: 0.0.0.0 HOST: 0.0.0.0
PUBLIC: true PUBLIC: true
ROLE: user
USERNAME: admin USERNAME: admin
PASSWORD: admin PASSWORD: admin
ROLE: user
CONNECTOR: very-super-secret CONNECTOR: very-super-secret
volumes: 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 ## Development
To develop Holesail-docker, clone this repository, create docker-compose.yml and run: To develop and test locally:
```yaml 1. Clone the repository or ensure `Dockerfile` and `run.sh` are in your working directory.
services: 2. Create a `docker-compose.yml` (e.g., use the Server Mode example above).
holesail: 3. Run:
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
```
```bash ```bash
docker compose up --build 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.