madoka.systems / wisp-deploy
minimal version of `wispcli deploy`
Star 0
Fork 0
Watch
Go 97%
Nix 3%
7 1 3
.tangled
cmd
internal
.gitignore
flake.lock
flake.nix
go.mod
go.sum
LICENSE
README.md
README.md

wisp-deploy #

wisp-deploy is a small, non-interactive go cli for deploying a directory to wisp.place from ci. it resolves an at protocol handle, finds its pds, uploads changed files, and writes the place.wisp.* records used by wisp.place.

it only deploys sites. use wispctl if you want oauth login or the other interactive commands.

authentication #

create an app password for the account and put it in the environment under WISP_APP_PASSWORD. this is the preferred option because the password does not appear in the process arguments.

--password is kept for compatibility with wispctl. command arguments may be visible to other processes or recorded by a ci runner, so avoid it when the environment variable is available. --password-file is also supported. an explicit flag or password file takes precedence over WISP_APP_PASSWORD; --password and --password-file cannot be used together.

handles are normally resolved through their /.well-known/atproto-did endpoint, with the _atproto dns record as a fallback. the resulting did:plc or did:web document provides the pds endpoint. pds connections must use https.

set WISP_MINIDOC_URL to the full blue.microcosm.identity.resolveMiniDoc xrpc endpoint to use a slingshot instance instead. this bypasses local handle and did resolution, so its response decides which pds receives the app password. use an https endpoint; plain http is only accepted for localhost.

usage #

usage: wisp-deploy [options] <handle>

deploy a static site to wisp.place

options:
  -p, --path <path>          directory to deploy (required)
  -s, --site <name>          site name (defaults to the directory name)
  --directory                enable directory listing
  --spa                      serve index.html for routes without a file
  -c, --concurrency <n>      number of concurrent uploads (default: 3)
  --force-gzip               gzip every file
  --password <password>      app password for headless authentication
  --password-file <path>     read the app password from a file
  -h, --help                 show help

for example:

export WISP_APP_PASSWORD='your app password'

wisp-deploy \
  example.com \
  --path ./dist \
  --site example

site names are at protocol record keys. they may contain letters, numbers, ., -, _, :, or ~, but cannot be . or ...

files #

all regular files below --path are deployed unless they match the built-in ignore list or .wispignore. symlinks and other non-regular files are skipped.

.wispignore uses gitignore-style patterns. the built-in list already skips version control directories, node_modules, virtual environments, caches, .env files, and .wispignore itself. point --path at the built site rather than the repository root unless you have checked everything that will be uploaded.

wisp.place currently allows up to 1,000 files, 300 mib per site, and 200 mib per file. the cli stops before uploading when a deployment exceeds one of those limits.

text files are gzipped before upload. unchanged blobs are reused from the existing manifest. uploads start with the requested concurrency and drop to two after a rate-limit response.

tangled ci #

add WISP_APP_PASSWORD to the spindle secrets, then use a step like this:

when:
  - event: ["push"]
    branch: ["main"]

engine: "nixery"

environment:
  SITE_PATH: "dist"
  SITE_NAME: "example"
  WISP_HANDLE: "example.com"

caches:
  https://madoka-systems.cachix.org: "madoka-systems.cachix.org-1:nUYOriy5WXsFsO/eok8g/IgME2IT+6Vmna3itvuxJH8="

dependencies:
  - git+https://tangled.org/madoka.systems/wisp-deploy#default

steps:
  - name: deploy to wisp
    command: |
      wisp-deploy \
        "$WISP_HANDLE" \
        --path "$SITE_PATH" \
        --site "$SITE_NAME"

use ?ref=refs/tags/v1.1.0 to pin this release. the did-based repository url is git+https://tangled.org/did:plc:ne3mufdifemv72zui4bqlp32.

license #

MIT. see LICENSE.