Custom domains

Taking a site to your own domain is three steps, in this order: register the name, set the canonical domain, then add any other hostnames. Each step prints the DNS records it needs, which you publish at your DNS provider. kamakiri domain has every flag, output and exit code.

The three roles

Canonical. The site’s primary address, one per site. Once its DNS points at the site, the site’s kamakiri-pages.jp address, while enabled, 301-redirects to it.
Redirect. Redirects to the canonical domain, with a 301 unless you choose another code.
Alias. Serves the same content under another hostname, with no redirect.

Register the name

Registering proves your account controls the name. A registration belongs to the account, not to a site, so you register a name once and attach it to any of your sites.

$ kamakiri domain register example.com

Publish this DNS record to prove ownership:
  TYPE  NAME                          VALUE
  TXT   _kamakiri-verify.example.com  kamakiri-verify=mfrggzdfmztwq2lknnwg23tp
  Add this value; keep any other `_kamakiri-verify` value already there.

  Add the TXT record above at your registrar, then come back.
  Safe to close any time (Ctrl-C). Re-run `kamakiri domain register example.com` or `kamakiri domain list` to resume.

✓ domain verified: example.com
Now run `kamakiri domain set example.com` to point a site at it.

$ kamakiri domain register example.com

所有権を証明するため、次のDNSレコードを公開してください:
  種別  名前                          宛先
  TXT   _kamakiri-verify.example.com  kamakiri-verify=mfrggzdfmztwq2lknnwg23tp
  この値を追加してください。既にある他の `_kamakiri-verify` の値はそのまま残してください。

  上記のTXTレコードをレジストラで追加したら、戻ってきてください。
  いつでも閉じて構いません (Ctrl-C)。`kamakiri domain register example.com` または `kamakiri domain list` を再実行すると再開できます。

✓ ドメインを確認しました: example.com
次に `kamakiri domain set example.com` を実行してサイトを割り当ててください。

The TXT record moves no traffic. The proof is one-time: a verified registration stays verified until you unregister it, even if you delete the record. A registration still unverified 72 hours after you made it is dropped, and registering the name again issues a new value to publish.

A registration covers the name and everything under it. Registering example.com covers www.example.com and a.b.example.com. Registering foo.example.com covers only what sits under foo.

Set the canonical domain

$ kamakiri domain set example.com
✓ Canonical domain set: example.com

Configure your DNS:
  Required records (pick ONE option):

    Option A: ALIAS or ANAME (if your DNS provider supports it)
      example.com  ALIAS  → fzks-qpb6r87d79wfblfj.c1.kamakiri-pages.site.

    Option B: A records
      example.com  A  → 198.51.100.10
      example.com  A  → 198.51.100.11

    Both options work. ALIAS/ANAME is slightly more convenient (CDN
    changes don't require DNS edits); A records work everywhere,
    including providers that don't support ALIAS/ANAME. If you don't
    know which your provider supports, A records are the safe choice.


example.com
  Add the DNS record above at your registrar, then come back.
  Safe to close any time (Ctrl-C). Re-run `kamakiri domain verify example.com` or `kamakiri status` to resume.

✓ domain linked on our side
✓ DNS propagated (~12m)
✓ SSL certificate provisioned (~30s)
✓ live: https://example.com

$ kamakiri domain set example.com
✓ 正規ドメインを設定しました: example.com

DNSを設定してください:
  必要なレコード（いずれか1つを選択）:

    選択肢A: ALIAS または ANAME（DNSプロバイダーが対応している場合）
      example.com  ALIAS  → fzks-qpb6r87d79wfblfj.c1.kamakiri-pages.site.

    選択肢B: Aレコード
      example.com  A  → 198.51.100.10
      example.com  A  → 198.51.100.11

    どちらの方法でも動作します。ALIAS/ANAME の方が少し便利です（CDNを
    変更してもDNSの編集が不要になります）。Aレコードはどの環境でも動作し、
    ALIAS/ANAME に対応していないDNSプロバイダーでも使えます。どちらに
    対応しているか分からない場合は、Aレコードを選べば確実です。

  上記のDNSレコードをレジストラで追加したら、戻ってきてください。
  いつでも閉じて構いません (Ctrl-C)。`kamakiri domain verify example.com` または `kamakiri status` を再実行すると再開できます。

✓ ドメインをこちら側でリンクしました
✓ DNSの反映を確認しました（約12分）
✓ SSL証明書を発行しました（約30秒）
✓ 公開中: https://example.com

（ブラウザでエラーが表示される場合、お近くまでDNSが反映されていない可能性があります）

An apex such as example.com cannot take a CNAME, so the command offers an ALIAS or ANAME record or a pair of A records. A subdomain such as www.example.com takes a single CNAME to the target instead, the host under kamakiri-pages.site that the command prints.

The target belongs to the domain and never changes. Re-running the command, or later changing the hostname’s role, never asks you to edit DNS again.

If you plan to put Cloudflare in front of the site, make www.example.com the canonical domain and add example.com as a redirect, because Cloudflare cannot serve an apex. CDN has the details.

The domain goes live once its record resolves to the target and the certificate is issued. Moving a domain from another host usually means waiting out the old record’s TTL, often about an hour and sometimes longer. The domain also needs content: until the site has a live deploy, the wait says so, and it finishes on its own once you run kamakiri deploy <path>.

Add www, redirects and aliases

$ kamakiri domain add www.example.com
✓ Domain added: www.example.com (redirect 301)

Configure your DNS:
  www.example.com  CNAME  → h1lc-qpb6r87d79wfblfj.c1.kamakiri-pages.site.

www.example.com
  Add the DNS record above at your registrar, then come back.
  Safe to close any time (Ctrl-C). Re-run `kamakiri domain verify www.example.com` or `kamakiri status` to resume.

✓ domain linked on our side
✓ DNS propagated (~12m)
✓ SSL certificate provisioned (~30s)
✓ live: https://www.example.com

$ kamakiri domain add www.example.com
✓ ドメインを追加しました: www.example.com (redirect 301)

DNSを設定してください:
  www.example.com  CNAME  → h1lc-qpb6r87d79wfblfj.c1.kamakiri-pages.site.

  上記のDNSレコードをレジストラで追加したら、戻ってきてください。
  いつでも閉じて構いません (Ctrl-C)。`kamakiri domain verify www.example.com` または `kamakiri status` を再実行すると再開できます。

✓ ドメインをこちら側でリンクしました
✓ DNSの反映を確認しました（約12分）
✓ SSL証明書を発行しました（約30秒）
✓ 公開中: https://www.example.com

（ブラウザでエラーが表示される場合、お近くまでDNSが反映されていない可能性があります）

An added hostname redirects to the canonical domain with a 301. --status 302 makes the redirect temporary, and --alias serves the content instead. A redirect needs the canonical domain set first. The example.com registration already covers www.example.com, so there is nothing more to register.

Move to a new domain

kamakiri domain register example.jp
kamakiri domain set example.jp
kamakiri domain add example.com

Setting a new canonical domain takes the old one off the site, and it stops serving until you add it back. Adding it as a redirect keeps old links working. Publish the records each command prints.

Remove a domain

kamakiri domain remove <domain> removes a redirect or an alias.
kamakiri domain unset removes the canonical domain, and the site goes back to its kamakiri-pages.jp address. It is refused while the site has redirects, so remove those first.
kamakiri domain unregister <domain> removes the registration. It is refused while any of your sites still uses a hostname under it. Afterwards you can delete the _kamakiri-verify record.

If a WebAccel CDN fronted the domain, its resource stays in your Sakura account until you delete it with kamakiri cdn cleanup, which CDN covers. A Cloudflare hostname is removed with the domain.

When a domain does not go live

A domain left mid-setup comes up on its own once its record is in place, whether or not a command is watching. A domain still waiting for its DNS 72 hours after you added it is taken off the site. Run the same set or add again; the record to publish stays the same. kamakiri status shows where each domain stood at its last check:

waiting for your DNS. No matching record is visible yet. It is not published, or it has not propagated.
DNS points at the wrong target. A record exists but does not match. The line names the expected and the observed values and the likely fix. A common cause is Cloudflare’s proxy left on for the record.
couldn’t reach your DNS. The last check could not reach your DNS, so the result is unknown. The domain is checked again on its own.
no published content yet. The DNS already points at the site, but the site has no live deploy. Deploy once with kamakiri deploy, and setup finishes by itself.
verifying edge, provisioning SSL certificate. The record is correct and setup is finishing. Nothing is needed from you.
live. The record resolves to the target and the domain is serving over HTTPS.

kamakiri domain verify <domain> has the domain checked again within about a minute, and watches it until it is live. It is also how you bring back a domain that has dropped out of service.