Greetings and Salutations Hiveans! 👋
Over the last few days we've shipped the biggest batch of changes the 3Speak encoder has had in a while: 20 updates covering installation, the dashboard, uploads and reliability. If you run an encoder for the community, this post is for you. There's a short "How to upgrade" section at the end.
🚀 Installing is now one line
New operators can get going with a single command:
Linux / Mac
curl -fsSL https://raw.githubusercontent.com/Mantequilla-Soft/3speakencoder/main/install.sh | bash
Windows (PowerShell)
iwr -useb https://raw.githubusercontent.com/Mantequilla-Soft/3speakencoder/main/install.ps1 | iex
The installer works out what's missing and installs it: Git, Node.js, FFmpeg and IPFS. Then it downloads the encoder, sets it up from a few questions and checks that everything works before it finishes. Every change is tested by installing on fresh Windows, Mac and Linux machines (Ubuntu, Debian, Fedora and Arch).
What got fixed along the way:
- Windows: "FFmpeg not found" is gone. The old installer needed an administrator window. Without one it failed quietly and still said everything was fine. It now uses winget, which comes with Windows 10 and 11 and needs no admin rights. It checks that FFmpeg actually runs and saves its location, so the encoder always finds it.
- Mac: works out of the box on Apple Silicon Macs.
- Linux: Fedora and Arch are supported, and older systems like Ubuntu 22.04 get a recent Node.js automatically.
- Start automatically (optional): the installer can make IPFS and the encoder start whenever the computer boots (Linux) or you log in (Mac, Windows). No more forgetting to restart your node after a reboot.
- New
npm run doctorcommand: checks Node.js, FFmpeg and IPFS and tells you in plain words what's missing. If something's off, run this first.
⚠️ Important for people who installed a while ago: an old installer option ("Gateway mode") set up encoders that never received any jobs. If your encoder has sat idle for a long time, that may be why. The encoder now warns at startup with No job source enabled. The fix is three lines in your .env:
EMBED_SYSTEM_ENABLED=true
EMBED_SYSTEM_MODE=community
EMBED_GATEWAY_URL=https://embed.3speak.tv
🖥️ A brand new dashboard
The local dashboard at http://localhost:3001 got a full redesign, inspired by the tiling-desktop look of Tokyo Night colours theme.
- Easier to read at a glance: the current job, encoder health, recent jobs, anything that needs your attention, and the live log.
- Accurate status: the dashboard used to show "Offline" while the encoder was busy and perfectly fine. It now tells apart Encoding, Not responding (frozen), Unreachable (stopped, or the port is blocked) and Offline (shutting down).
- Health numbers: how responsive the encoder process is, and how long it's been up.
- Install it as an app: on your phone or computer, the dashboard can be installed like an app with its own icon. Use Install app in the top bar in Chrome, Edge or Android, or Add to Home Screen in Safari. This needs the dashboard on HTTPS, so it's for operators who reach their node through a domain name.
- Optional password and safer defaults: you can now set a dashboard password, or limit the dashboard to your own machine. It also blocks a class of attacks where another website open in your browser tries to control your encoder.
🔄 Updates and versions
- Know when you're behind: the dashboard shows which version you run and how many updates you're missing, with a link to what changed. Check for updates checks right away.
- One-click updates (optional): turn it on with
SELF_UPDATE_ENABLED=trueand anUPDATE_PASSWORD, and you can update from the dashboard. The encoder finishes its current jobs first, updates, and restarts itself. If anything goes wrong, it rolls back to the version that was working. It's off by default, works on git installs (not Docker), and needs the encoder started with the included start script, which the installer's shortcuts use. - No more half-updated nodes: if the encoder can't build after an update (most often because files belong to another user after a
sudocommand), it now stops with a clear message instead of starting on a mix of old and new code. - Your version, visible to 3Speak: encoders now report which version they run and how far behind they are, so we can see at a glance who needs to update and reach out. It's only the version: no personal data, and nothing changes about the jobs you get.
📦 Uploads: simpler and more honest
- Uploads go to 3Speak's hotnodes only. The old upload path to the "supernode" has been removed for good.
- When an upload fails: by default the job is reported as failed, so 3Speak knows and can give it to another encoder. Before, the encoder fell back to the old supernode.
- Optional local backup (
ENABLE_LOCAL_FALLBACK=true): if the upload fails, your node keeps the video on its own IPFS node and keeps trying to move it to a hotnode in the background. The video keeps the same address, so viewers never notice. Only recommended for operators with fast and reliable internet connections. - See where every backed-up video stands: the dashboard's storage section lists each one as waiting to move, moved, removed or deleted, with dates and the video's owner and link. One click checks the video is reachable before you do anything by hand.
🛠️ Under the hood
- FFmpeg 8 support: the encoder failed to start on FFmpeg 8 and newer (
Input format lavfi is not available). Fixed. - Docker: the production Docker image and compose file wouldn't build or run. Both are fixed; the compose file runs the encoder together with its own IPFS node.
- Steadier startup: the encoder waits up to 90 seconds for IPFS instead of giving up at once, which matters when both start together at boot.
- Automatic tests: every change now runs through automatic tests on Linux and Windows, plus the full install on Windows, Mac and several Linux distributions.
- Documentation: the README and install guides have been rewritten to match how things work today.
✅ How to upgrade
Requirement: Node.js 20 or newer. Check with node -v. If you have 18 or older, update Node.js first from https://nodejs.org (the LTS version), or let the installer do it.
Option A: you installed with git (most operators)
In your encoder folder (usually ~/3speak-encoder, or C:\Users\<you>\3speak-encoder on Windows):
git pull
npm ci
npm run doctor
Then restart the encoder the way you normally start it. Your settings and your encoder identity stay as they are.
Option B: run the installer again
Run the one-line command from the top of this post. It keeps your encoder identity and saves your old settings as .env.bak. If you had changed extra settings (a dashboard password, local backup, and so on), copy them back from .env.bak into .env.
Option C: Docker
git pull
GIT_COMMIT=$(git rev-parse HEAD) docker compose -f docker-compose.production.yml up -d --build
Good to know after upgrading:
- Opening the dashboard by a name (like
encoder.mydomain.cominstead of an IP address)? Add that name to.envasDASHBOARD_ALLOWED_HOSTS=encoder.mydomain.comand restart. Otherwise the dashboard answers "Host not allowed". This is part of the new protection against malicious websites. - Don't use
sudoforgit pull,npmor starting the encoder. It leaves files the encoder can't update later. If you did in the past, fix it once on Linux or Mac withsudo chown -R $(whoami): .in the encoder folder. - Something not working? Run
npm run doctorfirst. It points at the problem in plain words.
Thanks to everyone running an encoder: you're the ones keeping 3Speak videos flowing. 🙌 If you hit a problem, open an issue on GitHub or find us on Discord.
— The Mantequilla Soft team