Update docs on custom domain

docs/SUMMARY.md

@@ -16,6 +16,7 @@
     - [Automatic TLS](guides/features/automatic-tls.md)
     - [GitHub Actions Integration](guides/features/github-actions-integration.md)
     - [Access Control](guides/features/access-control.md)
+    - [Custom Domain](guides/features/custom-domain.md)
 
 # References
 

docs/guides/features/custom-domain.md

@@ -0,0 +1,32 @@
+# Custom Domains
+
+Pageship supports custom domains for serving pages for an app. We assume a
+cooperative model for custom domain association, so domain ownership
+verification is not required.
+
+To enable custom domain, configure `pageship.toml` and specify the site to serve
+from the domain:
+
+```toml
+# 2 sites for the app: 'main' & 'dev'
+[[app.sites]]
+name = "main"
+
+[[app.sites]]
+name = "dev"
+
+# For 'main' site, serve it at 'example.com'. Traffic to default domain is
+# redirected to the configured domain automatically.
+[[app.domains]]
+domain="example.com"
+site="main"
+```
+
+If the domain name is already in-use by other apps, the custom domain would not
+be activated automatically when first added to the configuration. It can be
+activated/deactivated manually using `pageship domains activate <domain name>`/
+`pageship domains deactivate <domain name>` command.
+
+Custom domains of the app can be listed with `pageship domains` command.
+Additional setup instruction (e.g. DNS setup) would be shown if provided by
+server operator.

docs/references/configuration-file.md

@@ -24,7 +24,10 @@ server.
   subdomain.
 - `app.deployments`: Configuration for preview deployments
     - `access`: ACL rules controlling access of preview deployments.
-    - `ttl`: the lifetime of a preview deployment (default to `24h`)``
+    - `ttl`: the lifetime of a preview deployment (default to `24h`)
+- `app.domains`: Configuration for custom domains
+    - `domain`: The custom domain to use
+    - `site`: The site name associated the custom domain
 
 ### `site` section