Skip to content

Deployment

Jump to bottom
Nick Hamze edited this page Sep 2, 2026 · 1 revision

Deployment

Dashless deploys a completed Astro dist/ directory as an immutable release. It supports WP Cloud, a local release directory, and SSH/rsync.

WP Cloud

WP Cloud exposes one public document root per Atomic site. Dashless works inside that constraint instead of trying to run Astro as another persistent process.

Build machine                          WP Cloud document root
─────────────                          ──────────────────────
Astro static output ─────────────────> wp-content/uploads/dashless/releases/<id>
Companion staged by key-based SFTP ──> wp-content/mu-plugins/dashless-wpcloud-<id>.stage
Verified companion installed ────────> wp-content/mu-plugins/dashless-wpcloud.php
Release activated through WP REST ───> dashless_wpcloud_release option

Astro and Node run on the local machine only. The WP Cloud site receives static HTML, CSS, JavaScript, images, social cards, mirrored media, and dashless-release.json.

Requirements

  • An existing WP Cloud/Atomic site
  • A WordPress user and dedicated Application Password
  • A key-enabled site SSH/SFTP user
  • Access to the document root's wp-content directory
  • A public HTTPS hostname served directly by the site

The default document root is /srv/htdocs; chrooted accounts commonly see /htdocs.

A WP Cloud API key is not required for deployment to an existing site. Account creation, site purchasing, provisioning, billing, DNS registration, and domain validation are outside Dashless 1.0.

Configuration

Conceptually, the target contains:

kind: wpcloud
public_url: https://example.com
host: <site SSH/SFTP host>
user: <key-enabled site user>
port: 22
htdocs_path: /srv/htdocs

Ask Codex to configure the target conversationally. Never paste a private SSH key into chat. Dashless uses the key or agent already available to the local SSH/SFTP client.

Read-only preflight

Configuration checks:

  • key-based SFTP access;
  • access to wp-content inside the selected document root;
  • WordPress REST authentication;
  • installed companion version and SHA-256 hash;
  • safe upgrade compatibility; and
  • whether the public hostname is direct or behaves like an alias.

The preflight refuses to replace a newer installed companion with an older packaged version.

Upload and activation

Every release receives an ID shaped from its build time and a random suffix. Dashless:

  1. builds at a stable WordPress content generation;
  2. rejects server-executable files from the static tree;
  3. creates a manifest containing every path, byte count, SHA-256 hash, release ID, public host, and content generation;
  4. uploads into a brand-new release directory with bounded retries;
  5. asks the authenticated companion to verify the entire directory;
  6. atomically selects the release;
  7. verifies the authenticated release state and public route; and
  8. restores the prior release automatically if public verification fails.

The immediately previous verified release remains available for explicit rollback.

Request routing

The companion reserves WordPress system routes such as /wp-admin, /wp-json, /wp-login.php, and /wp-cron.php. Reader-facing paths are resolved inside the active release. It never serves PHP from a release directory.

Hashed Astro assets and mirrored media are ordinary immutable static files. Reader HTML passes through a small PHP file router before WP Cloud's edge cache. Release-specific validators and cache-busted verification prevent a stale edge response from looking current.

Keep WP Cloud's static_file_404 behavior set to wordpress so generated routes with extensions, such as /rss.xml, can reach the companion when no root-level file exists.

Domains and aliases

The same hostname can serve both the Astro reader experience and WordPress REST. A separate cms.example.com is optional.

When the public hostname is a WP Cloud alias, it must be served directly rather than canonicalized to another host. DNS creation and validation remain a hosting operation, not a Dashless deployment step.

Same server with separate roots

When the host allows separate web roots, keep WordPress and the static frontend apart:

example.com      -> /var/www/dashless/current
cms.example.com  -> /var/www/wordpress

Point the reader virtual host at the current symlink. WordPress remains reachable at its own host for REST and emergency administration.

Local release directory

Use kind: local when the Dashless process can write directly to the public server filesystem. The releases path must be absolute.

Each deployment creates a new directory under releases/ and atomically changes current. Dashless 1.0 keeps old releases; the host may apply a retention policy after deployment is proven.

SSH/rsync release directory

Use kind: ssh when the static root is on another machine. SSH must already work with a key or agent. Dashless stores the hostname, username, port, and paths; it never asks for or stores an SSH password.

The remote path is limited to ordinary absolute-path characters. Dashless uploads to a new release with rsync, then changes the remote current symlink. A failed upload or activation leaves the previous release intact.

Recovery commands

Ask Codex:

Check whether the current WP Cloud deployment is ready without changing anything.

Build and deploy the current published WordPress state again. Do not republish any post.

Roll back the WP Cloud frontend to the immediately previous verified release.

The final operation requires explicit confirmation and affects only the static frontend pointer.

Dashless 1.0 · WordPress without the dashboard · Regionally Famous · MIT license

Dashless 1.0

Source repository
Security policy
Changelog

Clone this wiki locally