colin
/
host-port-ingress-proxy
1
0
Fork 0
Code Pull Requests Activity

Update README.md

This commit is contained in:
colin 2023-12-12 16:54:13 +00:00
parent 9972656e5f
commit 5ea048a78a
1 changed files with 40 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
README.md
View File

@ -1,38 +1,51 @@
Nginx Reverse Proxy Setup
### host-port-ingress-proxy
This repository provides a setup to run an Nginx container as a reverse proxy. The backend address and port can be set via environment variables.
Repository Structure
1. **Docker Container Setup**:
- The Docker container is based on the official NGINX Alpine image.
- Several environment variables are defined in the Dockerfile to configure the NGINX reverse proxy. These include `BACKEND_HOST`, `BACKEND_TCP_PORT`, `BACKEND_UDP_PORT`, and `ALLOWED_IPS`.
- The Dockerfile also installs `curl` for health checking purposes and includes a custom entrypoint script.
Dockerfile: Contains instructions to build the custom Nginx Docker image.
nginx.conf: Nginx configuration to set up reverse proxy using environment variables.
docker-compose.yml: Docker Compose configuration to build and run the Nginx container.
2. **NGINX Configuration**:
- A template for the NGINX configuration (`nginx.conf.template`) is used. This template is processed by the entrypoint script (`entrypoint.sh`) to replace placeholders with the actual environment variable values.
- The NGINX configuration sets up NGINX as a reverse proxy to forward TCP and UDP traffic to the configured backend host and ports. It also includes IP-based access control.
- Additionally, NGINX listens on a separate HTTP port (8080) with a specific location (`/healthz`) that always returns a `200 OK` response. This endpoint is used for health checks.
Setup Instructions
1. Clone the Repository
3. **Health Checking**:
- The Dockerfile defines a `HEALTHCHECK` instruction that uses `curl` to periodically check the health of the NGINX server by accessing the `/healthz` endpoint.
- If the health check fails (does not return `200 OK`), Docker marks the container as unhealthy.
To get started, first clone the repository:
4. **Running the Container**:
- When the container is run, the environment variables can be set to define the backend host, ports, and allowed IPs.
- Docker's health check mechanism monitors the container's health status by checking the `/healthz` endpoint.
bash
### Mermaid Diagram
git clone https://codeberg.org/Iridium-net/lan-to-nginx.git
cd lan-to-nginx
Here's a Mermaid diagram that visualizes the flow:
2. Modify Environment Variables (Optional)
```mermaid
graph LR
subgraph Docker Container
NGINX[NGINX Reverse Proxy]
ENTRYPOINT[Entrypoint Script]
CONFIG[nginx.conf.template]
HEALTHCHECK[Health Check]
The docker-compose.yml file has environment variables set for a backend address of 192.168.8.1 and port 80. If you want to point the reverse proxy to a different backend, modify the docker-compose.yml file and adjust the BACKEND_ADDRESS and BACKEND_PORT environment variables.
3. Build and Run
ENTRYPOINT -->|Processes| CONFIG
CONFIG -->|Configures| NGINX
NGINX -->|TCP/UDP Proxy| BACKEND[Backend Service]
NGINX -->|HTTP Health Check| HEALTHCHECK
HEALTHCHECK -->|curl /healthz| NGINX
end
Using Docker Compose, build and run the setup:
USER[User] -->|TCP/UDP Request| NGINX
NGINX -->|Responds| USER
DOCKER[Docker Daemon] -->|Periodic Check| HEALTHCHECK
bash
style NGINX fill:#f96,stroke:#333,stroke-width:2px
style BACKEND fill:#ff9,stroke:#333,stroke-width:2px
style USER fill:#9f6,stroke:#333,stroke-width:2px
style HEALTHCHECK fill:#6f9,stroke:#333,stroke-width:2px
style DOCKER fill:#f69,stroke:#333,stroke-width:2px
```
docker-compose up --build -d
The --build flag ensures that the image is built using the provided Dockerfile. The -d flag runs the container in detached mode.
4. Access
Once the container is running, access any machine where Docker is running on port 80. It will reverse proxy the request to the backend specified (in this example, 192.168.8.1:80).
Notes
This setup uses the image from codeberg.org/Iridium-net/lan-to-nginx:latest. If you modify the Dockerfile and wish to use the locally built image, the docker-compose.yml configuration takes care of this by specifying both a build context and an image name.
Make sure to adjust firewall or security group settings if you're running this in a cloud environment or behind a firewall.
This diagram represents the flow of requests through the NGINX reverse proxy and how the health check mechanism works within the Docker container. The `NGINX Reverse Proxy` handles both TCP/UDP requests and health check requests, forwarding the former to the `Backend Service` and responding directly to the latter. The `Docker Daemon` periodically triggers the health check to ensure the NGINX server is functioning correctly.