Server Settings Reference

The MT Showcase server reads its settings from YAML configuration files. Most installations need none of these: the defaults suit a standard installation, and the public address, certificate and email are set in the Editor; see Network, HTTPS and email.

Where settings come from

The server combines settings from these sources. Later sources override earlier ones:

Built-in defaults.
The packaged configuration file: production.yaml on Ubuntu, production_win.yaml on Windows, or the macOS equivalent inside the app bundle. Do not edit it: it is replaced when you upgrade.
production_users.yaml, the file you edit. For its location, see File locations.
Environment variables; see Environment variables.
Command-line options given to the server.

Settings saved in the Editor (public addresses, the certificate installed on Network & Public Access, and Email settings) take precedence over the matching settings in the configuration files.

Windows: settings are replaced when you upgrade

On Windows, production_users.yaml is in the installation folder, and upgrading MT Showcase replaces it with a new, empty template. Keep a copy of your changes and apply them again after each upgrade; see Upgrade. Where a setting can be made in the Editor instead, prefer that: settings saved in the Editor are kept in the database. On Ubuntu and macOS the file is kept when you upgrade.

Edit production_users.yaml

Open production_users.yaml in a text editor as an administrator (on Ubuntu, for example, sudo nano /etc/MultiTaction/mt-showcase/server/production_users.yaml). On macOS, create the file first; see File locations.
Every setting is listed in the file, commented out. Remove the # at the start of the line you want to change and set the value. Leave a space after the colon:
```
https_port: 9443
```
Save the file and restart the MT Showcase server; see Start and stop MT Showcase.

Storage paths

Values must point at persistent storage. The built-in defaults are under the system temporary folder, which can be cleared on restart, so the packaged configuration overrides them on each platform.

Setting	Description	Default
`asset_root`	Media library: images, videos and PDFs added to MT Showcase	Ubuntu: `/var/lib/mt-showcase-server/assets`. Windows: `%APPDATA%/mt-showcase-server/assets`. macOS: `~/.mt-showcase/data`
`sites_root`	Hosted sites, served at `/www/<site>/`	Ubuntu: `/var/lib/mt-showcase-server/sites`. Windows: `%APPDATA%/mt-showcase-server/sites`. macOS: `~/.mt-showcase/sites`
`backup_root`	Default folder for backups. A subfolder is created for each backup.	Ubuntu: `/var/lib/mt-showcase-server/backups`. Windows: `%LOCALAPPDATA%/MultiTaction/showcase/backups`. macOS: `~/.mt-showcase/backups`
`export_root`	Working folder for export archives	Ubuntu: `/var/lib/mt-showcase-server/exports`. macOS: `~/.mt-showcase/exports`. Windows: `\tmp\showcase-export` on the installation drive
`tmp_root`	Working folder for uploads in progress and import staging	Ubuntu: `/var/lib/mt-showcase-server/tmp`. macOS: `~/.mt-showcase/tmp`. Windows: `\tmp\showcase` on the installation drive

Large imports on Windows

Imports are staged in tmp_root and need roughly twice the archive size in free space. On Windows, if the installation drive is short of space, set tmp_root and export_root to folders on a drive with enough room.

Databases

Setting	Description	Default
`db`	The main application database, as `sqlite://<path>`	Ubuntu: `sqlite:///var/lib/mt-showcase-server/showcase.db`. Windows: `sqlite://%APPDATA%/mt-showcase-server/showcase.db`. macOS: `sqlite://~/.mt-showcase/showcase.db`
`reporting_db`	The reporting database for data gathering, as `sqlite://<path>`	`showcase-reporting.db` beside the main database

Components

Setting	Description	Default
`component_paths`	Comma-separated folders scanned for widget and service packages. Add a folder here to install custom widgets.	Ubuntu: the installed version's `lib` folder and `/etc/MultiTaction/mt-showcase/plugins`. Windows: the installation folder, `%PROGRAMDATA%/MultiTaction/showcase/plugins` and `%LOCALAPPDATA%/MultiTaction/showcase/plugins`

Networking

Setting	Description	Default
`http_host`	Address the Editor listens on. `0.0.0.0` means all network interfaces.	`0.0.0.0`
`port`	Plain-HTTP port. Used only when `https_enabled` is `false`.	Ubuntu, Windows: `80`. macOS: `8080`
`control_port`	Port the MT Showcase client connects to the server on	`9299`
`control_host`	Address the control channel listens on	`127.0.0.1` (the application computer only)
`public_url`	The server's public address, used in links in emails. Normally set in the setup wizard or on Network & Public Access, which take precedence.	Derived from the HTTPS settings, for example `https://localhost`

Keep the control channel local

Leave control_host at 127.0.0.1. The MT Showcase client runs on the same computer as the server, and the control channel is not meant to be reachable from the network. See the Hardening checklist. The comment in the shipped production_users.yaml template may show 0.0.0.0 as the default; the default that applies is 127.0.0.1.

HTTPS

Setting	Description	Default
`https_enabled`	Serve the Editor over HTTPS. Leave it `true`: browsers discard the Editor's sign-in cookies over plain HTTP on any address other than `localhost`, so users are signed out every few minutes. Set it to `false` only if a reverse proxy in front of the server handles HTTPS.	`true`
`https_port`	HTTPS port	Ubuntu, Windows: `443`. macOS: `8443`
`tls_cert_path`	Path to your certificate (PEM, full chain). Leave empty for the self-signed certificate. See HTTPS certificate.	Empty
`tls_key_path`	Path to the matching private key (PEM)	Empty
`cert_dir`	Folder for the self-signed certificate	Ubuntu: `certs` beside the database. Windows: `%PROGRAMDATA%/mt-showcase-server/certs`. macOS: `~/.mt-showcase/certs`

When https_port is 443 and the port is unavailable, the server uses 8443 instead. Any other port you set is used as given, and the server does not start if it is unavailable; see Troubleshooting.

Email

These settings configure the mail server for invitations and password resets. Settings saved in the Editor's Email settings dialog take precedence over them.

Setting	Description	Default
`smtp_host`	SMTP server host name	Empty
`smtp_port`	SMTP port. `587` for STARTTLS, `465` for implicit TLS.	`587`
`smtp_user`	SMTP user name. Empty means no authentication.	Empty
`smtp_password`	SMTP password. It is stored as plain text in this file, so prefer the Email settings dialog.	Empty
`smtp_from`	Sender address	`noreply@localhost`
`smtp_secure`	`true` for implicit TLS, `false` for STARTTLS	`false`

Public content

Setting	Description	Default
`public_asset_folders`	Comma-separated folders, relative to `asset_root`, that anyone who can reach the server may read without signing in. Set it only for files you intend to be public.	Empty (off)
`profile_url`	URL of the visitor profile page, usually a hosted site such as `/www/<site>/`. Empty turns off the profile bubble.	Empty

Audience uploads

These settings control visitor uploads from phones; see Audience Integrations.

Setting	Description	Default
`audience_public_origin`	Address visitors' phones use. Normally set as Audience and phone URL on Network & Public Access.	Empty (uses the public address)
`audience_upload_page_path`	Path of the upload page	`/upload`
`audience_person_fields`	Comma-separated fields visitors may edit about themselves	`firstName, lastName`
`audience_max_upload_bytes`	Largest single upload, in bytes	`10485760` (10 MB)
`audience_max_pixels`	Largest image, in total pixels	`50000000`
`audience_accepted_mime`	Comma-separated file types visitors may upload	`image/jpeg, image/png, image/webp, video/mp4`
`audience_max_uploads_per_token`	Uploads allowed for each QR code issued	`10`
`audience_upload_token_ttl_seconds`	How long an upload QR code stays valid, in seconds	`600`
`audience_max_pending_per_target`	Uploads awaiting moderation before new ones are refused	`50`
`audience_upload_per_ip_max`	Uploads allowed from one IP address within the window below	`30`
`audience_upload_per_ip_window`	Window for the per-address limit	`10 minutes`
`audience_quarantine_retention_days`	Days rejected uploads are kept before they are deleted	`30`

Media tools

Both are found automatically on a normal installation. Set them only if previews do not appear (thumbnails show as "?").

Setting	Description	Default
`ffmpeg`	Path to the `ffmpeg` program used for video and image previews	Detected automatically
`showcase_app`	Path to the MT Showcase client program, used for PDF previews	Detected automatically

Feature switches

Setting	Description	Default
`integrations_enabled`	Audience features: hosted sites, personal folders, visitor uploads and external integrations. `false` turns them off and hides them in the Editor.	`true`
`setup_allow_remote`	Allow the setup wizard to be completed from another computer. Use only for a headless installation, and remove it once setup is complete.	`false`

Environment variables

These environment variables override the configuration files. They are useful for temporary changes you do not want on disk.

Variable	Overrides
`SHOWCASE_EDITOR_PORT`	`port`
`SHOWCASE_HTTPS_PORT`	`https_port`
`SHOWCASE_HTTPS_ENABLED`	`https_enabled` (`false` turns HTTPS off)
`SHOWCASE_HTTP_HOST`	`http_host`
`SHOWCASE_CONTROL_PORT`	`control_port`
`SHOWCASE_CONTROL_HOST`	`control_host`
`SHOWCASE_INTEGRATIONS_ENABLED`	`integrations_enabled` (`true` turns them on)
`SHOWCASE_SETUP_ALLOW_REMOTE`	`setup_allow_remote` (`true` allows remote setup)