From 021e8acd3b371c87e9f884d714eb6e1ca9d51cb3 Mon Sep 17 00:00:00 2001 From: anaxios Date: Tue, 13 Aug 2024 21:44:59 -0700 Subject: [PATCH] Update README.md: reorganize content, add warnings, and improve documentation for setup, modes, and development. --- README.md | 124 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 83 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 681ae4c..c2ace17 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,60 @@ # Holesail-docker -> ⚠️ **Warning!** Some of these features are untested. +================ -Holesail-docker proxies traffic from or to other containers. +**Warning!** Some of these features are untested. -Clone this repo then from within the directory run: -``` -docker compose up --build -``` +Holesail-docker is a Docker container that proxies traffic from or to other containers. -The easiest way to do this is to create a network in Docker: -``` -docker network create proxy -``` -## Server mode +## Setup -You can then use the contaier name and port of the container you want to proxy, as exampled below. - -``` --- + +### Create a Docker Network + +Create a Docker network to connect your containers: + +```bash +docker network create holesail +``` + +### Pull the Image + +Pull the latest Holesail-docker image: + +```bash +docker run -d --name holesail \ + -e MODE=server \ + -e PORT=25565 \ + -e HOST=minecraft \ + -e CONNECTOR=very-super-secret \ + --network holesail \ + ghcr.io/anaxios/holesail-docker:latest +``` + +## Modes + +--- + +Holesail-docker can run in three modes: Server, Client, and Filemanager. + +### Server Mode + +In Server mode, Holesail-docker proxies traffic from one container to another. Example `docker-compose.yml` file: + +```yaml services: holesail: container_name: holesail restart: unless-stopped - build: . + image: ghcr.io/anaxios/holesail-docker:latest environment: - MODE: server # defaults to client + MODE: server PORT: 25565 - HOST: minecraft # defaults to 0.0.0.0 - CONNECTOR: very-super-secret # leave this blank to generate a random secret. + HOST: minecraft + CONNECTOR: very-super-secret networks: - - proxy + - holesail mc: image: itzg/minecraft-server @@ -47,50 +71,68 @@ services: depends_on: - holesail networks: - - proxy + - holesail networks: - proxy: - external: true + holesail: + external: true ``` -## Client Mode +### Client Mode -Client mode is untested! +**Note:** Client mode is untested! -``` +In Client mode, Holesail-docker connects to a remote host. Example `docker-compose.yml` file: + +```yaml services: holesail: container_name: holesail restart: unless-stopped - network_mode: "host" # host mode is required - build: . + network_mode: "host" + image: ghcr.io/anaxios/holesail-docker:latest environment: - MODE: client # defaults to client + MODE: client PORT: 8989 - HOST: 0.0.0.0 # defaults to 0.0.0.0 - CONNECTOR: very-super-secret # leave this blank to generate a random secret. + HOST: 0.0.0.0 + CONNECTOR: very-super-secret ``` -"host" network mode only works with linux. Windows and Mac are incompatible. +**Note:** Client mode only works on Linux, and is incompatible with Windows and Mac. -## Filemanager Mode +### Filemanager Mode -``` +In Filemanager mode, Holesail-docker serves a file manager interface. Example `docker-compose.yml` file: + +```yaml services: holesail: container_name: holesail restart: unless-stopped - build: . + image: ghcr.io/anaxios/holesail-docker:latest environment: - MODE: filemanager # defaults to client - PORT: 8989 - HOST: 0.0.0.0 # defaults to 0.0.0.0 - PUBLIC: true # Defaults to true - ROLE: user # admin for write priveleges. + MODE: filemanager + PORT: 8989 + HOST: 0.0.0.0 + PUBLIC: true + ROLE: user USERNAME: admin PASSWORD: admin - CONNECTOR: very-super-secret # leave this blank to generate a random secret. + CONNECTOR: very-super-secret volumes: - - :/data # Change to the directory you wish to share. + - :/data ``` + +Replace `` with the directory you wish to share. + +## Development + +--- + +To develop Holesail-docker, clone this repository and run: + +```bash +docker compose up --build +``` + +This will start the containers and rebuild the image if necessary.