Deploying
App templates
Templates start an app with an image, a port and variables that already fit stackd, plus the databases and volumes it needs: WordPress, Ghost, Umami, n8n, Metabase, Vaultwarden, Gitea, Directus, Firefly III, and the frameworks Laravel, Next.js, Astro and Vite, built from your repo.
Picking one
The New app page lists the templates in one gallery, beside an app from any image. Filter by category (websites, analytics, productivity, developer tools, frameworks: those built from a repo) or search by name, tagline, description and engine. Each card shows what the template needs, optional databases and volumes dashed. Picking one folds the gallery into a line with a way back, and its form follows.
Optional databases (WordPress's Redis) and volumes (Laravel's) can be left out, with the variables that reference them.
The frameworks are built from your repo (Apps built from git):
Next.js and Astro with optional databases, whose links' DATABASE_URL and
REDIS_URL the app reads as it likes; Laravel with processes and a release
command (Processes and release commands). Their request
takes a source, and the app is built first, then deployed.
Making one
The form, or POST /api/templates/{id}/apps, takes the app's name and
replicas, the template's inputs (Ghost's site URL, say), and for each
database and volume of the template either an existing one (database_id)
or a new one to make with the app (create: name, topology, servers).
- Databases. The app is linked as usual, with the user and database
(MySQL: schema) named after it unless you choose (
username,database_name). A chosen user must be new on that database; a PostgreSQL database must be new too, since the app owns it, while on MySQL an existing schema is granted to the new user. Custom names work on MySQL and PostgreSQL that aren't sharded, also throughPOST /api/apps/{id}/databases. A database slot can set variables by the engine picked (Laravel'sDB_CONNECTION). - Volumes. The app mounts the template's path (WordPress:
wp-content), seeing a folder named after it by default, any other folder, or the volume's root (subdir: ""). One volume serves many apps, each in its own folder, so you don't need a volume per app. - Waiting. A database or volume that isn't ready yet (a new one,
usually) is linked or mounted as soon as it is. With
deploy, the app deploys at once if nothing waits, or as soon as nothing does. The app's page shows what it waits for; "Stop waiting" drops one and the automatic deploy. A database apps wait for can't be deleted. - Undo. If anything fails while making it, the app and the databases made for it are deleted again.
Services, after the app is made
A template's databases (Laravel's database, Redis and object storage) can be
linked, changed and removed later from the app's Settings → Services
(GET /api/apps/{id}/services, PUT and
DELETE /api/apps/{id}/services/{slot}), each with the template's variables
for it, as when the app was made:
- Linking or changing (an existing store, or a new one made then)
replaces the slot's link, sets the template's variables that name it
(
DB_HOST=${{DATABASE_HOST}},AWS_BUCKET=${{S3_BUCKET}}) and the engine's (DB_CONNECTION,CACHE_STORE=redis,FILESYSTEM_DISK=s3), and redeploys the app if it runs. With a store that isn't ready yet, the app keeps what it had until it is, then switches over and redeploys. Picking the linked store again drops the change. Data isn't copied between stores. - Removing an optional slot unlinks it and takes its variables away. A required one (Laravel's database) can only be changed. Refused while something the app runs needs it: Horizon needs Redis, as does Reverb on more than one replica.
Variables you changed are left alone: a template variable is added only if
missing and removed only if it still has the template's value; an engine's
only while it holds one of the slot's values (a QUEUE_CONNECTION=sync
chosen with no queue stays when Redis comes).
Variable references
Templates fill their image's variables from the link's with references:
WORDPRESS_DB_HOST=${{DATABASE_HOST}}:${{DATABASE_PORT}}. At each deploy,
${{NAME}} in any app's variable becomes NAME's value, links' variables
included, in one pass; unknown names stay as written. Secrets (WordPress's
keys and salts, Umami's APP_SECRET, n8n's N8N_ENCRYPTION_KEY) are made
once, when the app is.
WordPress
The template runs stackd/wordpress:7: WordPress 7, PHP 8.5 and Apache 2.4
on Debian 13, the official image plus two additions, each off without its
variables. Patch releases of PHP and Apache arrive with stackd's updates.
Apps made with the template before keep stackd/wordpress:6 (WordPress 6 on
its image's PHP), so a redeploy doesn't move them to another PHP.
- Database reads stay on the server. Writes go to
WORDPRESS_DB_HOST(the link's read/write port, the primary), reads toWORDPRESS_DB_RO_HOST(its read-only port, the member on the same server, Managed databases), and reads of a table the request wrote to the primary. - Object cache in Redis (Redis Object Cache, optional). Reads go to Redis's copy on the server, writes to the primary. A read in another request just after a write can be milliseconds old.
- The volume. On a replicated volume (the default) the template mounts
all of
/var/www/html: WordPress, its plugins and themes on every server's disk, so updates from WordPress's admin reach every server within seconds. While an update made on another server is still arriving, pages answer 503 "back in a moment". On a shared volume it mountswp-contentand caches metadata for 30 seconds; core updates from the admin don't work there (core files are in each container), and the first page after a while idle can be slow when the volume's primary is far away.
Logging in, saving and other writes wait on the primaries, so keep the database and volume primaries close to the servers that serve the site.
Firefly III
fireflyiii/core on PostgreSQL or MySQL, attachments on a volume
(storage/upload), and optionally Redis.
- More than one replica needs Redis. The form and
POST /api/templates/firefly-iii/appsrefuse more than one without it, and Settings → Services won't remove Redis from an app with more. Logins, API tokens and preferences then work through every replica. - Sessions are kept in the database, so they outlive redeploys.
- Attachments: Firefly III stores uploads as local files only, so for object storage use a shared volume (in S3). A replicated volume works too, files reaching the other servers within seconds.
- Jobs, made with the app (Scheduled jobs):
cron(firefly-iii:cron, 03:00 UTC: recurring transactions, auto-budgets, bill reminders, exchange rates) andclear-cache(03:30), which keeps Redis from filling up. - Queue (option): in the request, Firefly III's default, or a worker
(
queue:work,QUEUE_CONNECTION=database). With the worker, what Firefly III queues (a new user's group, balances, webhooks) lands a second or two later.
Personal access tokens fail ("Personal access client not found") until you run this once, from the app's Run command:
php artisan passport:client --personal --name=personal --provider=users --no-interaction