{"id":42842313,"url":"https://github.com/fini-net/fini-coredns-example","last_synced_at":"2026-01-30T11:52:40.675Z","repository":{"id":299227487,"uuid":"1002399985","full_name":"fini-net/fini-coredns-example","owner":"fini-net","description":"Coredns with dnscontrol example","archived":false,"fork":false,"pushed_at":"2025-12-05T02:36:25.000Z","size":96,"stargazers_count":5,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-08T10:09:56.191Z","etag":null,"topics":["coredns","dns-server","dnscontrol","example"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fini-net.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-15T11:51:08.000Z","updated_at":"2025-12-05T02:36:25.000Z","dependencies_parsed_at":"2025-06-15T13:18:29.587Z","dependency_job_id":"d8c966c1-17fb-4309-b4f8-2e0d7abc3490","html_url":"https://github.com/fini-net/fini-coredns-example","commit_stats":null,"previous_names":["fini-net/fini-coredns-example"],"tags_count":5,"template":false,"template_full_name":"fini-net/template-repo","purl":"pkg:github/fini-net/fini-coredns-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fini-net%2Ffini-coredns-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fini-net%2Ffini-coredns-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fini-net%2Ffini-coredns-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fini-net%2Ffini-coredns-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fini-net","download_url":"https://codeload.github.com/fini-net/fini-coredns-example/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fini-net%2Ffini-coredns-example/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28912108,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-30T08:15:08.179Z","status":"ssl_error","status_checked_at":"2026-01-30T08:14:31.507Z","response_time":66,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coredns","dns-server","dnscontrol","example"],"created_at":"2026-01-30T11:52:40.600Z","updated_at":"2026-01-30T11:52:40.667Z","avatar_url":"https://github.com/fini-net.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FINI coredns example\n\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/11155/badge)](https://www.bestpractices.dev/projects/11155)\n[![Go Report Card](https://goreportcard.com/badge/github.com/fini-net/fini-coredns-example)](https://goreportcard.com/report/github.com/fini-net/fini-coredns-example)\n[![GitHub release](https://img.shields.io/github/release/fini-net/fini-coredns-example/all.svg)](https://github.com/fini-net/fini-coredns-example/releases)\n![GitHub Issues](https://img.shields.io/github/issues/fini-net/fini-coredns-example)\n![GitHub Pull Requests](https://img.shields.io/github/issues-pr/fini-net/fini-coredns-example)\n![GitHub License](https://img.shields.io/github/license/fini-net/fini-coredns-example)\n\nA complete example demonstrating how to use\n[DNSControl](https://github.com/StackExchange/dnscontrol) to generate DNS zone\nfiles and serve them with [CoreDNS](https://coredns.io/) in a container.\n\n## What's Included\n\nThis repository provides:\n\n- **JavaScript DNS Configuration**: Define DNS records using DNSControl's\n  JavaScript syntax for `example.com` and `example.org` domains\n- **Automated Zone File Generation**: Convert JavaScript configurations to BIND\n  zone files with `just push`\n- **Containerized DNS Server**: Ready-to-run CoreDNS container serving the generated zones\n- **Automated Testing**: Go test suite validating DNS responses for 10+ specific records\n- **Development Workflow**: Complete `just` command recipes for building, testing, and deploying\n- **GitHub Container Registry**: Pre-built container images available at\n  `ghcr.io/fini-net/fini-coredns-example`\n\n## Quick Start\n\n1. **Generate zone files**: `just push` (uses DNSControl to create BIND files from JavaScript)\n2. **Build container**: `just build_con` (creates local container with CoreDNS + zone files)\n3. **Start DNS server**: `just run_con` (runs container on port 1029)\n4. **Test functionality**: `just test_dns` (validates DNS responses) or `dig\n   @localhost -p 1029 www.example.com`\n\nThe [development process](.github/CONTRIBUTING.md#development-process)\ndocuments all available `just` subcommands for working with this repository.\n\n### Working with the container\n\nTo generate the container on your local machine run `just build_con`.\n\nTo run the built container run `just run_con`.  A DNS server should be\navailable on port 1029.  You can see it working with `dig` like so:\n\n```ShellSession\n% dig @localhost -p 1029 www.example.com\n\n; \u003c\u003c\u003e\u003e DiG 9.10.6 \u003c\u003c\u003e\u003e @localhost -p 1029 www.example.com\n; (2 servers found)\n;; global options: +cmd\n;; Got answer:\n;; -\u003e\u003eHEADER\u003c\u003c- opcode: QUERY, status: NOERROR, id: 3344\n;; flags: qr aa rd; QUERY: 1, ANSWER: 2, AUTHORITY: 4, ADDITIONAL: 1\n;; WARNING: recursion requested but not available\n\n;; OPT PSEUDOSECTION:\n; EDNS: version: 0, flags:; udp: 4096\n;; QUESTION SECTION:\n;www.example.com.               IN      A\n\n;; ANSWER SECTION:\nwww.example.com.        3600    IN      CNAME   server1.example.com.\nserver1.example.com.    3600    IN      A       10.0.0.101\n\n;; AUTHORITY SECTION:\nexample.com.            3600    IN      NS      ns0.example.com.\nexample.com.            3600    IN      NS      ns1.example.com.\nexample.com.            3600    IN      NS      ns2.example.com.\nexample.com.            3600    IN      NS      ns3.example.com.\n\n;; Query time: 6 msec\n;; SERVER: ::1#1029(::1)\n;; WHEN: Sat Jul 05 20:26:48 PDT 2025\n;; MSG SIZE  rcvd: 287\n```\n\nThat is the same CNAME and IP that you can see in the\n[zone file](dns/zones/example.com.zone).\n\n#### Easier working wih the container\n\nTo save you some typing you could run `just test_con` to get this\nexperience:\n\n```ShellSession\n% just test_con\nExpect to see in dig output:\n;; ANSWER SECTION:\nwww.example.com.        3600    IN      CNAME   server1.example.com.\nserver1.example.com.    3600    IN      A       10.0.0.101\n\ndig @localhost -p 1029 www.example.com\n\n; \u003c\u003c\u003e\u003e DiG 9.10.6 \u003c\u003c\u003e\u003e @localhost -p 1029 www.example.com\n; (2 servers found)\n;; global options: +cmd\n;; Got answer:\n;; -\u003e\u003eHEADER\u003c\u003c- opcode: QUERY, status: NOERROR, id: 36425\n;; flags: qr aa rd; QUERY: 1, ANSWER: 2, AUTHORITY: 4, ADDITIONAL: 1\n;; WARNING: recursion requested but not available\n\n;; OPT PSEUDOSECTION:\n; EDNS: version: 0, flags:; udp: 4096\n;; QUESTION SECTION:\n;www.example.com.               IN      A\n\n;; ANSWER SECTION:\nwww.example.com.        3600    IN      CNAME   server1.example.com.\nserver1.example.com.    3600    IN      A       10.0.0.101\n\n;; AUTHORITY SECTION:\nexample.com.            3600    IN      NS      ns0.example.com.\nexample.com.            3600    IN      NS      ns1.example.com.\nexample.com.            3600    IN      NS      ns2.example.com.\nexample.com.            3600    IN      NS      ns3.example.com.\n\n;; Query time: 2 msec\n;; SERVER: ::1#1029(::1)\n;; WHEN: Thu Jul 10 12:37:44 PDT 2025\n;; MSG SIZE  rcvd: 287\n```\n\nLooks great until we can automate it!™\n\n#### Container commands reference\n\nFor direct podman usage without `just`:\n\n```bash\n# Run the container (DNS server on port 1029)\npodman run -d --name corednstest -p 1029:53/udp ghcr.io/fini-net/fini-coredns-example --config /etc/Corefile\n\n# Test the DNS server\ndig @localhost -p 1029 www.example.com\n\n# Stop and clean up\npodman stop corednstest\npodman rm corednstest\n\n# Inspect container metadata\npodman inspect fini-coredns-example | jq '.[0].Labels'\n```\n\n## Testing\n\nThe repository includes automated Go tests that validate DNS responses from the\ncontainer.  After evaluating existing DNS test solutions, none were suitable for\nthis scenario. So Claude generated a [test suite](test).\n\nThis is what it looks like in action:\n\n```ShellSession\n% just test_dns\nMake sure container is running: just run_con\n=== RUN   TestDNSRecords\n=== RUN   TestDNSRecords/example.com_root_A_record\n=== RUN   TestDNSRecords/server1.example.com_A_record\n=== RUN   TestDNSRecords/ns0.example.com_A_record\n=== RUN   TestDNSRecords/www.example.com_CNAME_record\n=== RUN   TestDNSRecords/ftp.example.com_CNAME_record\n=== RUN   TestDNSRecords/server1.example.com_AAAA_record\n=== RUN   TestDNSRecords/server1.example.com_TXT_record\n=== RUN   TestDNSRecords/example.org_root_A_record\n=== RUN   TestDNSRecords/www.example.org_A_record\n=== RUN   TestDNSRecords/calendar.example.org_CNAME_record\n--- PASS: TestDNSRecords (0.01s)\n    --- PASS: TestDNSRecords/example.com_root_A_record (0.00s)\n    --- PASS: TestDNSRecords/server1.example.com_A_record (0.00s)\n    --- PASS: TestDNSRecords/ns0.example.com_A_record (0.00s)\n    --- PASS: TestDNSRecords/www.example.com_CNAME_record (0.00s)\n    --- PASS: TestDNSRecords/ftp.example.com_CNAME_record (0.00s)\n    --- PASS: TestDNSRecords/server1.example.com_AAAA_record (0.00s)\n    --- PASS: TestDNSRecords/server1.example.com_TXT_record (0.00s)\n    --- PASS: TestDNSRecords/example.org_root_A_record (0.00s)\n    --- PASS: TestDNSRecords/www.example.org_A_record (0.00s)\n    --- PASS: TestDNSRecords/calendar.example.org_CNAME_record (0.00s)\n=== RUN   TestContainerHealthCheck\n--- PASS: TestContainerHealthCheck (0.00s)\n=== RUN   TestNSRecords\n--- PASS: TestNSRecords (0.00s)\n=== RUN   TestMXRecords\n=== RUN   TestMXRecords/example.com\n=== RUN   TestMXRecords/example.org\n--- PASS: TestMXRecords (0.00s)\n    --- PASS: TestMXRecords/example.com (0.00s)\n    --- PASS: TestMXRecords/example.org (0.00s)\nPASS\nok  \tgithub.com/fini-net/fini-coredns-example/test\t0.220s\n```\n\nThe test suite validates specific DNS records including A, AAAA, CNAME, TXT,\nNS, and MX records across both example domains. Tests require the container to\nbe running first via `just run_con` or direct `podman` commands.\n\n## Standards Compliance\n\nThe domains and IPs in the examples contained in this repo should comply with\n\n- [RFC2606: Reserved Top Level DNS Names](https://www.rfc-editor.org/rfc/rfc2606.html)\n- [RFC1918: Address Allocation for Private Internets](https://www.rfc-editor.org/rfc/rfc1918.html)\n- [RFC4193: Unique Local IPv6 Unicast Addresses](https://www.rfc-editor.org/rfc/rfc4193.txt)\n\nto avoid interfering with any existing infrastructure.\n\n## Contributing\n\n- Please follow our [Code of Conduct](.github/CODE_OF_CONDUCT.md) while participating\n  in this project.\n- [Contributing Guide](.github/CONTRIBUTING.md) includes a step-by-step guide to our\n  [development process](.github/CONTRIBUTING.md#development-process).\n\n## Support \u0026 Security\n\n- [Getting Support](.github/SUPPORT.md)\n- [Security Policy](.github/SECURITY.md)\n\n## Thanks\n\n- Robb Manes wrote\n  [Running CoreDNS as a DNS Server in a Container](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry)\n  which walks you how to do something similar for yourself.\n- This [ServerFault answer](https://serverfault.com/a/216611/205542) helped me find RFC4193\n  for the safe IPv6 address range.\n- [networkupstools](https://github.com/networkupstools/nut/wiki/Building-NUT-integration-for-Home-Assistant)\n  shows how to set a lot of metadata during your container build.\n- Kudos to Jason Hall for [documenting the nice way to login to ghcr](https://github.com/cli/cli/pull/8558),\n  but it doesn't work (yet?) so I had to create a PAT after all.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffini-net%2Ffini-coredns-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffini-net%2Ffini-coredns-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffini-net%2Ffini-coredns-example/lists"}