nemanjaslijepcevic/public_ip_tracker

By nemanjaslijepcevic

Updated 3 months ago

Tracks your public IP, sends Telegram alerts on changes, and offers secure API access, even via VPN.

Image
Networking
0

69

Public IP Tracking and Notification App

This application tracks your public IP address and provides a REST API endpoint to retrieve the current IP address, secured by a bearer token.

This setup is particularly useful for machines behind Carrier-Grade NAT (CGNAT), where direct access from the internet is not possible due to shared public IPs. By running a VPN on the machine, you can access the API endpoint securely via the VPN connection, even when the machine is behind CGNAT. This allows you to reliably track and retrieve the public IP address of your machine through the VPN without needing a public-facing IP address.

Features

  • Public IP Tracking: Periodically checks your public IP address.
  • Telegram Notifications: Sends a Telegram message when your IP changes. (Supported until 1.1.0)
  • REST API: Provides an API to fetch the current IP address.
  • Logging: Logs all actions to both the console and a log file (app.log).

Setup

Environment Variables

The application relies on the following environment variables:

VariableDescription
TELEGRAM_BOT_TOKENYour Telegram bot token (required). (Supported until v1.1.0)
TELEGRAM_CHAT_IDThe chat ID where the bot sends notifications (required). (Supported until v1.1.0)
API_IP_TOKENBearer token for accessing the /current_ip API (required).
IP_FILE_NAMEName of the file storing the current IP (default: current_ip.txt).
LOG_LEVELLogging level (default: INFO).
CHECK_FREQUENCYTask execution frequency in sedonds (default: 60).

API

Get Current IP

You can retrieve the current public IP address by making a GET request to /current_ip:

  • URL: /current_ip
  • Method: GET
  • Headers: Authorization: Bearer <API_IP_TOKEN>

Example:

curl -H "Authorization: Bearer your_api_token" http://localhost:5000/current_ip

Response:

{
  "ip": "123.45.67.89"
}

Docker

You can run the application in a Docker container using the provided Dockerfile. The latest Docker image for this application is available at ghcr.io/nemanjaslijepcevic/public_ip_tracker:latest.

Using Pre-Built Docker Image
  1. Pull the latest image from GitHub Container Registry (GHCR):

    docker pull ghcr.io/nemanjaslijepcevic/public_ip_tracker:latest
    
  2. Run the Docker container:

    docker run -d \
      --name public_ip_tracker \
      -e API_IP_TOKEN="${API_IP_TOKEN}" \
      -e TZ="Europe/Belgrade" \
      -e LOG_LEVEL="DEBUG" \
      --restart unless-stopped \
      nemanjaslijepcevic/public_ip_tracker:latest
    

    This command pulls and runs the container in detached mode (-d), mapping port 5000 on your host to port 5000 in the container. The --env-file .env flag ensures that the required environment variables are provided to the container.

Docker Compose

For easier management of Docker containers and environment configuration, you can use Docker Compose.

  1. Create a docker-compose.yml file in the root of your project:

    version: '3'
    
    services:
      public_ip_tracker:
        image: nemanjaslijepcevic/public_ip_tracker:latest
        container_name: public_ip_tracker
        environment:
          API_IP_TOKEN: "${API_IP_TOKEN}"
          TZ: "Europe/Belgrade"
          LOG_LEVEL: "DEBUG"
        volumes:
          - /path/to/current_ip.txt:/app/current_ip.txt:rw # optional
        restart: unless-stopped
    

    This configuration does the following:

    • Builds the Docker image from the current directory.
    • Exposes the app on port 5000.
    • Restarts the container unless it's stopped manually.
  2. Build and run with Docker Compose:

    Run the following command to build and start the application using Docker Compose:

    docker-compose up --build -d
    

    The --build flag forces a rebuild of the Docker image, and -d runs the containers in detached mode.

  3. Stopping the app:

    To stop the app when running with Docker Compose:

    docker-compose down
    

    This will stop and remove the containers but leave the images intact.

Building and Running with Docker
  1. Build the Docker image:

    docker build -t public_ip_tracker .
    

    This command will create a Docker image with the name public_ip_tracker.

  2. Run the Docker container:

    Once the image is built, you can run the application in a Docker container:

    docker run -d -p 5000:5000 --env-file .env public_ip_tracker
    

    This will run the container in detached mode (-d), mapping port 5000 on your host to port 5000 in the container. The --env-file .env flag ensures that the required environment variables are provided to the container.

  3. Access the app:

    After starting the container, the application will be accessible at http://localhost:5000.

This setup with Docker and Docker Compose makes it easy to deploy, manage, and run the application in a consistent environment.

Running Tests

You can run the unit tests using pytest. If you have Docker configured for testing, you can use it as well.

Deployment

This application can be deployed on any server that supports Docker. Make sure to configure the environment variables correctly for the production environment.


Important Update: Telegram Notifications Feature Change

With 1.2.0 release, the application no longer supports sending messages via Telegram. For users who wish to continue receiving Telegram notifications for events such as IP changes, we recommend switching to our new application, log_notification, which offers enhanced functionality and customization.

Introducing Log Notification

The log_notification application allows you to monitor logs and send notifications over Telegram with significantly improved control and flexibility. You can now define custom notification patterns, such as WARNING, EXCEPTION, ERROR, or any specific log content that you want to be notified about.

Docker Pull Command

docker pull nemanjaslijepcevic/public_ip_tracker