upsun · pjcdawkins · Apr 22, 2026
diff --git a/plugins/upsun/skills/upsun/references/config.md b/plugins/upsun/skills/upsun/references/config.md
@@ -1,142 +1,57 @@
-# .upsun/config.yaml -- Reference Templates
+# Configuration reference
 
-Full config reference: https://developer.upsun.com/docs/get-started/here/configure
+This chapter indexes per-language and per-framework configuration
+guidance for Upsun. Always check the canonical registry for
+currently-supported runtime and service versions before committing:
 
-## Hook phases
+- https://meta.upsun.com/images
 
-Hooks are shell scripts (Dash) that run in order:
-
-1. **`build`** -- runs in an isolated container with internet access but **no access to services** (databases, caches). The app filesystem is writable here. Start with `set -ex` to fail fast.
-2. **`deploy`** -- runs after the app is built and connected to services, but before it accepts internet traffic. Use for database migrations, cache warming. The app filesystem is **read-only** at this point.
-3. **`post_deploy`** -- runs after the app is open to traffic. Use only when tasks must happen after public access (reduces deployment downtime for long-running tasks, but risks inconsistency).
-
-## `.environment` file
-
-A shell script at the app root, sourced at runtime. Use it to construct derived env vars from the auto-generated service variables:
-
-```bash
-# Example: build a DATABASE_URL from the auto-generated relationship vars.
-# If the relationship is named "database", Upsun exposes $DATABASE_HOST, $DATABASE_PORT, etc.
-export DATABASE_URL="${DATABASE_SCHEME}://${DATABASE_USERNAME}:${DATABASE_PASSWORD}@${DATABASE_HOST}:${DATABASE_PORT}/${DATABASE_PATH}"
-```
-
-Write to `.environment` in the build hook if the content needs shell logic.
-
----
-
-## Minimal app (no services)
-
-```yaml
-applications:
-  myapp:
-    type: 'nodejs:24'        # check https://meta.upsun.com/images for supported versions
-    build:
-      flavor: none           # manage dependencies explicitly in the build hook
-    hooks:
-      build: |
-        set -ex
-        npm install
-        npm run build
-    web:
-      commands:
-        start: 'node server.js'   # required for all runtimes except PHP
-
-routes:
-  'https://{default}/':
-    type: upstream
-    upstream: 'myapp:http'
-  'https://www.{default}/':
-    type: redirect
-    to: 'https://{default}/'
-```
-
----
-
-## Adding services
-
-To add services, declare them under the top-level `services` key and connect them via `relationships` in the app. The relationship name determines the env var prefix (uppercased, runtime-only).
-
-```yaml
-applications:
-  myapp:
-    # ... (type, build, hooks, web as above)
-    relationships:
-      database: 'db:postgresql'   # exposes $DATABASE_HOST, $DATABASE_PORT, etc.
-      cache: 'redis:redis'        # exposes $CACHE_HOST, $CACHE_PORT, etc.
-
-services:
-  db:
-    type: 'postgresql:16'
-  redis:
-    type: 'redis:7.2'
-```
-
----
-
-## Monorepo (multiple apps)
-
-Use `source.root` to point each app at its subdirectory:
+## A minimal working example
 
 ```yaml
 applications:
-  frontend:
-    source:
-      root: /frontend
-    type: 'nodejs:22'
-    build:
-      flavor: none
-    hooks:
-      build: |
-        set -ex
-        npm install
-        npm run build
-    web:
-      commands:
-        start: 'npm start'
-
-  backend:
-    source:
-      root: /backend
-    type: 'nodejs:22'
-    build:
-      flavor: none
-    hooks:
-      build: |
-        set -ex
-        npm install
+  app:
+    type: nodejs:24
     web:
       commands:
-        start: 'npm start'
+        start: npm run start
     relationships:
-      database: 'db:postgresql'
-
+      database: db:postgresql
 services:
   db:
-    type: 'postgresql:16'
-
-routes:
-  'https://{default}/':
-    type: upstream
-    upstream: 'frontend:http'
+    type: postgresql:18
 ```
 
----
-
-## Available runtimes, services and versions
-
-Canonical source (always up to date): https://meta.upsun.com/images
-
-Each image entry has a `versions` map with a `status` of `supported`, `deprecated`, `retired`, or `decommissioned`.
-Use only `supported` (or `deprecated` if a specific older version is required).
-Services have `"service": true`; runtimes have `"service": false`.
-
----
-
-## Notes
-
-- `{default}` resolves to the project's default domain. In preview environments, auto-generated URLs are used.
-- Resources (CPU, memory, disk) are set via the API/CLI (`upsun resources:set`), not in the YAML config.
-- `web.commands.start` is expected for all runtimes except PHP (which uses PHP-FPM by default).
-- For PHP apps, set `build.flavor: none` and use `composer install --no-dev --no-interaction --optimize-autoloader` in the build hook.
-- Relationship names become the env var prefix (uppercased). The vars are runtime-only.
-- Run `upsun init` to auto-detect your stack and generate a starter config.
+## Per-language references
+
+- [go](config/go.md)
+- [js](config/js.md)
+- [php](config/php.md)
+- [python](config/python.md)
+- [ruby](config/ruby.md)
+- [static](config/static.md)
+
+## Per-framework references
+
+- [directus](config/directus.md)
+- [django](config/django.md)
+- [drupal](config/drupal.md)
+- [echo](config/echo.md)
+- [express](config/express.md)
+- [flask](config/flask.md)
+- [gatsby](config/gatsby.md)
+- [gin](config/gin.md)
+- [hugo](config/hugo.md)
+- [jekyll](config/jekyll.md)
+- [laravel](config/laravel.md)
+- [nextjs](config/nextjs.md)
+- [nuxt](config/nuxt.md)
+- [rails](config/rails.md)
+- [reactjs](config/reactjs.md)
+- [sinatra](config/sinatra.md)
+- [strapi](config/strapi.md)
+- [sylius](config/sylius.md)
+- [symfony](config/symfony.md)
+- [vite](config/vite.md)
+- [vuejs](config/vuejs.md)
+- [wordpress](config/wordpress.md)
diff --git a/plugins/upsun/skills/upsun/references/config/directus.md b/plugins/upsun/skills/upsun/references/config/directus.md
@@ -0,0 +1,130 @@
+## Directus Application Configuration
+
+Reference configuration for Directus applications on Upsun.
+
+**Framework Priority**: Use Directus-specific configuration instead of generic Node.js guidance when both apply.
+
+**Minimum Requirements**: Node.js 18+ required for Directus compatibility
+
+**Template Usage**: Adapt database service and authentication configuration to project requirements. Exclude explanatory comments from production configurations.
+
+```yaml
+applications:
+  directus:
+
+
+    type: nodejs:24
+
+    build:
+      flavor: none
+
+    hooks:
+      build: |
+        set -ex
+        npm install
+        npm run argon2-rebuild
+
+        # Create .environment file with dynamic variables
+        cat > .environment <<EOF
+        CACHE_ENABLED=true
+        CACHE_STORE=redis
+        REDIS_HOST=\$REDIS_HOST
+        REDIS_PORT=\$REDIS_PORT
+        RATE_LIMITER_ENABLED=true
+        RATE_LIMITER_STORE=redis
+        RATE_LIMITER_REDIS_HOST=\$REDIS_HOST
+        RATE_LIMITER_REDIS_PORT=\$REDIS_PORT
+        KEY=\$PLATFORM_PROJECT_ENTROPY
+        SECRET=\$PLATFORM_PROJECT_ENTROPY
+        EOF
+
+      deploy: |
+        set -ex
+        if [ ! -f var/upsun.installed ]; then
+          echo 'Bootstrapping Directus on first deploy...'
+
+          export PROJECT_NAME='Directus on Upsun'
+          export ADMIN_EMAIL='admin@example.com'
+          export ADMIN_PASSWORD='password'
+
+          npx directus bootstrap
+
+          touch var/upsun.installed
+        else
+          npx directus database migrate:latest
+        fi
+
+    web:
+      commands:
+        start: npx directus start
+
+    variables:
+      env:
+        NODE_ENV: production
+        DB_CLIENT: pg
+        EXTENSIONS_PATH: ./extensions
+        UPLOADS_LOCATION: local
+        UPLOADS_LOCAL_ROOT: ./uploads
+
+    mounts:
+      var:
+        source: storage
+      uploads:
+        source: storage
+
+    relationships:
+      db: {}
+      redis: {}
+
+services:
+  db:
+    type: postgresql:18
+
+  redis:
+    type: redis:8.0
+
+routes:
+  https://{default}/:
+    type: upstream
+    upstream: directus:http
+    cache:
+      enabled: true
+      default_ttl: 0
+      cookies: ['*']
+      headers: ['Accept', 'Accept-Language']
+
+  https://www.{default}/:
+    type: redirect
+    to: https://{default}/
+```
+
+**Configuration Details**:
+
+- **Database Service**: PostgreSQL 16 service. Service named "db" exposes standard DB_ environment variables.
+- **Caching**: Single Redis service for both application caching and rate limiting. Service named "redis" exposes standard REDIS_ environment variables.
+- **Environment File**: Dynamic variables written to `.environment` file during build hook for proper substitution
+- **Authentication**: Uses platform project entropy for key/secret generation ensuring unique values per environment
+- **File Storage**: Local upload storage with persistent mount for file retention
+- **First Deploy**: Automated bootstrap process creates admin user on initial deployment
+- **Database Migration**: Automatic schema updates on subsequent deployments
+- **Argon2 Rebuild**: Required dependency rebuild for password hashing compatibility
+- **Upload Directory**: Persistent storage mount for file uploads with local storage driver
+- **Extensions**: Support for custom Directus extensions in dedicated directory
+
+**Security Notes**:
+- Change default admin credentials immediately after first login
+- Project entropy provides cryptographically secure keys unique to each environment
+- Database credentials managed automatically via service relationships
+- File uploads restricted to designated mount for security isolation
+
+**Build Process**:
+1. Install Node.js dependencies including Directus core
+2. Rebuild Argon2 native bindings for platform compatibility
+3. Create `.environment` file with dynamic Redis and authentication variables
+4. Bootstrap database and admin user on first deployment
+5. Run schema migrations on subsequent deployments
+6. Start Directus server with production configuration
+
+---
+
+Version numbers change over time. Verify against https://meta.upsun.com/images before committing configuration.