Upgrade notes

From mnema-talk v3.3.13, rendered on this site.

What operators need to know when moving between versions, and the update procedure for a self-hosted (NAS) compose deployment. The full list of changes is in CHANGELOG.md; the configuration is described in operations.md.

Database migrations are embedded in the binary and run automatically at startup, in order, and are forward-only: an older version cannot use a schema a newer one migrated. Take a backup before every update.

Messages with a lifetime, auto-delete in hours (migration 0106)

Members can send messages that the server deletes after a lifetime they choose, and auto-delete works in hours, days or weeks, can remove only the files, and can follow a community default (timed messages). Lifetimes are on by default (Server settings > Messages switches them off); the auto-delete default is off. Channels keep their period; a channel whose auto-delete was turned off in its settings stays off, every other channel without a period follows the default once one is set, which the confirmation of the default says. A channel whose entry the audit retention has already removed cannot be told from one never set: it follows the default too. The column channels.auto_delete_days is replaced by auto_delete_hours; the API still answers auto_delete_days (whole days between 1 and 90 while auto-delete is on). See the 0106 row below.

Nothing new may name an erased account (migration 0103)

Migration 0103 adds triggers: one on every table with a foreign key to users, one on messages, one on message_reports (a report's copy of the conversation) and one on audit_log, and tightens the trigger on users that keeps a deleted account final. A row that names an erased account (a message, reaction or upload that was still under way while the member deleted their account) is refused, or, for another member's row about them (a thread follow, a mention, a report), written without them. The migration adds no column and rewrites no row. Each insert into those tables does one more primary key lookup on users, measured at about 9 µs per row on a bulk insert; a single request does not notice it. Restoring a backup is unaffected: pg_dump writes triggers after the data.

Removals from a Talk in the audit log

A moderator's removal of a member from one Talk is now recorded as voice.disconnect, so in the console it moves from the Members ("user") filter group to Talk presence ("voice"); the admin-wide kick keeps user.talk_kick. Like voice.join, it is read only by auditors who can view the Talk, and older user.talk_kick entries of such a removal (they carry the Talk in their details) are now read the same way. A removal from a conversation's call Talk is no longer recorded; older entries of that kind stay in the log, readable by the Owner and Administrators (the log is immutable, and a call Talk is usually gone, so they cannot be told apart).

Calls in conversations no longer need View channels

The Talk started from a conversation was resolved like a community channel, so in a community that hides its channels from @everyone a member without a role granting View channels could start a call but neither open its chat nor join it. Membership of the conversation now decides: no View channels is needed, and channel or category overwrites, if any were set on such a Talk, no longer apply there. The server-wide permissions (Connect, Speak, Video, Send messages, a timeout, the new-member speak wait) still do. Nobody outside the conversation gets anything, as before.

Conversations' calls leave the community's objects

A Talk started from a conversation is no community channel. It can no longer be the location of an event or an exemption of an automod rule, and the administrative channel routes (rename, delete, duplicate, auto-delete, overwrites, layout) answer for it what they answer for a channel that does not exist; its leader renames it with PATCH /api/talks/{id}. Nothing about such an event (cancelling it, its roster, deleting a comment) is audited any more. Audit entries written earlier (event.talk_*, channel.update, channel.duplicate, channel.delete, automod.rule_* naming a call) stay readable by the Owner and the Administrators: the log is immutable.

A role mention next to @all breaks a mute

A message such as @all @Dev stored the members of the role as reached by @all only, so a member who muted the channel got no mention badge and no push, although @Dev alone breaks the mute. A member reached several ways is now stored by the strongest reason: a name, then a role, then @all or @here. The other way round, a name the sender may not use no longer counts: a webhook with allow_user_mentions off, or a bot whose allowed_mentions leaves users out and does not list the member, posting @all @name reaches that member through @all only, which a mute silences, and does not mention a bot it names at all (@all never reaches bots). Messages sent before the update keep the kinds they were stored with.

Messages gain direct_mentions (REST and the message_create and message_update events): the members of mentions addressed by name or role, not by @all or @here alone. The web app reads it in a muted channel for the live badge, the desktop notification and the sound, so they match the badge after a reload. mentions is unchanged. A web app from before this release ignores the new field and still counts a plain-text name next to @all live in a muted channel until it reloads; against an older server the web app reads the text as before.

Snippets of long messages are their plain text

Places that show only the start of a message took its first 200 characters of Markdown, so a ||spoiler|| that closed after the cut was open in the snippet and its text showed: reply quotes, search thread roots, reminders (list, in-app notice and push) and the conversation list. A message longer than 200 characters is now reduced to its plain text first and cut after that; the snippet is that text written as Markdown, each spoiler as ||…|| (a shorter message is still sent as it is). This concerns reply_to.content of messages, snippet of search roots and reminders, and last_message.text of conversations. Clients that strip the snippet themselves, older web and desktop clients included, show the same text as before without the hidden part.

For bots and outgoing webhooks (message_create deliveries carry reply_to.content), a snippet of a long message is escaped plain text: a backslash stands before every symbol that would start Markdown, and the : of http:// and https:// is escaped too. Rendered as Markdown it shows the plain text and the spoilers, but no formatting and no links, not even for an address the message had in a code span; a text such as @everyone stays text and is drawn the way the renderer draws it, which notifies nobody. The escaping makes a snippet longer than its 200 characters of text: at most 996 characters (UTF-16 units), when every character of it is a spoiler.

The server's plain text (pushes and these snippets) now reads a message exactly like the web renderer: it is a port of the client's Markdown parser, checked against messages the renderer judged. Before, the two could disagree about where a spoiler starts (for example around code spans), and a push could show the text of a spoiler. Where only a browser can tell how a link reads (a host with non-ASCII characters, written or percent-encoded, an IPv6 address, punycode) and that could move a spoiler, the server hides everything between the first and the last || of the message.

Trusted Types in the web app's policy

The web app's Content-Security-Policy now also sends require-trusted-types-for 'script' and a trusted-types list of the four policies the app uses (see SECURITY.md under "Trusted Types"). In Chromium, Safari 26+ and Firefox 148+ a script on the page can no longer hand a plain string to innerHTML, new Worker and similar sinks; older browsers ignore the directives. Nothing needs to be configured, and the app, the installed web app and the desktop clients work as before.

It matters only where something else adds scripts to the page: a reverse proxy or CDN feature that rewrites the HTML to inject a script (which script-src 'self' already refused), or a proxy that replaces the policy with its own. A replaced policy that requires Trusted Types must list vue, mnema-markdown, mnema-script-url and mnema-emoji-picker. The API reference (/api/docs) keeps the policy without the two directives.

Bot uploads: mentions in the caption need allowed_mentions

The caption of a file a bot posts (POST /api/bot/v1/channels/{id}/upload) now follows the mention rule the bot API documents for messages. Before, a caption with @all, @here or @Role notified whenever the bot's roles allowed it. Now it notifies only when the request also asks for it in the new optional form field allowed_mentions, the JSON object the message route takes, for example {"parse":["everyone","roles"]}. Members named in the caption are notified as before.

A bot that relied on the old behaviour must send allowed_mentions with its uploads. Nothing else changes for bots: the field is optional and the permissions (Mention @all and @here, mentionable roles) decide as before. See bots.md.

Picture attachments lose their metadata (migration 0101)

A JPEG, PNG or WebP sent as an attachment used to be stored byte for byte, so a phone photo kept its EXIF record: GPS position, camera model, time. From this version the server stores it without EXIF, XMP, IPTC, comments, text chunks, content credentials (C2PA) and embedded thumbnails, and the stored file ends where the picture ends. What stays is an allow-list: the image data, the colour information and the animation; a segment or chunk the server does not know is removed, whatever it is called. The picture is not re-encoded: image data, colour profile and animation frames are the bytes that were sent, and the orientation is written back so a photo is still shown the right way up. Every other file type is stored as before. Details and limits are in SECURITY.md ("Metadata of picture attachments").

  • What members can notice. Data appended to a picture is no longer stored: a motion photo arrives as its still picture without the video, an HDR photo with a gain map is shown in standard range, and a file hidden behind a picture (an archive, a second picture) is gone. A photo whose colour space is named in EXIF only (Adobe RGB from a camera, without a colour profile) is shown as sRGB, and a WebP without the extended header loses its EXIF orientation. A download is not byte-identical to the JPEG, PNG or WebP that was sent.
  • On by default, also after an update. Migration 0101 adds instance_settings.strip_image_metadata (default on). A community that shares photos for their metadata (camera settings, position) can switch it off in the admin System tab (Upload size, Remove metadata from pictures), Owner only, recorded in the audit log.
  • New uploads only. Attachments stored before the update keep their metadata; nothing is rewritten in storage.
  • Sizes. The size shown for an attachment, counted against UPLOAD_QUOTA_MB_PER_DAY and sent as Content-Length is the stored one, which is never larger and usually a little smaller than the file that was sent. The upload limit still applies to the file as sent.
  • API. GET and PUT /api/admin/upload-limit gained the optional field strip_image_metadata; a client that does not send it changes nothing. A file fetched back from /api/media/{id} is no longer guaranteed to be byte-identical to the JPEG, PNG or WebP that was uploaded.

Key rotation

Nothing to do. An instance that sets none of the new variables stores and reads exactly what it did before: session cookies are signed with JWT_SECRET, and the authenticator secrets and recovery codes of two-factor sign-in stay under the keys derived from it, in the same format. No stored value is rewritten.

New and optional: JWT_SECRET_PREVIOUS lets you replace the session secret without signing anyone out, DATA_KEY moves the second factor's data to a key of its own (with DATA_KEY_PREVIOUS while that one is replaced), and mnema-talk rotate-keys moves every stored authenticator secret to the current key. Replacing JWT_SECRET no longer forces a two-factor reset when the old value is named in JWT_SECRET_PREVIOUS. The steps are in operations.md.

Once DATA_KEY is set and secrets have been moved to it, an older release cannot read them: after a rollback to one, the affected accounts need reset-2fa. Without DATA_KEY a rollback is unaffected.

DATA_KEY stays once it is set: from then on authenticator secrets are sealed under it, and emptying it later leaves them unreadable (the server logs AUTHENTICATOR SECRETS CANNOT BE READ at start and mnema-talk doctor shows it). Keep the value with your backups. To go back to the keys derived from JWT_SECRET, follow Stop using a data key.

Migration 0102 adds a nullable column to recovery_codes that records which key a new recovery code is under, so codes under a retired key are no longer counted as remaining. Existing codes are untouched, and an older release ignores the column.

Public message and talk totals (migrations 0098 and 0099)

The totals on a profile and in the member list are public, so they no longer include anything that is private to a few people.

  • Messages. The chat of a conversation's call is as private as the conversation and is no longer counted in a member's message total (messages.counted, decided when the message is written). Migration 0098 recomputes every total once; members who wrote in calls see a lower number.
  • Talk time. voice_seconds and user_stats now show a separate public total that only counts stays in Talks visible to @everyone (decided when the stay starts). The stored history cannot tell public from hidden time, so the public total starts at zero with this version and counts from then on. The old private total stays in the database (and the data export); it is not shown to other members.

Database statement timeout

From this release the server cancels a database statement of a request that runs longer than DB_STATEMENT_TIMEOUT (default 15s) and ends its own sessions that sit idle inside a transaction for a minute. Nothing needs to be configured: migrations, the data export, the sweeps and bulk deletes keep longer limits of their own, and backups are not affected. DB_MAX_CONNS (default 25, the size the pool always had) is new as well. See operations.md.

Broad trusted proxies

TRUSTED_PROXY_CIDRS entries wider than an IPv4 /24 or an IPv6 /64 used to log a startup warning when the listener was not loopback. Production and staging now refuse to start with that configuration. A single proxy address, an IPv4 prefix of /24 or longer, an IPv6 prefix of /64 or longer, and any range while the listener is loopback, still start. Set the value to the reverse proxy's address before updating, or the new process exits during configuration and the previous container is already gone.

Update procedure (compose, released image)

The steps (backup, choosing between the update button, docker compose pull and a pinned tag, verification) are on one page: Updating. This page keeps the per-version notes below and the rollback procedure.

Rollback

Do not roll back below this release once roles or private channels exist. Migration 0017 adds the tables that restrict access. A binary that does not know them (0.7.x before roles, or older) would ignore them and show every private channel to everyone. This release and later ones refuse to start on a database migrated by a newer version, but binaries from before that guard existed cannot. To go back, restore a backup taken before the update.

Stop the app before changing its image or database. If the new version applied migrations (migration applied in its log), restore the pre-update database and media before starting the old app. Released 0.4.x binaries, including 0.4.4, have no downgrade refusal guard. The newer migration runner adds that guard; it cannot protect an older binary. Never run the old image against the migrated PostgreSQL 18 database.

For a PostgreSQL 17 → 18 upgrade, use the saved 0.4.x compose file and image with the preserved postgres-data volume. PostgreSQL 18 has a separate postgres18-data volume; keep both until the rollback or recovery is verified. The preserved PostgreSQL 17 database reflects the upgrade's cutover, so writes made afterward on PostgreSQL 18 are not in that rollback.

set -e
docker compose stop app postgres
cp docker-compose.yml.bak docker-compose.yml
sed -i "s|^MNEMA_IMAGE=.*|MNEMA_IMAGE=ghcr.io/msch128/mnema-talk:0.4.4|" .env # the saved old version
docker compose pull app
docker compose up -d --wait postgres seaweedfs
# If the preserved volume is unavailable or a backup rollback is required,
# restore a complete pre-update backup here, while the app is still stopped:
# ./scripts/restore.sh /path/to/backups/<timestamp> --verify
# ./scripts/restore.sh /path/to/backups/<timestamp> --yes
docker compose up -d --wait app
curl -fsS http://127.0.0.1:8080/api/health

For an update that kept the same database volume, the backup restore is required if migrations changed its schema. The restore replaces the database and media with the backup's state and preserves the current .env and compose configuration. Keep the complete backup (Updating, step 1) and the saved compose file until the new release has passed your application checks.

Automatic rollback in an unattended updater

A script that updates without you (the cron example in Unattended updates) should go back in this order when the new version does not become healthy:

  1. Wait while a migration still runs. The server holds a PostgreSQL advisory lock (key 470003576161) from the first migration to the last and logs migration applied for each file; a rollback in the middle of a long migration helps nobody.
  2. Put the old image back (the old .env or tag) and start it. If the new version applied no migration, the old one starts and nothing is lost.
  3. If the old version refuses the database (the database was migrated by a newer version), restore the backup this very update took, after checking its COMPLETE file, manifest and SHA256SUMS, never an older one, then start the old version and require it to be healthy. Writes made after that backup are lost.
  4. If that fails too, stop the app, leave a marker that stops further update attempts and report it. Never retry the same release in a loop; wait for a newer one.

Version notes

3.0.x to 3.3.x

Each 3.x release after 3.0.0 is an ordinary update (procedure above, backup first); none breaks the public API. The notes at the top of this page describe what changed; this list says which release brought it. Taking several releases at once applies their migrations in order (see the migration table under 1.1.x → 1.2.0).

  • Image path (3.2.1). The repository moved to the mnema-xyz organization. Releases after 3.2.1 are published only at ghcr.io/mnema-xyz/mnema-talk; ghcr.io/msch128/mnema-talk gets no new ones and GHCR does not redirect, so docker compose pull there finds nothing new. If MNEMA_IMAGE in .env still names the old path, change it to ghcr.io/mnema-xyz/mnema-talk with the same tag, then docker compose pull && docker compose up -d. Admin > System says so while the old path is set, and "Update now" refuses until it is changed. The updater trusts releases signed before and after the move.
  • 3.0.2: DB_STATEMENT_TIMEOUT and DB_MAX_CONNS (Database statement timeout).
  • 3.0.3: optional key rotation (Key rotation).
  • 3.0.4: migrations 0101 and 0102; picture attachments lose their metadata (details), bot upload captions need allowed_mentions, Trusted Types in the policy.
  • 3.0.9 and 3.0.10: migrations 0103 and 0104; snippets, mentions next to @all, and the calls of conversations (the sections above).
  • 3.1.0: migration 0105, the bot platform (manifests, buttons and selects, the bot SDKs; bots.md).
  • 3.2.0: migrations 0106 and 0107: messages with a lifetime and auto-delete in hours (details); a bot can be given access to every channel. An older release refuses to start on the database 0106 migrated.
  • 3.3.0: migrations 0108 to 0110: members can create invites (invites.md). On an existing install the new permission Create invites goes only to roles that already hold Manage invites, so members cannot create invites until the Owner gives it to them.
  • 3.3.5: the server checks at startup that its database role may run pg_logical_emit_message (PostgreSQL grants it to PUBLIC) and does not start without it. Only an external PostgreSQL whose administrator revoked that grant is affected (operations.md).
  • 3.3.8 and 3.3.9: migrations 0111 (display names lose invisible format characters) and 0112 (a new covering index for the unread counts, built at startup; it blocks message writes for about 0.5 s per million messages).

Upgrading to 3.0.0

3.0.0 is the major release that collects the changes of 2.9.2 to 2.9.21 which touch the public API (api-stability.md). Update as usual (backup first, then the procedure above). It works from any 2.9.x; an older 2.x applies the migrations of every release in between.

What runs automatically (migrations 0092 to 0100, in order, at startup):

  • 0092 adds attempts and retry_at to scheduled_messages. A scheduled message whose send keeps failing on the server's side is retried with growing pauses and, after five tries, kept as a failed draft instead of being retried every 15 seconds for ever.
  • 0093 indexes messages(user_id). It is a plain CREATE INDEX, which blocks writes to messages while it builds, like 0091. On a large database update at a quiet time.
  • 0094 adds seven indexes on foreign keys, so deleting a channel, member, poll or media row no longer scans the referencing table (same note as 0093 for the build).
  • 0095 deletes media rows of event covers whose event is gone (older than a day). The stored objects are removed by the next orphan sweep.
  • 0096 creates upload_usage. The daily upload budget resets at the upgrade and from then on no longer refunds the bytes of deleted files or messages. Community icons, covers, avatars and banners no longer count; wiki images do.
  • 0097 gives the built-in Moderator and Admin roles Manage reports and Kick members. Only the roles the seed of migration 0034 created are changed (a role still named Moderator or Admin, the oldest with that name, still holding Timeout members and created together with 0034; a role you renamed, a custom or imported role with the same name, @everyone and bot roles do not), and permissions are only added. Untick them on the role afterwards if you do not want them.
  • 0098 takes the chat of a conversation's call out of the public message totals and recomputes every total once (see Public message and talk totals).
  • 0099 counts public talk time separately (public_voice_seconds); the public total restarts at 0.
  • 0100 creates message_nonces for the offline outbox: a message written while offline is sent again after reconnecting without being posted twice. Entries are pruned after 24 hours.

What you do (only with your own compose file; the bundled docker-compose.yml already has both):

  • Mount the status folder read-only into the app, ./backup-status:/backup-status:ro, and set BACKUP_STATUS_FILE=/backup-status/status.json. Admin > Status then shows the last backup and its restore test instead of "unknown".
  • Copy the new scripts/backup.sh next to your deployment. After each backup it writes backup-status/status.json (the folder can be changed with BACKUP_STATUS_DIR) and, by default, test-imports the dump into a throwaway database first; RESTORE_TEST=0 skips that test. See Backups and restore.

Clients. The web app updates with the server. Use desktop client 1.3.4 or newer. Bots and webhook consumers should read the 3.0.0 changes; the most visible are the 404 for deleting a command an admin disabled, the 50-command cap that now includes disabled commands, and the nonce field on messages.

Rollback. The migrations are forward-only, so an older binary cannot run on the migrated database. To go back, stop the stack and restore the backup you took before the update (see Rollback).

2.x: every minor since 2.0.0

Each 2.x minor is an ordinary update (procedure above, backup first). None breaks the public API: api-stability.md still holds, and 2.x only adds endpoints, fields and events. Most patch releases (2.1.1, 2.5.1, 2.8.1 to 2.8.3, 2.9.1) fix bugs and need no configuration; 2.8.2 and 2.9.1 only change what the signed desktop bundle contains. The patches 2.9.2 to 2.9.21 added migrations and one operator step; see Upgrading to 3.0.0. The migrations are listed in the migration table below. Taking several minors at once applies their migrations in order. Newest first.

2.9.2 to 2.9.21

The patch releases after 2.9.1 changed behaviour and the schema in small steps (migrations 0091 to 0100); all of it is described under Upgrading to 3.0.0 above, because a server that skips straight from 2.9.1 to 3.0.0 applies them together. Migration 0091 adds four indexes (see the table); it changes no behaviour and needs no setting, and building them takes a moment on a very large database.

2.9.0 (wiki)

  • Migrations 0089 and 0090. New tables only (wiki_pages, wiki_revisions, wiki_redirects, wiki_images) and trigram indexes for the wiki search.
  • Three new permissions, set by migration 0089. View the wiki is turned on for @everyone; Edit the wiki and Manage the wiki go to every role that already holds Timeout members (not @everyone, not bot roles). Nobody else can edit until a role is given the permission. See Wiki.
  • No new environment variable. Erasing an account keeps the wiki pages and revisions and any picture a page still shows, detached from the person; see Wiki. A reverse proxy needs no rule for /wiki.

2.8.0 (events)

  • Migrations 0086, 0087 and 0088. New tables (event_roles, event_signups, event_comments, event_comment_mutes, event_series) and a series link on events. Existing events stay single, without roles or comments.
  • Event role templates ship disabled; nothing shows to members until an administrator enables one. Recurring events repeat weekly, every two weeks or monthly. See Events.
  • No new environment variable. 2.8.1 limits what an image may decode to before it is processed and counts background-job failures in mnema_job_errors_total (operations.md).
  • Migrations 0083, 0084 and 0085. Settings columns and roles.self_assignable. Everything defaults to off: no lockdown, no sign-up limit, no minimum age, no vanity link, no self-assignable role.
  • New permission Bypass new member limits, set by migration 0083 on every role that holds Timeout members. Without it, a role's members wait out the minimum age once an administrator turns that setting on. See Moderation.
  • The vanity link /join/<name> is served by the app itself and shows only the community name; forward it like every other path (Reverse proxy).

2.6.0 (voice limits)

  • No migration. New optional VOICE_UPLOAD_LIMIT_MBIT (default 0, no limit): with a value, the server steps viewers down screen and camera layers to stay under that upload. Metrics mnema_sfu_upload_* appear.
  • Microphones now use Opus DTX: a quiet speaker stops sending a stream of packets. Nothing to configure; members see no change except lower traffic.
  • The admin Status tab gains a capacity panel, and Test my connection shows an upload hint from a bounded download. See operations.md.

2.5.0 (cameras as layers)

  • No migration, no setting. Cameras are sent as layers and a viewer receives only the cameras on screen, with a server cap per viewer. Server and web app must be the same release (they are one image); a desktop client picks the change up with the signed bundle of the new release.
  • The retransmission history is sized in bytes and shrinks with load, with a budget per subscriber. This lowers memory under load; no setting.

2.4.0 (load behaviour)

  • No migration. New optional PPROF_ADDR (default empty, off): serves Go profiles on a loopback host:port; the server refuses to start with an address that is not loopback.
  • The server reads the container memory limit and keeps its heap within 85 % of it (GOMEMLIMIT set in the environment wins), and asks for 4 MiB UDP socket buffers. The kernel's net.core.rmem_max and wmem_max cap what it gets; see Deployment.

2.3.0

No migration, no setting. Server error sentences are translated in the web app (English and German). A client that matches an error's English message should read the stable error.code instead.

2.2.0 (the large one)

  • Migrations 0079 to 0082. A Talk started from a direct message belongs to that conversation (channels.dm_id); community icon columns; staged attachments (media.staged, media.position); the forum rework. Columns and tables only; existing rows keep their defaults.
  • Several attachments per message (up to 10). The composer uploads first and a message claims the files. Staged files no message claimed are deleted after 6 hours.
  • A start with missing settings now stops with the complete list. The log line Mnema Talk cannot start - fix these settings in .env: names every required setting that is missing or still a placeholder, and the process exits with status 78. mnema-talk setup --check prints it without starting. The .env.example and docker-compose.yml of the release were reorganised (required settings first); your existing files keep working.
  • New optional WEBRTC_LAN_IP (default empty): the host's LAN address, announced next to the public one so members on the same network reach voice on a router without NAT loopback. Entries must be IPv4 addresses a neighbour could reach; anything else stops the start.
  • The updater trusts the Docker Hub mirror (docker.io/msch128/mnema-talk) next to GHCR and pulls from the registry of the running image. A fork that sets UPDATER_IMAGE_REPOSITORY drops the mirror. See Updating.
  • mnema-talk setup (guided assistant) and the Owner's Get started checklist are new; nothing in an existing install changes.
  • INITIAL_LANGUAGE now defaults to en (it was de since 1.1.0). It only names the default channels of a brand-new installation; an existing one is never renamed.

2.1.0

No migration, no setting.

1.2.x → 1.5.x

Update with the procedure above and take the backup first. Nothing in .env has to change. 1.3.0 adds migration 0076 (a covering index for the unread counts), 1.5.0 migration 0077 and 1.5.1 migration 0078 (it drops the index 0076 made redundant); see the migration table. 1.5.0 also brought the setup assistant and the automatic voice address, described under 1.5.x → 2.0.0.

Migration 0077 drops native_session_families, native_access_tokens, native_refresh_tokens and native_ciphertext_events (added by 0015 and 0016). They belonged to a native client transport that was never mounted in a release; nothing wrote to them, and the server no longer reads or deletes from them. No web, desktop or bot client is affected, and the event native_access_renewed, which the server never sent, is removed from the event registry. A rollback to an older image needs the restore of the pre-update backup (see "Rollback" above).

1.5.x → 2.0.0

Update with the procedure above and take the backup first. No migration, no API break. (Coming from 1.4.x or older, also read 1.2.x → 1.5.x above.)

The in-app privacy policy is now version 1.7 (the version is shown on the page; members are not asked to accept it again). It describes the TURN relay built into the server as part of your instance (IP address and port seen, encrypted media it cannot read, nothing stored persistently) while it is offered, and it names the external TURN servers from WEBRTC_TURN_URLS, which earlier versions never listed. GET /api/legal gains the field builtin_turn. If you publish your own copy of the policy, update it to match.

New port 3479 UDP+TCP for the built-in voice relay (TURN); forward it on your router; switch with WEBRTC_BUILTIN_TURN=auto|on|off; external coturn keeps working and turns the built-in relay off automatically.

  • Ports. Every port and outbound connection is listed in Network ports.
  • Built-in TURN relay. The server can relay media for members whose network blocks UDP, without a second service. WEBRTC_BUILTIN_TURN (auto by default) runs it only while WEBRTC_TURN_URLS is empty, so an installation with an external TURN server changes nothing. on runs it anyway; with WEBRTC_TURN_URLS set too, members are offered both servers. off never runs it. Details, limits and metrics: operations.md.
  • docker-compose.yml publishes port 3479 (UDP and TCP) for the app. Take the new file (pinned procedure) and forward 3479/udp and 3479/tcp in your router (only needed while the relay runs; with off, or an external TURN under auto, nothing listens there). It does not collide with coturn on 3478; if something else uses 3479, set WEBRTC_BUILTIN_TURN_PORT. Hosts that freeze their compose file keep the old one until they take the new file.
  • Admin > System shows the relay (listening, sessions, a reachability hint) and warns when it could not start.
  • Easier first setup (from 1.5.0). mnema-talk setup (today run as in the quick start) writes a complete .env and docker-compose.yml, and the admin Status tab has a Setup checks list (quick start, setup checks).
  • Two new outbound requests (from 1.5.0), both only from the server's IP address. A production server with an empty WEBRTC_NAT_1TO1_IP finds its public IPv4 address with a STUN request to Google or Cloudflare at startup and announces it (WEBRTC_AUTO_ANNOUNCE=false turns this off). The server clock is compared with an NTP server (CLOCK_CHECK_ENABLED=false turns this off). An install that sets WEBRTC_NAT_1TO1_IP sends the first request never. Both are named in the in-app privacy policy (policy version 1.6) while they are active.
  • A PUBLIC_URL that is an IPv4 address (a LAN install opened by IP) is now also announced for voice when WEBRTC_NAT_1TO1_IP is empty.

1.1.x → 1.2.0

Update with the procedure above and take the backup first. 1.2.0 only adds, apart from removing media frame format 2 (see "Calls and the security floor" below). A 1.1.x web app keeps working against a 1.2 server, and a 1.2 web app hides what a 1.1.x server lacks (it reads the features list of GET /api/health). Nothing in .env has to change. A rollback to a 1.1.x image needs the restore of the pre-update backup (see "Rollback" above).

Database

MigrationAdds
0059channels.is_lobby, is_temp, lobby_id and leader_id: Create-a-Talk lobbies and the temporary Talks they open (see Talks). Existing channels keep false and null.
0060Unused: the number was reserved while 1.2 was planned and no change needed it. The gap is intentional; migrations are applied in order and nothing depends on it.
0061users.status_expires_at (a status line that clears itself, feature status.expiry). It also raises the limit of channels.slow_mode_seconds from 6 hours to 24 hours.
0062message_reminders and scheduled_messages (see "Reminders and scheduled messages").
0063poll_voters, poll_anon_ballots, poll_options.anon_votes, polls.anon_voters and a trigger on poll_votes (anonymous polls); channels.auto_delete_days with its checks.
0064user_sessions: one row per browser session (device label, created, last active).
0065instance_settings.session_inactivity_days (1 to 365, default 7).
0066automod_rules and automod_state with the default rules (below), and the columns source, automod_rule, automod_outcome and hit_count of message_reports (existing reports keep source = 'member').
0067moderation_notes: private moderator notes about members.
0068channels.is_stage: Stages. Existing channels keep false; a Stage is never a lobby or a temporary Talk.
0069channels.type = 'forum', messages.title, messages.is_locked, forum_tags and forum_post_tags: Forum channels with tag management and post threads (see Forum channels). Existing rows keep null and false.
0070events and event_rsvps tables: community events, RSVPs (see events); the new Manage events permission is granted to every non-bot role that holds Timeout members (the seeded Moderator and Admin roles).
0072media_original_filename_trgm_idx: GIN trigram index on media.original_filename for fast case-insensitive attachment filename search.
0073server_notify: a member's server-wide notification default (see Notification settings). Adds a table only.
0074dm_members.hidden_at and dm_members.favourite_pos, users.dm_mute_all and users.dm_list_collapsed: member-local direct message list preferences (see Direct message list).
0075channels.slug and channel_slugs: the speaking addresses of channels (see "Speaking URLs"). Every existing channel except a direct message gets its slug in the same migration.
0076messages_channel_unread_idx: covering index on messages (channel_id, created_at) INCLUDE (user_id, parent_id, reply_to_id) for the unread counts. Adds an index only; building it briefly slows message writes on a very large database.
0077Drops the unused native-client tables (native_session_families, native_access_tokens, native_refresh_tokens, native_ciphertext_events) of migrations 0015 and 0016. Nothing wrote them any more.
0078Drops the redundant index idx_messages_channel_created, covered by messages_channel_unread_idx (0076).
0079channels.dm_id: a Talk started from a direct message belongs to that conversation and goes with it (see Talks). Adds a column and an index only.
0080instance_settings.community_icon_version and community_icon_updated_at: the community icon the Owner or an administrator uploads. Empty by default, so the Mnema icon stays.
0081media.staged and media.position: several attachments per message. Files the composer uploaded but no message claimed are swept away after a timeout. Existing media keep staged = false.
0082Forum rework: forum_tags.color, forum_tags.position (existing tags keep their name order) and forum_tags.moderated, forum_settings (require a tag, guidelines), messages.is_resolved and forum_post_reads (per-post read markers). Adds columns and tables only; existing rows keep the defaults. See Forum channels.
0083Raid protection settings on instance_settings: sign-up throttle, lockdown and the minimum age before a new member may write or react (see moderation). The defaults leave all of it off.
0084instance_settings.vanity_slug and vanity_accepts_signups: the vanity invite link served at /join/<slug>. Empty by default.
0085roles.self_assignable: roles members may add to or remove from their own account. Off for every existing role (see Roles and permissions).
0086event_roles and event_signups: roles with slots and a waitlist for community events (see events). Adds tables only.
0087event_comments and event_comment_mutes: a flat discussion under each event (see events). Adds tables only.
0088event_series: recurring events; occurrences are ordinary events linked to their series (see events). Existing events stay single.
0089The wiki tables: pages, revisions and redirects, one tree per community. Adds tables only.
0090wiki_images: marks the media rows used as wiki pictures. Adds a table and an index only.
0091Indexes on saved_messages (message_id), forum_post_reads (post_id), message_reminders (message_id) and thread_follows (thread_id), which replaces the partial idx_thread_follows_thread: deleting a message no longer scans those tables. Building them briefly slows writes to them on a very large database.
0092scheduled_messages.attempts and retry_at: count failed sends and delay the next try. Adds two columns only; existing rows start at zero.
0093messages_user_idx on messages (user_id): lookups by author (the inbox, the from: search filter, account export, erasure) no longer scan the whole table. Adds an index only.
0094Indexes on the referencing columns of foreign keys that lacked one (poll_anon_ballots, channel_reads, message_reactions, messages, events, scheduled_messages), so deleting a parent row no longer scans the child table. Adds indexes only.
0095Deletes event cover pictures that stayed behind as channel-less media rows when their channel was deleted (older than a day and attached to no event). The files stay in storage until the orphan sweep removes them.
0096upload_usage: the per-member daily upload budget is booked in its own table, so deleting a file or message no longer refunds the bytes. Adds a table and an index only.
0097Adds Manage reports and Kick members to the built-in Moderator and Admin roles. Changes permission bits of those two roles only.
0098messages.counted: messages in the chat of a conversation's call are left out of the public message total. Existing rows are marked and the totals on users.message_count are recomputed.
0099users.public_voice_seconds: the public time in Talks counts only stays in Talks everyone can see. It starts at zero; voice_seconds stays as the private total.
0100message_nonces: the client nonce that makes a repeated send of a message return the first one (feature messages.nonce). Adds a table and two indexes; rows older than a day are pruned.
0101instance_settings.strip_image_metadata: the Owner's switch for storing JPEG, PNG and WebP attachments without their metadata, on by default. Adds a column only; stored files are not touched.
0102recovery_codes.key_fingerprint (nullable): which key a new recovery code is hashed under, so codes under a retired key are not counted as remaining. Existing rows keep NULL and stay counted.
0103Triggers that refuse a row naming an erased account (or write another member's row without it), keep a deleted member's messages and profile empty, write report copies without an erased account's text, and write audit entries about an erased account without names and details. Adds functions and triggers only.
0104channels.last_message_number: the number of each channel's newest message, written while a new message holds the channel's lock, so GET /api/read-state can say exactly which messages its counts include. Adds a column and fills it once from the stored messages (one pass over messages); an older release ignores it.
0105The bot platform: bots.description and bots.homepage (empty by default, filled when a bot is added from a manifest) and message_components, the buttons and select menus of bot messages (a new, empty table that goes with its message). Adds two columns with defaults and a table only; an older release ignores them.
0106Messages with a lifetime and auto-delete in hours (timed messages). messages.expires_at (with two checks added without a scan and a partial index, the one pass over messages), scheduled_messages.lifetime_seconds, media.width and height, the lifetime and auto-delete default settings in instance_settings, and channels.auto_delete_hours and auto_delete_scope. channels.auto_delete_days is dropped: a period of 1, 7, 30 or 90 days becomes 24, 168, 720 or 2160 hours; 0 becomes 0 (off for this channel, the opt-out) when the channel's last channel.auto_delete_set audit entry turned it off, and otherwise "follows the community default", which is off until the Owner or an Administrator sets one. A call Talk's old period, never applied, is dropped. The API keeps auto_delete_days; PUT /api/admin/channels/{id}/auto-delete with an empty body ({}) now answers 400 (before, it read as days: 0). An older release refuses to start on the migrated database.
0107bots.access_all: whether a bot was given access to every channel in one step (false for every existing bot, so nothing changes for them). Adds a column with a default only; an older release ignores it.
0108Member invites: invites.channel_id (an invite that lands the joiner in a channel; empty for every existing invite), the member_invite_* limits on instance_settings (7 days, 25 uses, 10 active, 10 per hour) (the per-hour limit counts the audit log). Adds columns with defaults only; an older release ignores them.
0109The permission Create invites (1 << 30, see invites). A fresh install gives it to @everyone. An existing install does not: members cannot create invites after the upgrade, and only the roles that already hold Manage invites get it, so nothing changes for members until the Owner turns it on.
0110bot_commands.default_member_permissions: permission bits required to run a slash command by default (NULL for existing commands, so nothing changes for them). Adds a nullable column only; an older release ignores it.
0111Display names: drops direction and invisible format characters (such as U+202E and U+200B) from the names stored before they were cleaned on the way in; a name with nothing left becomes the username. A data change on users only; an older release reads the cleaned names as they are.
0112messages_channel_unread_id_idx: covering index on messages (channel_id, created_at) INCLUDE (user_id, parent_id, reply_to_id, id, counted), so GET /api/read-state and the member list's totals run from the index alone; it replaces messages_channel_unread_idx (0076). Adds and drops an index only; building it took about 0.5 s on a million messages and blocks message writes while it runs (at startup, before the server listens).

The numbers 0046, 0053, 0055 and 0060 are unused: they were skipped while the releases 1.0, 1.1 and 1.2 were planned (0046 in 1.0, 0053 and 0055 in 1.1, 0060 in 1.2) and no change took them. Migrations are applied in order and nothing depends on the missing numbers, so no file is lost.

Speaking URLs

Channels, Talks, forum posts and conversations have readable web addresses. The id stays the key everywhere; the slug is only an address.

AddressOpens
/c/general, /c/general/m/<message id>, /c/general/t/<thread id>a text channel, a message in it, a thread
/v/lounge, /v/lounge/chat, /v/lounge/chat/m/<message id>a Talk, its chat, a message in it
/c/ideas/p/neue-kueche-0f3a9c1ea forum post: its title and the first 8 characters of its id
/dm/alice, /dm/g/0f3a9c1ea conversation of two (the other member's username) and a group (first 8 characters of its id)
  • Slugs. Lowercase ASCII (a-z, 0-9, -), at most 60 characters: German umlauts and the sharp s are spelled out (a-umlaut gives ae, the sharp s gives ss), other accents are dropped, anything else becomes one dash; a name without a usable character gives channel. A slug is unique on the server; on a collision the channel's own slug gets the first 6 hex characters of its own id (plans-0f3a9c). A temporary Talk has the fixed slug talk- and the first 8 hex characters of its id, never changed by a rename and not kept in the history. It is set when the channel is created or renamed, in the same transaction. Migration 0075 backfills existing channels in the order (created_at, id).
  • Renames keep old links alive. Former slugs stay reserved for their channel (channel_slugs), so a freed slug is never handed to another channel and an old link never opens something else (a channel keeps its newest ten former slugs; older ones are free again). The web app rewrites an old slug to the current one (replacing the history entry). The rows go with the channel when it is deleted.
  • Old links keep working. /c/<id> and /v/<id> (bookmarks, shared links, notifications of older clients) open the channel and are rewritten to the slug address; so are /c/<conversation id> links, which move to /dm/....
  • API. Channel objects carry slug and previous_slugs (additive). They come with the channel, so a member only learns them for channels they may see; there is no endpoint that resolves a slug, and an unknown address and a channel the member may not see give the same answer in the app. Web Push payloads carry channel_slug so a click opens the address directly.
  • Conversations. /dm/<username> is resolved from the member's own conversation list. After the other member changes their username the old address no longer matches and is treated as unknown; /c/<conversation id> still works.

Small additions: emoji shortcodes, past events, avatar updates

No migration and no setting.

  • Emoji shortcodes. Typing :smi in the composer also suggests standard emoji (:smile: gives 😄) after the community's custom emoji; Enter or Tab inserts the character itself. The table (about 1,900 GitHub-style shortcodes) ships with the web app and loads on first use.
  • Past events. GET /api/events?when=past lists events that are over (completed, cancelled or ended), newest first, with limit and the cursor before and before_id (start time and id of the last event of the previous page). The same visibility rules as for upcoming events apply. Without when the endpoint answers as before; the events dialog's Past tab uses it.
  • Avatar re-encode job. When the hourly job redraws or removes an old avatar it now broadcasts user_update, as a manual change does, so open clients refresh the picture without a reload.
  • Desktop gaming settings: add the last app. In the desktop client's gaming settings, Add the app I was just in detects the executable that was in front before switching to Mnema Talk and offers to add it after confirmation, so custom games and non-Steam launchers do not have to be entered by hand.

Everyday features: status, reminders, polls, auto-delete

  • Status that clears itself (feature status.expiry). A member can give a status line an end time, at most 366 days ahead; the status disappears then. An empty status carries no expiry. Existing statuses keep no end time.
  • Slow mode up to 24 hours. slow_mode_seconds may now be 0 to 86400 (it was 6 hours at most); existing values stay.
Reminders and scheduled messages
  • Remind me (feature reminders) points at a message without copying it. What the member sees when it falls due depends on their access at that moment; if the message is gone the reminder still arrives, as "a message you can no longer see". A due reminder is announced in the app (event reminder_update) and by Web Push when that is on, and stays until dismissed (removed after 30 days at the latest). Routes: GET and POST /api/me/reminders, DELETE /api/me/reminders/{id}. At most 100 per member.
  • Send later (feature messages.scheduled) lets a member write a message for a channel or conversation and have the server send it as them at a chosen time (10 seconds to 366 days ahead). Routes: POST /api/channels/{id}/scheduled, GET /api/me/scheduled, PATCH and DELETE /api/me/scheduled/{id}; event scheduled_message_update. At most 50 waiting or failed per member. Every check (permissions, slow mode, timeout, blocks) runs at send time, not when the message is scheduled. A message the server has to refuse is not lost: it becomes failed and stays as a draft to edit, reschedule or delete.
  • Editing a scheduled message keeps its time unless the member changed it: the web app sends a new time only when it differs (or when the message had failed), and the server keeps the stored time and state when send_at is absent. A failed message edited only in its text stays a draft.
  • Both belong to their owner only. Account erasure deletes them and the account export includes them.
Anonymous polls
  • Anonymous polls keep no link between a member and a choice (feature polls.anonymous). The server stores only that a member voted and how many votes each option has. A vote in an anonymous poll cannot be changed or withdrawn, and a running anonymous poll pushes no tally at each vote: the result is announced when it ends. This is hardening, not a guarantee against an operator with direct database access (see SECURITY.md).
  • Existing anonymous polls are converted by migration 0063 and this cannot be undone: the tallies and who took part stay, who chose what is deleted, and votes in them can no longer be changed. Keep the pre-update backup if you may want the old rows.
Auto-delete
  • Auto-delete (feature channels.auto_delete) removes messages older than 1, 7, 30 or 90 days from a text channel. It is off everywhere after the upgrade and always an explicit choice of someone with Manage channels (PUT /api/admin/channels/{id}/auto-delete, audited as channel.auto_delete_set; the channel settings ask for a confirmation). Direct messages never take part. Pinned messages stay, and so does a thread root that still has a younger or pinned reply; the attachments of deleted messages are deleted with them. Each run that removes something is audited (channel.auto_delete_run).

Sessions and inactivity sign-out

  • Where you are signed in (migrations 0064 and 0065). Members see and end their own browser sessions under Settings > Sessions, including the push devices of a session (GET /api/auth/sessions, DELETE /api/auth/sessions/{id}, POST /api/auth/sessions/revoke-others). Only a coarse device label is stored, never the user agent or an IP address.
  • Sessions that are not used for 7 days end. The limit is session_inactivity_days (1 to 365, default 7) in PUT /api/admin/onboarding, set by the Owner and Administrators; SESSION_EXPIRY_HOURS still caps the total. A session that exists at the upgrade gets its record on its first request afterwards and its clock starts then, so nobody is signed out by the upgrade itself; a member who then stays away for a week signs in again. See Operations.
  • View server as role. In Admin > Roles, a read-only preview of what a member holding only @everyone and a given role would see and may do (GET /api/admin/roles/{id}/view-as, Manage roles). It changes nothing and has no health key.
  • New search filters and ordering. The message search API (GET /api/search) supports during:YYYY-MM-DD (matching messages within a single local day, accepting tz offset parameter from the client), filename:<text> (matching original filenames of attachments case-insensitively via trigram index), author:bot|webhook|member (filtering by author type), has:embed, and a sort=newest|oldest|relevance parameter (default newest).
  • Interactive filter dropdown and chips. When the search box is focused, suggestion chips allow quick selection of from:, in:, mentions:, has:, during:, author:, and filename: filters, rendered as removable chips in the query line. A sort order toggle in the results header allows switching between Newest, Oldest, and Relevance.
  • One filter row, quoted phrases, exclusions. The search dialog shows a single filter row. In q, a quoted phrase is one term and a leading minus excludes messages containing a word or phrase ("build failed" -nightly); a lone -, a-b and a quoted -x stay literal text. This is handled by the server (GET /api/search, at most 8 terms), so any client gets it.
  • Earlier filters. search.filters.v2 (1.1) is unchanged and still advertised; a client that only knows it keeps working.
  • Feature flag. Advertised as search.filters.v3 in GET /api/health. A web client connected to an older server hides the new dropdown and sort toggle.

Talks

  • A Talk can be marked as a lobby; joining it opens a temporary Talk ("Talk 1", "Talk 2", ...) for the member, who leads it. Members need no Manage channels for that. Empty temporary Talks are removed after 30 seconds, and the server removes all of them at start.
  • "Start a Talk" in a direct message opens a temporary Talk from the first lobby the member can use and posts an invitation card. The card only links to the Talk; joining runs the usual permission checks.
  • Feature name talks.lobby in GET /api/health. New events talk_leader and talk_moved; new voice_kicked reasons talk_rate_limited and talk_unavailable. REST: PATCH /api/talks/{id}, POST /api/talks/{id}/invites, POST /api/dms/{id}/talk, and the fields is_lobby, is_temp, leader_id of a channel (additive).
  • A Talk can be a Stage (feature talks.stage): without talk power nobody sends audio, camera or screen there. The new permission Manage stage (bit 1 << 24, off for everyone but the Owner and Administrators) gives and takes talk power; members raise a hand to ask. Nothing about a Stage session is stored. Existing Talks stay normal Talks. New events stage_hand, stage_talk_power, talk_reaction; REST: the field is_stage of a channel and of POST /api/admin/channels and PATCH /api/admin/channels/{id} (additive).
  • Live reactions (feature talks.reactions): a member in a Talk sends an emoji that floats over their tile for everyone in that Talk, at most 5 per 10 seconds. The server relays it and keeps nothing.
  • Role and overwrite editors list Manage stage. A role that holds Administrator has it already; no existing role or overwrite changes.

Automod and moderation history

Defaults at the upgrade. Automod is on after the upgrade, with conservative rules that every server gets the same way (new servers included). Look at them under Admin > Automod and change or delete what does not suit you:

RuleDefault
Mention spamon: a message with more than 10 different mentions is blocked
New accountson: accounts younger than 10 minutes cannot post links (blocked)
Raid protectionon: more than 10 joins within 10 seconds time the newcomers out for 10 minutes and add one alert to the reports queue
Blocked wordsoff, word list empty
Linksoff (block-list mode, empty list)

The Owner and Administrators are never checked. The effect you may notice: a member who joined a few minutes ago gets "it breaks the community rule" when posting a link, and a burst of invitations used at once (a party of more than 10 within 10 seconds) is held back for 10 minutes; delete or loosen the rule if that does not suit your community. Nothing changes for existing messages.

Moderation tab. Members with Manage reports get a Moderation tab in the profile (history and private moderator notes). No permission changes hands: the Owner and Administrators have it, other roles only if you gave them Manage reports. Notes about a member are moderator data; they are not in the member's own data export (see moderation and the privacy page, "Moderation records").

API. Mostly additive: the report objects gain source, automod_rule, automod_outcome and hit_count, kind may be alert and category automod. New routes /api/admin/automod* and /api/admin/users/{id}/moderation*. The health features list gains automod and moderation.history. One contract change: message_id and channel_id of an admin report entry (GET /api/admin/reports, /reports/{id}) are now optional: an automod entry about a blocked message (never stored) has no message_id, and a raid alert has neither. Clients must treat both as optional; reports filed by members always carry them.

Operator status

  • A dedicated Admin → Status page (feature key ops.status, endpoint GET /api/admin/status, Owner and Administrator only) provides an at-a-glance operational overview: version, available updates and auto-deploy status, database size and migration count, storage reachability and disk free space, backup status, live activity (active sessions, WebSocket connections, Talks and participants), and active operator warnings. See operations.md.

Forum channels

  • Admins can create channels with type 'forum' (Manage channels). A forum channel holds posts; each post is a root message with a required title (<=100 characters), an initial message, and up to 5 optional tags. Replies form a standard thread (messages.parent_id).
  • Up to 20 admin-defined tags per forum channel (name <=20 characters, optional emoji <=32 characters). Members can filter posts by tag and sort by latest activity or creation.
  • Moderation: Members holding Manage messages can lock posts to prevent replies from regular users and update tags on others' posts.
  • Feature name channels.forum in GET /api/health. New event forum_tags_changed. REST: GET/POST /api/channels/{id}/tags, PATCH/DELETE /api/channels/{id}/tags/{tagID}, GET/POST /api/channels/{id}/posts, and PATCH /api/channels/{id}/posts/{postID}.

Community events

  • Scheduled community events with title, markdown description, start and end times, optional cover image (re-encoded 3:1 banner, max 5 MB), and location (see events).
  • Location can be a Talk channel or free text. Talk-based events are only visible to members holding View channels on that Talk.
  • New permission Manage events (1 << 25 in internal/perm); granted by the migration to every non-bot role that holds Timeout members, such as the seeded Moderator and Admin roles (Administrators and the Owner have it implicitly).
  • RSVPs: going, interested, and not_going responses, with participant counts and avatars.
  • Automated reminders sent 15 minutes before event start via in-app notifications and Web Push to members RSVP'd going or interested.
  • Automatic transition from scheduled to active at start time, showing a direct "Join Talk" button for voice events.
  • Feature key events in GET /api/health. Real-time WebSocket events event_update and event_reminder.
  • Audit logging for event.create, event.edit, and event.cancel.
  • Account erasure deletes personal RSVPs and clears event creator links; account export includes rsvps.json.

Notification settings

  • Migration 0073 adds server_notify (one row per member who changed their server-wide default: level, optional mute end, "suppress @all and @here"). Without a row a member keeps today's behaviour: every channel without its own or its category's setting notifies for all messages.
  • Precedence: channel, then category, then the server default. The level in GET /api/read-state (notify_level) is the effective one, so existing clients show it correctly without changes. A server-wide "Nothing" behaves like a channel mute: only messages addressed to the member by name, through a role or as a reply still notify and count. Direct messages ignore the server default.
  • Feature name notify.levels.v2 in GET /api/health. New PUT /api/notification-settings/server (level all, mentions or mute, muted_until for a timed mute, suppress_everyone); GET /api/notification-settings gains a server object (additive). Changes reach the member's other sessions with the existing read_state refresh event. Account export and erasure include the new row.
  • Desktop client: the rail's right-click menu can call the same endpoints as the web app (PUT /api/channels/{id}/notifications, PUT /api/categories/{id}/notifications, PUT /api/notification-settings/server); it should hide the server-wide entries when notify.levels.v2 is missing.

Direct message list: close, favourites, mute all

  • Migration 0074 adds dm_members.hidden_at and dm_members.favourite_pos (a member's closed and favourite conversations) and users.dm_mute_all and users.dm_list_collapsed. Nothing changes for anybody until they use it: every conversation stays in the list, nothing is muted. Nothing is deleted by closing a conversation; the next message in it shows it again.
  • Feature name dm.v2 in GET /api/health. New routes, all for the caller's own list and all answering 404 for a conversation they are not in: PUT /api/dms/{id}/hidden, PUT /api/dms/favourites (at most 25, in order), GET and PUT /api/users/me/dm-settings (mute_all, list_collapsed). GET /api/dms and GET /api/dms/{id} gain hidden, favourite_position and last_message (additive); a new event dm_prefs_updated reaches the member's own sessions only.
  • Mute all direct messages sends no push, and reads as notify_level: mute with no mention count in the list, unless the conversation has a setting of its own (which wins). Unread counts are unchanged. The existing who may start a conversation setting (dm_policy) is unchanged and now sits in the same Direct messages section (Settings > Privacy).
  • A 1.1.x web app on a 1.2 server works as before; a 1.2 web app on an older server hides the new parts.

Calls and the security floor

  • Media frame format 2 is removed. The end-to-end encryption of call media now speaks only frame format 3 (the one that binds a unit to its line). Clients that can only send or open the old format can no longer take part in calls: a web tab that predates 0.8.2, and any browser or desktop shell that still runs such a bundle. A 1.0.x or 1.1.x tab keeps working in a Talk with 1.2 members once it has heard every member's capability message, but its media is dropped for the first moment of each epoch (join, leave, key rotation), usually a second or two. Members see a notice once per call ("Someone in this Talk uses an outdated Mnema client ...") when a unit in the old format arrives. Fix: reload the app, or update the desktop client; there is nothing to configure on the server, which only relays media it cannot read.
  • Security floor not changed by 1.2.0. The release commit meant to raise it, but its Security-Floor: raise line was not a git trailer, so the signed web bundle of 1.2.0 carries security_floor 0.7.23. The high-water mark has the same effect: a desktop client that has run the 1.2 bundle refuses every older bundle of web_client_api 1: it will not connect to a server that still serves a 1.1.x bundle until that server is updated, and it never runs a bundle that seals the old format. Update the server before (or together with) the clients. web_client_api is unchanged (still 1), so older desktop clients keep loading the 1.2 bundle. Why this is allowed under API stability: it is a security fix (RT-4 in SECURITY.md), the high-water mark is the documented rollback protection, and no public API, event or bridge contract changes.
  • Rollback. Going back to 1.1.x is possible for the server, but desktop clients that already saw the 1.2.0 bundle will refuse the older one (the high-water mark); web tabs reload into the older bundle.

1.0.x → 1.1.0

Update with the procedure above and take the backup first. 1.1.0 only adds. A 1.0.x web app keeps working against a 1.1 server, and a 1.1 web app hides what a 1.0.x server lacks (it reads the features list of GET /api/health). Nothing in .env has to change.

Database

Eight migrations run at the first start. All are additive and forward-only. A rollback to a 1.0.x image needs the restore of the pre-update backup, because the 1.0.x image refuses a schema that a newer version migrated (see "Rollback" above).

MigrationAdds
0049user_blocks and message_reports.
0050Direct messages: dm_members, the dm channel type, users.dm_policy, instance_settings.direct_messages_enabled, messages.in_dm. The permission Send direct messages is added to @everyone.
0051saved_messages.
0052messages.forward_of and messages.forwarded.
0054thread_follows, filled from the existing threads (root authors and repliers) so threads keep notifying the people who took part.
0056bot_tokens.minter_inferred, a flag for tokens bound to their likeliest issuer (see "Bots and webhooks").
0057The nullable column users.banner_s3_key (the profile banner). It also extends the tombstone trigger of 0043 so a deleted account keeps no banner.
0058users.avatar_reencoded_at, the marker of the one-time avatar redraw (see "Profile pictures").

The numbers 0053 and 0055 are unused.

New permissions

PermissionBitDefault
Manage reports1 << 21Off for @everyone and every existing role.
Send direct messages1 << 22On for @everyone (set by migration 0050). An administrator can take it away.
Kick members1 << 23Off for @everyone and every existing role.

The Owner and Administrators have all three implicitly, so nobody else gains access to reports or kicking until a role is given the permission.

Configuration

  • New: INITIAL_LANGUAGE (de default, or en) names the default categories and channels of a brand-new installation. An upgrade never renames anything.
  • Changed defaults: LEGAL_OPERATOR_COUNTRY and LEGAL_PROJECT_NOTICE are now empty by default. The legal page then shows a translated default (the country "Germany" and "Private, non-commercial project") instead of the former fixed German text. A value you set in .env is unchanged. If you relied on the old defaults and use the English interface, set the two variables.
  • Self-update (profile autoupdate): fetch the compose file of the 1.1 tag and run docker compose --profile autoupdate up -d after the update. The updater service is now this project's verifying sidecar (started from the app image). A second service, recreator (the Watchtower that used to be the updater), only restarts the app from the image the updater verified. "Update now" refuses an image whose cosign signature or build provenance does not verify. It needs outbound HTTPS from the updater to the registry and to Sigstore. The new networks mnema-recreator and mnema-updater-egress are created by compose; a custom compose file needs the same two services and networks. Details: operations.md, SECURITY.md.

What members and moderators get

  • Direct messages. Conversations of two to ten members (architecture, SECURITY). The Owner can switch them off for the community (direct_messages_enabled, under Welcome & rules): existing conversations stay readable and nothing new can be written. Members choose in their privacy setting (dm_policy) who may start conversations with them. Channels and messages are numbered as before; private messages are numbered apart.
  • Blocking and reports. Members block each other and report a message to the moderators (moderation). In any direct message conversation (group too), unread counts, mention counts and the last-activity time leave out messages by members the reader blocked, and push recipients skip blockers. The admin console gets a Reports tab for holders of Manage reports.
  • Profile banner (feature profile.banner). A picture across the top of a member's profile, set under Change banner next to Change avatar and removed with Remove banner. The server never stores the upload: it crops the centre 3:1, shrinks it to at most 1500x500 and writes a new file, so EXIF and other metadata are gone. PNG, JPEG, GIF or WebP up to 5 MB and at least 300x100 pixels; an animated GIF stays animated within the same pixel budget as animated emoji, an animated WebP is rejected. The file is stored under banners/ (the daily orphan check covers it), is deleted when replaced or removed, goes into the data export as banner.* and is removed when the account is erased. Without the feature (a 1.0.x server) the 1.1 web app shows no banner controls.
  • Profile pictures (privacy fix). Until 1.0 an avatar was stored exactly as uploaded, so the EXIF block of a phone photo (GPS position, camera model) was readable by every member. From 1.1 an avatar or banner is decoded, cropped (square, or 3:1 for a banner), shrunk (at most 512x512, or 1500x500, never enlarged) and written again, so EXIF, XMP, trailing bytes and polyglot payloads cannot survive. Limits and types are unchanged (5 MB; PNG, JPEG, GIF, WebP). Animations stay within the pixel budget animated emoji have; a one-frame GIF becomes a PNG and an animated WebP is rejected. Bot and webhook avatars follow the same rules. Chat attachments are stored byte for byte, so a photo sent as a file keeps its metadata. A Remove avatar button sits next to Change avatar (DELETE /api/users/me/avatar, feature profile.avatar_remove).
  • Avatars stored before 1.1 are redrawn once by a background job (migration 0058). It starts 30 seconds after the server, processes the accounts without the marker, writes the new file, points the account at it and only then deletes the old object (a short extra copy per avatar exists meanwhile). It repeats hourly until nothing is left, so a storage outage at start only delays it, and it never touches an avatar twice. Old files were accepted without limits, so the job is more lenient than an upload: a canvas of up to 30,000 pixels an edge and 64 million in total, and for a long or large animation only its first frame. An old avatar that cannot be decoded even so is removed: the file is deleted, the account has no avatar, and an audit entry media.avatar_removed with the reason is written (Owner and Administrators only). Keeping the original would keep its metadata public. The member can set a new avatar.
  • Saved messages. A private list of up to 1,000 messages per member with an optional note of up to 200 characters. A row is a reference, never a copy, and access is checked on every read: a message the member can no longer see comes back as unavailable.
  • Forwarding and "Pinned by". A message can be forwarded into a channel or a direct message (architecture). Older web apps show a forwarded message as just its comment; a forwarded message with an empty comment is pushed as "Forwarded message". The pinned list shows who pinned a message and when.
  • Slash commands. /me, /shrug, /tableflip, /unflip, /spoiler, /nick, /thread, /msg, /timeout, /ban and /kick join /poll in the menu (bots). /kick signs the member out on every device and drops them from their Talk; they can sign in again.
  • Threads and search. A thread reply notifies only the thread's followers: the root's author, repliers, people mentioned in a reply and anyone who followed it by hand. Search gains the filters has (file, image, video, link, poll, edit), is=pinned, after and before_date (see api/openapi.json).
  • A Talk's chat without joining. A chat button on each Talk row opens the Talk's chat with a Join button in its header. The chat follows the channel permissions only (View channels to read, Send messages to write, roles). No server change.
  • Web app. A skip link and a fixed Tab order, the connection banner also on the browser's offline event, Talk controls that stay visible when alone in the call on a phone, and in-page notifications that follow the "show message text" setting. The style is built on Tailwind CSS 4; nothing to configure.
  • Audit log. New entries message.edit_history_view and poll.end; the message.delete entry of an edited message carries its earlier versions. Audit retention applies to them as to any entry.

API, events and export

All changes are additive; web_client_api is unchanged.

  • GET /api/health has a features list: blocks, dm, reports, saved, forward, search.filters.v2, threads.follow, slash.builtins, profile.banner, profile.avatar_remove.
  • New routes: /api/me/saved, /api/messages/{messageId}/forward, /api/threads/{id}/follow, /api/threads/following, PUT / DELETE /api/users/me/banner (multipart field banner), DELETE /api/users/me/avatar, plus the routes for blocks, reports and direct messages (see api/openapi.json).
  • banner_url is added to GET /api/users/{userID} and GET /api/auth/me only, never to message, member or event payloads.
  • Messages carry a forward marker ({forwarded: true}, no ids and no quoted text, for bots and webhooks too). Messages and the pin event carry pinned_at and pinned_by while pinned.
  • New events: dm_created, dm_member_added, dm_member_removed, block_updated (only to the blocker's own sessions), saved_updated (only to the member's own sessions), thread_follow_updated and kicked.
  • The web app asks for conversation events by opening the socket as /api/ws?dm=1. A desktop client from before 1.1 forwards the socket without that query, so conversations there do not update live until the client is updated (the list and sending work).
  • The account export gains blocks.json, reports.json, saved.json (ids, notes and times, not the saved text), thread_follows.json and banner.*. Erasing an account removes the saved list.

Security

  • Stricter style policy. The web app's Content-Security-Policy no longer allows inline styles: style-src 'unsafe-inline' became style-src 'self' plus style-src-attr 'none' (see SECURITY.md under "Security headers"). Nothing to configure. A browser tab that was loaded before the update may show the emoji picker unstyled until it is reloaded; installed apps update on their next start. The desktop shells apply the strict web CSP (style-src 'self'; style-src-attr 'none') only for web bundles >= 1.1.0; older bundles keep the old policy. The bundle's security_floor is not raised.
  • Bots and webhooks. Bot tokens issued before 1.0 are bound to their likeliest issuer the first time they are used; nothing is revoked and no token needs regenerating (bots.md). The admin console marks tokens that were bound by assumption.
  • Media frame format. No change in 1.0.x. Refusing frame version 2 was re-evaluated for 1.1 and done in 1.2.0 (see "1.1.x → 1.2.0").

1.0.0 → 1.0.1

A patch release: fixes and polish, no new features, and nothing in it changes a public surface (API stability). Update with the procedure above; take the backup first.

  • No migrations. The schema is the one 1.0.0 left, so a rollback to the 1.0.0 image needs no restore.
  • Three new rate limiters, per member, each under its own label in mnema_ratelimit_hits_total{limiter} (see operations.md): poll_create (10 polls per minute), pin (60 pins or unpins per minute) and emoji_upload (10 uploads per 10 minutes). Members and bots never meet them in normal use; a script that creates polls or pins in bulk now gets 429 with Retry-After.
  • Unknown or deleted custom emoji are refused as new reactions (400, "invalid emoji"): a token whose emoji was deleted, or never existed, cannot be added. A reaction that already exists can always be taken back.
  • The data export is complete. Besides profile, settings, messages, edits, reactions, uploads, audit entries and sign-in setup, the archive now holds the polls the member started, the messages they pinned, their push devices (label and dates only, no keys) and the custom emoji they uploaded (with the image files). Its README.txt also says that the files are English and machine-readable and keep messages as typed.
  • Mute rule, now the same everywhere. In a muted channel or category, a message addressed to the member breaks the mute: @username, a role the member holds, or a reply to their message. @all, @here and Do Not Disturb stay silent. The unread mention badge, Web Push and the notifications shown while the page is open follow this rule alike.
  • A deleted account is named "Deleted member" on the server too. New deletions store that name; accounts deleted under 1.0.0 keep the stored "Deleted user" (the web app shows "Deleted member" in the member's language for both). Bots and API clients that read display_name see the stored text.
  • The release workflow mirrors the required checks. release.yml reads the checks that main's ruleset requires (including the upgrade-drill jobs) and reports each one's result from the tested commit on the release pull request; it does not merge when one of them did not succeed. Nothing to do for operators; forks with their own ruleset get the same behaviour.
  • Recovery codes have their own rate limiter. The authenticator lockout no longer blocks them, so a member locked out of the app can still sign in with a recovery code.
  • Bot and webhook names are stricter. ZWJ and ZWNJ stay only inside emoji and in scripts that need them; other invisible characters are stripped.
  • @everyone and @here are reserved on a normalized skeleton, so look-alike spellings of those names are refused too.
  • Push and OS notification text is plain text. Markdown is stripped and spoilers show as "Spoiler".
  • Mail language: the member's stored language, then the request's Accept-Language, then English.
  • Erasing an account updates open pin panels right away.

0.9.x → 1.0.0

1.0.0 is the first release under the API stability contract: nothing in it is a breaking change to a public surface, and 1.x keeps working for existing clients, bots, webhooks, dashboards and alerts. What changes for an operator is below. Update with the procedure above; take the backup first.

  • Ten migrations run on first start: 0038 to 0045, 0047 and 0048 (0046 is intentionally unused). All are quick on any instance; 0044 and 0047 are described under custom emoji and edit history below.
    • 0038 drops idx_messages_content_trgm, a duplicate of the trigram search index messages_content_trgm_idx (both came from earlier releases), so message writes no longer maintain the same index twice and search is unchanged. DROP INDEX takes a short exclusive lock on messages; the migration runs in a transaction, so it is not CONCURRENTLY. On a large instance this takes well under a second.
    • 0039 adds the nullable column bot_tokens.created_by (who issued a bot token), with a foreign key to users. It rewrites no rows and holds only a brief lock on bot_tokens while the foreign key is added.
    • 0040 adds the nullable columns users.email and users.email_verified_at (with a partial unique index on confirmed addresses) and the table account_tokens for single-use e-mail links. Adding nullable columns rewrites no rows. No account has an address afterwards.
    • 0041 adds the tables user_totp, recovery_codes, login_challenges and second_factor_failures for optional two-factor sign-in. They start empty; nobody is asked for a code until they turn it on.
    • 0042 belongs to Web Push and the installable web app (see below).
    • 0043 adds the nullable column users.deleted_at, the table data_exports and replaces the audit log's immutability trigger function with one that allows blanking names and details during an account deletion (and nothing else). No existing row changes.
    • 0045 adds the nullable columns messages.pinned_at and messages.pinned_by (who pinned a message and when; existing pins get their last-change time) and a small partial index on pinned messages. Nothing else changes: the pin flag already existed, and the limit of 50 pins per channel applies to new pins only, so a channel that already has more keeps them.
    • 0048 adds the tables polls, poll_options and poll_votes for the /poll command. They start empty and nothing else changes.
    • The app waits for these locks like any other statement; there is nothing to stop or schedule. If startup is slow, check docker compose logs app for migration applied.
  • Edit history for moderators (migration 0047). The new table message_edits keeps the previous text of every edit from now on (up to 50 per message). Members with Manage messages can read it from the message menu; nobody else can, and it is not searched or exported to anyone but the author. It starts empty and the migration touches no existing row. Nothing to configure; EDIT_HISTORY_RETENTION_DAYS (default 0, keep) drops old versions after that many days. See moderation.
  • Unread divider and "Jump to first unread". No migration and no setting. The new read-only endpoint GET /api/channels/{id}/first-unread is additive. Marking a channel read now writes nothing when it has no news since the last read (the first read still stores the member's marker), which reduces writes on busy instances; see Capacity.
  • Desktop client is Beta. The Windows desktop client stays Beta at 1.0.0; see desktop-app.md.
  • Optional e-mail, SMTP and password reset by mail. Members may now add an e-mail address in the account settings (Sign-in) (never required, never shown to other members or to the Owner). Setting SMTP_HOST (see operations.md) lets the server confirm an address by a single-use link and lets members reset a forgotten password with an address they confirmed (link valid 30 minutes, signs every device out). Without SMTP_HOST nothing changes: no mail is sent, saved addresses stay unconfirmed and unused, and the "Forgot your password?" link does not appear. The Owner can still set a temporary password for any member (Admin > Members), after confirming their own password and, with two-factor sign-in on, a current code. Reset by mail also works for the Owner account if the Owner confirmed an address. Put SMTP_PASSWORD in the environment or mount a file and name it in SMTP_PASSWORD_FILE; SMTP_TLS=none is refused in production.
  • Two-factor sign-in (optional). Every member may turn on TOTP in Account & security; the Owner is advised to. A client that does not know the new second step (an old browser tab, a script) gets 202 with a challenge instead of a session for such an account and cannot sign in; the shipped web app and desktop clients handle it. Stored authenticator secrets are encrypted with a key derived from JWT_SECRET: rotating it requires resetting two-factor for the accounts that use it (Admin > Members, or mnema-talk reset-2fa <username> for the Owner). See operations.md.
  • Members can delete their account and export their data. Both are in the account settings (Data & account); the Owner account cannot be deleted. A deleted account leaves its messages in place without text, written by "Deleted member" (1.0.0 stored "Deleted user" and keeps it for accounts deleted before 1.0.1; the web app ignores the stored text and names a deleted author in the member's language from the reserved deleted-… username). Exports need object storage and live there for at most 24 hours. Clients built before this release show a deleted author by the placeholder name instead. See operations.md.
  • Weak custom invite codes stop working. Custom invite codes typed by an admin that fall below the new minimum (12 or more characters, 7 or more distinct, letters and digits below 16 characters, no common word with little around it) are treated as unknown by the invite preview and by registration. Admin > Invites marks them "Disabled, regenerate"; delete them and create new ones (a random generated code is always accepted). Generated codes and custom codes that meet the minimum are unaffected. Invite lookups and registrations are also limited per IPv6 /48 in addition to the per-client limits.
  • Uploads have a daily budget per account. UPLOAD_QUOTA_MB_PER_DAY (default 2048) is what one member, bot or webhook may upload in any rolling 24 hours; further uploads answer 429, and deleted files still count. 0 turns it off. Two optional guards are off by default: MEDIA_MAX_TOTAL_MB (pause all uploads once stored media reaches this size, 0 = no cap) and MEDIA_MIN_FREE_MB (default 1024) together with MEDIA_DISK_PATH (a volume the app can see; empty = no free-space check). A busy community that shares large files will hit the default; raise it before updating if members upload more than 2 GiB each per day. MEDIA_RETENTION_DAYS still defaults to 0: nothing is deleted automatically. See operations.md.
  • coturn is capped (only if you run the turn profile). The compose file now starts coturn with --user-quota=8 (relayed sessions per credential) and --total-quota=48 (all sessions, matching the 49 ports of 49152-49200). Fetch the compose file of the tag (pinned procedure) and restart the profile. If you widened the relay port range, raise --total-quota with it; see TURN.
  • PUBLIC_URL over plain http:// warns. In production and staging, a PUBLIC_URL that is not https:// logs a startup warning and shows "PUBLIC_URL is not https" under Admin > System. The server still starts, so a trusted-LAN install keeps working; behind a TLS-terminating reverse proxy set it to the public https:// address (see operations.md).
  • Bot tokens are bound to whoever issued them. From 1.0 a token records its issuer, and stops working when that person loses Manage bots, is disabled, or can no longer act as the bot. Tokens created before the upgrade have no recorded issuer: they keep working and are not re-checked until someone regenerates them (bots). Regenerate the tokens of every bot you still use to bind them, and delete the ones you do not.
  • Audit log visibility. Category and layout entries (category.*, layout.apply) are visible to the Owner and Administrators only, like the other privileged entries.
  • Realtime limits are stricter. Sockets end with the session that opened them (a sign-out closes them at once), oversized or flooding frames are dropped, and there are per-account budgets for frames, events and voice handshakes across connections. Ordinary use is not affected. A reverse proxy must still pass WebSocket upgrades; nothing else changes.
  • Mention fan-out is capped. A message whose author may not mention everyone notifies at most 50 members (named users first, then role members).
  • Security floor trailer. The desktop client's security floor (the lowest web bundle it accepts) now rises only for a commit with a Security-Floor: raise trailer; a fix(security) subject alone no longer does. Operators need to do nothing. Forks and maintainers must add the trailer to security fixes in anything the web bundle ships, see desktop-trusted-client.md and AGENTS.md.
  • Alert rules moved. The example alert rules are now the file deploy/monitoring/mnema-alerts.yml, checked with promtool and against /api/metrics in CI. Metric names are part of the stability contract.
  • Web Push (migration 0042). Members can turn on push notifications per device (Settings > Push & app) and get messages while the app is closed; on iPhone and iPad only for the installed app. The migration creates push_vapid (the server's VAPID key, generated on first start: it is in your database backups, so restores keep working subscriptions), push_subscriptions (one row per device) and users.push_preview. Nothing is sent until a member subscribes. New settings, all optional: PUSH_ENABLED (default true), PUSH_PREVIEWS (user, default, or off to never put message text in a push) and PUSH_VAPID_SUBJECT; see operations.md. The server needs outbound HTTPS to the browser vendors' push services (Google, Mozilla, Apple, Microsoft) when a member uses push; it connects only to public addresses. Rolling back needs the pre-upgrade backup like every migration.
  • Custom emoji (migration 0044). Members holding the new permission Manage emoji (the Owner always does; nobody else gets it from an upgrade) add PNG, GIF or WebP pictures under Admin > Emoji; everyone uses them as :name: in messages and reactions. 0044 creates the table custom_emoji and widens message_reactions.emoji from 32 to 80 characters (a custom emoji reaction is the token <:name:id>); no row is rewritten. EMOJI_MAX (default 200, 0 forbids new ones) caps the count. Uploads are decoded and redrawn on the server (at most 128 x 128, metadata and trailing bytes dropped, 256 KiB, SVG/JPEG/animated WebP refused) and stored under emoji/ in object storage. Older web bundles show the token text <:name:id> instead of the picture.
  • Installable app. The web app now has a manifest, icons and a service worker (/sw.js) that keeps its shell available offline; browsers offer "Install", and Account menu > App explains it (on iPhone and iPad: Share > Add to Home Screen). Nothing to configure and no migration. The worker never stores API answers. A reverse proxy must pass /sw.js and /manifest.webmanifest through unchanged (no caching of /sw.js, no rewriting); the app's own Cache-Control: no-cache already says so.
  • Polls and built-in slash commands (migration 0048). /poll and a poll button in the composer let members ask a question with 2 to 10 answers (single or multiple choice, open for 1 hour to 1 week, optionally anonymous). Voting needs View channels and Add reactions, posting Send messages; nothing to configure and no new setting. The server's built-in commands share the slash menu with the bots' (bots); bots can now give a text option choices. New surface, all additive: the poll object on messages, the poll_update WebSocket event, the routes under /api/channels/{id}/polls and .../messages/{id}/poll, and 200 as an answer of running a built-in command. A reverse proxy needs no change. The data export gains poll_votes.json.
  • Rollback means restoring the pre-upgrade backup. Migrations are forward-only and the 0.9.x code has not been verified against the 1.0 schema and data (the bot token column, the dropped index), so do not simply start the old image on the migrated database. Stop the app, restore the backup taken before the update with scripts/restore.sh and start the old image (see "Rollback" above). Anything written after the update is lost with the restore. CI drills this path for the supported source versions: the old release refuses to start on the migrated data and a restore into the new build succeeds.

0.8.x → 0.9.0

  • Three migrations run on first start: 0035, 0036 and 0037. 0035 adds notification levels per channel and category (with timed mutes), 0036 adds role mentions (message_mentions.kind, message_role_mentions) and 0037 adds the community onboarding settings (welcome text, rules, start channel) and each member's accepted rules version. Take the usual backup first.
  • Nobody loses notifications. 0035 rewrites every stored channel level all to inherit, so a category setting now reaches those channels; with no category setting inherit still means all. Explicit mentions and mute levels are kept as they were.
  • Rules enforcement is off until an Owner or Administrator writes rules. Empty rules text enforces nothing, so the upgrade itself never locks anyone out. Writing rules for the first time (or publishing a new version) puts every member who has not accepted them in a pending state.
  • What pending members lose. Once rules exist, a member who has not accepted the current version cannot send messages, react, upload or join a Talk (RULES_NOT_ACCEPTED, and voice_kicked with reason rules_not_accepted for someone already in a Talk). They keep read access and can accept through the web app. The Owner and bots are exempt. See SECURITY.md for the model.
  • Rollback means restoring the pre-upgrade backup. The 0.8.16 code has not been verified against inherit notification rows or the new tables, so do not simply start the old image on the migrated database; restore the backup taken before the upgrade (see "Rollback" above).

0.8.x (up to 0.8.16)

  • Upload limits are now editable by the Owner. MAX_UPLOAD_SIZE_MB (default 50, unchanged) stays the hard ceiling and the initial limit, so nothing changes until the Owner acts. In the System tab the Owner can lower the global limit; in the role editor a role can set its own limit (empty inherits). A member gets the highest limit among their roles, otherwise the global one, never above the ceiling; the Owner always gets the ceiling. Migration 0025 adds the instance_settings table and roles.max_upload_mb.
  • To allow bigger files, raise MAX_UPLOAD_SIZE_MB and your reverse proxy. The proxy must accept at least that body size plus a little for multipart framing: nginx client_max_body_size (for example client_max_body_size 140m; for 128 MB), Caddy request_body { max_size 140MB }. The default of nginx is 1 MB, so large uploads fail with 413 there first. Then raise the global limit in the System tab (it does not follow the env value upward once the Owner has set one).

0.7.x → 0.8.0

  • The compose file publishes the app port on loopback only (127.0.0.1:${PORT:-8080}, before: all interfaces). Set PUBLISH_ADDR=0.0.0.0 (or a LAN address) in .env to reach the app directly from the network. A reverse proxy on the same host keeps working.

  • TRUSTED_PROXY_CIDRS is empty (loopback only) in compose (before: also 172.16.0.0/12). Requests through Docker's published port, or from a proxy container, arrive from the Docker bridge, so the whole range could forge X-Forwarded-For. If you run a reverse proxy on another host or in a container, set TRUSTED_PROXY_CIDRS to that proxy's address, e.g. 192.168.0.20 or the container's IP (a proxy on the compose host reaches the app from the bridge gateway: docker network inspect <project>_default). Until you do, X-Forwarded-For is ignored: nothing breaks, but all clients share the proxy's address for rate limits and login lockout, and the log says ignoring X-Forwarded-For from a peer that is not in TRUSTED_PROXY_CIDRS. A deployment that still trusts a broad private range logs a startup warning. Setups:

    • Caddy or nginx on the compose host: set PUBLISH_ADDR unchanged (loopback); the proxy reaches 127.0.0.1:8080 through Docker, so the app sees the bridge gateway, not loopback. Set TRUSTED_PROXY_CIDRS to that gateway (docker network inspect <project>_default, field Gateway).
    • A proxy container on the same Docker network: set it to the container's IP, or the network's subnet if the proxy's IP can change (the subnet holds only your own containers).
    • A proxy on another host: set PUBLISH_ADDR to a LAN address (or 0.0.0.0 behind a firewall) and TRUSTED_PROXY_CIDRS to the proxy's address. An existing deployment with its own compose file that already sets TRUSTED_PROXY_CIDRS (or its own default) is unaffected by this change.
  • Owner password: 14 characters minimum when the administrator is created (ADMIN_INITIAL_PASSWORD) or changes their password (members keep 10). An existing administrator is not affected until they change it, and a too-short ADMIN_INITIAL_PASSWORD is only logged as ignored once an administrator exists.

  • Login lockout is stricter. After 100 failed attempts on one account across addresses, only browsers that signed in to it before (a signed known-device cookie, set again at the next login) are checked as usual; all other devices together share about one password check per minute for the account. The cap lasts at most 15 minutes; mnema-talk unlock clears it (see operations.md).

  • Signing out revokes the session (migration 0021_revoked_sessions). Sessions issued before the upgrade stay valid until they expire.

  • APP_ENV=development only listens on loopback. BIND_ADDR defaults to 127.0.0.1 there and any other address is refused at startup. Production, staging and test are unchanged (0.0.0.0).

  • Two new migrations: 0021_revoked_sessions and 0022_search_trigram (a pg_trgm index for search). Both run at startup; the trigram index can take a moment on a large message table. Do not roll back below 0.7.20 once roles or private channels exist, and the app now refuses to start on a database that a newer version migrated (restore a backup instead).

  • Media keys rotate every 30 minutes and members silent for 20 minutes are removed from the call's key group and re-admitted when they are active again. Calls between 0.7.25 and 0.8 tabs interoperate, so a running call survives the update; reload tabs when the "new version available" notice appears to get the new key lifecycle.

  • Screen shares carry quality layers: the source plus smaller ones, and each viewer picks one or leaves Auto. Nothing to configure; sharers need a current browser.

  • Release images are signed with cosign (keyless); see Verifying a release image. Pin the digest in MNEMA_IMAGE if you want the verified bytes to stay put.

  • Desktop client: it runs a signed web bundle with a security floor that rises with releases that carry a Security-Floor: raise commit; see desktop-trusted-client.md. The server needs no configuration for it.

0.4.x → 0.5.0

  • PostgreSQL 17 → 18, one manual step. The database moves to a new volume (postgres18-data); the PostgreSQL 17 volume (postgres-data) stays untouched for rollback. Take the complete database/media/config backup (Updating, step 1) with 0.4.x still running. Follow the pinned procedure: it fetches the new compose file and every script, including backup-common.sh, backup-online.sh and upgrade-postgres.sh. Instead of its final docker compose up -d, run:

    # backup saved, new compose file, scripts and image selected
    docker compose pull
    ./scripts/upgrade-postgres.sh
    

    The script stops both the app and the existing PostgreSQL service before copying the old volume. It mounts the original read-only, makes a cold copy in a disposable volume, and starts the throwaway PostgreSQL 17 without a network on that copy. It dumps the database to BACKUP_DIR, imports it into PostgreSQL 18, checks the imported tables, and then starts the stack. The original PostgreSQL 17 volume receives no temporary-server writes; media is not changed by the upgrade.

    Normal startup beside an old PostgreSQL 17 cluster requires the persistent completion marker /var/lib/postgresql/.mnema-pg17-upgrade-complete, with contents mnema-postgres17-upgrade-v1. The script publishes it atomically only after import and verification succeed. Merely initializing an empty PostgreSQL 18 cluster, or completing part of an import, does not authorize startup. MNEMA_PG_UPGRADE=1 is a temporary import bypass; do not save it in .env or leave it exported. If import fails, keep the app stopped and use the rollback above or the complete-backup recovery below. The upgrade's standalone SQL dump is not a complete backup.

    Keep the old volume until application checks and recovery verification succeed. The script prints its removal command. A local development database (make dev) upgrades the same way; docker compose down -v discards all database and media volumes and is suitable only for intentionally disposable development data.

  • Migrations 0013_readable_numbers.sql (link numbers for channels and messages) and 0014_channel_user_limit.sql. The new migration runner rejects a schema newer than its embedded migrations. Released 0.4.x binaries lack this guard: roll back using the saved 0.4.x compose file and original PostgreSQL 17 volume, or a complete pre-update backup, before starting them.

  • Production needs ADMIN_INITIAL_PASSWORD on a fresh install (no effect once the admin exists). The generated password is no longer logged.

  • Voice: one shared UDP port. WEBRTC_UDP_MUX_PORT now defaults to WEBRTC_UDP_PORT_MIN; no Docker or router change. An .env still saying WEBRTC_UDP_MUX_PORT=0 keeps the old per-peer mode (about 25 people in calls at once) and logs a warning: empty or remove the line.

  • Per-channel member limit replaces any idea of a global one: voice channels have an optional user_limit (default: none).

  • Compose: memory and pids limits, log rotation, digest-pinned images, POSTGRES_PASSWORD and S3_SECRET_KEY required at interpolation. New optional variables APP_MEM_LIMIT (1g), APP_TMP_SIZE (64m), POSTGRES_MEM_LIMIT (1g), SEAWEEDFS_MEM_LIMIT (1g). Uploads stream to S3 and no longer pass through /tmp.

Recover PostgreSQL 18 from a complete backup after a failed upgrade

Use this path when the new PostgreSQL 18 volume is initialized but its import failed, and you have a complete canonical backup from before the update. It also restores media from that same backup. Run in the existing deployment with the new compose file and all tagged scripts; the stopped app and existing SeaweedFS containers must still exist. Keep the original PostgreSQL 17 volume and the backup. Do not replace or delete volumes during this recovery.

Verify the backup before live changes. --verify checks the canonical manifest, completion marker, checksums, archive safety and an isolated SQL import. An upgrade-only SQL dump or an incomplete backup does not qualify; do not use --allow-legacy for this recipe. The verification proves structural recovery; login, media retrieval and voice/device checks still follow afterward.

(
  set -e
  MNEMA_RECOVERY_BACKUP="/path/to/backups/<timestamp>"
  ./scripts/restore.sh "$MNEMA_RECOVERY_BACKUP" --verify

  # Existing app stays stopped throughout database and media restoration.
  docker compose stop app
  MNEMA_PG_UPGRADE=1 docker compose up -d --wait --no-deps postgres
  ./scripts/restore.sh "$MNEMA_RECOVERY_BACKUP" --yes

  # Reached only after SQL AND media restoration have succeeded.
  docker compose exec -T postgres sh -c 'umask 077; printf "%s\n" mnema-postgres17-upgrade-v1 > /var/lib/postgresql/.mnema-pg17-upgrade-complete.tmp && mv /var/lib/postgresql/.mnema-pg17-upgrade-complete.tmp /var/lib/postgresql/.mnema-pg17-upgrade-complete'

  # Clear the temporary bypass even if inherited from the shell or .env.
  MNEMA_PG_UPGRADE= docker compose up -d --wait --no-deps postgres
  MNEMA_PG_UPGRADE= docker compose up -d --wait
  curl -fsS http://127.0.0.1:8080/api/health
)

restore.sh --yes records that the app was already stopped, so it does not resume it. If restore or marker publication fails, set -e stops the sequence; keep the app stopped and resolve the failure before proceeding. The marker lives in the PostgreSQL 18 volume and survives container recreation. Remove any MNEMA_PG_UPGRADE=1 setting from .env and the invoking shell before later normal operations; the empty assignments above apply only to those commands. After health succeeds, test login, an uploaded object and voice on the restored release. The newer app applies its embedded migrations when it finally starts.

0.3.x → 0.4.0

Operator-relevant changes (0.3.1, 0.3.2, 0.3.3 and 0.4.0):

  • New compose file. The app's image is now ${MNEMA_IMAGE:-mnema-talk:local} instead of a fixed mnema-talk:local, the app carries the updater labels, and there is a new optional updater service (profile autoupdate) with an internal network mnema-updater. Fetch the compose file of the tag (pinned procedure); an old file keeps working but cannot run released images.
  • Released images on GHCR for linux/amd64 and linux/arm64 (:X.Y.Z, :X.Y, :latest). Set MNEMA_IMAGE to use one instead of building on the server. If the package is private, docker login ghcr.io with a read:packages token first.
  • New variables (all optional, defaults are safe):
    • UPDATE_CHECK_ENABLED (default true): the server asks api.github.com every 30 minutes for the latest release; set false for no outbound request.
    • MNEMA_IMAGE (compose default mnema-talk:local): the image the app runs.
    • UPDATER_TOKEN (default empty = off) and UPDATER_URL (default http://mnema-updater:8080): "Update now" through the sidecar. The token needs at least 32 characters (openssl rand -hex 32); a short or placeholder token stops startup. Read SECURITY.md before enabling it.
  • Version reporting. The binary and the web app carry their version; /api/health returns it, and browsers on an older build show a reload banner (never an automatic reload).
  • Voice channels have a text chat (panel under the Talk stage, deep link /v/<id>/chat). Messages, uploads, threads and read state for voice channels use the existing tables; no migration.
  • Stream audio behaviour change. A shared screen's sound now travels on its own line instead of being mixed into the sharer's microphone. Viewers control it with the stage's volume slider (0–100 %, default 50 %, remembered per sharer); the member menu's volume and mute affect only the voice. Every new share starts at 1080p / 30 FPS; the sharer changes quality in the stream's gear menu. Make sure everyone reloads after the update (the reload banner asks them to): a tab still running the old web app sends its screen sound mixed into the microphone, so viewers can't control it separately.
  • Migrations: none since 0.1.16 (latest is 0012_message_count.sql), so rolling back to 0.3.x needs no database restore unless the changelog of the release you install says otherwise.

0.1.16 → 0.3.0

No configuration, compose or schema changes. 0.3.0 brings the sidebar management (drag and drop, Alt+↑/↓, context menus, duplicate channel) and the Talk stage (cameras on the stage, viewers of a share, grid, full screen, picture-in-picture). Update the image or rebuild; nothing else to do.

0.1.15 or older → 0.1.16

This release tightened configuration and storage security. Check these before updating, or the app (or SeaweedFS) will refuse to start:

  • Stricter configuration validation. In production/staging every public example value from .env.example is refused: JWT_SECRET, S3_ACCESS_KEY/S3_SECRET_KEY, the database password inside DATABASE_URL (i.e. POSTGRES_PASSWORD), METRICS_TOKEN, WEBRTC_TURN_SECRET, and ADMIN_INITIAL_PASSWORD in any environment. Also enforced: booleans must be true/false/1/0, LOG_LEVEL one of debug|info|warn|error (or empty), SESSION_EXPIRY_HOURS 1–8760, PORT 1–65535, APP_ENV one of production|staging|development|test, and every TRUSTED_PROXY_CIDRS entry a valid CIDR or IP. PUBLIC_URL and CORS origins are normalised (no trailing slash or default port).
  • TRUSTED_PROXY_CIDRS default is loopback only (before: loopback plus all private ranges, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7). The compose file adds 172.16.0.0/12 (Docker's default bridge range). A reverse proxy on another LAN host or in a Docker network with a custom subnet must be listed explicitly, otherwise all clients share the proxy's IP for rate limits and login lockout.
  • SeaweedFS requires S3 credentials. The seaweedfs service now writes an S3 identity from S3_ACCESS_KEY/S3_SECRET_KEY and the gateway accepts only that pair (before, it allowed anonymous access on the Docker network). Both must be set, use only letters, digits and ._~+/=-, and the secret needs at least 8 characters; otherwise the container exits. Use the compose file of the release.
  • Migrations 0011_username_ci_unique.sql (usernames unique regardless of case) and 0012_message_count.sql. 0011 fails, and startup stops, if two accounts differ only in case: rename one of them in the database and start again. From this release on each applied migration's checksum is recorded, and startup stops if an applied migration file was changed.
  • Backups. scripts/backup.sh refuses a BACKUP_DIR inside a git checkout (the backup holds .env) unless BACKUP_ALLOW_IN_REPO=1, and stops SeaweedFS briefly for a consistent media copy (SEAWEED_LIVE=1 for the old behaviour).

Something wrong on this page? Tell us.