Provider reference

Overview

A provider is a local or remote website hosting service. HyperTemplates currently provides a built-in git provider and s3 provider for deploying HyperTemplates websites to dozens of hosting services.

Example

Providers are configured on a per-website basis in the website configuration file (site.yaml or site.json).

site.yaml 
 1---
 2base_url: https://hypertemplates.net
 3title: HyperTemplates
 4description: the pure-HTML templating system for the modern web.
 5...: ... # other website settings
 6providers:
 7  cloudflare-r2:
 8    kind: s3
 9    endpoint: https://xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.r2.cloudflarestorage.com
10    config:
11      bucket: hypertemplates-production
12    secrets:
13      - name: access_key_id
14        key: AWS_ACCESS_KEY_ID
15      - name: secret_access_key
16        key: AWS_SECRET_ACCESS_KEY

Reference

provider.kind
The provider type.

See hosting providers for more information.

provider.endpoint
The provider endpoint.

See hosting providers for more information.

provider.config
Provider-specific configuration settings.

See hosting providers for supported config settings:

provider.secrets
The provider secret(s).

See secrets providers for more information on how HyperTexting clients read secrets.

See hosting providers for supported secrets names:

Hosting providers

git provider

git config
The git provider supports the following configuration parameters:
  • branch: the branch name to use (required)
  • publish_dir: the subdirectory (if any) to write to (default: .)
  • known_hosts: SSH known_hosts entries used to verify the Git remote host identity.
  • author_name: optional author name (default: hyperproviders)
  • author_email: optional author email (default: hyperproviders@localhost)
  • tag_enabled: if enabled, tags deployed commit as <tag_prefix><build_id> (default: false)
  • tag_prefix: optional tag prefix (default: "build-")
  • tag_retain_last: keep only the N most recent matching tags; older ones are pruned locally and on the remote (default: 0, no pruning)

Example:

 1providers:
 2  github_pages:
 3    kind: git
 4    endpoint: [email protected]:OWNER/REPO.git
 5    config:
 6      branch: gh-pages
 7      known_hosts: |
 8        github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl
 9        github.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEmKSENjQEezOmxkZMy7opKgwFB9nkt5YRrYMjNuG5N87uRgg6CLrbo5wAdT/y6v0mKV0U2w0WZ2YB/++Tpockg=
10        github.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndNxQowgcQnjshcLrqPEiiphnt+VTTvDP6mHBL9j1aNUkY4Ue1gvGC7uEnztnZyaVWQ7B381AK4Qdrwt51ZqExKbQpTUNn+EjqoTwvqNj4kqx5QUCI0ThS/YkOxJCXmPUWZbhjpCg56i+2aB6CmK2JGhn57K5mj0MNdBXA4/WnwH6XoPWJzK5Nyu2zB3nAZp+S5hpQs+p1vN1/wsjk=        
11    secrets:
12      - name: ssh_private_key
13        key: ${HOME}/.ssh/id_ed25519

NOTE: publish_dir must be a relative path and cannot escape the repository root or target .git.

NOTE: if known_hosts is not configured, SSH connections are made with host key verification disabled.
git secrets
The git provider supports the following secrets for authentication:
  • token: the authorization token for HTTP/HTTPS endpoints
  • ssh_private_key: the SSH key
  • ssh_passphrase: SSH key passphrase

Example

 1providers:
 2  default:
 3    kind: git
 4    endpoint: [email protected]/herdworks/hypertemplates-web.git
 5    config:
 6      branch: gh-pages
 7
 8    secrets:
 9      - name: ssh_private_key
10        key: ${HOME}/.ssh/gh_pages

HTTP/HTTPS git endpoints must provide a token secret (e.g. GitHub Personal Access Token or Deploy Token), and SSH git endpoints must provide an ssh_private_key secret.
git hosting services
The git provider works with the following hosting services:

The HyperTexting git provider works with any service that builds and serves a site from a git branch — including a plain SSH server with git installed and a post-receive hook deploying to a web server like nginx, Caddy, or Apache.

s3 provider

s3 config
The s3 provider supports the following configuration parameters:
  • addressing_style: path or virtual (default: path)
  • bucket: the target bucket name (required)
  • region: the bucket region (default: auto)
  • cache_control: optional Cache-Control header value applied to every uploaded object
  • conditional_mode: if set to etag, objects whose remote ETag matches the local MD5 are skipped (default: not set / always upload)
  • workers: maximum concurrent uploads (default: 10, must be ≥ 1)
s3 secrets
The s3 provider requires the following secrets for authentication:
  • access_key_id: the access key ID (required)
  • secret_access_key: the secret access key (required)

NOTE: region: auto only works for endpoints that don't care (e.g. Cloudflare R2); set region explicitly for hosting providers that require a region (e.g. Amazon S3).
s3 hosting services
The s3 provider works with the following hosting services:

The HyperTexting s3 provider is built on the (AWS SDK for Go v2) and should work with any S3-compatible object store.

ssh provider

A dedicated ssh provider is coming soon, but in the interim the git provider already supports deploying to ssh-based git endpoints, complete with SSH key authentication.

.deploymentignore files

All hosting provider implementations support .deploymentignore files for excluding files from deployments.

.deploymentignore uses .gitignore-style patterns, with one pattern per line. Blank lines and lines starting with # are ignored.

Example

.deploymentignore 
1build.log
2build.json

NOTE: the hyperctl build and hyperctl deploy commands auto-generate .deploymentignore files whenever the --log-file and/or --date-file flags are set.

Secrets providers

HyperTexting secrets providers are key-value stores that return sensitive values needed for access to one or more hosting providers. The HyperTexting secrets manager currently supports the following key-value stores:

  • Environment variables (e.g. $AWS_ACCESS_KEY_ID)
  • Files (e.g. path/to/local/key or ${HOME}/.ssh/example)
  • Runtime secrets

NOTE: the "runtime" secrets provider enables client applications to handle secret retrieval directly instead of relying on the underlying HyperTexting libraries, while ensuring sensitive values are never persisted to disk or printed in HyperTexting log outputs. Clients such as the official HyperTexting iOS app use the runtime provider to take advantage of platform-native secrets APIs such as iCloud Keychain.

Secret key variable expansion

Secret keys support variable expansion of ~/, $HOME/, and ${HOME}/, which are replaced with the absolute path to the current user's home directory.

Resolving secrets

HyperTexting clients such as the official CLI (hyperctl) and HyperTexting app resolve secrets by looking up the provided secret.key value using one or more secrets providers. For example, because the hyperctl CLI supports the environment variable and files providers, it will first check for an environment variable matching the provided secret key, and if no match is found, it will attempt to read a file at the provided secret key.

Example:

In the following example, hyperctl will skip checking if an environment variable named ${HOME}/.ssh/example exists (because / is an illegal character for environment variable names), and proceed to check if a file exists at that path.

site.yaml 
 1providers:
 2  default:
 3    kind: git
 4    endpoint: [email protected]:herdworks/hypertemplates-web.git
 5    config:
 6      branch: gh-pages
 7      publish_dir: public/
 8    secrets:
 9      - name: ssh_private_key
10        key: ${HOME}/.ssh/example

while the official HyperTexting app supports the runtime provider (i.e. the iOS app provides secrets at runtime)

💬 Join the community

Stay up-to-date with the latest releases and other news from the Team behind HyperTemplates. Ask the developers questions, get help from the community, and share your creations! 🎨