Skip to content

Mediabot 3.3

Latest
Latest

Choose a tag to compare

View all tags
@teuk teuk released this 12 Jul 14:32
3.3
129d613

Mediabot 3.3 — Stable Release

( if you don't have time the archives are at the bottom :p )

Mediabot 3.3 is the stable release produced from the long-running 3.2 development line.

This release combines new everyday IRC features, stronger channel-history tools, safer installation and upgrades, database drift detection, authentication hardening, startup integrity checks, richer URL previews, extensive UTF-8 correctness work, improved help and documentation, and deterministic public release artifacts.

The release was validated on the development instance and through a complete fresh installation on Debian 13.

Table of contents

Release identity

Item Value
Stable version 3.3
Git tag 3.3
Release commit 129d61362bbdfe9949adec42cdd8b585bdd5b93a
Release date 2026-07-12
Archive root mediabot_v3-3.3/
Archived paths 824
Next development line 3.4dev
License GNU GPL version 3 or later

Mediabot uses odd minor versions for stable releases and even minor versions for development lines. Version 3.3 is therefore the stable successor to the 3.2 development cycle.

Official release assets

The official release contains six attached files:

File Purpose
mediabot_v3-3.3.tar.gz Official gzip-compressed source archive
mediabot_v3-3.3.tar.xz Official xz-compressed source archive
mediabot_v3-3.3-FILES.txt Complete archive file manifest
mediabot_v3-3.3-RELEASE.txt Release provenance and build metadata
mediabot_v3-3.3-SHA256SUMS SHA-256 verification file
mediabot_v3-3.3-SHA512SUMS SHA-512 verification file

The two source archives contain the same Git-tagged tree. Choose either format according to your preferred compression tool.

Official mirror:

The automatically generated GitHub “Source code” archives are not the canonical Mediabot 3.3 release artifacts. Use the attached mediabot_v3-3.3.* files when you need the deterministic, verified release build described here.

SHA-256 and SHA-512

SHA-256

b09bf6b003b18780fbc1d8ad9791fbd42b11741f2c603e17af867c3bd2ac42ca  mediabot_v3-3.3.tar.gz
268ae18c5c1dc8d55886ceb1865ff5e19d42dfef41d88b84b549594d75431fd1  mediabot_v3-3.3.tar.xz

SHA-512

c7e2bb0073551b63d40c1f1f5bbe7e55b25d5c036855059f2dce360b4bd8f1032f48e404394fdc8f8174d639d3918ee28dc9dfaa7b51a7c6add197886b0f9c6e  mediabot_v3-3.3.tar.gz
1852067eaec0dcb34a61cd935e96aa6bdf3c0a5a11fa35fec40f23f1dcf206ccd2dd48d811282ee7f014f2fe18c7f25b53117312c5649484c234ec6349a8df8d  mediabot_v3-3.3.tar.xz

Verify an archive from the directory containing the downloaded files:

sha256sum -c mediabot_v3-3.3-SHA256SUMS
sha512sum -c mediabot_v3-3.3-SHA512SUMS

You can also validate the compression streams directly:

gzip -t mediabot_v3-3.3.tar.gz
xz -t mediabot_v3-3.3.tar.xz

Executive summary

Mediabot 3.3 is focused on five areas.

1. Better day-to-day IRC use

Users gain delayed messages, persistent channel factoids, guarded command suggestions, offline unit conversion, richer statistics, historical channel recall, quote rankings and milestone tracking.

2. Safer installation and upgrades

The supported ./configure workflow now generates a complete configuration atomically, audits configuration coverage, installs Perl dependencies through CPAN, validates database drift, checks column types and required indexes, and fails closed when unresolved drift remains.

3. Stronger security and integrity

Authentication can lazily migrate successful logins to bcrypt. The final security audit checks eleven critical invariants. Startup integrity checks load all Mediabot modules and resolve cross-module methods and dispatch handlers before normal traffic reaches them.

4. Greater runtime reliability

The 3.2 development cycle closed numerous issues involving worker lifecycle, asynchronous DNS, SQL quoting, channel-case normalization, URL parsing, UTF-8 boundaries, database-backed notes, ban matching, random-number isolation, karma selection and command output limits.

5. Reproducible public releases

The release builder exports the exact Git tag, includes the tracked contrib/ and plugins/ trees, excludes local and runtime-only data, produces deterministic gzip and xz archives, validates the extracted result and publishes SHA-256 and SHA-512 sums.

New everyday IRC features

Delayed messages with !tell

Mediabot can leave a message for another user:

!tell Bob remember to review the new configuration

Delivery occurs when the recipient next joins or speaks on the same channel.

Important behavior:

  • delivery is channel-aware;
  • a message is marked delivered before it is emitted;
  • joining and speaking cannot cause duplicate delivery;
  • the existing reminder infrastructure is reused rather than creating a second incompatible message system.

Guarded “Did you mean?” suggestions

Unknown public commands can now produce a conservative suggestion:

unknown command '!raodm'. Did you mean !random?

The suggestion engine:

  • runs only for public channel command misses;
  • ignores very short tokens;
  • supports adjacent transpositions through Damerau-Levenshtein distance;
  • offers at most one suggestion;
  • has a per-channel cooldown;
  • can be disabled with the DidYouMean channel setting.

This is intentionally designed to help with obvious typos without responding to normal conversation.

Persistent channel factoids

Mediabot now provides shared, channel-scoped facts:

!learn coffee = black gold of the morning
!whatis coffee
!factoid coffee
!factoids
!factoids top
!forget coffee

A quiet shortcut is also available:

?coffee

Factoids include:

  • channel scope;
  • normalized keywords;
  • stored values;
  • author information;
  • creation and update timestamps;
  • recall hit counters;
  • top-factoid ranking;
  • detailed metadata views;
  • author or channel-operator deletion rules;
  • per-channel enable/disable control through the Factoids setting.

The ?keyword shortcut stays silent when no factoid exists, preventing random question-like chat from generating noise.

Input is bounded and sanitised. Factoid values use UTF-8-safe truncation rather than byte-level cutting.

Offline unit conversion

The new !convert command performs local conversions without an API or code evaluation:

!convert 100 km mi
!convert 100 c f
!convert 1 kg in lb
!convert 1 gb mib

Supported families include:

  • length;
  • mass;
  • temperature;
  • volume;
  • speed;
  • decimal data units;
  • binary data units.

Temperature conversions use explicit affine formulas. Incompatible dimensions are rejected cleanly rather than producing meaningless output.

Achievement count in !stats

When a user has unlocked achievements on the current channel, !stats can now include the achievement count.

The line remains absent when the count is zero, keeping the output compact for new users.

Channel history and engagement

!onthisday and !otd

Long-running channels can resurface activity from the same calendar date in previous years:

!onthisday
!otd
!onthisday 12-25

The output can include:

  • years represented;
  • message totals;
  • active participants;
  • the most active nickname;
  • a representative historical message;
  • per-year context.

The command uses parameterised SQL and is gated by the OnThisDay channel setting.

Optional daily “on this day” digest

Channels can opt in to an automatic daily historical digest through OnThisDayDigest.

The posting hour is controlled by:

ONTHISDAY_DIGEST_HOUR

The default is 12. Setting it to -1 disables the automatic digest globally.

This feature remains opt-in and does not affect channels that have not enabled the corresponding channel setting.

Quote hall of fame

The quote system now records recall hits.

Commands:

!topquote
!halloffame

The ranking is channel-specific and based on the number of times a quote is actually recalled, whether by identifier or random selection.

The database adds a hits counter and a supporting composite index.

Channel milestones

Commands:

!milestone
!milestones

The milestone output can report:

  • total logged messages;
  • the last milestone passed;
  • the next milestone;
  • current progress;
  • an ETA based on recent daily activity;
  • channel logging age.

The command has a per-nick cooldown because it analyses channel log data and can otherwise become expensive or noisy on active channels.

Richer !seen

The stored last message shown by !seen is now safer and more useful:

  • IRC colour codes are removed;
  • IRC formatting and control codes are stripped;
  • display length is bounded;
  • malformed display content cannot leak raw control sequences;
  • recent channel activity can be added as a hint, for example the number of messages in the last 24 hours.

Richer !mood

The mood report now includes an activity pulse in addition to sentiment and energy.

It can show:

  • top talkers during the last 60 minutes;
  • the busiest hour of the current day;
  • top emoji when present.

Database-handle checks and cooldown protection were added to the command.

Bounded AI recap output

!recap ai now caps the number of emitted lines.

If the generated summary exceeds the configured output budget, Mediabot emits a truncation notice rather than flooding the channel.

Help and command discovery

The public help system received a substantial consistency and usability pass.

Dispatch/help consistency

A release guard now checks both directions:

  • public commands in dispatch must have help;
  • public help entries must resolve to real commands.

This prevents undocumented commands and stale help entries from silently shipping.

Cleaner categories

The help parser no longer treats comments as fake commands.

Categories are cleaner and include dedicated grouping for areas such as factoids, statistics, channel tools and radio commands.

Improved !help entry point

A plain !help now presents a compact navigation screen with useful paths such as:

help <command>
help <category>
help commands <category>
help search
help level
help chansets
help #channel

The screen is deliberately kept below the NOTICE queue limit.

Better category output

Small categories can display concise descriptions for each command. Large categories remain compact to prevent output flooding.

Historical problems with empty headings, truncated category screens and category-name collisions were corrected.

Quote command categorisation

!topquote and !halloffame are now grouped with the rest of the quote commands rather than appearing in an unrelated help section.

URL, media and AI output improvements

Apple Music

Apple Music previews can extract richer data from JSON-LD rather than relying exclusively on a full browser pass.

This provides a faster path and better metadata when the page exposes structured information.

X / Twitter

X links can display:

  • tweet text;
  • like counts;
  • repost/retweet counts.

The handler uses guarded extraction and compact numeric formatting.

Facebook and Instagram

Facebook and Instagram previews received multiple reliability improvements:

  • richer title and metadata extraction;
  • hexadecimal HTML entity decoding;
  • paired-quote extraction for apostrophes;
  • safer Chromium fallback behavior;
  • isolated temporary browser profiles;
  • crash-reporter suppression flags;
  • bounded browser budgets and timeouts.

Faster handlers

Where structured metadata or a direct lightweight path is available, the URL subsystem avoids launching Chromium.

This reduces latency and resource usage for supported services.

Counter formatting

The compact counter formatter no longer produces 1000k at the 999,999 boundary. Values roll over correctly to the million representation.

Host validation

YouTube-like paths on unrelated hosts are no longer accepted as YouTube identifiers.

Specialised URL handlers validate the actual host before applying service-specific parsing.

YouTube search runtime restoration

The YouTube search path was restored and covered by targeted regression tests after a runtime regression.

Output sanitisation

URL and AI output paths share stronger IRC sanitisation and output-bound rules, reducing the chance of control-code leakage or channel flooding.

Installation and configuration

Debian 13 fresh installation validated

The final release was exercised through a complete fresh Debian 13 installation.

The configuration audit reported:

active sample keys : 125
configured keys    : 125
missing defaults   : 0
custom/extra keys  : 0
duplicate keys     : 0
safety warnings    : 0

The installation completed database creation, application-user creation, configuration generation and startup validation.

Supported entry point: ./configure

./configure is the supported installation and maintenance entry point.

It should not be replaced with a manual copy of mediabot.sample.conf.

The wizard can:

  • generate a complete mediabot.conf;
  • write the file atomically;
  • audit coverage against active sample keys;
  • preserve existing custom settings;
  • add missing safe defaults;
  • normalise duplicate INI keys;
  • back up an existing configuration;
  • create a fresh database;
  • guide an existing database through drift review;
  • validate dependencies;
  • install and verify Perl modules through CPAN;
  • configure IRC/network data;
  • validate database types and required indexes;
  • avoid enabling Partyline eval.

Useful modes include:

./configure --config mediabot.conf --sync-only
./configure --config mediabot.conf --drift-only

CPAN-based Perl dependency path

The supported installer uses CPAN for the Perl database modules and other Perl dependencies.

On Debian, libmariadb-dev remains necessary because it provides the native MariaDB connector headers and mariadb_config required to build the CPAN driver.

The supported path intentionally does not rely on distribution packages such as:

libdbi-perl
libdbd-mariadb-perl
libdbd-mysql-perl

Atomic configuration updates

Configuration creation and updates use an atomic write path.

If an installation or maintenance operation fails, it is less likely to leave a partially written mediabot.conf.

Fresh database-user creation fix

The database installer previously used a malformed sed expression for SQL string literal quoting.

That could break application-user creation even with the generated alphanumeric password.

Version 3.3 replaces the fragile expression with dependency-free Bash quoting, checks each conversion explicitly and uses an idempotent DROP USER IF EXISTS rollback with validated literals.

Fail-closed database workflow

The existing-installation path no longer treats a non-strict drift report as proof that the database is in sync.

The workflow now performs:

initial strict drift check with types and indexes
reviewable migration-plan generation with types and indexes
final strict drift check with types and indexes

Unresolved drift stops the workflow unless an explicit maintenance bypass mode was deliberately selected.

Database validation and migrations

Strict drift validation

The reference check is:

perl tools/check_schema_drift.pl \
  --conf=mediabot.conf \
  --strict \
  --types \
  --indexes

For an existing installation, first generate a reviewable plan against the configuration that points to the real target database:

perl tools/check_schema_drift.pl \
  --conf=mediabot.conf \
  --generate-migration \
  --types \
  --indexes

The tool compares:

  • required tables;
  • required columns;
  • column definitions and types;
  • selected reference data;
  • required indexes.

Missing non-primary indexes can be represented as non-destructive ADD INDEX statements.

Extra live-only indexes are intentionally ignored.

Fresh schema and migration alignment

The fresh-install schema and the ordered migration path now carry the same release indexes, including:

idx_quotes_channel_hits

This prevents a fresh installation and an upgraded installation from ending in different expected states.

Migration ordering

Migration discovery uses chronological date ordering rather than a simplistic lexical assumption.

Recent migrations included in the 3.3 line

The authoritative order remains in:

install/migrations/README.md

Recent release migrations include:

20260706_channel_log_channel_ts.sql
20260707_channel_report_chanset.sql
20260707_didyoumean_chanset.sql
20260707_factoid.sql
20260707_factoids_chanset.sql
20260708_onthisday_chanset.sql
20260708_onthisday_digest_chanset.sql
20260710_quotes_hits.sql

Purpose:

Migration Purpose
20260706_channel_log_channel_ts.sql Composite channel/time index for channel-log queries
20260707_channel_report_chanset.sql Per-channel report gate
20260707_didyoumean_chanset.sql Per-channel command-suggestion gate
20260707_factoid.sql Persistent shared factoid storage
20260707_factoids_chanset.sql Per-channel factoid gate
20260708_onthisday_chanset.sql OnThisDay channel setting
20260708_onthisday_digest_chanset.sql Opt-in daily historical digest setting
20260710_quotes_hits.sql Quote recall counter and supporting composite index

These migrations are designed to be idempotent and non-destructive.

Do not blindly apply every historical migration to a fresh 3.3 installation. Fresh installs already use the current reference schema. Existing installations should back up the database, generate a drift plan, review the ordered migration list and apply only what is required.

Security and authentication hardening

bcrypt lazy migration

Successful login can migrate an eligible legacy password hash to bcrypt without requiring a disruptive all-at-once reset.

The migration is lazy:

  • it occurs only after successful authentication;
  • the existing database schema does not need to change;
  • the replacement hash is written only after the original credential has been verified.

Final security audit

The release security audit reports:

Verdict: GO — all 11 security invariants hold.

The audited areas include:

  • secret masking;
  • authenticated HTTP transport;
  • TLS certificate verification;
  • shell/command execution boundaries;
  • yt-dlp list-form execution;
  • IRC output sanitisation;
  • Partyline eval defaults;
  • runtime credential handling.

Partyline eval disabled by default

The generated configuration never enables Partyline evaluation automatically.

Administrators must make an explicit, informed decision before enabling any high-risk evaluation capability.

Secret handling

Runtime and operational paths avoid exposing selected sensitive values, including:

  • database passwords;
  • API credentials;
  • IRC channel keys;
  • DCC passive tokens;
  • private configuration values.

The release archive does not include a real mediabot.conf.

Safer external execution

External program invocation paths use list-form execution where applicable rather than building shell command strings from user input.

This applies in particular to hardened yt-dlp execution.

TLS verification

Authenticated remote calls covered by the security audit use TLS verification rather than silently accepting unverified certificates.

Startup, deployment and runtime integrity

Startup integrity check

The final candidate passed the startup integrity audit:

loaded 41/41 Mediabot modules
resolved 80 cross-module methods
resolved 197 dispatch handlers

The check loads the module set and validates callable relationships before normal IRC traffic can reach them.

This converts an entire class of delayed runtime failures into an immediate, understandable startup failure.

Dispatch-handler validation

The integrity check resolves:

  • *_ctx handlers;
  • stored code references;
  • public/private dispatch targets;
  • cross-module methods called by mediabot.pl.

Optional orphan detection

Long-lived deployments can accumulate stale local modules that no longer belong to the release.

The integrity tool supports a generated manifest for orphan detection. Administrators upgrading an old working tree should consider validating against the candidate archive manifest rather than assuming that every leftover local file is still part of 3.3.

Systemd deployment

Foreground startup remains the first validation step:

perl mediabot.pl --conf=mediabot.conf

After a clean foreground start, production deployments can use the systemd template:

sudo systemctl start mediabot@<instance>

The repository documentation no longer recommends historical start wrappers that are not present in the project.

Worker lifecycle

The trivia worker lifecycle was repaired after a queued trivia command could start a worker and then produce no question.

Pipe and child-write ownership are now explicit, and worker start-to-output behavior is covered by regression tests.

Asynchronous DNS

The asynchronous DNS path was hardened to avoid blocking or unreliable resolution behavior in runtime command paths.

Netsplit and reconnect resilience

The release retains the reconnect and netsplit hardening developed during the 3.2 line, including guarded lifecycle behavior for long-running IRC instances.

Reliability and correctness fixes

The 3.2 development cycle included many fixes that are less visible than the headline features but are important for a stable IRC bot.

Database-backed notes after restart

All relevant note operations now load persisted state before deciding what exists.

This closes cases where, immediately after a restart:

  • the ten-note limit could be bypassed;
  • note export could claim there were no notes;
  • note search could miss notes that were present in SQL.

Ban matching

JOIN enforcement now matches stored wildcard bans against the real joining identity:

nick!ident@host

The normalised mask used for the eventual IRC ban operation remains separate from the identity used for matching.

Karma correctness

Karma calculations were tightened so that:

  • a channel-local delta cannot be combined with a score from another channel;
  • equal-second events have deterministic ordering;
  • recent-change selection is reproducible.

Poll consistency

Poll winner calculation was aligned across the relevant result paths.

Private whereis behavior

The private whereis path now replies in the expected private context rather than leaking or misrouting output.

Channel-case normalization

Channel refresh paths now handle IRC channel-name case consistently rather than treating equivalent channel spellings as unrelated state.

SQL quoting

Installer SQL literals are validated and escaped for:

  • application username;
  • authentication host;
  • password.

Apostrophes and backslashes are handled without relying on an ambiguous external sed expression.

IRC channel prefixes

Newer command paths use the shared IRC channel predicate and support standard prefixes:

#  &  !  +

They no longer assume that every channel starts with #.

Command-list pagination

Long-item pagination no longer emits a heading-only line before the first actual item.

Safe calculator modulo

Perl’s % operator performs integer arithmetic. The calculator now rejects floating-point modulo input rather than silently discarding fractions.

Users can use the appropriate floating-point remainder function when needed.

Horoscope random-number isolation

The horoscope command no longer reseeds Perl’s process-wide random generator.

It uses a local deterministic generator, preserving a stable result for a nickname and date without perturbing unrelated features such as rolls, duels, random quotes, Hailo probability or trivia selection.

Duration helpers

Previously under-tested duration helpers now have executable coverage for:

  • permanent and timed channel bans;
  • minute/hour/day/week multipliers;
  • invalid durations;
  • Spotify millisecond durations;
  • Spotify ISO-8601 durations;
  • hour-long media.

URL host and identifier validation

Service-specific ID extraction now confirms that the URL belongs to the expected service before accepting a path that merely looks similar.

UTF-8 and international text correctness

Mediabot often handles IRC and database text as UTF-8 bytes. Version 3.3 closes several bugs caused by treating already encoded bytes as decoded Perl characters, or by cutting multibyte characters at arbitrary byte offsets.

URL encoding

Accented terms and emoji are now percent-encoded exactly once in affected commands.

Examples fixed during the development line include:

define café
weather Genève
YouTube search: café musique
weather formats containing emoji

The correct transformation is preserved:

café -> caf%C3%A9

rather than a double-encoded result.

UTF-8-safe truncation

Display paths that previously used raw byte substr now use shared UTF-8-safe truncation.

Affected areas include:

  • Chronos excerpts;
  • database command pagination;
  • channel output;
  • login output;
  • Partyline output;
  • helper output;
  • factoid values;
  • user command output.

A source-tree regression test blocks the return of a known unsafe truncation idiom.

Trivia answer boundaries

Short answers are no longer accepted inside the UTF-8 byte sequence of a longer accented word.

Quote-game author boundaries

Quote-game masking and answer validation now treat UTF-8 bytes as part of the neighbouring word rather than accidental separators.

Mood emoji detection

The mood analyser decodes a tolerant copy for emoji scanning while leaving the established byte-aware word pipeline intact.

IRC display sanitisation

Stored text displayed by commands such as !seen is cleaned of IRC control sequences and bounded safely before emission.

Plugin and script integration

ScriptDryRun plugin

The release includes the ScriptDryRun bridge for controlled execution of external scripts.

It supports example integrations in:

  • Perl;
  • Python;
  • Tcl.

Example public commands include the demonstration paths for:

hello
pyhello
tclhello
proll

Safety defaults include:

  • dry-run mode by default;
  • IRC output disabled by default;
  • explicit apply mode;
  • scope requirements;
  • command and script allowlisting;
  • bounded execution and result handling.

The local release workflow and public documentation do not depend on the private commit.sh helper.

Public plugins/ tree

The official release archive includes the tracked plugins/ directory and its documentation.

Public contrib/ tree

The official release archive includes the tracked contrib/ directory, including observability resources such as Grafana documentation where present in the tag.

Testing and validation

Mediabot 3.3 was not produced from a working tree copy or an unverified snapshot.

Test suite

The offline regression suite runs green end to end.

The project’s test catalogue reached release case 721 and covers:

  • command behavior;
  • database/install workflows;
  • configuration generation;
  • drift detection;
  • migrations;
  • URL parsing;
  • security contracts;
  • help/dispatch consistency;
  • release packaging;
  • UTF-8 boundaries;
  • lifecycle behavior;
  • user-visible feature regressions.

Release-specific validation

The release-document and packaging contract passed:

PASSED: 131/131

The corrected path and naming contract passed:

PASSED: 67/67

Security audit

Verdict: GO — all 11 security invariants hold.

Startup integrity

41/41 modules loaded
80 cross-module methods resolved
197 dispatch handlers resolved

Fresh-install validation

The release completed a new Debian 13 installation from configuration generation through database creation and application-user verification.

Database validation

The development database workflow was verified with table, column, type and index drift checks.

Archive validation

The public builder verifies:

  • Git tag and release commit;
  • version inside the tag;
  • dated changelog state;
  • tracked-tree cleanliness;
  • required files;
  • required contrib/ and plugins/ content;
  • excluded local/runtime material;
  • extracted archive structure;
  • gzip integrity;
  • xz integrity;
  • SHA-256 sums;
  • SHA-512 sums.

Deterministic release packaging

The official release builder uses the committed Git tag rather than copying the active installation directory.

Build source

Git tag: 3.3
Commit: 129d61362bbdfe9949adec42cdd8b585bdd5b93a

Deterministic compression

For a fixed release commit:

gzip: -n -9
xz:   -T1 -9e --check=crc64

The gzip build omits timestamp and original filename metadata. The xz build uses one thread and an explicit integrity check.

Archive root

Both archives extract beneath:

mediabot_v3-3.3/

Included material

The release includes the complete tracked public source tree, including:

Mediabot/
contrib/
plugins/
docs/
install/
t/
tools/

Excluded material

Local, generated or runtime-only material is excluded, including:

commit.sh
mediabot.conf
mp3/
node_modules/
private test configuration
logs
snapshots
backups
runtime secrets

The release contains 824 archived paths.

Fresh installation

The complete installation guide is maintained in the wiki:

https://github.com/teuk/mediabot_v3/wiki/Installation

The essential path is:

1. Install system prerequisites

On Debian, install the required bootstrap packages, MariaDB server/client and native MariaDB development headers.

The supported Perl dependency path is CPAN-based.

2. Use a dedicated unprivileged account

Mediabot must not run as root.

3. Verify the downloaded archive

sha256sum -c mediabot_v3-3.3-SHA256SUMS
sha512sum -c mediabot_v3-3.3-SHA512SUMS

4. Extract one archive

tar -xzf mediabot_v3-3.3.tar.gz

or:

tar -xJf mediabot_v3-3.3.tar.xz

5. Run the supported configuration wizard

cd mediabot_v3-3.3
./configure

Do not create the runtime configuration by manually copying the sample file.

6. Review local configuration

Protect and review mediabot.conf:

chmod 600 mediabot.conf

Check at least:

[main]
[mysql]
[connection]
network section
[metrics]
[antiflood]
[openai]
[anthropic]
[chromium]
[radio]

Never commit the real configuration.

7. Validate the database

perl tools/check_schema_drift.pl \
  --conf=mediabot.conf \
  --strict \
  --types \
  --indexes

8. Start in foreground

perl mediabot.pl --conf=mediabot.conf

Resolve missing dependencies, database errors, IRC connection failures or character-set warnings before moving to systemd.

Upgrade guidance

Existing installations should treat the upgrade as an operational change, not as a blind source overwrite.

Recommended sequence

  1. Back up the current application tree.
  2. Back up the real mediabot.conf.
  3. Back up the MariaDB database.
  4. Record the current release and commit.
  5. Stop the relevant bot instance.
  6. Extract Mediabot 3.3 into a separate candidate directory.
  7. Review CHANGELOG.md.
  8. Review install/migrations/README.md.
  9. Generate a drift and migration plan against the real target configuration.
  10. Apply only the required migrations in chronological order.
  11. Re-run strict type and index validation.
  12. Run syntax checks.
  13. Run the security audit.
  14. Run startup integrity checks.
  15. Start in foreground first.
  16. Verify registration/login, public commands, URL handling and instance-specific features.
  17. Deploy or switch the production service only after the candidate is clean.

Generate the review plan

perl tools/check_schema_drift.pl \
  --conf=mediabot.conf \
  --generate-migration \
  --types \
  --indexes

Final strict check

perl tools/check_schema_drift.pl \
  --conf=mediabot.conf \
  --strict \
  --types \
  --indexes

Important migration rule

Do not infer the complete upgrade order from this release description alone.

The authoritative ordered list is:

install/migrations/README.md

Long-lived working trees

A long-lived checkout can contain stale modules or local files not present in the release tag.

For the cleanest upgrade:

  • compare against the official file manifest;
  • consider deploying from the official archive into a new directory;
  • use the startup integrity manifest option to detect obsolete local modules;
  • keep runtime data and configuration outside Git staging.

Operational notes

Channel history requirements

Features such as !onthisday, !mood, !seen activity hints and !milestone depend on the available channel-log history.

A new installation cannot show historical data that has not yet been collected.

Opt-in channel settings

Several features are gated per channel, including:

DidYouMean
Factoids
OnThisDay
OnThisDayDigest

Review the channel settings after upgrade rather than assuming every new feature should be enabled everywhere.

Daily digest control

Set:

ONTHISDAY_DIGEST_HOUR=-1

to disable automatic daily historical digests globally.

Metrics ports

Each bot instance on the same host must use a unique metrics port.

Partyline status paths

Each instance should use a unique PARTYLINE_STATUS_JSON path.

Character sets

Fresh installations should prefer utf8mb4.

Older databases, especially long-running historical IRC instances, should review existing character-set behavior before changing it.

Credentials

Do not expose passwords in a public channel.

Registration and login should be performed in a private message to the bot.

Root access

Mediabot must not run as root and should not retain passwordless sudo after installation.

Official assets

Keep the release files and their checksum files together. A checksum file is useful only when it verifies the exact assets being distributed.

Support, contributions and security reports

Repository

https://github.com/teuk/mediabot_v3

Documentation

Bugs and feature requests

Live IRC support

Network:    EpiKnet
Server:     irc.epiknet.org
Port:       6697
Encryption: SSL/TLS
Channel:    #i/o

Security vulnerabilities

Do not disclose a vulnerability in a public GitHub issue or public IRC channel.

Use the repository security policy and GitHub private vulnerability reporting:

https://github.com/teuk/mediabot_v3/security

License

Mediabot v3 is free software licensed under the GNU General Public License version 3 or later.

SPDX-License-Identifier: GPL-3.0-or-later

See LICENSE.md in the release archive for the complete license text.

Release provenance

Release:       Mediabot 3.3
Git tag:       3.3
Git commit:    129d61362bbdfe9949adec42cdd8b585bdd5b93a
Release date:  2026-07-12
Archive root:  mediabot_v3-3.3/
Archived paths: 824

The release artifacts were created from the annotated Git tag, not from a private runtime snapshot.

The public archives were generated with the project release builder, validated after extraction, and verified again after publication.

Mediabot 3.3 closes the 3.2 development line as a stable, documented and reproducible release. Development after this release continues separately on the 3.4dev line.

Assets 10
Loading