diff --git a/README.md b/README.md index 734406b..3522b54 100644 --- a/README.md +++ b/README.md @@ -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: - - :/data + - /path/to/share:/data ``` -Replace `` with the directory you wish to share. +Replace `/path/to/share` with the host directory to share. Access the file manager at `http://: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. \ No newline at end of file