Add more docs

docs/SUMMARY.md

@@ -7,9 +7,9 @@
 - [Installation](guides/installation.md)
 - [Getting Started](guides/getting-started.md)
 - [Setup Server](guides/setup-server.md)
-    - [Single site](guides/setup/single-site.md)
-    - [Unmanaged sites](guides/setup/unmanaged-sites.md)
-    - [Managed sites](guides/setup/managed-sites.md)
+    - [Single-site](guides/setup/single-site.md)
+    - [Unmanaged-sites](guides/setup/unmanaged-sites.md)
+    - [Managed-sites](guides/setup/managed-sites.md)
 - [Deploying Sites](guides/deploying-sites.md)
 - [Features](guides/features.md)
     - [Preview Deployment](guides/features/preview-deployment.md)

docs/guides/deploying-sites.md

@@ -2,15 +2,63 @@
 
 ## Deploying using `pageship` command
 
-For managed sites mode, you may deploy a site through `pageship` command.
+For managed-sites mode, you may deploy a site through `pageship` command.
 
 ## Configure app
 
+If it's the first time deploying the app on server, create the at with the
+server through `pageship apps create` command.
+
+```
+$ pageship apps create
+API Server: https://api.example.com
+App "..." is created.
+$
+```
+
+Then apply the configuration file (`pageship.toml`) through `pageship apps configure`.
+
+```
+$ pageship apps configure
+Configured app "...".
+```
+
 ## Deploy site
 
+By default, each app has a default `main` site. Other sites can be configured in
+`pageship.toml`.
+
+To deploy to a site, use `pageship deploy` command with `site` parameter.
+
+```
+$ pageship deploy --site main
+Deploy to site "main" of app "...": y
+  INFO   Collecting files...
+  INFO   69 files found. Tarball size: 1.0 MB
+  INFO   Setting up deployment 'tmytb2i'...
+uploading 100%
+  INFO   Activating deployment...
+  INFO   You can access the deployment at: ...
+  INFO   Done!
+```
+
+To deploy as a preview deployment, omit the `site` parameter.
+
+```
+$ pageship deploy --site main
+Deploy to app "...": y
+  INFO   Collecting files...
+  INFO   69 files found. Tarball size: 1.0 MB
+  INFO   Setting up deployment 'ztyflzy'...
+  INFO   Site not specified; deployment would not be assigned to site
+uploading 100%
+  INFO   You can access the deployment at: ...
+  INFO   Done!
+```
+
 ## Deploying single site
 
-For single site/unmanaged sites mode, you may deploy a site by copying the site
+For single-site/unmanaged-sites mode, you may deploy a site by copying the site
 files to the site directory.
 
 You may copy the site files using `rsync` with SSH access to the server.

docs/guides/features/access-control.md

@@ -1 +1,79 @@
 # Access Control
+
+## Users & Credentials
+
+In pageship, users are mostly just ID for internal reference. For purpose
+of access control, each user/request is associated with a set of credentials, and
+credentials are matched with ACL for permission check.
+
+Pageship currently recognizes following credentials:
+
+### GitHub user
+
+The user/request is associated with a specific GitHub user.
+
+Users can be authenticated as GitHub user through SSH login with
+`pageship login` command:
+```sh
+$ pageship login
+GitHub user name: *****
+SSH key file: *****
+Logged in as *****.
+$
+```
+
+### [Github repository actions](./github-actions-integration.md)
+
+The user/request is originated from GitHub Actions running in a specific
+GitHub repository.
+
+`pageship` command would authenticate as GitHub repository actions automatically
+when it detected running in GitHub Actions environment.
+
+### IP address
+
+The user/request is originated from a specific IP address. All users/requests
+are automatically associated with an IP address credential.
+
+## Site Access
+
+Site access can be specified through ACL in the `access` field:
+```toml
+[site]
+access = [
+    { ipRange="127.0.0.1/32" }
+]
+```
+
+## App Management Access
+
+App management access can be specified through ACL in the `team` field:
+```toml
+[app]
+team = [
+    { githubUser="...", access="admin" },
+    { gitHubRepositoryActions="oursky/pageship", access="deployer" }
+]
+```
+
+There are three levels of access for management:
+- `reader`: read-only access to app metadata (e.g. list of deployments/sites)
+- `deployer`: access neccessary for deploying sites
+- `admin`: full access to the app
+
+In addition, the creator user of an app is considered as the owner of the app,
+and always has full access to the app.
+
+## API Access Control
+
+The server API may be protected from unwanted access by specifying an ACL file
+in `PAGESHIP_API_ACL` environment variable.
+
+```toml
+[[access]]
+githubUser="..."
+
+[[access]]
+gitHubRepositoryActions="oursky/pageship"
+
+```

docs/guides/features/automatic-tls.md

@@ -1 +1,3 @@
 # Automatic TLS
+
+Pageship supports automatic TLS through [certmagic](https://github.com/caddyserver/certmagic) library.

docs/guides/features/github-actions-integration.md

@@ -1 +1,21 @@
 # GitHub Actions Integration
+
+Pageship detects if it is running in GitHub Actions environment, and would
+authenticate with server automatically if possible.
+
+To deploy from GitHub Actions, first configure the app to accept GitHub Actions
+running in the repo as `deployer` permission. See [Access Control](./access-control.md)
+guide for details.
+
+After configuring access control, install `pageship` command in workflow and
+deploy directly.
+
+```
+docker run --rm \
+    -e PAGESHIP_API="..." \
+    -e ACTIONS_ID_TOKEN_REQUEST_URL="$ACTIONS_ID_TOKEN_REQUEST_URL" \
+    -e ACTIONS_ID_TOKEN_REQUEST_TOKEN="$ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
+    -v "$PWD:/var/pageship" \
+    ghcr.io/oursky/pageship:v0.3.1 \
+        deploy /var/pageship --site main -y
+```

docs/guides/setup-server.md

@@ -3,34 +3,34 @@
 Pageship supports three modes of deployment:
 
 
-## Single Site
+## Single-site mode
 
-Single site mode is the simplest deployment mode.
+Single-site mode is the simplest deployment mode.
 It hosts a single static site in a server, and pages can be updated by directly
 copying the files to the data directory.
 
 If you'd like to use the `pageship` command for deployment, or uses advanced
-features like preview deployment, please use managed sites mode.
+features like preview deployment, please use managed-sites mode.
 
 See the [setup guide for single site mode](./setup/single-site.md)
 
 
-## Unmanaged Sites
+## Unmanaged-sites mode
 
-Unmanaged sites mode hosts multiple static site on different sub-domains in a
+Unmanaged-sites mode hosts multiple static site on different sub-domains in a
 server. Static sites can be created by creating a site directory in the 
 data directory, and pages can be updated by copying the files to the site
 directory.
 
 If you'd like to use the `pageship` command for deployment, or uses advanced
-features like preview deployment, please use managed sites mode.
+features like preview deployment, please use managed-sites mode.
 
 See the [setup guide for unmanaged sites mode](./setup/unmanaged-sites.md)
 
 
-## Managed Sites
+## Managed-sites mode
 
-Managed sites mode provides advanced features like preview deployment, GitHub
+Managed-sites mode provides advanced features like preview deployment, GitHub
 Actions integration, but is more complex to setup.
 
 You can use `pageship` command to deploy to server and manage sites using this

docs/guides/setup/managed-sites.md

@@ -1,9 +1,63 @@
-# Managed sites
+# Managed-sites mode
 
-Managed sites mode hosts a multiple static sites in a server. The sites can
+Managed-sites mode hosts a multiple static sites in a server. The sites can
 be managed/deployed through `pageship` command.
 
-## Setup
+## Prerequisites
+
+Pageship in managed-sites mode requires a database to store management metadata,
+and object storage to store the actual site content.
+
+For database, we supports:
+- SQLite
+- PostgreSQL
+
+For object storage, we supports:
+- Filesystem
+- Azure Blob
+- GCS
+- S3
+
+For simplicity, Pageship uses SQLite with Filesystem storage by default. You
+may configure alternate database/object storage through configuration.
+
+## Docker compose
+
+```yaml
+version: "3"
+services:
+  controller:
+    image: ghcr.io/oursky/pageship-controller
+    volumes:
+      - data:/var/pageship
+    environment:
+      - PAGESHIP_MIGRATE=true
+      - PAGESHIP_DATABASE_URL=sqlite:///var/pageship/data.db
+      - PAGESHIP_STORAGE_URL=file:///var/pageship/storage?create_dir=true
+      - PAGESHIP_HOST_PATTERN=http://*.localhost:8001
+    ports:
+      - "8001:8001"
+```
+
+## Configuration
+
+The host pattern (`PAGESHIP_HOST_PATTERN`) specify how Pageship should map the
+request host to a site. The wildcard part would be extracted as the site name.
+
+By default, database schema is upgraded automatically on start. To disable it,
+set `PAGESHIP_MIGRATE` to false. You may run migration manually using the
+`migrate` subcommnad.
+
+The database can be specified by `PAGESHIP_DATABASE_URL`.
+- For SQLite, provide the path to the database file like `sqlite:///var/pageship/data.db`.
+- For PostgreSQL: provide the DSN like `postgres://postgres:postgres@db:5432/postgres?sslmode=disable`.
+
+The object storage can be specified by `PAGESHIP_STORAGE_URL`. Refer to
+documentation of [gocloud](https://gocloud.dev/howto/blob/) for URL format of
+different providers.
+
+Refer to [Server configuration](../../references/server-configuration.md) for
+detailed reference on configuration.
 
 ## What's Next
 

docs/guides/setup/single-site.md

@@ -1,6 +1,6 @@
-# Single site
+# Single-site mode
 
-Single site mode hosts a single static site in a server.
+Single-site mode hosts a single static site in a server.
 
 ## Setup
 
@@ -21,7 +21,7 @@ layout should look like this:
 ```yaml
 version: "3"
 services:
-  controller:
+  pageship:
     image: ghcr.io/oursky/pageship-server
     volumes:
       - /var/pageship:/var/pageship

docs/guides/setup/unmanaged-sites.md

@@ -1,6 +1,6 @@
-# Unmanaged sites
+# Unmanaged-sites mode
 
-Unmanaged sites mode hosts multiple static sites in a server.
+Unmanaged-sites mode hosts multiple static sites in a server.
 
 ## Setup
 
@@ -28,7 +28,7 @@ The directory layout should look like this:
 ```yaml
 version: "3"
 services:
-  controller:
+  pageship:
     image: ghcr.io/oursky/pageship-server
     volumes:
       - /var/pageship:/var/pageship