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_DAYand sent asContent-Lengthis 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.
GETandPUT /api/admin/upload-limitgained the optional fieldstrip_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_secondsanduser_statsnow 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:
- Wait while a migration still runs. The server holds a PostgreSQL advisory
lock (key
470003576161) from the first migration to the last and logsmigration appliedfor each file; a rollback in the middle of a long migration helps nobody. - Put the old image back (the old
.envor tag) and start it. If the new version applied no migration, the old one starts and nothing is lost. - If the old version refuses the database (
the database was migrated by a newer version), restore the backup this very update took, after checking itsCOMPLETEfile, manifest andSHA256SUMS, never an older one, then start the old version and require it to be healthy. Writes made after that backup are lost. - 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-talkgets no new ones and GHCR does not redirect, sodocker compose pullthere finds nothing new. IfMNEMA_IMAGEin.envstill names the old path, change it toghcr.io/mnema-xyz/mnema-talkwith the same tag, thendocker 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_TIMEOUTandDB_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
attemptsandretry_attoscheduled_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 plainCREATE INDEX, which blocks writes tomessageswhile 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_noncesfor 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 setBACKUP_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.shnext to your deployment. After each backup it writesbackup-status/status.json(the folder can be changed withBACKUP_STATUS_DIR) and, by default, test-imports the dump into a throwaway database first;RESTORE_TEST=0skips 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).
2.7.0 (raid protection, vanity link, self-assignable roles)
- 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(default0, no limit): with a value, the server steps viewers down screen and camera layers to stay under that upload. Metricsmnema_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 loopbackhost: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 (
GOMEMLIMITset in the environment wins), and asks for 4 MiB UDP socket buffers. The kernel'snet.core.rmem_maxandwmem_maxcap 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 --checkprints it without starting. The.env.exampleanddocker-compose.ymlof 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 setsUPDATER_IMAGE_REPOSITORYdrops 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_LANGUAGEnow defaults toen(it wasdesince 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(autoby default) runs it only whileWEBRTC_TURN_URLSis empty, so an installation with an external TURN server changes nothing.onruns it anyway; withWEBRTC_TURN_URLSset too, members are offered both servers.offnever runs it. Details, limits and metrics: operations.md. docker-compose.ymlpublishes 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; withoff, or an external TURN underauto, nothing listens there). It does not collide with coturn on 3478; if something else uses 3479, setWEBRTC_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.envanddocker-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_IPfinds its public IPv4 address with a STUN request to Google or Cloudflare at startup and announces it (WEBRTC_AUTO_ANNOUNCE=falseturns this off). The server clock is compared with an NTP server (CLOCK_CHECK_ENABLED=falseturns this off). An install that setsWEBRTC_NAT_1TO1_IPsends the first request never. Both are named in the in-app privacy policy (policy version 1.6) while they are active. - A
PUBLIC_URLthat is an IPv4 address (a LAN install opened by IP) is now also announced for voice whenWEBRTC_NAT_1TO1_IPis 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
| Migration | Adds |
|---|---|
| 0059 | channels.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. |
| 0060 | Unused: 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. |
| 0061 | users.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. |
| 0062 | message_reminders and scheduled_messages (see "Reminders and scheduled messages"). |
| 0063 | poll_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. |
| 0064 | user_sessions: one row per browser session (device label, created, last active). |
| 0065 | instance_settings.session_inactivity_days (1 to 365, default 7). |
| 0066 | automod_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'). |
| 0067 | moderation_notes: private moderator notes about members. |
| 0068 | channels.is_stage: Stages. Existing channels keep false; a Stage is never a lobby or a temporary Talk. |
| 0069 | channels.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. |
| 0070 | events 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). |
| 0072 | media_original_filename_trgm_idx: GIN trigram index on media.original_filename for fast case-insensitive attachment filename search. |
| 0073 | server_notify: a member's server-wide notification default (see Notification settings). Adds a table only. |
| 0074 | dm_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). |
| 0075 | channels.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. |
| 0076 | messages_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. |
| 0077 | Drops 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. |
| 0078 | Drops the redundant index idx_messages_channel_created, covered by messages_channel_unread_idx (0076). |
| 0079 | channels.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. |
| 0080 | instance_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. |
| 0081 | media.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. |
| 0082 | Forum 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. |
| 0083 | Raid 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. |
| 0084 | instance_settings.vanity_slug and vanity_accepts_signups: the vanity invite link served at /join/<slug>. Empty by default. |
| 0085 | roles.self_assignable: roles members may add to or remove from their own account. Off for every existing role (see Roles and permissions). |
| 0086 | event_roles and event_signups: roles with slots and a waitlist for community events (see events). Adds tables only. |
| 0087 | event_comments and event_comment_mutes: a flat discussion under each event (see events). Adds tables only. |
| 0088 | event_series: recurring events; occurrences are ordinary events linked to their series (see events). Existing events stay single. |
| 0089 | The wiki tables: pages, revisions and redirects, one tree per community. Adds tables only. |
| 0090 | wiki_images: marks the media rows used as wiki pictures. Adds a table and an index only. |
| 0091 | Indexes 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. |
| 0092 | scheduled_messages.attempts and retry_at: count failed sends and delay the next try. Adds two columns only; existing rows start at zero. |
| 0093 | messages_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. |
| 0094 | Indexes 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. |
| 0095 | Deletes 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. |
| 0096 | upload_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. |
| 0097 | Adds Manage reports and Kick members to the built-in Moderator and Admin roles. Changes permission bits of those two roles only. |
| 0098 | messages.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. |
| 0099 | users.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. |
| 0100 | message_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. |
| 0101 | instance_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. |
| 0102 | recovery_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. |
| 0103 | Triggers 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. |
| 0104 | channels.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. |
| 0105 | The 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. |
| 0106 | Messages 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. |
| 0107 | bots.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. |
| 0108 | Member 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. |
| 0109 | The 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. |
| 0110 | bot_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. |
| 0111 | Display 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. |
| 0112 | messages_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.
| Address | Opens |
|---|---|
/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-0f3a9c1e | a forum post: its title and the first 8 characters of its id |
/dm/alice, /dm/g/0f3a9c1e | a 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 givesae, the sharp s givesss), other accents are dropped, anything else becomes one dash; a name without a usable character giveschannel. 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 slugtalk-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
slugandprevious_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 carrychannel_slugso 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
:smiin 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=pastlists events that are over (completed, cancelled or ended), newest first, withlimitand the cursorbeforeandbefore_id(start time and id of the last event of the previous page). The same visibility rules as for upcoming events apply. Withoutwhenthe 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_secondsmay 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 (eventreminder_update) and by Web Push when that is on, and stays until dismissed (removed after 30 days at the latest). Routes:GETandPOST /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,PATCHandDELETE /api/me/scheduled/{id}; eventscheduled_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 becomesfailedand 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_atis 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 aschannel.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) inPUT /api/admin/onboarding, set by the Owner and Administrators;SESSION_EXPIRY_HOURSstill 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.
Message search
- New search filters and ordering. The message search API (
GET /api/search) supportsduring:YYYY-MM-DD(matching messages within a single local day, acceptingtzoffset 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 asort=newest|oldest|relevanceparameter (defaultnewest). - Interactive filter dropdown and chips. When the search box is focused,
suggestion chips allow quick selection of
from:,in:,mentions:,has:,during:,author:, andfilename: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-band a quoted-xstay 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.v3inGET /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.lobbyinGET /api/health. New eventstalk_leaderandtalk_moved; newvoice_kickedreasonstalk_rate_limitedandtalk_unavailable. REST:PATCH /api/talks/{id},POST /api/talks/{id}/invites,POST /api/dms/{id}/talk, and the fieldsis_lobby,is_temp,leader_idof 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 (bit1 << 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 eventsstage_hand,stage_talk_power,talk_reaction; REST: the fieldis_stageof a channel and ofPOST /api/admin/channelsandPATCH /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:
| Rule | Default |
|---|---|
| Mention spam | on: a message with more than 10 different mentions is blocked |
| New accounts | on: accounts younger than 10 minutes cannot post links (blocked) |
| Raid protection | on: more than 10 joins within 10 seconds time the newcomers out for 10 minutes and add one alert to the reports queue |
| Blocked words | off, word list empty |
| Links | off (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, endpointGET /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.foruminGET /api/health. New eventforum_tags_changed. REST:GET/POST /api/channels/{id}/tags,PATCH/DELETE /api/channels/{id}/tags/{tagID},GET/POST /api/channels/{id}/posts, andPATCH /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 << 25ininternal/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, andnot_goingresponses, with participant counts and avatars. - Automated reminders sent 15 minutes before event start via in-app notifications and Web Push to members RSVP'd
goingorinterested. - Automatic transition from
scheduledtoactiveat start time, showing a direct "Join Talk" button for voice events. - Feature key
eventsinGET /api/health. Real-time WebSocket eventsevent_updateandevent_reminder. - Audit logging for
event.create,event.edit, andevent.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.v2inGET /api/health. NewPUT /api/notification-settings/server(levelall,mentionsormute,muted_untilfor a timed mute,suppress_everyone);GET /api/notification-settingsgains aserverobject (additive). Changes reach the member's other sessions with the existingread_staterefresh 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 whennotify.levels.v2is missing.
Direct message list: close, favourites, mute all
- Migration 0074 adds
dm_members.hidden_atanddm_members.favourite_pos(a member's closed and favourite conversations) andusers.dm_mute_allandusers.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.v2inGET /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),GETandPUT /api/users/me/dm-settings(mute_all,list_collapsed).GET /api/dmsandGET /api/dms/{id}gainhidden,favourite_positionandlast_message(additive); a new eventdm_prefs_updatedreaches the member's own sessions only. - Mute all direct messages sends no push, and reads as
notify_level: mutewith 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: raiseline was not a git trailer, so the signed web bundle of 1.2.0 carriessecurity_floor0.7.23. The high-water mark has the same effect: a desktop client that has run the 1.2 bundle refuses every older bundle ofweb_client_api1: 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_apiis 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).
| Migration | Adds |
|---|---|
| 0049 | user_blocks and message_reports. |
| 0050 | Direct 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. |
| 0051 | saved_messages. |
| 0052 | messages.forward_of and messages.forwarded. |
| 0054 | thread_follows, filled from the existing threads (root authors and repliers) so threads keep notifying the people who took part. |
| 0056 | bot_tokens.minter_inferred, a flag for tokens bound to their likeliest issuer (see "Bots and webhooks"). |
| 0057 | The nullable column users.banner_s3_key (the profile banner). It also extends the tombstone trigger of 0043 so a deleted account keeps no banner. |
| 0058 | users.avatar_reencoded_at, the marker of the one-time avatar redraw (see "Profile pictures"). |
The numbers 0053 and 0055 are unused.
New permissions
| Permission | Bit | Default |
|---|---|---|
| Manage reports | 1 << 21 | Off for @everyone and every existing role. |
| Send direct messages | 1 << 22 | On for @everyone (set by migration 0050). An administrator can take it away. |
| Kick members | 1 << 23 | Off 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(dedefault, oren) names the default categories and channels of a brand-new installation. An upgrade never renames anything. - Changed defaults:
LEGAL_OPERATOR_COUNTRYandLEGAL_PROJECT_NOTICEare 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.envis 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 rundocker compose --profile autoupdate up -dafter the update. Theupdaterservice 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 networksmnema-recreatorandmnema-updater-egressare 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 underbanners/(the daily orphan check covers it), is deleted when replaced or removed, goes into the data export asbanner.*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, featureprofile.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_removedwith 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,/banand/kickjoin/pollin the menu (bots)./kicksigns 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,afterandbefore_date(seeapi/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_viewandpoll.end; themessage.deleteentry 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/healthhas afeatureslist: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 fieldbanner),DELETE /api/users/me/avatar, plus the routes for blocks, reports and direct messages (seeapi/openapi.json). banner_urlis added toGET /api/users/{userID}andGET /api/auth/meonly, never to message, member or event payloads.- Messages carry a
forwardmarker ({forwarded: true}, no ids and no quoted text, for bots and webhooks too). Messages and the pin event carrypinned_atandpinned_bywhile 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_updatedandkicked. - 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.jsonandbanner.*. 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'becamestyle-src 'self'plusstyle-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'ssecurity_flooris 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) andemoji_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 gets429withRetry-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.txtalso 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,@hereand 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_namesee the stored text. - The release workflow mirrors the required checks.
release.ymlreads the checks thatmain's ruleset requires (including theupgrade-drilljobs) 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.
@everyoneand@hereare 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 indexmessages_content_trgm_idx(both came from earlier releases), so message writes no longer maintain the same index twice and search is unchanged.DROP INDEXtakes a short exclusive lock onmessages; the migration runs in a transaction, so it is notCONCURRENTLY. 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 tousers. It rewrites no rows and holds only a brief lock onbot_tokenswhile the foreign key is added. - 0040 adds the nullable columns
users.emailandusers.email_verified_at(with a partial unique index on confirmed addresses) and the tableaccount_tokensfor 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_challengesandsecond_factor_failuresfor 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 tabledata_exportsand 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_atandmessages.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_optionsandpoll_votesfor the/pollcommand. 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 appformigration applied.
- 0038 drops
- Edit history for moderators (migration 0047). The new table
message_editskeeps 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(default0, 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-unreadis 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). WithoutSMTP_HOSTnothing 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. PutSMTP_PASSWORDin the environment or mount a file and name it inSMTP_PASSWORD_FILE;SMTP_TLS=noneis 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
202with 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 fromJWT_SECRET: rotating it requires resetting two-factor for the accounts that use it (Admin > Members, ormnema-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(default2048) is what one member, bot or webhook may upload in any rolling 24 hours; further uploads answer 429, and deleted files still count.0turns 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) andMEDIA_MIN_FREE_MB(default1024) together withMEDIA_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_DAYSstill defaults to0: nothing is deleted automatically. See operations.md. - coturn is capped (only if you run the
turnprofile). The compose file now starts coturn with--user-quota=8(relayed sessions per credential) and--total-quota=48(all sessions, matching the 49 ports of49152-49200). Fetch the compose file of the tag (pinned procedure) and restart the profile. If you widened the relay port range, raise--total-quotawith it; see TURN. PUBLIC_URLover plainhttp://warns. In production and staging, aPUBLIC_URLthat is nothttps://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 publichttps://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: raisetrailer; afix(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 andAGENTS.md. - Alert rules moved. The example alert rules are now the file
deploy/monitoring/mnema-alerts.yml, checked withpromtooland against/api/metricsin 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) andusers.push_preview. Nothing is sent until a member subscribes. New settings, all optional:PUSH_ENABLED(defaulttrue),PUSH_PREVIEWS(user, default, oroffto never put message text in a push) andPUSH_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 tablecustom_emojiand widensmessage_reactions.emojifrom 32 to 80 characters (a custom emoji reaction is the token<:name:id>); no row is rewritten.EMOJI_MAX(default200,0forbids 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 underemoji/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.jsand/manifest.webmanifestthrough unchanged (no caching of/sw.js, no rewriting); the app's ownCache-Control: no-cachealready says so. - Polls and built-in slash commands (migration 0048).
/polland 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 optionchoices. New surface, all additive: thepollobject on messages, thepoll_updateWebSocket event, the routes under/api/channels/{id}/pollsand.../messages/{id}/poll, and200as an answer of running a built-in command. A reverse proxy needs no change. The data export gainspoll_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.shand 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
alltoinherit, so a category setting now reaches those channels; with no category settinginheritstill meansall. Explicitmentionsandmutelevels 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, andvoice_kickedwith reasonrules_not_acceptedfor 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
inheritnotification 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(default50, 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 theinstance_settingstable androles.max_upload_mb. - To allow bigger files, raise
MAX_UPLOAD_SIZE_MBand your reverse proxy. The proxy must accept at least that body size plus a little for multipart framing: nginxclient_max_body_size(for exampleclient_max_body_size 140m;for 128 MB), Caddyrequest_body { max_size 140MB }. The default of nginx is 1 MB, so large uploads fail with413there 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). SetPUBLISH_ADDR=0.0.0.0(or a LAN address) in.envto reach the app directly from the network. A reverse proxy on the same host keeps working.TRUSTED_PROXY_CIDRSis empty (loopback only) in compose (before: also172.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 forgeX-Forwarded-For. If you run a reverse proxy on another host or in a container, setTRUSTED_PROXY_CIDRSto that proxy's address, e.g.192.168.0.20or 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 saysignoring 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_ADDRunchanged (loopback); the proxy reaches127.0.0.1:8080through Docker, so the app sees the bridge gateway, not loopback. SetTRUSTED_PROXY_CIDRSto that gateway (docker network inspect <project>_default, fieldGateway). - 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_ADDRto a LAN address (or0.0.0.0behind a firewall) andTRUSTED_PROXY_CIDRSto the proxy's address. An existing deployment with its own compose file that already setsTRUSTED_PROXY_CIDRS(or its own default) is unaffected by this change.
- Caddy or nginx on the compose host: set
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-shortADMIN_INITIAL_PASSWORDis 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 unlockclears 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=developmentonly listens on loopback.BIND_ADDRdefaults to127.0.0.1there and any other address is refused at startup. Production, staging and test are unchanged (0.0.0.0).Two new migrations:
0021_revoked_sessionsand0022_search_trigram(apg_trgmindex 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_IMAGEif 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: raisecommit; 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, includingbackup-common.sh,backup-online.shandupgrade-postgres.sh. Instead of its finaldocker compose up -d, run:# backup saved, new compose file, scripts and image selected docker compose pull ./scripts/upgrade-postgres.shThe 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 contentsmnema-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=1is a temporary import bypass; do not save it in.envor 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 -vdiscards 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) and0014_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_PASSWORDon a fresh install (no effect once the admin exists). The generated password is no longer logged.Voice: one shared UDP port.
WEBRTC_UDP_MUX_PORTnow defaults toWEBRTC_UDP_PORT_MIN; no Docker or router change. An.envstill sayingWEBRTC_UDP_MUX_PORT=0keeps 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_PASSWORDandS3_SECRET_KEYrequired at interpolation. New optional variablesAPP_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 fixedmnema-talk:local, the app carries the updater labels, and there is a new optionalupdaterservice (profileautoupdate) with an internal networkmnema-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/amd64andlinux/arm64(:X.Y.Z,:X.Y,:latest). SetMNEMA_IMAGEto use one instead of building on the server. If the package is private,docker login ghcr.iowith aread:packagestoken first. - New variables (all optional, defaults are safe):
UPDATE_CHECK_ENABLED(defaulttrue): the server asksapi.github.comevery 30 minutes for the latest release; setfalsefor no outbound request.MNEMA_IMAGE(compose defaultmnema-talk:local): the image the app runs.UPDATER_TOKEN(default empty = off) andUPDATER_URL(defaulthttp://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/healthreturns 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/stagingevery public example value from.env.exampleis refused:JWT_SECRET,S3_ACCESS_KEY/S3_SECRET_KEY, the database password insideDATABASE_URL(i.e.POSTGRES_PASSWORD),METRICS_TOKEN,WEBRTC_TURN_SECRET, andADMIN_INITIAL_PASSWORDin any environment. Also enforced: booleans must betrue/false/1/0,LOG_LEVELone ofdebug|info|warn|error(or empty),SESSION_EXPIRY_HOURS1–8760,PORT1–65535,APP_ENVone ofproduction|staging|development|test, and everyTRUSTED_PROXY_CIDRSentry a valid CIDR or IP.PUBLIC_URLand CORS origins are normalised (no trailing slash or default port). TRUSTED_PROXY_CIDRSdefault 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 adds172.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
seaweedfsservice now writes an S3 identity fromS3_ACCESS_KEY/S3_SECRET_KEYand 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) and0012_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.shrefuses aBACKUP_DIRinside a git checkout (the backup holds.env) unlessBACKUP_ALLOW_IN_REPO=1, and stops SeaweedFS briefly for a consistent media copy (SEAWEED_LIVE=1for the old behaviour).