Self-hosted server to monitor WHOIS records for specified domains, to help alert you of unwanted/unexpected changes to your domains and to help remind you when they need renewed.
If you use domain-monitor, make sure to abide by the terms of service of the TLD WHOIS server. Most forbid high-volume queries, marketing usage, and automated queries that are more than reasonably needed to register domain names.
To help you abide by WHOIS server TOS, domain-monitor barely queries the whois databases. domain-monitor acts in this way:
- Creates a local cache of the whois info for the domain, including time queried
- Updates a whois info only if one of these conditions is met:
- No cached whois info for the domain
- Reference info becomes 9 months old
- It's 3 months until the domain expiry date
- It's 2 months until the domain expiry date
- It's 1 month until the domain expiry date
- It's 2 weeks until the domain expiry date
- It's 1 week until the domain expiry date
- Manual update is requested
- A DNS query of the FQDN returns a different set of name servers than the cached whois info
The docker image has a single volume for the files generated by the server.
| Image Mount | Contains |
|---|---|
| /app/data | config.yaml, domain.yaml and WHOIS cache |
| Exposed Ports | Used for |
|---|---|
| 3124/tcp | WEB GUI and API |
Using Github Packages
docker run -p 127.0.0.1:3124:3124 -v ./data:/app/data ghcr.io/nwesterhausen/domain-monitor:1
Example docker-compose:
services:
dm:
image: ghcr.io/nwesterhausen/domain-monitor:1
ports:
- 127.0.0.1:3124:3124/tcp
volumes:
- ./data:/app/data:rw
version: "3.9"Using Docker Hub
Image is just nwesterhausen/domain-monitor, latest tag will be the most recent version, or pull by tagged version. The most recent old (non-go) version is tagged with 0.3.4.
docker run -p 127.0.0.1:3124:3124 -v ./data:/app/data docker.io/nwesterhausen/domain-monitor
Should be OS-agnostic. Requires Go and NodeJS. Clone this repo and follow the build instructions. Then you can run the binary alongside the assets folder.
Configuration can be done via the configuration page of the web gui (default http://localhost:3124)
There are two config files which you can edit yourself if you so choose.
A sample is provided as sample.config.yaml and on first run if you don't have an existing config.yaml, domain-monitor will create one with all default values. Any changes you made in the webgui persist in config.yaml.
Port
Set the port used by the http server
Automated Whois Lookups
Enable or disable automated whois lookups. If disabled, whois lookups will only be done when manually requested.
app:
port: 3124
automateWHOISRefresh: yesadmin
Set what email should receive alerts from domain-monitor
sendalerts
Boolean, if false prevents all alerts from being sent.
Send Alert at 2 Months to Expiry
Boolean, if true, an alert will be sent when a domain is 2 months from expiry.
Send Alert at 1 Month to Expiry
Boolean, if true, an alert will be sent when a domain is 1 month from expiry.
Send Alert at 2 Weeks to Expiry
Boolean, if true, an alert will be sent when a domain is 2 weeks from expiry.
Send Alert at 1 Week to Expiry
Boolean, if true, an alert will be sent when a domain is 1 week from expiry.
Send Alert at 3 Days to Expiry
Boolean, if true, an alert will be sent when a domain is 3 days from expiry.
Send Daily Expiry Alerts
Boolean, if true, an alert will be sent every day for domains that expire within a week.
alerts:
admin: support@example.com
sendalerts: true
send2MonthAlert: false
send1MonthAlert: true
send2WeekAlert: false
send1WeekAlert: false
send3DayAlert: true
sendDailyExpiryAlert: falseSet smtp settings for domain-monitor to use to send email alerts.
Host
The hostname of the SMTP server
Port
The port of the SMTP server
Secure
Boolean, if true, will force the SMTP connection to use TLS. If false, will use opportunistic TLS (so fallback to plaintext if the server doesn't support TLS)
Authuser
The username to use to authenticate with the SMTP server
Authpass
The password to use to authenticate with the SMTP server
Enabled
Boolean, if false, domain-monitor will not send any email alerts
FromName
The name to use in the "from" field of the email alerts
FromEmail
The email address to use in the "from" field of the email alerts
smtp:
host: localhost
port: 25
secure: false
authuser: domain-alert@example.com
authpass: SECRET-PASS
enabled: false
fromName: Domain Monitor
fromEmail: domain-monitor@example.comSet some schedule options for the WHOIS lookups.
WHOIS Cache Stale Interval
The number of days after which the WHOIS cache is considered stale and a new lookup will be done.
Use Standard WHOIS Refresh Schedule
Boolean, if true, domain-monitor will use a standard schedule for WHOIS lookups. If false, it will still perform the automated WHOIS lookup for stale, new domains and DNS changes, but will not perform regular lookups.
scheduler:
whoisCacheStaleInterval: 190
useStandardWHOISRefreshSchedule: trueContains a single object (domains) which is a list of domains to monitor. Each domain has the following properties:
| Property | Type | Description |
|---|---|---|
| name | string | Descriptive name for the domain entry |
| fqdn | string | FQDN for the domain in question. This is just host.tld |
| alerts | bool | If true, email alerts will be sent for this domain |
| enabled | bool | If true, whois lookups will be done (on the schedule described above) for this domain. |
Requirements:
- golang
- nodejs
- pnpm
- air
go install github.com/air-verse/air@latest - templ
go install github.com/a-h/templ/cmd/templ@latest
Build steps:
- Install npm dependencies and "build" (copy the JS libraries to the
assetsfolder).
pnpm i && pnpm build- Compile the templates
templ generate- Build the go binary
go build cmd/main.goThe binary requires the assets folder to be in the same directory as the binary.
To run the development server, use the following command:
airAir will take care of all the build steps whenever a change is detected.