Files

user c5b0430da8 docs: add podman-compose, update all project documentation

- docker-compose.yml for podman-compose deployment
- Makefile: add up/down/logs compose targets
- README: plugin table, container quickstart, make targets
- PROJECT: plugin categories, deployment matrix, design decisions
- ROADMAP: v0.1 done, v0.2 current, v0.3-v1.0 planned
- TASKS: current sprint with priorities
- TODO: full backlog organized by wave
- CHEATSHEET: reorganized by category (OSINT, Red Team, OPSEC)
- INSTALL: container deployment instructions
- DEBUG: container logs, hot-reload, DNS troubleshooting
- USAGE: all 19 commands documented

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-15 01:46:21 +01:00

2.7 KiB

Raw Blame History

Debugging

Verbose Mode

derp --verbose                    # Bare metal
make up                           # Compose (--verbose in compose file)
podman run ... derp --verbose     # Manual container

Shows all IRC traffic:

>>> NICK derp
>>> USER derp 0 * :derp IRC bot
<<< :server 001 derp :Welcome
>>> JOIN #test

Log Levels

Set in config/derp.toml:

[logging]
level = "debug"    # debug, info, warning, error

Or override with --verbose flag (forces debug).

Container Logs

make logs                  # podman-compose
podman logs -f derp        # direct

Common Issues

Connection refused

ERROR derp.irc  connection lost: [Errno 111] Connection refused

Check host and port in config
Verify TLS setting matches port (6697 = TLS, 6667 = plain)
Test connectivity: nc -zv <host> <port>
In container: ensure DNS resolution works (check /etc/resolv.conf)

Nickname in use

The bot appends _ to the nick and retries automatically:

<<< :server 433 * derp :Nickname is already in use
>>> NICK derp_

TLS certificate errors

For self-signed certificates, set tls_verify = false in config:

[server]
tls_verify = false

Plugin load failures

ERROR derp.plugin  failed to load plugin: plugins/broken.py

Check plugin for syntax errors: python -c "import py_compile; py_compile.compile('plugins/broken.py')"
Ensure handlers are async def
Check imports (from derp.plugin import command, event)
In container with mounted plugins: verify mount path and permissions

No response to commands

Verify prefix in config matches what you type
Check that the plugin is loaded: !plugins
Ensure the bot has joined the channel (check logs for JOIN)
Try !ping first to confirm basic connectivity

Hot-reload issues

!reload <plugin> re-reads the file from disk
In container: plugins are mounted read-only, edit on host then !reload
Core plugin cannot be unloaded (but can be reloaded)
Check logs for loaded plugin / unloaded plugin messages

DNS plugin timeouts

The DNS plugin uses raw UDP to the system resolver
In container: resolver is typically 127.0.0.11 (Podman DNS)
Fallback: 8.8.8.8 if no resolver found in /etc/resolv.conf

Testing IRC Connection

# Test raw IRC (without the bot)
openssl s_client -connect irc.libera.chat:6697
# Then type: NICK testbot / USER testbot 0 * :test

Inspecting State

From IRC, use these commands:

!plugins               # List loaded plugins + handler counts
!help <plugin>         # Show plugin description + commands
!uptime                # Bot uptime
!version               # Running version

2.7 KiB Raw Blame History