Add more docs

oursky · Jun 27, 2023 · 40f4ccc · 40f4ccc
1 parent ba27aa0
commit 40f4ccc
Show file tree

Hide file tree

Showing 4 changed files with 43 additions and 2 deletions.
diff --git a/docs/guides/deploying-sites.md b/docs/guides/deploying-sites.md
@@ -42,7 +42,8 @@ uploading 100%
   INFO   Done!
 ```
 
-To deploy as a preview deployment, omit the `site` parameter.
+To deploy as a preview deployment, omit the `site` parameter. For details,
+refer to [Preview Deployment](./features/preview-deployment.md) guide.
 
 ```
 $ pageship deploy --site main

diff --git a/docs/guides/features/automatic-tls.md b/docs/guides/features/automatic-tls.md
@@ -1,3 +1,19 @@
 # Automatic TLS
 
 Pageship supports automatic TLS through [certmagic](https://github.com/caddyserver/certmagic) library.
+
+Automatic TLS can be activated by passing `--tls` command line parameter.
+Certificates would be obtained from Let's Encrypt when a site domain is accessed
+for the first time. It is recommnded to provide a email to receive notifications
+from certificate issuer using `--tls-acme-email` command line parameter.
+
+## Certificate Persistence
+
+In single-site & unmanaged-sites mode, certificate data is stored on the default
+filesystem directory specified by `certmagic` library
+(`${XDG_DATA_HOME}/certmagic`) in plain-text. Care should be taken to secure
+the key materials.
+
+In managed sites mode, certificate data is stored in database. Optionally, an
+encryption key can be specified through `--tls-protect-key` parameter to
+encrypt the certificate data at rest using NaCL secretbox.
diff --git a/docs/guides/features/preview-deployment.md b/docs/guides/features/preview-deployment.md
@@ -1 +1,25 @@
 # Preview Deployment
+
+Pageship supports preview deployments. When a deployment is created without
+assigning to a site, it is treated as preview deployments.
+
+Preview deployments has limited lifetime, and expires after a period not
+assigned to a site. This period can be configured in `pageship.toml`:
+```toml
+[app.deployments]
+ttl = "24h"     # expires after 24 hours.
+```
+
+An expired preview deployment is inaccessible and deleted automatically after
+some time.
+
+## Access Control
+
+By default, preview deployments are not accessible. To enable access to
+preview deployments, setup access control for preview deployment in `pageship.toml`:
+```toml
+[app.deployments]
+access = [
+    { ipRange="0.0.0.0/0" }     # preview deployments are accessible to anyone.
+]
+```
diff --git a/docs/guides/installation.md b/docs/guides/installation.md
@@ -10,7 +10,7 @@ Docker images are available from GitHub Packages:
 
 ```sh
 docker pull ghcr.io/oursky/pageship:v0.3.1
-docker pull ghcr.io/oursky/pageship:v0.3.1
+docker pull ghcr.io/oursky/pageship-controller:v0.3.1
 ```
 
 ## Go install