Squashed commit of the following:

commit 50f699bb966a014c92ecbb05f96a05fe515ff6d8
Author: Foster Hangdaan <foster@hangdaan.email>
Date:   Tue Nov 14 20:58:51 2023 -0500

    doc: Update README.org

    - Added a table of API URLs with their respective response type and
      sample output.
    - Place the `curl` examples in their own section.

commit 28d1bdc4e457cfc44830c8a20013a3f588dafca4
Author: Foster Hangdaan <foster@hangdaan.email>
Date:   Tue Nov 14 20:46:59 2023 -0500

    feat: Added `jsonp` format

    Accepts the `callback` query param for changing the name of the callback function.

commit 126455a3fd96ec3a998847e29cbdcefbd18b16ac
Author: Foster Hangdaan <foster@hangdaan.email>
Date:   Tue Nov 14 20:35:30 2023 -0500

    refactor: Convert `if...else` to `switch`

commit 8945673d5e0644ab6aea8dc268cbaeb12530649c
Author: Foster Hangdaan <foster@hangdaan.email>
Date:   Tue Nov 14 05:50:20 2023 -0500

    doc: Update README.org

    - Added new sections.
    - Moved copyright text into its own section.
    - Some minor edits here and there.

commit f5a6804a9ea57ad52a5f000643661ffd3908dcaa
Author: Foster Hangdaan <foster@hangdaan.email>
Date:   Tue Nov 14 05:11:47 2023 -0500

    Bump version to 0.3.0

2023-11-14 21:05:52 -05:00

3.9 KiB

Raw Permalink Blame History

IpMe

About
Live API Usage
- Examples using curl
Self-hosting
Contributing
Core maintainers
License
Copyright

About

A self-hosted API for obtaining your public IP address.

Live API Usage

An implementation of the API is available at ipme.fosterhangdaan.com.

URL	Response Type	Sample Output
https://ipme.fosterhangdaan.com	text	`98.207.254.136`
https://ipme.fosterhangdaan.com?format=json	json	`{"ip":"98.207.254.136"}`
https://ipme.fosterhangdaan.com?format=jsonp	jsonp	`callback({"ip":"98.207.254.136"})`
https://ipme.fosterhangdaan.com?format=jsonp&callback=getIp	jsonp	`getIp({"ip":"98.207.254.136"})`

Examples using `curl`

To get your public IP address in plain text:

curl --silent https://ipme.fosterhangdaan.com

For a response in json format:

curl --silent https://ipme.fosterhangdaan.com?format=json

Self-hosting

Requirements

Podman or Docker installed
Ports 80 and 443 opened
A domain name pointing to the server

For reliable IP address identification, the instance should be hosted on an external server outside of your home or local network.

Compose setup

The following compose.yaml can be used as reference:

version: "3.9"

volumes:
  caddy-data:
    external: true
  caddy-config:
    external: true

networks:
  proxy-tier:
    driver: bridge

services:
  ipme:
    image: code.fosterhangdaan.com/foster/ipme:latest
    container_name: ipme
    restart: unless-stopped
    env_file: .env.ipme
    networks:
      - proxy-tier
  caddy:
    image: docker.io/library/caddy:2-alpine
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
      - caddy-config:/config
    networks:
      - proxy-tier

.env.ipme

RUN_MODE=prod

Caddyfile

# Replace this domain with your own
https://ipme.mydomain.com {
  reverse_proxy ipme:8000
}

Run the services

Run podman-compose up to start the services.

The API should be available at the domain you selected. For example: https://ipme.mydomain.com.

Contributing

Please send patches and bug reports by email to one of the maintainers. See the Core maintainers section for a list of contacts.

Refer to this guide if you are not familiar with sending Git patches over email.

Core maintainers

Foster Hangdaan
- Website: www.fosterhangdaan.com
- Email: foster@hangdaan.email
- GPG Public Key: DBD3 8E38 4B9E 1F4F 19F9 5BAE E48D 7F49 A852 F112
- OpenAlias: pay.fosterhangdaan.com

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

3.9 KiB Raw Permalink Blame History