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).

 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 supported providers for more information.

provider.endpoint

The provider endpoint.

See supported providers for more information.

provider.config

Provider-specific configuration settings.

See supported providers for supported config settings:

• git config
• s3 config

provider.secrets

The provider secret(s).

See supported providers for supported secrets names:

• git secrets
• s3 secrets

Supported 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

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:

• Cloudflare Pages (recommended)
• Netlify
• Vercel
• Render
• Fly.io
• Railway
• GitHub Pages
• GitLab Pages
• Codeberg Pages
• DigitalOcean App Platform
• AWS Amplify Hosting
• Azure Static Web Apps
• Self-hosted with any physical or virtual server that builds and serves a site from a git branch.
• ...and more!

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:

• Cloudflare R2 (recommended)
• Amazon S3
• Google Cloud Storage (via S3 Interoperability mode)
• Fastly Object Storage
• DigitalOcean Spaces
• Linode Object Storage
• Hetzner Object Storage
• Backblaze B2
• Self-hosted S3 buckets with MinIO, Ceph, SeaweedFS, Garage
• ...and more!

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.