Mousehole, a Seedbox IP Updater for MAM

A background service to update a seedbox IP for MAM and an HTTP server to manage it.

This can be helpful if you are using a host/VPN/seedbox to seed and its IP address is not stable.

Features:

• Background service that regularly updates MAM with the IP address of the host.

  Before an update, Mousehole checks that it actually needs to update by comparing the host's current IP address and AS and with the last MAM response.

• Frontend website to manage the service, allowing:

  • Setting your MAM cookie
  • Displaying status information
  • Manual triggering of checks

• API server with management endpoints.

  See API.md for details.

Usage

Docker Compose

services:
  mousehole:
    image: tmmrtn/mousehole:latest
    environment:
      TZ: Etc/UTC # Optional, but set to your timezone for localization of API times
    ports:
      - "127.0.0.1:5010:5010" # or just "5010:5010" if you want it accessible to the outside world too
    # persist cookie data across container restarts
    volumes:
      - "mousehole:/srv/mousehole"
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "curl -fs http://localhost:5010/state || exit 1"]

volumes:
  mousehole:

If you intend to run this service alongside a VPN container to tunnel your connection, it is imperative that you run mousehole in the same network as the VPN container.

Example with WireGuard and qBittorrent Docker Compose stack:

services:
  wireguard:
    image: lscr.io/linuxserver/wireguard:latest

    # configure as necessary, see https://docs.linuxserver.io/images/docker-wireguard

    ports:
      # anything that wants to use the wireguard network must expose ports here, such as
      # bittorrent port, webui port, and mousehole http port
      - "127.0.0.1:5010:5010" # or just "5010:5010" if you want it accessible to the outside world too
      # - <qbittorrent port>:<qbittorrent port>
      # - <qbittorrent webui port>:<qbittorrent webui port>

    # optional - healthcheck to ensure the VPN is up. replace `airvpn` with your VPN interface name
    healthcheck:
      test: ["CMD-SHELL", "wg show airvpn | grep -q 'latest handshake'"]

  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest

    # configure as necessary, see https://docs.linuxserver.io/images/docker-qbittorrent

    # CRITICAL - Use wireguard container's network stack
    network_mode: "service:wireguard"

    # optional - only run after wireguard is healthy
    depends_on:
      wireguard:
        condition: service_healthy

  mousehole:
    image: tmmrtn/mousehole:latest

    # CRITICAL - Use wireguard container's network stack
    network_mode: "service:wireguard"

    environment:
      TZ: Etc/UTC # Optional, but set to your timezone for localization of API times
    # persist cookie data across container restarts
    volumes:
      - "mousehole:/srv/mousehole"
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "curl -fs http://localhost:5010/state || exit 1"]

    # optional - only run after wireguard is healthy
    depends_on:
      wireguard:
        condition: service_healthy

volumes:
  mousehole:

Docker Tags

Mousehole publishes several image tags to Docker Hub:

• SemVer versions (0, 0.1, 0.1.11, etc)
• latest, the latest released version
• edge, the tip of master branch

Choose latest if you do not know which to pick.

Proxying

Mousehole works great with reverse proxies like Nginx Proxy Manager.

However, the Web UI makes use of WebSockets, so you need to ensure that your reverse proxy is configured to use them.

Local

Run the server with:

bun run start

Environment Variables

• MOUSEHOLE_PORT: (Default 5010) The port on which the HTTP server will listen.
• MOUSEHOLE_STATE_DIR_PATH: (Default /srv/mousehole) The directory where the service will store its data.
• MOUSEHOLE_USER_AGENT: (Default mousehole-by-timtimtim/<version>) The user agent to use for requests to MAM.
• MOUSEHOLE_CHECK_INTERVAL_SECONDS: (Default 300 (5 minutes)) The interval in seconds between checks.
• MOUSEHOLE_STALE_RESPONSE_SECONDS: (Default 86400 (1 day)) The number of seconds after which a MAM response is considered stale. This ensures that we're still talking with MAM at some regular interval and are detecting out-of-band changes to the cookie.

First-time Setup (or if cookie gets out of sync)

When running this service for the first time (or if the cookie gets out of sync), you need to set the Mousehole's cookie manually.

On navigating to the Mousehole web interface, you will see a form to set the cookie -- paste your cookie and click the "Set" button.

If you need help getting the cookie, click the "What do I enter here?" button for a tutorial.

Contributing

Want to contribute? Check out the contribution guidelines.

There is also a contrib directory with useful, supplementary functionality.

Links

• Repository
• Docker Hub image
• Forum post

Development

• Start the dev server with:

  bun run dev

• New versions can be tagged, released and pushed to Docker Hub by simply changing the version in package.json and pushing to GitHub. The CI workflows will take care of the rest.

Attribution

Mouse Hole by Sergey Demushkin from Noun Project (CC BY 3.0)