Skip to content

Latest commit

 

History

History
355 lines (285 loc) · 11.3 KB

HOWTO.md

File metadata and controls

355 lines (285 loc) · 11.3 KB
Raw

How To

This section is a work in progress.

DNS Records

Our setup on Cloudflare supports the follow record types: (octoDNS docs)

A, AAAA, ALIAS, CAA, CNAME, MX, NS, PTR, SPF, SRV, TXT

You'll mostly wish to use these common types:

  • A: most common and basic (ipv4)
  • AAAA: same as A, but for ipv6
  • CNAME: domain name aliases. only works on subdomains. often used in custom domains for hosted services like GitHub Pages, Heroku, etc.
  • ALIAS: similar to CNAME, but works only on root domain
  • MX: used to setting up email addresses
  • TXT: holds arbitrary text data

Both A and CNAME records can be proxied with Cloudflare, if specified as below. This is most convenient for domain.com and sub.domain.com, but for second-level subdomains like 2nd.sub.domain.com, you're likely to hit issues. (Cloudflare docs. General docs.)

See the examples below to support in managing records.

(Note that either value or values can be used as key, but the latter expects an array.)

Examples

Adding an MX record to existing [sub]domain 
diff --git a/g0v.ca.domain/g0v.ca.yaml b/g0v.ca.domain/g0v.ca.yaml
index 3050a90..474481e 100644
--- a/g0v.ca.domain/g0v.ca.yaml
+++ b/g0v.ca.domain/g0v.ca.yaml
@@ -15,3 +15,7 @@
       - 301 https://g0v.tw/intl/en/
   - type: ALIAS
     value: 301.ronny.tw.
+  - type: MX
+    values:
+      - exchange: mx.example.com.
+        preference: 10
Add one more TXT record 
diff --git a/g0v.ca.domain/g0v.ca.yaml b/g0v.ca.domain/g0v.ca.yaml
index 3050a90..2a62d42 100644
--- a/g0v.ca.domain/g0v.ca.yaml
+++ b/g0v.ca.domain/g0v.ca.yaml
@@ -6,6 +6,7 @@
       - admin=patcon
       # Used for 301 redirect service below
       - 301 https://g0v.tw/intl/en/
+      - google-site-verification=1234-abcd-5678-EFGH
   - type: ALIAS
     value: 301.ronny.tw.
Create mysubdomain.g0v.ca and point to IP 
diff --git a/g0v.ca.domain/mysubdomain.g0v.ca.yaml b/g0v.ca.domain/mysubdomain.g0v.ca.yaml
new file mode 100644
index 0000000..d079979
--- /dev/null
+++ b/g0v.ca.domain/mysubdomain.g0v.ca.yaml
@@ -0,0 +1,11 @@
+---
+mysubdomain:
+  - type: A
+    octodns:
+      cloudflare:
+        proxied: true
+    value: 123.45.67.89
+    metdata:
+      repository: https://github.com/your-user/your-repo
+      maintainer:
+        - some-username
Delete subdomain oldapp.g0v.network 
diff --git a/g0v.network.domain/oldapp.g0v.network.yaml b/g0v.network.domain/oldapp.g0v.network.yaml
deleted file mode 100644
index ed900a2..0000000
--- a/g0v.network.domain/oldapp.g0v.network.yaml
+++ /dev/null
@@ -1,11 +0,0 @@
----
-oldapp:
-  type: CNAME
-  value: my-old-app.netlify.com.
-  metadata:
-    repo: https://github.com/g0v-network/my-old-app
-    maintainer:
-      - some-username

Subdomains

To add a new subdomain, just add an A or CNAME record as above, but for a new subdomain using a new config file.

Email Forwarders

Add a New Forwarder

#todo

Domains

Add a New Domain

If you'd like to start managing a new domain through this repo, you can do that! You'll only need to point your registrar at our Cloudflare nameservers -- you keep the domain with your registrar, and the domain itself stays in your hands.

  1. Create a new domain directory and config (see below)
  2. Copy your existing records into appropriate yaml config.
  3. Submit a pull request.
  4. We'll create a new zone for your domain in the Cloudflare admin interface.
  5. We'll add that zone to our existing Cloudflare API token, so it can be managed by our automation.
  6. We'll merge the pull request after review
    • Cloudflare's nameserver will be updated on merge, but your registrar won't be pointed to it yet.
  7. After merging, point your registrar at our Cloudflare nameservers: 
    clyde.ns.cloudflare.com
tina.ns.cloudflare.com
  8. Confirm that your DNS records work as expected, using:

Examples

Adding example.com as newly managed domain 
diff --git a/README.md b/README.md
index b079994..8266139 100644
--- a/README.md
+++ b/README.md
@@ -7,6 +7,7 @@ The following damains can be managed here:
 - `g0v.ca`
 - `c4nada.ca`
 - `t0ronto.ca`
+- `example.com`

 Changing or adding DNS records in `main` branch of this repository will update
 the actual domain records.
diff --git a/config.yaml b/config.yaml
index 3d10aed..c23c490 100644
--- a/config.yaml
+++ b/config.yaml
@@ -35,3 +35,8 @@ zones:
       - config-files
     targets:
       - cloudflare
+  example.com.:
+    sources:
+      - config-files
+    targets:
+      - cloudflare
diff --git a/example.com.domain/example.com.yaml b/example.com.domain/example.com.yaml
new file mode 100644
index 0000000..acedadd
--- /dev/null
+++ b/example.com.domain/example.com.yaml
@@ -0,0 +1,6 @@
+---
+'':
+  - type: TXT
+    values:
+      # Who has admin for this domain
+      - admin=<some identifier of person who owns it>

Redirects

This section describes how we support redirects, e.g. having g0v.ca redirect to https://g0v.tw/intl/en/.

Recommended Approach: Cloudflare URLFWD record type

Some DNS providers offer helpers to provide url redirects without hosting a special app. This is sometimes done through non-compliant pseudo-records (like DNSimple does), or through a separate platform feature (like Cloudflare does with Page Rules).

Our tool OctoDNS is using the Cloudflare provider. This provider supports a pseudo-record type called URLFWD, which is used to configure Page Rules. This is currently the best way to set up forwarding in this repo.

Examples

Create a redirect: g0v.london to example.com

Note: This only works when using the Cloudflare provider.

It will redirect any path on the g0v.london top-level domain directly to https://example.com :

diff --git a/g0v.london.domain/g0v.london.yaml b/g0v.london.domain/g0v.london.yaml
index 09f6e1e..c4be0bf 100644
--- a/g0v.london.domain/g0v.london.yaml
+++ b/g0v.london.domain/g0v.london.yaml
@@ -1,5 +1,21 @@
 ---
 '':
+  # In order for URLFWD pseudo-record to work via Cloudflare's Page Rule
+  # mechanism, the DNS must be proxied to a no-op IP address.
+  # See: https://support.cloudflare.com/hc/en-us/articles/218411427-Understanding-and-configuring-Cloudflare-Page-Rules-Page-Rules-Tutorial-
+  - type: A
+    value: 192.0.2.1 # no-op record to allow Cloudflare to proxy
+    octodns:
+      cloudflare:
+        proxied: true
+  # Create the catch-all Page Rule
+  - type: URLFWD
+    values:
+    - path: /*   # match every path
+      target: https://example.com/
+      code: 302  # permanent 301 or temporary 302
+      masking: 2 # always same
+      query: 0   # always same
   - type: TXT
     values:
       # Who has admin for this domain

Legacy Approach: 301.ronny.tw

Note: This is NOT LONGER THE RECOMMENDED approach, as it's finicky when the redirect origin has SSL, which is very common now.

To help allow redirects to be created in this repo in a consistent way, we instead opt to use a g0v-hosted tool called ronnywang/301-service. It's hosted at 301.ronny.tw (translated into English).

For specific examples of how to add redirects, see DNS Records examples above.

Examples

Create root domain redirect: g0v.network to example.com 
diff --git a/g0v.network.domain/g0v.network.yaml b/g0v.network.domain/g0v.network.yaml
index aca1501..8049f5d 100644
--- a/g0v.network.domain/g0v.network.yaml
+++ b/g0v.network.domain/g0v.network.yaml
@@ -42,3 +42,9 @@
         preference: 10
       - exchange: mx2.forwardemail.net.
         preference: 10
+  - type: TXT
+    values:
+      # Used for 301 redirect service below
+      - 301 https://example.com/
+  - type: ALIAS
+    value: 301.ronny.tw.
Create subdomain redirect: mysubdomain.g0v.ca to example.com 
diff --git a/g0v.ca.domain/mysubdomain.g0v.ca.yaml b/g0v.ca.domain/mysubdomain.g0v.ca.yaml
new file mode 100644
index 0000000..7536024
--- /dev/null
+++ b/g0v.ca.domain/mysubdomain.g0v.ca.yaml
@@ -0,0 +1,8 @@
+---
+mysubdomain:
+  - type: TXT
+    values:
+      # Used for 301 redirect service below
+      - 301 https://example.com/
+  - type: A
+    # 301.ronny.tw
+    value: 52.69.187.52

Once you've added a redirect like this, then the non-SSL link will work fine.

E.g., Non-SSL http://g0v.ca can redirect to https://g0v.tw/intl/en/

But note that HTTPS https://g0v.ca (with SSL) won't redirect cleanly without a browser warning. This is due to how all HTTPS security certificates work, and how this 301-service app works with these certificates.

But there's good news! If you'd like HTTPS redirects to also work, @ronnywang is willing to add your redirect origin domain to his certificate.

E.g., if you wished https://sub.example.com to cleanly redirect to http://g0v.tw, you would ask @ronnywang to add sub.example.com to his certificate. Even without submitting this additional request, http://sub.example.com (without SSL) would still redirect fine.

Click here to submit a request.