BånderPart I — Operator's Guide
Use this manual to understand, install and maintain a Baander instance. Start with the reading path for a new installation, or choose a task, symptom or component below when returning to an existing one.
Installed-instance commands use the dc function defined in
Getting Started, on the installation host from its checkout.
Worker-controller commands run separately on the trusted host. Repository Make
targets select development instances; see
Which installation a command targets
before carrying a command between environments.
Reading path
- Understand the instance. Understanding Baander introduces the components and the journey from files to playback. Storage and Data identifies the stores, their writers and what must be preserved.
- Set it up. Follow Getting Started, then use Configuration for settings and Background Work for the separate worker deployment and its operating limits.
- Run it day to day. Use Library Management, User Management, External APIs, Transcoding, Notifications and Watch Parties for the work your instance supports.
- Observe and diagnose. Monitoring explains health, job and transport evidence. Troubleshooting starts from symptoms and connects them to the responsible stage.
- Maintain and recover. Read Backup and Recovery before Upgrading or a recovery action. Security covers credential changes and account/session effects. The optional Registry has separate storage and recovery requirements.
Tasks
| I need to… | Start here |
|---|---|
| Install an instance and scan its first library | Getting Started |
| Change an environment variable or server setting | Configuration |
| Add media, scan again or inspect file-watcher limits | Library Management |
| Add users or change access, passkeys and OAuth clients | User Management |
| Configure metadata, artwork or lyrics enrichment | External APIs |
| Understand original playback or converted audio/video | Transcoding |
| Configure email, push or webhooks | Notifications |
| Use synchronized playback through the supported API | Watch Parties |
| Inspect, replace or recover background workers | Background Work |
| Preserve data or assess a restore | Backup and Recovery |
| Update code and schema | Upgrading |
| Rotate secrets or respond to exposed credentials | Security |
| Operate the separate registry | Registry |
Symptoms
| What I see | Start here |
|---|---|
| Web responds, but queued work does not progress | Observe background work, then Job Monitoring |
| Media has not appeared after a scan | Media not appearing after scan |
| Conversion fails or playback cannot obtain output | Transcoding failures |
| A job failed, or I need its retry/cancellation evidence | Retry and cancel and Failed messages |
| Redis, database, permissions or login checks fail | Common Issues |
| Email, push or webhooks do not arrive | Notifications |
| A worker operation has an uncertain outcome | Stop, replace or recover workers |
| Registry lookup or readiness fails | Registry readiness and failures |
Components and reference
| Component or detail | Explanation and operating reference |
|---|---|
| Web, proxy and real-time connections | The components, Monitoring |
| Control/execution pair, queues, scheduler and outbox | Background Work |
| PostgreSQL, Redis, source media and generated output | Storage and Data |
| Native encoding and delivery files | Transcoding |
| Optional registration/discovery service | Registry |
| Command arguments, options and outcomes | CLI Reference |