Servers

What is a server?

A server is a Linux machine you own, running Pierrr Agent, a small program that talks to your hub over HTTPS. Every enrolled server shows up as a card on the Servers page; it is the machine that runs the containers of the projects you deploy onto it.

A server of your own is in no way required: by default a project is deployed on Pierrr's own infrastructure. You only go through an agent if you want your containers to run on your own machine, which the project calls self-hosted mode.

Pierrr Agent licences

Each server consumes one Pierrr Agent licence seat, an add-on billed per server and independent of your main plan. A counter permanently shows how many seats are in use out of those you hold, and the page offers to subscribe one more unit when the quota is reached.

The "I have a code" button redeems a Pierrr Agent voucher handed out by the Pierrr team: it creates a server in the organization without consuming a seat.

Enrolling a new server

Connect a server mints a single-use enrollment token and the install command to paste on the target machine. You can name the server on the way; its real hostname is picked up on the agent's first connection. The token is shown only once: if it is lost, revoke the entry and mint another. The install detail lives on the Install Pierrr Agent page; the machine appears in the list around thirty seconds after a successful install.

Finish setting up a server

Until a freshly enrolled server is finalised, an assistant replaces its overview. It takes stock of the machine and lets you prepare it before you create your first project on it. It needs agent 0.77.0-beta or later; servers that are already set up do not go through it.

The shared database is the only blocking step: "Provision" prepares it on the server, with one instance per server and one isolated database per self-hosted project. Until it is ready, the "Finish setup" button stays disabled and says why.

The other checks are informational and never block finalising:

• Ports 80 and 443: free, or, if another program holds them, listed by number, since your domains will not work while they stay busy.
• Edge and certificates: whether public access for your projects and their certificates are set up on the agent.
• Disk space: free space out of the total, with a gauge that turns amber above 90% used.
• Detected public IP: the address the server is reached at from the Internet, the one your domains will need to point to.
• Security tools: installed on the server, or, failing that, scans run in a container, a little slower.

"Refresh" reads the server's state again after a fix. If the agent is offline or too old to answer, the assistant says so and picks up at its next connection. Once "Finish setup" is confirmed, the server's usual overview, with its tabs, takes the assistant's place.

Reset a server

In the Settings tab, "Reset server" brings the assistant back on the next visit to the page. The dialog has you choose between keeping the database and deleting it too, then asks you to type the server name to confirm. Resetting is refused while a self-hosted project still uses this server's local database.

The server list

The Servers page shows each agent as a card: icon, name (which opens the detail), hostname, status indicator, agent version with its badge, last contact and enrollment date. Tabs filter the list: all, online, offline, revoked and deleted.

Every card keeps actions visible to everyone: install instructions, agent update, a "More actions" menu (Rename, Revoke, Delete) and "Open". An action your role does not allow stays displayed, greyed out, with the reason on hover. The same goes for "I have a code" and "Connect a server".

Server states

An agent's status reflects its connectivity to the hub:

• Pending, the agent was created but has not registered yet: the enrollment token has not been used.
• Online, the agent is sending its presence signals; it can receive deployments.
• Offline, no recent signal (network down, machine off, agent stopped). Surfaced as a point of attention on the dashboard.
• Revoked, the agent's access has been cut; it can no longer connect and no longer sends metrics.
• Deleted, the entry has been removed from the active list; the agent is disconnected and can never reconnect.

Server detail

Opening a server shows its header, then tabs, as on a project page. The open tab is written into the page address: a link or a reload lands back on it.

• The header, with the back button to Servers, the name, the copyable hostname, the status, the "Update the agent" button and the "More actions" menu (Rename, Revoke, Delete). Renaming does not touch the machine's real hostname.
• Overview: the Machine card, with the agent's identity (host, system, architecture, version, enrollment date, last contact) and, on the right, three CPU, Memory and Disk gauges (amber above 75%, red above 90%), the age of the last reading and the number of containers, all healthy or in alert. Until a reading arrives, the gauges stay empty and a message says so. After a reinstall on the same machine, the notice to take the projects over shows at the top of this tab.
• Still in the overview, the Trends: three CPU, Memory and Disk charts over the last five minutes, with the current value, the average, the peak and the 75% and 90% thresholds.
• Then the Per-container detail, a collapsible card with each container's consumption over time and its share of the current total.
• At the bottom of the overview, the Linked projects, one card per project deployed on this server, with its health, containers and deployments. With no project, an empty state says so.
• Containers: a paginated table with a search field: application and replica, project, state, start time, CPU and memory. Containers in alert come first.
• Backups and Database, on a server of your own: the backup encryption key and the off-site copy on one side, your projects' database engine and its version upgrade on the other, described below.
• Settings: the "Live readings" switch, the server key, "Summary-only scans", "Updates by the Pierrr team" and, when a change is offered, the address the server reaches Pierrr by. A setting your role cannot change stays displayed, greyed out, with the reason on hover.
• Journal: the commands sent to the server, with their origin, state and duration.

When the agent has not been seen recently, the last recorded window stays displayed and readings resume on the next presence signal. For a revoked agent, the page states it no longer sends metrics and keeps only the overview and the journal.

Per-container network traffic (data received and sent) needs an up-to-date agent: it appears in a project's Topology tab, described on the Projects page. A server whose agent is not updated yet keeps working, but the tab states that no traffic is measured.

Updating the agent

The agent never updates itself. A version badge reads "Up to date" or "Update available"; the "Update the agent" button, in the page header and on the card, starts the update. It is greyed out, with the reason, if your role does not allow it (ask an owner or an admin) or if the agent is offline: it must be online to accept it.

A progress bar follows the four stages: download, verification, install and restart. The binary is verified before being installed, and the previous one is kept so a failed start can be rolled back.

What the agent does on your machine

Once connected, the agent builds and runs your containers, takes your projects' backups, kept on this server, and removes expired archives. After every successful build it keeps only the last two builds of an application, without touching the others. Your containers' secrets are not written in clear in their configuration. You can cap the resources it uses, see the install page. What stays on the server and what goes through Pierrr is detailed in the agent FAQ.

To serve your domains, the agent needs the machine's ports 80 and 443, free and open to your visitors. If another program holds them, it names the ports involved instead of failing without explanation.

Your projects' data

The agent creates on the server the database of each project hosted there, and it stays there: Pierrr does not host a database for these projects, and only keeps, encrypted, what it needs to connect it to your apps. These databases do not count towards your storage quota. The cache and volumes of a project on your server are included, with nothing to buy: add them from the project.

Your apps' logs are read on the server, from the agent, when you open a project's Logs tab: they are never stored at Pierrr.

The applications of a project on your server send their transactional emails through Pierrr as on our hosting: the agent installs a small relay that only listens on your projects' networks, with no port opened to the internet, and forwards each message over its encrypted connection.

When a build runs, the agent reads your application's configuration files (Dockerfile, package manifest, variables template) in its own copy of the repository and runs the pre-build checks there: Pierrr only receives the outcome, never the content. Built images stay on the server, unless you choose, in the project's Deployments tab, to publish them to your organization's registry.

The database panel and import go through the agent: an import is checked then restored on the server, with the project's rights, and the panel opens from the console without any port opened on the machine. The panel's pages go through Pierrr without being kept, and the database credentials stay on the server (agent 0.71.0-beta or later, the console tells you otherwise). Security scans, of containers and code, run on your server: your apps' image never leaves it, and only the report comes back to Pierrr, with no excerpt of your code (agent 0.66.0-beta or later, the console tells you otherwise). WordPress sites do run on your server: pick it when you create the site, and the agent creates its database on the machine.

A major version upgrade of the database is never automatic: start it from the Database tab of the server page, after a confirmation. Every database is copied to the new version and every table counted again before the switch; at the slightest failure, the previous version is put back in service. The databases are unreachable while it runs, it needs at least twice the size of the data in free space, and the data of the old version stays on the server.

Encrypting backups for your key

In the Backups tab of a server's page, the "Backup encryption key" card takes your public encryption key. Once it is saved, every backup that leaves the server, downloaded from the console or copied off site, is encrypted for it on the server: Pierrr no longer sees their content, and only your private key opens them. The console shows the key's fingerprint and when it was added; a private key pasted by mistake is refused and never stored. Removing the key brings back unencrypted downloads and stops the off-site copy.

The archive kept on the server stays readable by the agent: restoring from the console works as before. A downloaded archive arrives encrypted, to open with your private key. In a project's Backups tab, each backup carries the "Encrypted for your key" and "Off-site copy" badges, or the reason a copy did not happen. It takes agent 0.67.0-beta or later.

The off-site copy relies on a destination set on the server with sudo pierrr-agent backups set-remote: a directory of the machine (a mounted disk or share) or object storage. The "Off-site destination" card below prepares that command for you. Its credentials stay on the server. The console card shows whether a destination is set, as the server reports it, and two settings can be changed there without touching the key: pause the off-site copy, and refuse any download that could not be encrypted for your key (agent 0.68.0-beta or later). See the agent FAQ.

In the Backups tab, the "Off-site destination" card guides you without leaving the console. Choose "S3 storage" (a bucket, then, if needed, a folder, the storage address and a region, and the access key ID) or "Local folder" (the absolute path of a disk or a mounted share). The card prepares the command to paste in a terminal on the server: access keys never go through Pierrr, and the secret key of an S3 storage is typed on the server when the command runs. Reload the page afterwards to see the up-to-date state. Once a destination is in place, the card also offers the command to remove it; copies already made stay where they are.

Reinstalling the agent on the same machine

Uninstalling the agent keeps the projects, their backups and their databases on the machine. After a new install, the new server's overview shows a "Same machine as" notice naming the old one: the Take over the projects button attaches the old agent's projects to this server, finds their databases and files again, then brings each project back up. The old agent must be offline (uninstalled or revoked) and the new one online; without the role that allows managing servers, the button is greyed out with the reason.

A database missing from the machine is reported, project by project, and never recreated empty: restore a backup. A project that fails to come back up is redeployed from its page.

Updates to your server's system

From the agent, Pierrr reads your server's system version, when its support ends, how many updates are waiting (security ones included) and whether a restart is needed. Reading changes nothing. It shows in the "System updates" card of the server's page.

When an update deserves your attention, Pierrr can propose it: install the pending updates, or move to the next version of the system. You get a notification, and the proposal appears in the card. Nothing is installed until you accept it, and only the organization's owner and maintainers can answer. A proposal left unanswered lapses after 30 days.

Once accepted, the update runs on your server and keeps going even if the link with the console drops; progress shows in the card, and so do the details of a failure. The agent never restarts your server: the restart that may be needed, flagged in the card, happens when it suits you. A version upgrade restarts services on the server, containers included, and can take a long time: pick the moment.

What Pierrr sees of your server

The agent creates its own encryption key on the server. Your projects' variables, and your registry token when your images are published there, reach it encrypted for this key, and the agent puts them back in place: they no longer travel readable up to the server. The key's id is shown in the Settings tab of the server page, under "Server key"; pierrr-agent status shows the same one on the machine.

The "Summary-only scans" setting, in the Settings tab of the server page and off by default, cuts what security scans report down to each finding's identifier and severity: no file path, no package, no message. The server's owner can also enforce it from the agent's local policy.

Revoking or deleting a server

Both actions live in the server's "More actions" menu, and each is confirmed by typing the hostname:

• Revoke immediately cuts the agent's credentials and closes its session. The machine has to be enrolled again to come back. Its projects stay attached to this server, with their data: they no longer deploy until an agent reinstalled on the same machine takes them over.
• Delete removes the entry from the active list and disconnects the agent for good, with no way back from the console. As with a revocation, its projects stay attached to this server, with their data.