servd

name

servd

description

Servd (servd.host) — Craft-specialised managed hosting for Craft CMS. Covers git push-to-deploy with the optional servd.yaml build config, local → staging → production environments with uni-directional Project Config sync, the servd/craft-asset-storage plugin (S3-backed Flysystem volumes on the svdcdn.com CDN, off-server image transforms, Imager-X/ImageOptimize integrations), Servd's static caching (full vs tag-based purge, {% dynamicInclude %}, CSRF injection, cache-busting) and running Blitz alongside it in reverse-proxy mode, MariaDB/MySQL databases over an SSH tunnel, automatic + manual backups, the Dedicated Queue Runner, environment variables and secrets, the ephemeral load-balanced filesystem (Redis + remote volumes for runtime files), plugin/feature constraints, and Servd-vs-Craft-Cloud differences. Triggers on: servd.yaml, servd/craft-asset-storage, servd-asset-storage plugin handle, SERVD_PROJECT_SLUG, SERVD_SECURITY_KEY, SERVD_BUNDLE_HASH, files.svdcdn.com, Servd static caching, {% dynamicInclude %} (Servd), servd-asset-storage/clone, servd-asset-storage/local/pull-database, push-assets, clear-caches/servd-static-cache, clear-caches/servd-edge-caches, Dedicated Queue Runner, Servd Asset Platform, deploy to Servd, host Craft on Servd, Servd vs Craft Cloud. Do NOT trigger for Craft Cloud (use the craft-cloud skill), generic Craft deployment on Forge/bare metal (craftcms/deployment.md), or general DDEV local dev unrelated to Servd parity (ddev).

Servd — Managed Hosting for Craft CMS

Reference for Servd (servd.host), a Craft-specialised managed hosting platform. Covers git push-to-deploy and the servd.yaml build config, the local → staging → production workflow, the servd/craft-asset-storage plugin, Servd's static caching (and running Blitz alongside it), databases over SSH, backups, the queue runner, the ephemeral filesystem, and how Servd differs from Craft Cloud.

This skill is scoped to Servd specifically — what's different on Servd vs running Craft yourself on Forge or bare metal, and vs Pixel & Tonic's Craft Cloud. For generic Craft deployment, see the craftcms skill's deployment.md. For Craft Cloud, see the craft-cloud skill.

Companion Skills — Load When Needed

• craftcms — When the Servd topic intersects plugin or module PHP (ephemeral-filesystem guards, queue-job design, asset filesystem code).
• craft-site — When Servd intersects front-end templating ({% dynamicInclude %} islands in cached pages, transform usage, CSRF in cached forms).
• ddev — For local development; Servd has no first-party local environment, so DDEV is the standard local stack.
• craft-php-guidelines — When editing plugin PHP to add ephemeral-filesystem checks.

Documentation

Authoritative sources used to write this skill (Servd's own docs):

• Docs landing: https://servd.host/docs
• The Servd workflow: https://servd.host/docs/the-servd-workflow
• Node build step (servd.yaml): https://servd.host/docs/node-build-step
• Asset volumes & filesystems: https://servd.host/docs/servd-asset-volumes-and-filesystems
• Installing the plugin: https://servd.host/docs/installing-the-servd-plugin
• Static caching: https://servd.host/docs/static-caching
• Caching with Blitz: https://servd.host/docs/caching-with-blitz
• Handling runtime-created files: https://servd.host/docs/handling-runtime-created-files
• Dedicated queue runner: https://servd.host/docs/dedicated-queue-runner
• Backup & restore: https://servd.host/docs/backup-restore
• Plugin console commands: https://servd.host/docs/servd-plugin-console-commands
• Plugin source: https://github.com/servdhost/craft-asset-storage

Per-claim URLs appear in each reference file. Last verified against the docs on 2026-05-30. Some operational details (cron, exact plan tiers) are not in the public docs and are flagged as Verify where they appear.

What's Different on Servd vs Self-Hosted

Each row is a place self-hosted habits will mislead you.

Concern	Self-hosted	Servd
Config file	.env, config/*.php, web-server config	servd.yaml at repo root for the build step (optional; overrides dashboard); platform settings + runtime env vars in the Servd dashboard
Deploy	Whatever you've wired	Git push-to-deploy (GitHub/GitLab/Bitbucket or any SSH host) → Composer install + optional Node build
Environments	Yours to define	Fixed local → staging → production, uni-directional; allowAdminChanges off everywhere except local
Filesystem	Local disk	Ephemeral + load-balanced — disk writes don't persist; use Redis (Craft data cache) or a remote asset volume
Assets	Local or your own S3 config	servd/craft-asset-storage — S3-backed Flysystem on the *.files.svdcdn.com CDN, auto-separated per environment
Image transforms	Native / Imager-X / ImageOptimize on-server	Off-server transforms via the Servd Asset Platform; Imager-X uses transformer: 'servd'
Database	Whatever you installed	MariaDB or MySQL 8, reached over an SSH tunnel
Page caching	Blitz or similar	Servd static caching built in; Blitz runs alongside it in reverse-proxy mode (not instead of)
Queue	You run a worker	Default AJAX-triggered; opt into the Dedicated Queue Runner (paid plans) for isolated immediate processing
Cron	crontab	Not documented as a user-configurable feature — design around the queue (Verify for a given plan)
Redis	You install it	Provided — Craft's data cache is auto-mapped to a stateful Redis
SSH	ssh user@server	Yes — SSH sessions (used e.g. for the DB tunnel)
Env vars	.env	Dashboard-managed per environment (not a committed .env)

Servd vs Craft Cloud (quick contrast)

Both are managed Craft hosting with git deploy, ephemeral filesystems, S3 assets, off-server transforms, and dashboard env vars. Key differences for a developer:

	Servd	Craft Cloud
Repo config	servd.yaml (build) + dashboard	craft-cloud.yaml
Asset layer	servd/craft-asset-storage plugin	craftcms/cloud bundled filesystem
Database	MariaDB or MySQL 8	MySQL 8 / Postgres 15 (no MariaDB)
SSH	Yes	No
First-party CLI	None (plugin console commands + dashboard)	craftcms/cloud + php craft cloud/up
Caching	Servd static cache; Blitz runs alongside	Edge static caching; Blitz redundant
Transforms	Servd Asset Platform (svdcdn.com)	Cloudflare Images at the edge
Queue	Dedicated Queue Runner (paid)	Auto-processed

Common Pitfalls (Cross-Cutting)

• Writing to disk and expecting persistence. The filesystem is ephemeral and load-balanced — writes vanish and aren't shared across instances. Use Craft's data cache (auto-mapped to Redis) or a remote asset volume. See references/limitations.md.
• Making schema/Project Config changes anywhere but local. Servd sets allowAdminChanges: false on staging and production and syncs uni-directionally (local → staging → production). Make changes in local, commit, deploy. See references/deploy-and-environments.md.
• Treating Blitz as a replacement for Servd's caching. On Servd you run Blitz alongside the static cache in reverse-proxy mode (Yii Cache Storage + HTTP Generator + Servd Static Cache Purger) — Blitz's own server-rewrite mode is broken by Servd's load balancing. See references/caching.md.
• Committing a .env for runtime config. Runtime env vars live in the Servd dashboard per environment, not a committed .env. SERVD_PROJECT_SLUG / SERVD_SECURITY_KEY come from the dashboard's Assets page.
• Using a local asset volume. User assets must use the servd/craft-asset-storage filesystem so they land on the Servd Asset Platform and survive deploys. See references/asset-storage.md.
• Putting composer install / npm run build in a CI action. Servd runs both during its build step. Configure the Node build via servd.yaml or the dashboard instead. See references/deploy-and-environments.md.
• Assuming arbitrary cron. Servd doesn't document user-configurable cron. Move recurring work into queue jobs and the Dedicated Queue Runner. Verify per plan. See references/database-and-queue.md.
• Choosing the wrong database habits. Servd supports MariaDB and MySQL 8; reach the DB over the SSH tunnel, not a direct public port. See references/database-and-queue.md.

Reference Files

Read the relevant reference file(s) for your task. Multiple files often apply.

Task examples:

• "Deploy a Craft site to Servd" → deploy-and-environments.md
• "Configure the Node build step / servd.yaml" → deploy-and-environments.md
• "Set up environments and sync between them" → deploy-and-environments.md + local-dev.md
• "Install Servd asset storage" → asset-storage.md
• "Why are my uploaded assets disappearing?" → asset-storage.md + limitations.md
• "Set up image transforms on Servd" → asset-storage.md
• "Enable static caching" → caching.md
• "Run Blitz on Servd" → caching.md (Blitz reverse-proxy mode)
• "Add a dynamic island to a cached page" → caching.md ({% dynamicInclude %})
• "Connect to the Servd database" → database-and-queue.md
• "Set up the queue / run recurring jobs" → database-and-queue.md
• "Back up / restore / sync the database" → database-and-queue.md + local-dev.md
• "Set up local development for a Servd project" → local-dev.md
• "Pull production assets/database to local" → local-dev.md
• "Why does my plugin's file write fail on Servd?" → limitations.md
• "What plugins work on Servd?" → limitations.md
• "Should I use Servd or Craft Cloud?" → limitations.md (Servd vs Cloud) + this file's table

Load only the reference files your task needs.

Reference	Scope	~Lines
references/deploy-and-environments.md	Git push-to-deploy, the build step (Composer + Node, servd.yaml keys, Node versions), environments (local → staging → production, uni-directional), Project Config + allowAdminChanges, env vars & secrets, the deploy/clone workflow	~150
references/asset-storage.md	servd/craft-asset-storage plugin (composer package, handle, install), SERVD_PROJECT_SLUG/SERVD_SECURITY_KEY, the Servd filesystem on *.files.svdcdn.com, per-environment dirs, off-server transforms, Imager-X (transformer: 'servd') and ImageOptimize integrations	~140
references/caching.md	Servd static caching (enable + TTL, Full vs Tag-Based purge, exclude prefixes, {% dynamicInclude %} tag, CSRF injection, auto cache-busting on save, clear-caches/servd-static-cache + servd-edge-caches), and running Blitz in reverse-proxy mode	~140
references/database-and-queue.md	MariaDB / MySQL 8, SSH-tunnel access, automatic + manual backups (30-day retention, 90-day deleted-asset window), the Dedicated Queue Runner, the cron caveat, console sync commands	~130
references/local-dev.md	DDEV-based local dev (no first-party Servd local env), SERVD_* vars for local, servd-asset-storage/local/pull-assets·push-assets·pull-database·push-database, servd-asset-storage/clone, uni-directional sync discipline	~120
references/limitations.md	Ephemeral + load-balanced filesystem (Redis + remote volumes for runtime files), plugin/feature constraints, the documented-vs-unknown gaps (cron), the full Servd-vs-Craft-Cloud comparison, and the repo detection signals (servd/craft-asset-storage, servd.yaml, SERVD_* env vars)	~140