ipme/README.org

#+title: IpMe

* About

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

* Self-hosting

** Requirements

- [[https://podman.io/][Podman]] or [[https://www.docker.com/][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:

#+begin_src yaml
version: "3.9"

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

networks:
  proxy-tier:
    driver: bridge

services:
  ipme:
    image: code.hangdaan.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
#+end_src

=.env.ipme=:

#+begin_src env
RUN_MODE=prod
#+end_src

=Caddyfile=:

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

** 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=.

** Examples using ~curl~

To get your public IP address in plain text:

#+begin_src shell
curl --silent https://ipme.mydomain.com
#+end_src

For a response in =json= format:

#+begin_src shell
curl --silent https://ipme.mydomain.com?format=json
#+end_src


* 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 [[https://git-send-email.io][this guide]] if you are not familiar with sending Git patches over email.

* Core maintainers

- *Foster Hangdaan*
  - Website: [[https://www.foster.hangdaan.com][foster.hangdaan.com]]
  - Email: [[mailto:foster@hangdaan.email][foster@hangdaan.email]]
  - GPG Public Key: [[https://s3.hangdaan.com/public/foster-pubkey.asc][DBD3 8E38 4B9E 1F4F 19F9 5BAE E48D 7F49 A852 F112]]
  - OpenAlias: =pay.foster.hangdaan.com=

* License

#+attr_html: :width 200px
[[https://s3.hangdaan.com/public/images/logos/licenses/agplv3.svg]]

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/>.

* Copyright

Copyright \copy 2023 Foster Hangdaan