Troubleshooting Pierrr Agent

Agent stays "offline" in the dashboard

Check the logs: journalctl -u pierrr-agent -f. The most common cause is an outbound firewall blocking port 443: check the machine can reach agents.pierrr.com, or api.pierrr.com for a server connected before Pierrr version 0.0.49-beta. In the console, the Offline status comes with the last contact on the card. A Pending status means the enrollment token has not been used yet: run the install command again.

Heartbeats but no apps deploy

The agent needs Docker . Check with docker info that the account running the agent can reach the daemon; if it fails, fix its permissions and restart the unit.

Invalid or lost enrollment token

The token is shown only once and works only once. If it is lost or refused, revoke the entry in Servers, then use "Connect a server" to generate a new one and run the command again.

Disk fills up over time

After every successful build the agent keeps the last two builds of each application and removes orphan layers, without touching other applications' images. If the disk stays full, free some space or raise the reserve. Avoid global Docker cleanup commands: they can delete volumes, and so your data.

No network traffic measured

A project's Topology tab states that no traffic is measured until the server's agent is on version 0.53.0-beta or newer. Update the agent from the server page.

The agent update is refused

The button is greyed out and the reason shows on hover: the agent must be online, and your role must allow the update (owner or admin). If the binary check fails, the operation is abandoned and the previous version stays in place.

A build is refused for lack of disk space

With a ceiling in place, a build that would take the disk below the reserve is refused, with the remaining space shown. Free some space or lower the reserve.

A deployment was interrupted during maintenance

A deployment interrupted by platform maintenance restarts on its own. Check its state in the project history before launching another.

Commands are refused because of the server's clock

The server's clock is more than ten minutes away from the real time, and the agent refuses the commands it receives. Check that time synchronisation is on (timedatectl status), fix it, then run the operation again.

A command is refused by the server's policy

The /etc/pierrr-agent/policy.yaml file forbids this command, or it cannot be read and then counts as read-only. The command log, in the Journal tab of the server's page, gives the reason. Fix the file on the machine: the change applies from the next command. See Agent security.

Ports 80 or 443 are already in use

Another program, often a web server already installed, holds port 80 or 443 on the server: the agent cannot serve your domains there, and it names the ports involved in the Journal tab of the server page. Find that program with sudo ss -ltnp '( sport = :80 or sport = :443 )', stop it or move it to another port, then run the deployment again.

A project asks for an agent update

The database of a project on your server is created by the agent, which must be version 0.64.0-beta or later. While it is older, the console says so on the project, with a button to the server page: update the agent, then run the operation again.