Documentation · Reference

Concepts

Terms used in the console and guides, and what they mean in Pyrite.

01 /How a request travels

When someone opens an app that requires sign-in, the request passes through these stages.

BrowserThe person opens the app from the portal.http://SERVER:8101/
GatewayThe engine checks the session and the person’s access to the app.public port 8101
App instanceThe app’s PocketBase instance applies its rules.internal port 9101, accessible only from the server
App dataDatabase and uploaded files.apps\<id>\state\pb_data

Static apps take a shorter route. The engine serves pages directly from the app’s release\public folder. No instance or database is needed.

02 /Engine and apps

Engine: The pyrite.exe program running in its normal mode. It maintains the app registry, directory, access grants, metrics and events. It starts and monitors apps and serves the portal and console, usually on port 8080. Its data lives in control\pb_data.
App: An application hosted by the engine. On disk it is a folder under apps containing the manifest, code and, for apps that store data, a data folder.
Manifest: The app.json file in the app folder. It tells the engine the app’s name, type, port, sign-in requirement, roles and enabled engine tools. Only the administrator may change it, either through an Owner in the console or directly on the server. App scripts have read-only access. See the manifest reference for all fields.
Type: Static, PocketBase, or PocketBase with automations. The type describes what the app contains and whether it needs an instance.
Instance: The PocketBase process running one app with its data. The engine launches its own executable in worker mode. Do not start the worker manually. Each instance listens on an internal port accessible only on the server. Its number is the public port plus 1000, for example 9101 or 9102.
Gateway: The engine listens on each app’s public port and forwards requests to the instance. It controls access and counts requests, errors and traffic independently of the app. When the app is stopped, the gateway serves a page explaining its status.
Portal: The page everyone sees at the engine address. It contains tiles for apps and tools such as “Import preview”. People sign in and out here. Customize its appearance on the console’s “Portal home” page.
Engine console: The administrator area at http://SERVER:8080/console/ (/_/, the PocketBase dashboard address, also redirects there), with its own sign-in page. It contains the engine’s PocketBase dashboard, styled for Pyrite, plus sections for managing apps, people and backups. Only Owners and Admins can enter.
App dashboard: The PocketBase dashboard for a single app, limited to collections and records. Open it from the Data tab on the app’s page in the console. Direct access on the app port is unavailable. In this guide, “console” refers to the engine and “dashboard” to an individual app.

03 /People and permissions

Directory: The engine’s central list of people, including email, password and account status (active or disabled). It applies to all apps.
Group: People who need the same access grants, such as “Members”. A person can belong to multiple groups.
Console access level: A person’s console privileges. There are four levels: Owner (everything), People Admin (the people and groups of their unit), App Admin (their apps) and User (portal and apps only, no console). Whoever was an Admin before stays “Admin (as in 0.7.5)”. An Owner gives the roles on the person’s details page (see The console and the levels). In-app roles are managed separately.
Pending approval: The state of an app uploaded by an Admin with “Upload app”. The app is installed. It starts and appears in the portal only after an Owner approves it.
Access grant: Permission to enter an app, given to a person directly or through a group. One grant by either route is sufficient. The person’s role within the app is managed separately.
Role: A person’s level inside one app, such as manager or storekeeper. The app manifest lists the available roles from highest to lowest privilege. Roles are independent of group membership. An Owner or an Admin who manages the app can change them in “Access and roles”. If the app permits it, the person with the highest role can change them inside the app. Its rules and code define what each role can do.
Base role: The role assigned on first sign-in (defaultRole in the manifest, or the least privileged role when omitted). After that first sign-in, the engine leaves the role as assigned.
In-app account: The user record inside one app instance. The engine creates it the first time the person enters from the portal, using the directory email and name and the app’s base role. The app cannot change the email, name or password. These identity fields are locked.
Single sign-on: Sign in once through the portal and apps open with an authenticated session. The session is tied to the server’s hostname or IP address, so use the same address for both portal and apps. If each app has its own name (Network rules), one sign-in also works across the different names. Signing out of the portal ends the session for all apps.
Technical administrator: An administrator account inside each app, with a random password unknown to people. Only the engine uses this account to manage the app. Direct administrator sign-in on app ports is unavailable.
Engine service account: The engine’s PocketBase superuser, with a random password that is never written down. Only the engine uses it. Administrators sign in to the console with their own directory accounts.

04 /Data and continuity

Backup: An archive of the data from an app with a database. Automatic backups run nightly at 03:00 (computer time) and keep the latest seven. Manual backups are also available. The same nightly run backs up the engine registry.
Restore: Replacing the current data with data from a backup. The engine stops the app, saves a safety copy, replaces the data and restarts the app if it was running.
Safety copy: The copy of the existing data saved before a restore, under apps\<id>\state\copia_prima_del_ripristino_<data>. Remove it manually when it is no longer needed.
Archiving: Taking an app out of service while keeping a verified copy of the entire app in archivio\<id>_<data>. From the console’s Archive page you can restore it in a stopped state with its contents preserved, or delete it permanently.
Engine tool: A Go component built into the engine that app scripts use for heavier tasks. Eight tools are available, covering Excel and CSV import and export, PDFs, photos, numbering, change history, statistics and scheduled jobs. Only Owners can enable tools, separately for each app, in its Configuration tab. See the console’s Tools page for the list.
Recipe: Saved settings for a repeatable import. They specify how to read the file, the destination collection, how columns map to fields and which key identifies existing records.
Metrics: Memory, CPU, database size, requests, errors, writes, successful and denied access attempts, average response time and traffic. The engine collects these for each app every minute and keeps them for 30 days.
Restore point: A copy created automatically when pyrite.exe is replaced, stored in control\aggiornamenti. The engine applies the entire update or none of it. You can roll it back with pyrite.exe update-restore.
Network copy: A daily copy of backups to a network folder (such as a NAS) or another drive, with each file verified using SHA-256. Configure it in Engine settings.
Certificate and HTTPS: When a certificate is installed, the engine and all app ports serve HTTPS. Otherwise they serve HTTP. The certificate can come from the company CA, a .pfx or .pem file, or an internal CA created by Pyrite. Keys are stored in control\certificati.
Outbound network: The addresses an app’s scripts are allowed to call, declared in network in the manifest. The engine blocks disallowed calls or, in “Warn” mode, only counts them.
Profile: Each person’s page for their name, language, theme, password, console layout and “Sign out of all sessions”. The engine links the person to each app’s user record by ID. The link survives an email change.
Scheduled jobs: Tasks that apps or the engine run at set times. The engine registers them and shows the schedule and last result on its Scheduled jobs page. You can also pause jobs or select “Run now”.
Unit: A closed group of people, groups and apps, for example a customer, a work group or a site. With units one engine can serve more customers, and each sees only its own things. At the start there is one unit, called “Tutta l'azienda” (Italian for “the whole company”; see More customers on one engine: units).
Two-factor authentication: A six-digit code, taken from an app on the phone, that is written after email and password: for the console and for the portal, with ten reserve codes (see Two-factor authentication).
Console session: The time a person stays inside the console. It closes by itself after 30 minutes without use (from 5 minutes to 12 hours, in Network rules) and never lasts more than 12 hours; in the Profile everybody sees and closes their own (see The console closes by itself).
Script fence: The limit the engine puts on the scripts of an app: files, programs, databases and network. It reduces a lot what a script can do, but it is a defense inside the program, not a wall (see What an app can do).
Network rules: The console page, for Owners only, with the network rules of the engine: where the apps listen, a name for each app, the entry from the internet, the wrong attempts, from which addresses the console opens and the Windows firewall (see Network rules).
Sidebar: The console menu for Owners and Admins. It shows a configurable number of apps (5 by default, between 3 and 15), a “More apps” entry and each person’s preferred app order. Engine pages are grouped under Services and System. With the “Top menu” layout it sits at the top of the page.
Import people and groups: The directory page for adding groups, people and app access grants from an Excel template. You can preview the import and it is applied in full or rolled back. Temporary passwords are provided in a one-time download. The import only adds entries.
Smart import (“Whole file”): The option on the Import tab that loads multiple sheets, or a JSON file with multiple lists, into several collections at once. It suggests sheet-to-collection and column-to-field mappings, derives the order from relations and previews each collection. All writes succeed or none are applied. Limits are 50,000 rows and 60 seconds of writes. “Undo” reverses the entire import.
Delivery notes: The file at the root of an app package (DELIVERY.md, README.md, NOTES.md or CONSEGNA.md) describing what the app does and what the administrator should check. “Upload app” previews the beginning of the notes. Updating from a ZIP replaces them.
Engine history: The engine’s record of starts, stops, errors, backups, restores, portal sign-ins, changes and imports. They are kept in a file of their own, which nobody deletes or changes from the console. Owners see them all in the “Engine history” entry of the sidebar; Admins see the events of their apps (see The engine history).

05 /Folders

program folder\
├── pyrite.exe              the executable
├── README.html             folder readme (licenses are in THIRD-PARTY-NOTICES.txt)
├── control\pb_data\        engine data (registry, directory, events and engine backups)
├── control\aggiornamenti\  engine update restore points (and ritorno_ copies)
├── control\storico\  the engine history (and its copies)
├── control\pyrite.json  the network rules of the engine
├── control\doppia\  the key of the two-factor codes
├── control\certificati\    HTTPS keys and state (SYSTEM, Administrators and engine account only)
├── logs\                   engine.log, the engine log
├── apps\
│   └── <id>\
│       ├── app.json        the manifest
│       ├── release\        code: pages, hooks and migrations
│       ├── state\          live data (pb_data) and safety copies; the only folder writable by app scripts
│       └── logs\           process output
└── archivio\               archived apps

Code and data are stored separately. You can replace an app’s code while preserving its data.