servd

# 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/ca