🚀 Deploying the agent
How to set up a local agent for the first time: where to install it, how to create it in BolloPrint and how to start it on your computer. If you already have it running and BolloPrint tells you there's a new version, what you're looking for is Updating the agent.
Where to put it
On any computer in the workshop that's always switched on and on the same network as the printers:
- a NAS (Synology, QNAP…),
- a mini-PC or a workshop PC,
- a Raspberry Pi,
- a server you already have.
It needs Docker (or Portainer, which is Docker with a screen). It uses very little: between 10 and 20 MB of memory.
💡 Ideally it should be on the SAME network as the printers
If the agent is on one network and the printers on another (separate VLANs, a guest network, a separate wifi), it isn't that it stops working: what you lose is automatic discovery, because that "I'm here" announcement doesn't cross from one network to another.
The printers are then added by hand, by their IP, and they work just the same — with all their features, whatever the brand. The only essential thing is that the two networks can talk to each other (that the router or the firewall lets traffic pass between them).
On Docker Desktop (Windows and Mac) there's no automatic discovery. Those systems don't let the container see the computer's network, so printers have to be added by hand, by IP. Same as with separate networks: they work exactly the same, there's just one extra step when registering them.
Creating it in BolloPrint
- Go to Settings → Printers and open the Local agent tab.
- Click New agent and give it a name you'll recognize. Better where it is than what it is: "Ground floor", "Unit 2".
- Click Create agent.
- The second step shows the deployment manifest, with the agent's code and its identity already written in. Choose Docker Compose or Kubernetes and click Copy. There's nothing to replace.
🔐 The keys are shown only once
Copy the manifest right then. The keys don't expire, but we won't show them again. If you lose it, open the agent with Edit and, under Deployment, use Regenerate keys.
Always copy the block from the screen, not from an old email or a note: it carries the version of the agent that's current at that moment.
Starting it on your computer
Pick whichever method you use. In all three, the manifest goes in as is, without changing anything.
Docker Compose
- Create a folder for the agent, for example
bolloprint-agent. - Inside it, save the manifest as
docker-compose.yml. - From that folder, start it:
docker compose up -d
Portainer
- Go to Stacks → Add stack and give it a name, for example
bolloprint-agent. - In Web editor, paste the Docker Compose manifest as is.
- Click Deploy the stack.
Kubernetes
- Save the Kubernetes manifest to a file, for example
bolloprint-agent.yaml. - Apply it:
kubectl apply -f bolloprint-agent.yaml
Then go back to BolloPrint and click Save in the agent's window.
Checking it works
In under a minute, the agent shows up as Online in the Local agent tab. It won't ask you for authorization: that installation comes already authorized.
If it doesn't show up, look at its log on the computer it runs on:
docker logs bolloprint_agent --tail 50
| What's happening | What to check |
|---|---|
| It never shows up | Was the whole manifest pasted, unchanged? Can the computer reach the internet? Is a firewall blocking outbound traffic? |
| It shows up, but asks for authorization | The manifest doesn't include BP_AGENT_INSTANCE_ID (it was edited by hand or is an older one). Regenerate the keys and deploy the new manifest as is. |
| It's online but doesn't find any printers | If it's on a different network from the printers, or you're using Docker Desktop, that's expected: add them with Add by IP. |
There's no need to open ports on the router, request a fixed IP, or touch the firewall: the agent calls BolloPrint, not the other way round.
With the agent online, the next step is connecting your printers: you'll find it in Local network printers.