Updated README.md

2025-01-19 11:33:09 +00:00 · 2025-01-19 11:33:09 +00:00 · a91364dabe
commit a91364dabe
parent b13125c8d8
1 changed files with 131 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -1,3 +1,134 @@
 # echoip-server-setup

 Scripts and configuration files for quickly setting up the echo lookup server created by mpolden - https://github.com/mpolden/echoip
+The main persose of this project was to create a repository of config file for my setup, in the even I needed to quickly rebuild this service.
+
+This project provides an easy and fast way to set up EchoIP, a service that offers IP geolocation lookups, using the MaxMind GeoLite2 databases (City, ASN, and Country). The goal of this project is to streamline the deployment of EchoIP by automating the process of downloading, extracting, and organizing the required GeoLite2 data files, then running the service in a Docker container.
+
+
+
+# GeoLite2 IP Geolocation Service
+
+This project provides a geolocation service using the MaxMind GeoLite2 databases. It includes a Bash script to download, extract, and organize the required GeoLite2 database files, sets up an EchoIP service using Docker to provide IP geolocation data based on the downloaded databases, and configures an Apache HTTP server to proxy requests to the EchoIP service.
+
+## Features
+
+- Downloads and extracts GeoLite2 databases (City, ASN, Country).
+- Runs an EchoIP service in a Docker container to provide geolocation lookup via the GeoLite2 databases.
+- Configures Apache HTTP Server to proxy requests to EchoIP.
+
+## Prerequisites
+
+Before setting up the project, ensure the following tools are installed:
+
+- [Docker](https://www.docker.com/get-started) (for running the EchoIP service)
+- [Docker Compose](https://docs.docker.com/compose/install/) (for managing Docker services)
+- [Apache HTTP Server](https://httpd.apache.org/) (for proxying requests to EchoIP)
+- A MaxMind account with access to the [GeoLite2 databases](https://dev.maxmind.com/geoip/geoip2/geolite2/).
+
+## Setup Instructions
+
+### 1. Download GeoLite2 Databases
+
+To download the required databases (GeoLite2-City, GeoLite2-ASN, and GeoLite2-Country), you can run the provided Bash script.
+
+#### Bash Script (`download_geoip.sh`)
+
+The `download_geoip.sh` script will:
+
+- Download the required GeoLite2 databases from MaxMind.
+- Extract the `.tar.gz` files.
+- Organize the extracted files into the appropriate folders: `city`, `asn`, and `country`.
+
+#### Configuration
+
+- Set your MaxMind account ID and license key in the `AUTH` variable:
+  
+  ```bash
+  AUTH="YOUR_ACCOUNT_ID:YOUR_LICENSE_KEY"
+
+    The downloaded and extracted database files will be placed in the geolite2/db directory structure.
+
+Run the script:
+
+chmod +x download_geoip.sh
+./download_geoip.sh
+
+### 2. Docker Setup for EchoIP
+
+The Docker container uses the mpolden/echoip:latest image, which serves IP geolocation data based on the GeoLite2 databases. The docker-compose.yml file is provided to set up the service.
+Docker Compose Configuration (docker-compose.yml)
+
+This file defines the EchoIP service and mounts the database files for the container to access. It also binds the service to port 8085.
+Configuration
+
+Make sure the volumes section correctly points to the geolite2/db directory:
+
+volumes:
+  - ./geolite2/db/:/geolite2/db/:ro
+
+Start the Docker container:
+
+docker-compose up -d
+
+### 3. Apache Setup
+
+To proxy requests to the EchoIP service, you'll need to configure your Apache HTTP server.
+Apache Configuration (apache_config.conf)
+
+Add the following configuration to your Apache server's configuration file (httpd.conf or a dedicated virtual host file). This configures Apache to forward requests to the EchoIP service running on localhost:8085 and supports the X-Forwarded-For header.
+
+```
+<VirtualHost *:80>
+  ServerName FULLY.QUALIFIED.DOMAIN.NAME
+  RemoteIPHeader CF-Connecting-IP
+
+  ProxyPreserveHost On
+  ProxyRequests Off
+
+  ProxyPass / http://127.0.0.1:8085/
+  ProxyPassReverse / http://127.0.0.1:8085
+
+  # Add support for X-Forwarded-For
+  RequestHeader set X-Forwarded-For "%{REMOTE_ADDR}s"
+
+  ErrorLog ${APACHE_LOG_DIR}/echoip-error.log
+  CustomLog ${APACHE_LOG_DIR}/echoip-access.log combined
+</VirtualHost>
+```
+Replace FULLY.QUALIFIED.DOMAIN.NAME with your server's domain name.
+
+Restart Apache:
+
+```
+sudo systemctl restart apache2
+```
+
+Accessing the Service
+
+After setting up Docker and Apache:
+
+    The EchoIP service will be accessible through Apache on the domain you configured.
+    You can query geolocation data by making requests to the configured server.
+
+For example, a request to http://FULLY.QUALIFIED.DOMAIN.NAME/ip/8.8.8.8 will return geolocation information for the IP address 8.8.8.8.
+File Structure
+```
+.
+├── apache_config.conf          # Apache virtual host configuration
+├── download_geoip.sh           # Bash script for downloading and extracting GeoLite2 databases
+├── docker-compose.yml          # Docker Compose configuration for EchoIP service
+└── geolite2/
+    └── db/
+        ├── city/               # GeoLite2-City database
+        ├── asn/                # GeoLite2-ASN database
+        └── country/            # GeoLite2-Country database
+```
+
+Troubleshooting
+
+    Ensure that your MaxMind credentials are correct in the download_geoip.sh script.
+    Check the Apache logs (/var/log/apache2/echoip-error.log) for any issues related to the proxy configuration.
+    If Docker fails to start the EchoIP container, check the Docker logs with docker logs echoip.
+
+