Skip to content

Commit b74721f

Browse files
jaspermayonejaspermayone
committed
add readme
1 parent 8b1881d commit b74721f

1 file changed

Lines changed: 144 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# Wentworth Coding Club DNS
2+
3+
[![test](https://github.com/witcc/dns/workflows/test/badge.svg)](https://github.com/witcc/dns/actions?query=workflow%3Atest)
4+
[![deploy](https://github.com/witcc/dns/workflows/deploy/badge.svg)](https://github.com/witcc/dns/actions?query=workflow%3Adeploy)
5+
6+
This repository is used for managing the Wentworth Coding Club's DNS configuration through [OctoDNS](https://github.com/octodns/octodns). OctoDNS enables version-controlled, automated DNS management with validation and testing before changes go live.
7+
8+
## Managed Domains
9+
10+
- **witcc.dev** - Primary club domain
11+
- **hackwit.org** - For HackWIT Hackathon
12+
13+
## Adding a Subdomain
14+
15+
### Step 1: Fork the Repository
16+
17+
[Create a fork](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo) of this repository to your GitHub account.
18+
19+
### Step 2: Edit the Domain Configuration File
20+
21+
Open either [witcc.dev.yaml](./witcc.dev.yaml) or [hackwit.org.yaml](./hackwit.org.yaml) depending on which domain you want to add a subdomain to.
22+
23+
Add the following entry alphabetically based on the subdomain name:
24+
25+
```yaml
26+
SUBDOMAIN_NAME: # yourwitemail@wit.edu
27+
- ttl: 600
28+
type: CNAME
29+
value: SOURCE_DOMAIN_OR_IP.
30+
```
31+
32+
### Step 3: Configure Your Subdomain
33+
34+
- **SUBDOMAIN_NAME**: Replace with your desired subdomain name
35+
- Example: `hello` would create `hello.witcc.dev`
36+
- **SOURCE_DOMAIN_OR_IP**: Replace with the target domain or IP address
37+
- For domains: Use `CNAME` and include the trailing `.`
38+
- Example: `example.com.`
39+
- For IP addresses: Change `type: CNAME` to `type: A` and remove the trailing `.`
40+
- Example: `192.0.2.1`
41+
- **Contact info**: Add your wit email in a comment above your entry. This way we know who is responsible for the subdomain. If you're making the PR but it makes more sense for someone else to "own" the subdomain, you can add their email there instead. Feel free to list multiple people.
42+
43+
### Example Configurations
44+
45+
#### CNAME Record (Domain)
46+
```yaml
47+
myproject: # mayonej@wit.edu
48+
- ttl: 600
49+
type: CNAME
50+
value: myproject.vercel.app.
51+
```
52+
53+
#### A Record (IP Address)
54+
```yaml
55+
server: # lambertl@wit.edu
56+
- ttl: 600
57+
type: A
58+
value: 192.0.2.1
59+
```
60+
61+
#### Multiple Records
62+
```yaml
63+
docs: # team@hackwit.org, mayonej@wit.org, lambertl@wit.edu
64+
- ttl: 600
65+
type: CNAME
66+
value: docs-site.netlify.app.
67+
- ttl: 600
68+
type: TXT
69+
value: "verification-token-here"
70+
```
71+
72+
### Step 4: Submit Pull Request
73+
74+
1. Commit your changes to your fork
75+
2. [Create a pull request](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork) back to the main repository
76+
3. Wait for a maintainer to review your PR
77+
78+
**Note**: If changes are requested, update your existing PR by committing to your fork rather than closing and creating a new one.
79+
80+
## Common Record Types
81+
82+
| Type | Usage | Example |
83+
|------|-------|---------|
84+
| **A** | Points to an IPv4 address | `value: 192.0.2.1` |
85+
| **AAAA** | Points to an IPv6 address | `value: 2001:0db8::1` |
86+
| **CNAME** | Points to another domain | `value: example.com.` |
87+
| **TXT** | Text records (verification, SPF, etc.) | `value: "verification-string"` |
88+
| **MX** | Mail server records | See email configuration |
89+
90+
91+
92+
## Testing Changes Locally
93+
94+
If you want to validate your changes before submitting a PR:
95+
96+
### Prerequisites
97+
98+
```bash
99+
# Install Python 3 and pip
100+
# Install OctoDNS and the Cloudflare provider
101+
pip install 'octodns>=1.5.0' octodns-cloudflare
102+
```
103+
104+
### Validate Configuration
105+
106+
```bash
107+
# Run a dry-run to check for errors
108+
./bin/dry-run
109+
```
110+
111+
This will validate your YAML syntax and check for DNS configuration errors without making any actual changes.
112+
113+
## How It Works
114+
115+
1. **Configuration**: DNS records are defined in YAML files (witcc.dev.yaml, hackwit.org.yaml)
116+
2. **Validation**: GitHub Actions automatically validates changes on every PR
117+
3. **Review**: A maintainer reviews and approves your changes
118+
4. **Deployment**: Upon merge to main, changes are automatically deployed to Cloudflare
119+
5. **Propagation**: DNS changes typically propagate within minutes but can take up to 24 hours
120+
121+
## Project Eligibility
122+
123+
Subdomains are available for:
124+
- Official Wentworth Coding Club projects
125+
- Club-affiliated events and initiatives
126+
127+
For questions about eligibility, reach out to a club E-Board member on discord.
128+
129+
## Need Help?
130+
131+
- Check the [OctoDNS documentation](https://github.com/octodns/octodns)
132+
- Open an issue in this repository
133+
- Ask in the club's Discord
134+
- Contact a repository maintainer (primarilly @jaspermayone)
135+
136+
## Contributing
137+
138+
We welcome contributions! Please:
139+
- Follow the existing format and alphabetical ordering
140+
- Include your contact information in comments
141+
- Provide a clear description in your PR
142+
- Be responsive to review feedback
143+
144+
---

0 commit comments

Comments
 (0)