# FreeDomains — Free Custom Domains for Developer Projects

> An open-source platform by Stackryze that provides free custom domain names for developers, with DNS management and GitHub-based provisioning.

## Install

Save in your project root:

# FreeDomains — Free Custom Domains for Developer Projects

## Quick Use
```bash
# 1. Fork the FreeDomains repository on GitHub
# 2. Add a JSON file to the domains/ directory with your DNS records
# 3. Submit a pull request — your domain is provisioned on merge

# Example domain config (domains/myproject.json):
{
  "domain": "myproject.stackryze.dev",
  "records": [
    { "type": "CNAME", "value": "myproject.vercel.app" }
  ]
}
```

## Introduction
FreeDomains is an open-source service by Stackryze that gives developers free custom domain names for their projects. Instead of purchasing a domain, developers submit a pull request to the repository with their desired subdomain configuration, and the platform automatically provisions DNS records on merge. It lowers the barrier for hosting personal projects, portfolios, and open-source documentation.

## What FreeDomains Does
- Provides free subdomains under Stackryze-owned TLDs for developer projects
- Manages DNS provisioning through a GitHub-based pull request workflow
- Supports A, AAAA, CNAME, TXT, and MX record types
- Automates domain validation and conflict detection during PR review
- Maintains a public registry of all provisioned domains in the repository

## Architecture Overview
FreeDomains operates as a GitOps-driven DNS management system. Domain configurations are stored as JSON files in the repository. When a pull request is merged, a GitHub Actions pipeline reads the configuration, validates the records, and pushes them to the DNS provider via API. The pipeline also runs pre-merge checks to prevent conflicts, invalid records, and policy violations. The entire provisioning process is transparent and auditable through git history.

## Self-Hosting & Configuration
- Fork the repository to claim a subdomain — no account registration needed
- Add a JSON configuration file specifying your subdomain and DNS records
- Point your subdomain to any hosting provider (Vercel, Netlify, GitHub Pages, custom servers)
- Changes and updates follow the same PR workflow
- The DNS provider integration is managed by the Stackryze maintainers

## Key Features
- Zero-cost domain provisioning for developer projects
- Fully transparent GitOps workflow with public audit trail
- Supports common DNS record types for flexible hosting configuration
- Automated validation prevents misconfigured or conflicting domains
- No vendor lock-in — point your subdomain anywhere

## Comparison with Similar Tools
- **Freenom** — provided free TLDs but was unreliable and shut down; FreeDomains uses a sustainable maintainer-backed model
- **GitHub Pages** — offers *.github.io subdomains; FreeDomains provides custom TLD subdomains with more DNS flexibility
- **Vercel/Netlify** — provide *.vercel.app subdomains; FreeDomains works with any hosting provider
- **is-a.dev** — community free subdomains; FreeDomains offers a similar model with Stackryze-operated TLDs

## FAQ
**Q: Are there usage limits?**
A: Typically one to a few subdomains per user. The maintainers review PRs to prevent abuse.

**Q: Can I use this for commercial projects?**
A: Check the repository's terms of service. FreeDomains is primarily designed for personal and open-source projects.

**Q: What happens if the service shuts down?**
A: Since configurations are in a public repo, the git history preserves your setup. You would need to migrate to a paid domain provider.

**Q: How long does provisioning take?**
A: DNS records are provisioned shortly after PR merge, with propagation typically completing within minutes.

## Sources
- https://github.com/stackryze/FreeDomains
- https://github.com/stackryze/FreeDomains/blob/main/README.md

---
Source: https://tokrepo.com/en/workflows/asset-a641185c
Author: AI Open Source