Mediabot v3

A database-backed, operations-oriented IRC bot for long-running communities.

Mediabot 3.3 helps IRC communities run, remember, and understand their channels. It combines channel administration, persistent community history, analytics, modern URL and media integrations, observability, and upgrade tooling in one tested application.

Instead of assembling a large collection of unrelated scripts, operators get a coherent stack with one configuration model, one MariaDB-backed data model, migrations, security checks, startup integrity validation, systemd deployment guidance, and a documented release process.

Download Mediabot 3.3 · Install in production · Explore commands · Ask a question

Why Mediabot?

What you need	What Mediabot provides
Community memory	`seen`, `onthisday`, quotes, factoids, karma, notes, reminders, milestones, and long-term channel history
Operational safety	guided configuration, database migrations, schema/type/index drift checks, security audit, and startup integrity checks
Modern IRC features	rich URL previews, media helpers, AI integrations, radio tooling, antiflood protection, and community analytics
Observability	Prometheus metrics, Grafana resources, structured logs, and systemd-oriented operations
Extensibility	Perl modules, plugins, controlled script bridges, and public `contrib/` and `plugins/` trees

Mediabot is a strong fit for communities that want a bot to become part of their long-term infrastructure rather than remain a small disposable script. If you only need a tiny classic IRC bot with minimal dependencies, a lighter platform may be the better choice.

See what it can do

A typical channel can use commands such as:

<prefix>seen Alice
<prefix>mood
<prefix>onthisday
<prefix>topquote
<prefix>milestone
?coffee
<prefix>tell Bob remember the meeting

It can also enrich supported links, expose Prometheus metrics, integrate with radio workflows, and provide a dedicated TCP/DCC administration interface through Partyline.

The configured prefix is instance-specific and may be !, m, ., or another value chosen by the operator.

Start here

Goal	Recommended path
Install the stable release	Download Mediabot 3.3, verify the checksums, then follow the Installation guide
Understand the feature set	Browse Public commands, Private/admin commands, and Partyline
Upgrade an existing instance	Read the Release and upgrade notes before applying migrations
Operate and monitor it	See Configuration, Testing, and Monitoring
Report or discuss something	Use Issues for reproducible work and Discussions for questions and ideas

The wiki is the operational reference. This README keeps the essential installation and validation path available in the repository.

Release status

Mediabot uses odd minor versions for stable releases and even minor versions for development lines:

3.3      current stable release
3.4dev   next development line

Release resources:

Community

Contributions of all sizes are welcome: code, tests, documentation, plugins, translations, installation feedback, and validation on additional IRC networks.

Report a bug · Request a feature · Ask a question · Open the wiki

Live IRC support:

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

Quick install on Debian

The full install guide is here:

Installation

This section is only the essential path.

1. Install bootstrap packages

As root:

apt update
apt install -y \
  sudo \
  git \
  curl \
  wget \
  jq \
  unzip \
  zip \
  ca-certificates \
  perl \
  build-essential \
  make \
  gcc \
  pkg-config \
  mariadb-server \
  mariadb-client \
  libmariadb-dev

systemctl enable --now mariadb

libmariadb-dev provides the MariaDB Connector/C headers and mariadb_config needed to compile the CPAN driver. It is a native build dependency, not a Perl module package.

Do not install libdbi-perl, libdbd-mariadb-perl or libdbd-mysql-perl for the supported installation path. ./configure installs and verifies DBI, DBD::MariaDB and the remaining Perl modules through CPAN.

Optional but useful:

apt install -y screen tmux htop lsof net-tools iproute2 dnsutils rsync chromium

2. Create the dedicated user

Mediabot must not run as root.

adduser mediabot
su - mediabot

Expected:

whoami
pwd

mediabot
/home/mediabot

3. Get Mediabot

For the development tree:

cd /home/mediabot || exit 1
git clone https://github.com/teuk/mediabot_v3.git
cd /home/mediabot/mediabot_v3 || exit 1

For the stable 3.3 release, use one of the published source archives:

mediabot_v3-3.3.tar.gz
mediabot_v3-3.3.tar.xz

Verify the download against mediabot_v3-3.3-SHA256SUMS or mediabot_v3-3.3-SHA512SUMS before extracting it. The GitHub release uses the plain 3.3 tag, matching the established project tag convention. See docs/RELEASING.md for the complete artifact and verification workflow.

4. Run `./configure`

./configure is the supported fresh-install entry point.

Do not replace it with a manual cp mediabot.sample.conf mediabot.conf workflow.

cd /home/mediabot/mediabot_v3 || exit 1
./configure

mediabot.sample.conf is a reference file. The installer now generates a complete mediabot.conf directly from it, including all active safe defaults. It never enables Partyline eval.

On a fresh installation it creates the database, installs dependencies, configures IRC/network data and validates schema drift.

On an existing installation it creates a timestamped backup, preserves current and custom values, adds missing defaults, normalizes duplicate INI keys and offers the database drift/migration workflow without automatically applying generated SQL.

Useful maintenance modes:

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

See docs/CONFIGURE.md for the complete fresh/existing workflow and safety rules.

5. Review `mediabot.conf`

After configure:

chmod 600 mediabot.conf
vi mediabot.conf

Review at least:

[main]
[mysql]
[connection]
[undernet] or [libera]
[metrics]
[antiflood]
[openai]
[anthropic]
[chromium]
[radio]

Never commit the real mediabot.conf.

Database validation

Fresh installs use the current reference schema through the installer. Validate the newly created database with strict type checking:

cd /home/mediabot/mediabot_v3 || exit 1

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

For an existing instance, first generate a reviewable migration plan against the configuration that actually points to the target database:

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

For example, on the Undernet instance:

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

Review the output, back up the database, and apply only the required ordered migrations from install/migrations/README.md. With --indexes, the drift checker also compares every index required by install/mediabot.sql and can generate non-destructive ADD INDEX statements for missing non-primary indexes. Extra live-only indexes are intentionally ignored. Keep the explicit index checks in the release checklist as an independent verification step.

After the migration work, run:

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

Do not blindly apply historical migrations to a fresh install.

See:

Syntax checks

From the project root:

cd /home/mediabot/mediabot_v3 || exit 1

perl -c mediabot.pl
find Mediabot -name '*.pm' -print -exec perl -I. -c {} \;
perl -c tools/check_schema_drift.pl
perl -c t/test_commands.pl
perl -c t/test_live.pl

All files should report syntax OK.

Tests

Run the full static suite:

perl t/test_commands.pl --verbose

Profile the suite without changing its execution order:

perl t/test_commands.pl --profile

By default the 20 slowest test files are reported. Choose another limit with:

perl t/test_commands.pl --profile-top 30

Profiling is observational only: it does not parallelise, reorder or skip test files. Use the measured timings to guide test classification before considering parallel execution.

Run live tests when a local IRC test server is available:

perl t/test_live.pl --server localhost --channel '#testchan' --verbose

If t/full_test.sh is present, use it for a full validation with logs:

./t/full_test.sh -d /tmp/mediabot_tests

Expected final result:

===== Final verdict =====
OK: static tests passed
OK: live tests passed
OK: logs written successfully

See:

Testing

First start

Start in foreground first:

cd /home/mediabot/mediabot_v3 || exit 1

perl mediabot.pl --conf=mediabot.conf

For production, use the systemd template unit (recommended):

sudo systemctl start mediabot@<instance>

See tools/systemd/README.md for the systemd setup.

Do not switch to systemd until foreground startup is clean.

Watch for:

missing Perl modules;
database errors;
IRC connection errors;
charset warnings;
missing config keys.

First registration and login

When the bot is connected to IRC, register and login by private message to the bot.

Example with a bot named mediabot:

/msg mediabot register <user> <password>
/msg mediabot login <user> <password>

Then verify with the configured command prefix:

<prefix>whoami

Examples:

m whoami
!whoami
.whoami

Do not use the public channel for the password.

Partyline

Partyline is the Mediabot admin interface.

Connect locally with telnet:

telnet localhost 23456

Partyline can also be reached through DCC CHAT or CTCP CHAT depending on your IRC client and bot configuration.

A local TCP Partyline session prompts interactively:

Mediabot Partyline

Please enter your nickname.
<user>

Enter your password.

Connected to Mediabot Partyline.

Once authenticated, Partyline commands start with a dot:

.help
.stat
.console 3
.floodstatus
.netsplit
.quit

See:

Partyline

Configuration notes

The generated mediabot.conf is local runtime configuration.

Important rules:

do not commit mediabot.conf;
do not commit real API keys;
do not commit real database passwords;
do not commit IRC passwords;
keep PARTYLINE_STATUS_JSON unique per bot instance;
keep METRICS_PORT unique when multiple bots run on the same host;
review CHARSET_MODE carefully on legacy databases.

For fresh installs, CHARSET_MODE=utf8mb4 is recommended.

For old production databases, especially historical IRC instances, review charset behavior before changing it.

See:

Configuration

Metrics

If metrics are enabled:

[metrics]
METRICS_ENABLED=1
METRICS_BIND=127.0.0.1
METRICS_PORT=9108

Validate:

curl -s http://127.0.0.1:9108/metrics | head

Use one metrics port per bot instance.

Security notes

Do not run Mediabot as root.

Do not leave temporary passwordless sudo on the mediabot user after installation.

If you granted temporary sudo access for installation, remove it before normal IRC use:

sudo rm -f /etc/sudoers.d/mediabot
sudo -k

Then verify:

sudo -n true && echo "ERROR: sudo still active" || echo "OK: no passwordless sudo"

A bot connected to IRC must not have passwordless root access.

Recent versions also avoid logging some runtime secrets such as DCC passive tokens and channel JOIN keys.

For security vulnerabilities, do not open a public Issue or disclose the problem in a public IRC channel.

Use GitHub's private vulnerability reporting feature and read:

Security policy

Troubleshooting

Start with:

cd /home/mediabot/mediabot_v3 || exit 1

perl -c mediabot.pl
find Mediabot -name '*.pm' -print -exec perl -I. -c {} \;
perl tools/check_schema_drift.pl --conf=mediabot.conf --strict
./t/full_test.sh -d /tmp/mediabot_tests

Then check:

tail -n 100 mediabot.log

or instance-specific log paths.

Common issues are documented here:

Troubleshooting

Useful links

Documentation

Community

Live IRC support

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

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 for the complete GNU GPL version 3 license text.

Name		Name	Last commit message	Last commit date
Latest commit History 828 Commits
.github		.github
Mediabot		Mediabot
bin		bin
contrib		contrib
docs		docs
install		install
node_modules		node_modules
plugins/scripts		plugins/scripts
t		t
tools		tools
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.md		LICENSE.md
README.md		README.md
SUPPORT.md		SUPPORT.md
VERSION		VERSION
configure		configure
cpanfile		cpanfile
mb_restart.sh		mb_restart.sh
mediabot.pl		mediabot.pl
mediabot.sample.conf		mediabot.sample.conf

Navigation Menu

Repository files navigation

Mediabot v3

Why Mediabot?

See what it can do

Start here

Release status

Community

Quick install on Debian

1. Install bootstrap packages

2. Create the dedicated user

3. Get Mediabot

4. Run `./configure`

5. Review `mediabot.conf`

Database validation

Syntax checks

Tests

First start

First registration and login

Partyline

Configuration notes

Metrics

Security notes

Troubleshooting

Useful links

Documentation

Community

Live IRC support

License

About

Releases

Packages

Used by

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Mediabot v3

Why Mediabot?

See what it can do

Start here

Release status

Community

Quick install on Debian

1. Install bootstrap packages

2. Create the dedicated user

3. Get Mediabot

4. Run ./configure

5. Review mediabot.conf

Database validation

Syntax checks

Tests

First start

First registration and login

Partyline

Configuration notes

Metrics

Security notes

Troubleshooting

Useful links

Documentation

Community

Live IRC support

License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

4. Run `./configure`

5. Review `mediabot.conf`