Configuration

Updated

Matte runs with none of its own settings changed. Every key has a working default, and those defaults are what a Laravel Cloud deployment should use. Change one only when you have a reason to. Matte has no settings screen; everything here is an environment variable.

Settings Laravel Cloud fills in

Laravel Cloud injects the configuration for the database, the managed queue and the storage bucket, including connection selectors such as DB_CONNECTION, QUEUE_CONNECTION and FILESYSTEM_DISK. Never set these yourself on the Matte environment. A value you set shadows the injected one and breaks that resource.

Two Matte settings follow those injected values when they are left unset, and should stay unset on Cloud:

MATTE_DISK is the disk originals and results are written to. Unset, it uses FILESYSTEM_DISK, which is the attached bucket.
MATTE_QUEUE_CONNECTION is the queue connection conversion jobs run on. Unset, jobs go to the app's default connection, which is the managed queue.

Server settings

These live on the Matte environment.

Variable	Default	What it does
`MATTE_DEFAULT_MODE`	`ml`	The engine used when a request does not name one: `ml` or `grabcut`.
`MATTE_TIMEOUT`	`120`	Seconds a single conversion may run before it is stopped.
`MATTE_MODEL_NAME`	`isnet-general-use.onnx`	The model file `ml` mode uses by default.
`MATTE_MODEL_URL`	the model published with the `bg-remover` release	Where the build downloads that model from.
`MATTE_BG_REMOVER_TAG`	`v0.8.0`	The `bg-remover` release the build downloads.
`MATTE_ONNX_VERSION`	`1.19.2`	The ONNX Runtime version the build downloads.
`MATTE_RUNTIME_PATH`	`runtime/` inside the app	Where the binary, library and models are installed. Leave it unset: the build puts them at the default, inside the artifact.
`MATTE_ROUTE_PREFIX`	empty	A prefix for the three API routes, if you want them somewhere other than `/v1/...`. The Laravel client always calls `/v1/...` on `MATTE_URL`, so a prefix also has to be part of the `MATTE_URL` your apps use. Scalpels writes the bare environment URL when it attaches an app, so leave this empty if you attach apps through Scalpels.
`MATTE_CALLBACK_TIMEOUT`	`5`	Seconds a registered callback delivery may take in total.
`MATTE_CALLBACK_CONNECT_TIMEOUT`	`2`	Seconds spent connecting for that delivery.

MATTE_BG_REMOVER_TAG, MATTE_ONNX_VERSION, MATTE_MODEL_NAME and MATTE_MODEL_URL are read when the build runs matte:provision-binary, so a change takes effect on the next deploy.

The conversion timeout and the queue

MATTE_TIMEOUT has to stay below the managed queue's own job timeout. If the queue stops a job before Matte does, the conversion is killed from outside and its job is left at processing for good. You can satisfy this either by raising the managed queue's timeout above MATTE_TIMEOUT in Laravel Cloud, or by lowering MATTE_TIMEOUT below the queue's timeout. See Troubleshooting.

Settings in a connected app

These live in a Laravel app that uses artisan-build/matte-client. When you attach the app through Scalpels, it writes MATTE_URL and MATTE_TOKEN for you; the rest have working defaults.

Variable	Default	What it does
`MATTE_URL`	none	The Matte environment's base URL. Required.
`MATTE_TOKEN`	none	The credential for that instance. Required, and a secret.
`MATTE_DEFAULT_MODE`	`ml`	Mode used when a call does not pass one.
`MATTE_DEFAULT_PRESET`	`balanced`	Preset used when a call does not pass one.
`MATTE_POLL_INTERVAL`	`2`	Seconds between status checks while waiting.
`MATTE_POLL_TIMEOUT`	`120`	Seconds to wait for a job before giving up.
`MATTE_STORE_DISK`	none	If set, `AwaitRemovalJob` saves each result to `matte/<job-id>.png` on that disk.
`MATTE_CALLBACK_PATH`	`matte/callback`	Where the client mounts its callback receiver.
`MATTE_CALLBACK_SUBJECT_REF`, `MATTE_CALLBACK_INSTALLATION`, `MATTE_CALLBACK_APPLICATION`, `MATTE_CALLBACK_AUDIENCE`	none	Used only for registered completion callbacks. They must match the destination registered on the Matte server.

MATTE_POLL_TIMEOUT should be long enough for your slowest conversion. With the server's 120-second limit and a busy queue, a job can still be queued or processing when the client gives up, and the client then reports a timeout even though the job may finish later.

To publish the client's config file to config/matte.php:

php artisan vendor:publish --provider="ArtisanBuild\MatteClient\MatteClientServiceProvider" --tag=matte-config