App settings file

Every App has one platform-managed settings file:

synsmarts-deploy:.synsmarts/{app_uuid}.yaml

The portal, CLI, and supported automation update this file before the platform renders and applies the change. It is the sole authority for customer-facing desired App configuration.

File shape

The file is YAML with schema_version: 1 and customer-editable sections. A platform-generated file can contain:

Section	Purpose
resources	CPU controls plus memory reservations for the seven reservable services.
services	Service enablement, offered versions, and registered service parameters.
config	Registered PHP values and validated Nginx snippet slots.
jobs	Scheduler enablement and cron-style job definitions.
env	Non-secret environment values.
secret_refs	Secret key names and delivery references, never secret values.
code	Customer-editable shared-path behavior for web and scheduled workloads.
tools	Enabled managed-shell tools from the offered catalog.
domains	App domains, DNS mode, role, redirects, and Magento store binding when applicable.
waf	Customer-editable origin WAF policy.
tracing	Default-on request-tracing collection state.
maintenance	Maintenance state and customer page content.
lifecycle	Platform lifecycle marker. Customers must not set deleting.

The exact nested fields depend on the App framework, purchased resources, enabled services, and current platform catalogs. Start with the file shown in App Settings or exported by a supported API rather than constructing a file from an internal AppSpec schema.

PHP service fields

The settings file has no runtime section. PHP-FPM for web requests and PHP-CLI for Scheduled Jobs are separate services:

Field	Purpose
services.php_fpm.version	Full x.y.z PHP version selected for web requests.
services.php_fpm.extensions	Complete desired list of supported opt-in extensions for PHP-FPM. An absent key preserves that context; [] clears its list.
services.php_cli.version	Full x.y.z PHP version selected for Scheduled Jobs.
services.php_cli.extensions	Complete desired list of supported opt-in extensions for PHP-CLI. An absent key preserves that context; [] clears its list.

For example, a WordPress App can record independent PHP selections like this:

services:
  php_fpm:
    version: "8.3.30"
    extensions:
      - imagick
  php_cli:
    version: "8.3.30"
    extensions: []

The two versions may differ. synsmarts validates each service and extension list against its own selected PHP version; it doesn’t require PHP-FPM and PHP-CLI to match.

The file never records a WordPress or Magento release or a catalog revision. Your composer.json owns the framework release; the settings file records only service choices that synsmarts can apply.

WordPress and Magento support imagick, memcached, apcu, oauth, rdkafka, ssh2, gnupg, and memcache (the classic PECL module, distinct from memcached; both can be enabled together). Magento also supports mongodb. apcu takes effect for web (PHP-FPM) requests; PHP disables it for command-line runs, so selecting it for Scheduled Jobs has no effect. Extension selections apply to PHP 8.1–8.4 and are validated against the selected PHP version. Each enabled extension consumes memory in every PHP worker, so it can reduce the shape-derived PHP-FPM worker count.

Service and config fields

• services.<service>.enabled controls optional service enablement where supported.
• services.<service>.version selects an offered version.
• services.redis.engine records the Redis-compatible implementation (valkey or redis) and must be submitted with its matching version.
• services.<service>.params contains only settings from the customer-editable parameter registry.
• config.phpIni.web and config.phpIni.cron contain registered PHP settings for web and Scheduled Job processes.
• config.nginxSnippets.server and config.nginxSnippets.location contain the validated Nginx snippet slots.
• env contains non-secret App environment values.
• secret_refs maps workload environment names to managed secret references.
• tracing.enabled is a strict boolean. If omitted, request tracing is enabled. Set it through Diagnostics so the portal can confirm the impact and show apply status.

See Service configuration fields for every current service parameter and platform-owned running value.

Required rules

• schema_version must be the supported integer version.
• The path must contain the exact App UUID.
• Top-level keys must be from the supported customer allowlist.
• Values must fit the purchased shape and service minimums.
• MySQL, the three Valkey roles, OpenSearch, RabbitMQ, Varnish, and NFS can carry customer memory_request values. Each renders as request equals limit.
• PHP-FPM, Nginx, cron, and Coraza/WAF can’t carry customer memory requests, limits, or burst-memory state. Legacy values are ignored on read; a new write is rejected with DYNAMIC_MEMORY_NOT_EDITABLE.
• Every recorded service version must be offered for the App; engine-bearing service versions must match their catalog engine.
• Service settings must appear in the customer-editable registry.
• Secret values must not appear in the file.
• tracing.enabled, when present, must be true or false, not a string.
• A file can be at most 256 KiB.
• Duplicate YAML keys, unsafe parser features, invalid types, and unsupported null values are rejected.

See Service configuration fields and Variables and secret references.

Platform authority

The platform-managed file remains authoritative whether the App deploys from Git or a workspace. The last-applied read model can lag while a newer settings revision is pending or failed. The deployment system consumes only generated runtime configuration; it doesn’t read .synsmarts/** directly.

Don’t mutate customer-facing desired configuration directly in the database or generated runtime configuration.

Customer repository import

A connected customer repository may contain:

.synsmarts/{app_uuid}.yaml

That file is untrusted, one-shot import input. During connect or an explicit later import, synsmarts:

1. pins the customer repository commit;
2. reads only the matching App path;
3. validates size, YAML, schema, App binding, shape, versions, service fields, secret references, and tenant isolation;
4. commits the accepted envelope to the platform-managed file;
5. dispatches the normal render and apply.

The customer repository never becomes the settings authority. Later pushes don’t change App settings. Re-import must be explicit and creates a new audited platform commit.

If the file is absent, repository connection continues without changing App settings. If validation fails, neither the settings file nor repository binding is changed.

Revisions and conflicts

A settings read returns the desired YAML and its current revision. A write submits the full desired envelope based on that revision.

If another change updated the App file after the read, the stale write is rejected. Load the latest settings, reapply the intended edit, and submit against the new revision. synsmarts never uses last-writer-wins for this file.

Apply and failure behavior

An accepted configuration revision becomes desired state before apply. The running App can temporarily remain on the last successful revision while the new revision is pending.

• A successful apply updates the running App and the applied read model.
• A failed apply leaves the committed desired file authoritative and preserves the last valid running projection.
• A superseded configuration change remains pending and is reconciled after the active App operation.
• A retry renders from the authoritative file, not reconstructed database values.

History and rollback

Every accepted change is a normal Git commit in the platform repository. Rollback creates a new commit that reapplies an earlier customer configuration; it doesn’t force-push, erase history, or write the database directly.

In App Settings, review the authoritative YAML, current revision, ingestion state, and available prior versions before restoring one. See Manage App Settings.