Skip to main content

Photo upload providers

Configure photo hosting in config/server/opensource.lua. This file is server-only and editable outside escrow. FiveManage is the default; you can use the included raw PNG adapter for your own host or add another provider. Permissions and the photo UI do not change.

warning

Keep credentials in the server-only file. Never put them in shared/client configuration, public image URLs, provider results, or photo metadata. Do not publish a configured file containing real keys.

Install and configure​

  1. Follow Installation and install screenshot-basic for photo capture with any provider.
  2. Start screenshot-basic before wasabi_mdt. If renamed, update Resources.SCREENBASIC.name in shared configuration. Keep its capture endpoint reachable from players.
  3. Configure one of the providers below in config/server/opensource.lua.
  4. Restart wasabi_mdt after configuration changes. On a controlled server, check photo capture, public image display, and deletion before deploying the configuration to production.

FiveManage (default)​

Create a FiveManage account and set:

Config.PhotoProvider = 'fivemanage'
Config.FIVEMANAGE_API_KEY = 'YOUR_SERVER_ONLY_API_KEY'

The server obtains a short-lived presigned URL. The client uploads through screenshot-basic using the multipart file field; it does not receive your API key.

Self-hosted raw PNG PUT​

Edit the existing settings (do not add duplicate configuration blocks):

Config.PhotoProvider = 'raw_png'
Config.RawPhotoUpload = {
enabled = true,
uploadBase = 'https://uploads.example.invalid/mugshots',
publicBase = 'https://images.example.invalid/mugshots',
headers = { Authorization = 'YOUR_SERVER_ONLY_TOKEN' },
}

Replace both .invalid placeholder URLs with your real HTTPS endpoints and replace the token/header to match your host. Do not add trailing slashes to the base URLs. These placeholders are not a hosted service.

Your upload endpoint must:

  • Accept PUT /mugshots/<generated-name>.png with your configured headers and Content-Type: image/png.
  • Store the raw PNG request body: not JSON, a data URI, or multipart form data.
  • Return a 2xx status only after storing the image. The response body is ignored.
  • Make the same filename available at publicBase/filename. The MDT image viewer must be able to read this URL without the private upload header.

The adapter captures PNG through screenshot-basic on behalf of the requesting player, decodes the data URI on the server, and sends the PUT from the server. Your custom upload URL and authentication headers are not sent to the client. The generated filename is stored as the photo's remote ID.

The included raw_png.delete hook sends DELETE to uploadBase/filename using the same headers and accepts 2xx or 404. Remove this hook if your host does not support deletion. Local photo removal still works.

Custom provider contract​

Add a uniquely named entry to Config.PhotoProviders and select its name with Config.PhotoProvider. Each entry supports:

FunctionContract
ready() (optional)Return true when configured and available.
upload(ctx, done)Call done({ url = 'https://public/image.png', id = 'remote-id' }) on success, or done(false, 'upload_failed') on failure. fileId is also accepted instead of id.
delete(photo, ctx, done) (optional)Read photo.stored_id and call done(true) or done(false) after attempting remote deletion.

The public URL must use HTTP or HTTPS and fit within 255 characters; use HTTPS in production. The optional remote ID must be a string of at most 120 characters. Deletion is skipped when no remote ID was saved.

Server-owned helpers:

  • ctx.source: requesting player for uploads; absent for deletion.
  • ctx.filename: generated PNG filename, not taken from player input.
  • ctx.capturePNG(function(bytes, errorCode) ... end): capture and decode PNG with a 5 MiB decoded size limit, base64 checks, and a PNG signature check.
  • ctx.http(url, method, body, headers, callback): server HTTP; callback receives status and response body. Redirects are disabled to avoid forwarding credentials. Handle status codes and host-specific responses in your adapter.
  • ctx.uploadPresigned(httpsUrl, done): client multipart upload for short-lived presigned URLs only. Never pass long-lived credentials here.
  • ctx.pathSegment(value): escape a remote ID as a single URL path segment for deletion.

Callbacks settle once. Provider operations have a 30-second deadline; client multipart capture/upload has a 25-second deadline. Only one capture per player can run at a time. Missing configuration or screenshot-basic prevents capture, and failed uploads do not create a photo record. The UI reports capture failure generically.

Provider history and deletion​

New photos store the provider name in metadata.photoProvider, not a snapshot of its configuration. Legacy photos without this field belong to FiveManage. Removing a photo uses its saved provider, not the currently selected upload provider.

Keep historical provider names, credentials, and endpoints available if you want their images deleted remotely. Create a new provider name when changing hosts instead of repointing an old entry. Existing photo URLs are not migrated, and changing a provider's settings does not update stored URLs.

Remote deletion is best-effort. Local rows are removed even if the provider is missing, disabled, has no deletion hook, times out, or rejects deletion. This also applies to bulk removal. No separate database migration is required for provider selection.

Hosting limits and troubleshooting​

  • If capture is unavailable, check screenshot-basic's resource name/start order and the selected provider's credentials or enabled setting.
  • If upload fails, check the host's method, authorization, MIME type, response status, and response time. Use a direct endpoint: redirects are not followed.
  • If upload succeeds but display fails, check that the generated public URL serves the image without private authentication.
  • PNG signature and size checks are not a complete image decoder or content sanitizer. Harden your host's storage and image serving, and apply upstream request limits; screenshot-basic buffers its upload before MDT validates the decoded image size.
  • Timeouts stop MDT processing but cannot cancel an HTTP request already sent. A timed-out PUT or failed database insert can leave an orphaned image; configure host retention/cleanup policies.
  • Before changing providers, verify both new uploads and deletion of older photos using the historical provider configuration.