Installation and updates
Orbitra is optimized for a quick start without complex environment setup. It is built on a lightweight PHP + SQLite + Nginx stack β no separate DB server (no ClickHouse, Redis or MySQL).
System requirements
Orbitra stores everything in a single SQLite file, so it needs significantly less RAM than ClickHouse-based trackers and runs on the cheapest VPS plans.
Basic (required):
- CPU: 1 vCPU (x86_64)
- RAM: 1 GB (2 GB recommended)
- Disk: 20 GB SSD
- OS: Ubuntu 22.04 through 26.04, or Debian 12 / 13
- A clean server without a control panel; root/sudo access
Sizing by traffic volume (a guideline):
| Clicks per day | RAM | CPU | Disk |
|---|---|---|---|
| up to ~100,000 | 1β2 GB | 1β2 vCPU | 20 GB SSD |
| ~100,000 β 500,000 | 2β4 GB | 2 vCPU | 40 GB SSD |
| ~500,000 β 1,000,000 | 4β8 GB | 4 vCPU | 80 GB SSD |
β Verified in practice: Orbitra runs stably on a 2 vCPU / 2 GB RAM / 20 GB SSD VPS (Ubuntu 24.04) with light traffic β a convenient and inexpensive starting point. The upper rows of the table are headroom for higher traffic, not a hard requirement.
π‘ Why less than Keitaro? Keitaro stores clicks in ClickHouse + Redis + MySQL, so its RAM requirements grow up to 64 GB at millions of clicks per day. In Orbitra everything lives in a single SQLite file β the bottleneck is not RAM but disk I/O and SQLite's single-threaded writes. For low and medium volumes (in WAL mode) this is enough; for sustained millions of clicks per day with heavy analytics, a columnar-DB tracker (like Keitaro) is architecturally the better fit.
π‘ When installing on a 1 GB RAM server, add 1β2 GB of swap: building the frontend (Vite) is the most memory-hungry step. The tracker itself runs fine on 1 GB.
Quick Automatic Installation (Production)
The fastest and proper way to launch the project on a server is the built-in installer.
- Make sure you have a "clean" Linux server (Ubuntu 22.04+ or Debian 12+).
- Run the command as root/sudo:
wget -O orbitra-install.sh https://raw.githubusercontent.com/fenjo26/Orbitra.link/main/install.sh && bash orbitra-install.sh
The download is a separate step on purpose: with wget -qO- β¦ | bash, a failed download silently pipes emptiness into bash, and the installation "completes" without a single line of output. This way it stops at &&, and wget reports the reason.
- The script installs Nginx, a current PHP (8.5, falling back to 8.4 from the OndΕej SurΓ½ repository; if that is unavailable too β the distro one), SQLite, downloads the frontend code and sets up HTTPS certificates.
First sign-in: there is no "default" account. After installation, open
http://<your-domain>/admin.phpβ on first run Orbitra starts the initial setup wizard, where you create your own administrator (login β₯ 3 characters, password β₯ 8 characters, time zone and language).
Panel access by IP
The panel is always available at the server address β http://<ip>/admin.php β no matter how many domains you bind and which of them you later delete. This is handled by a catch-all block that Orbitra puts first in the Nginx config; certificates are issued via certbot certonly --webroot, so Certbot does not rewrite the config.
https://<ip>/admin.php works too, but with a browser warning: Let's Encrypt does not issue certificates for bare IPs, so a self-signed one is used.
If the panel still stops responding β for example, the Nginx config was edited by hand β rebuild it from the database:
sudo php /var/www/orbitra/cli/nginx_sync.php
The command also repairs Certbot renewal configs left over from the previous issuing method and generates a self-signed certificate. After updating from a version below 0.9.6.4, run it once.
What the installer sets up
- Nginx, PHP-FPM (the pool is sized from the amount of RAM,
fastcgi_read_timeout 180s), SQLite, Composer with SHA-256 verification. - The code in
/var/www/orbitra, owned bywww-data. - Its own postback key.
- The Sypex Geo City database (free, no key). If the server could not reach sypexgeo.net, the installation still completes, and the database can be added later in β β Geo Databases.
- SSL and nginx helpers with argument validation (
cli/server_setup.sh). - Crons: click spool, postback queue, Web Push, rotation auto-optimization, Telegram polling, SSL issuance, cost import, IP ranges, geo databases. Full table in Architecture.
- MCP server dependencies, if npm is present on the server.
- Opens 80/443 in ufw if it is enabled.
Not installed automatically: retention-based cleanup (cli/cleanup_cron.php, see Administration), the postback monitor, and source URL checks.
Re-running the installer on a live server is safe: it updates PHP, configs and crons without touching data.
Panel security settings after installation β a custom panel path, access by IP, two-factor sign-in β are covered in Administration.
Updating PHP
Security advisory: CVE-2026-109618 / CVE-2026-109619 (October 2026)
Two critical unauthenticated RCE vulnerabilities in PHP itself ("php2shell", CVSS v4.0 9.2, public exploit) were patched upstream on 2026-10-21. Fixed releases: 8.5.12, 8.4.27, 8.3.36, 8.2.35. A tracker is an internet-facing PHP app, so every web-facing interpreter must be patched. The panel shows a red banner on the dashboard until the running PHP reports one of these versions (or newer).
- PHP 8.2β8.5, unpatched:
NEEDRESTART_MODE=a apt install -y --only-upgrade 'php8.X-'(replace X with your branch), then restart PHP-FPM and the web server (systemctl restart php8.X-fpm nginx). Paste-safe by design: the-yflag removes theContinue? [Y/n]confirmation (paste a multi-line block and the NEXT line gets read as the answer β apt aborts), andNEEDRESTART_MODE=aanswers the Ubuntu 22.04+ "which services to restart" dialog automatically. Do not use a bareapt upgrade 'php': apt expands the glob to every php-named package in the archive and aborts on conflicts before upgrading anything. Distro builds may carry the fix backported without reaching the version number β checkapt changelog php8.X-fpm | grep 109618before assuming you are exposed. - PHP 8.1 or older: the branch is EOL and will never receive the fix. Upgrade via the installer path below (
sudo bash install.shinstalls PHP 8.5 alongside and switches everything over). - If PHP was installed by a hosting panel (ispmanager etc.), update it from that panel.
Routine upgrade
Ubuntu 22.04 / Debian 12 / Ubuntu 24.04 ship PHP 8.1 / 8.2 / 8.3 out of the box β these versions no longer receive security updates (8.1 and 8.2 are EOL; 8.3 gets only security fixes until the end of 2027). Orbitra v1.5.10 runs on all of them, but a fresh install or a server upgrade should start from PHP 8.4+.
The simplest path is to re-run the installer (it is idempotent and supports upgrading over an existing installation):
sudo bash /var/www/orbitra/install.sh
The installer adds the current PHP builds repository (ondrej/php on Ubuntu, packages.sury.org on Debian), installs PHP 8.5 (falling back to 8.4) alongside the old one, switches the php CLI alternative (used by crons and Composer), rewrites the Nginx config to the new FPM socket, applies the pool settings and restarts the services. The old PHP version stays installed but stops serving traffic; you can remove it after checking, if you like.
Manual (Ubuntu):
sudo add-apt-repository -y ppa:ondrej/php && sudo apt-get update
sudo apt-get install -y php8.5-fpm php8.5-cli php8.5-sqlite3 php8.5-curl php8.5-mbstring php8.5-xml php8.5-zip php8.5-intl php8.5-bcmath
sudo update-alternatives --set php /usr/bin/php8.5
sudo bash /var/www/orbitra/install.sh # switches nginx/FPM/crons to the new version
Manual (Debian):
. /etc/os-release
curl -fsSL https://packages.sury.org/php/apt.gpg | sudo gpg --dearmor --yes -o /usr/share/keyrings/deb.sury.org-php.gpg
echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ ${VERSION_CODENAME} main" | sudo tee /etc/apt/sources.list.d/php-sury.list
sudo apt-get update
sudo apt-get install -y php8.5-fpm php8.5-cli php8.5-sqlite3 php8.5-curl php8.5-mbstring php8.5-xml php8.5-zip php8.5-intl php8.5-bcmath
sudo update-alternatives --set php /usr/bin/php8.5
sudo bash /var/www/orbitra/install.sh
After the update, check: php -v shows 8.4/8.5, the panel opens, Logs β System log has no postback.php database error entries, and the worker ping in the postback queue settings is fresh. When updating via the button, the panel will warn by itself if the server stays on PHP < 8.4.
One-time server step after updating (1.6.0+)
The "Update" button in the panel runs as the web user and cannot modify sudoers. Servers installed before 1.6.0 need a single run of cli/server_setup.sh as root after updating β the panel will show a banner with the command:
curl -fsSL https://raw.githubusercontent.com/fenjo26/Orbitra.link/v1.6.0/cli/server_setup.sh | sudo ORBITRA_REF=v1.6.0 bash
The script is downloaded from the release tag, not from /var/www/orbitra (that directory belongs to the web user, and root must not execute files the web user can rewrite). It replaces the old sudo rules (certbot with any arguments, and cp into sites-available β either one could let the web user gain root) with helpers that validate arguments, installs the click queue cron and writes the version to /etc/orbitra/server-setup-version. Running it again is safe. install.sh calls the same script, so new installations get the same thing.
After updating to 1.8.4: nginx hardening (October 2026 advisories)
Nothing to run on the server: the update itself regenerates the nginx vhost without the alias directive and reloads nginx (through the same verified path a domain save uses). What remains is the operating system half of the October 2026 advisories β the nginx package itself (rated up to CVSS 9.2), the kernel and the CA trust store β which only the operator can update:
apt update && NEEDRESTART_MODE=a apt upgrade -y # Debian/Ubuntu; dnf upgrade on the RHEL family
systemctl reload nginx
reboot # loads the fixed kernel
nginx -v # fixed: 1.31.7+ mainline / 1.30.6+ stable
Distro builds may backport the fix without bumping the version β check with apt changelog nginx. The dashboard shows a dismissible banner until the running nginx reports a fixed version (when a shell is available to read it). The tracker is not affected by the PostgreSQL / Redis / Node.js items of the same digest: it runs PHP + SQLite and ships no Node.js on the server.
After updating to 1.8.3: session recordings for whole sites
Nothing to run on the server. The update adds the campaign-level session recordings with the One click per visit visit gluing and the consent mode, all off by default β click statistics and recordings change only where you switch them on yourself. No cron to add: cleanup still rides the incoming recordings.
After updating to 1.8.2: browser check
Nothing to run on the server. The update adds the browser check but leaves it off on an existing install, so routing doesn't change by itself. Admins see a one-time banner on the dashboard: Turn on soft mode switches it on, Learn more opens Settings β Bots, Not now hides the banner (the mode can be changed in Settings β Bots at any time). A fresh installation starts in soft mode.
Update integrity
composer.pharis not kept in the repository: the installer downloads the version pinned ininstall.sh(COMPOSER_VER) and verifiesCOMPOSER_SHA256; a mismatch stops the installation. An already existing/var/www/orbitra/composer.pharis used as is.- The panel (
frontend/dist) is built on the release machine and committed: the server never runsnpm install/npm run build, and the working copy stays clean after installation. - Release tags should be signed (
git tag -s) so that updating from the panel pulls verifiable code.
Local Development (React & PHP Server)
If you plan to modify the frontend source code (React) and the tracker's visual part, you will need a local PHP + Vite setup.
Part 1: Starting the Backend API
Open a first terminal and start the built-in PHP server with the router:
cd Orbitra
php -S localhost:8080 router.php
This server will handle API requests and redirects.
Part 2: Starting the Frontend (Vite)
Open a second terminal, install the npm packages and start the dev server:
cd Orbitra/frontend
npm install
npm run dev
Then open http://localhost:5173 in your browser. All API requests from the frontend are automatically proxied (via the vite.config.js proxy) to http://localhost:8080/api.php, which avoids CORS and session issues in development mode.
Building the panel
Only needed if you change the panel code:
cd Orbitra/frontend
npm run build
The build lands in frontend/dist/, which is committed to the repository β the server takes the ready-made panel via git pull or an update from the panel and builds nothing itself.
Telegram bot
Connecting and operating modes β Telegram bot.
Quick start: your first campaign
The short path: install the tracker, create a campaign, and get your first clicks and conversions in under an hour.
Read guide βDocsInstallation and updates
Install Orbitra on a fresh Ubuntu or Debian server with one command, and update to new versions safely.
Read guide βDocsMigrating from Keitaro
Move campaigns, offers, sources and domains from Keitaro to Orbitra in one click β what transfers and what to check.
Read guide βDocsMigrating from Binom
Move campaigns and streams from Binom to Orbitra: what transfers automatically and what to set up by hand.
Read guide βDocsFeature overview
Everything Orbitra can do: campaigns and streams, cloaking, landings, PWA, postbacks, costs, reports and integrations.
Read guide βDocsCampaigns and streams
The complete reference: campaign settings, stream types, schemas, rotation, filters, test links and every option explained.
Read guide βDocsCloaking
Full cloaking reference: detection layers, global settings, per-stream filters, verdicts and reports.
Read guide βDocsBrowser check
How the JS check catches bots, VMs and emulators through contradictions in the browser environment.
Read guide βDocsLanding pages
Landing types, the {offer} macro, the JS adapter, LeadForge and multi-offer landings β the complete reference.
Read guide βDocsPWA and Web Push
Build installable PWA apps and collect push subscribers: settings, icons, events and notifications.
Read guide βDocsPWA Funnel
A multi-step PWA funnel: install prompts, event tracking and re-engagement notifications.
Read guide βDocsConversion popups
Show real conversion events as on-page popups: setup, triggers and placement.
Read guide βDocsSession recordings and heatmaps
Replay real visits and see click and scroll maps. Storage limits and privacy notes.
Read guide βDocsContent gallery
Central storage for icons, screenshots and creatives used across PWAs and landings.
Read guide βDocsCreatives library
Store creatives with subid tracking and test them across campaigns.
Read guide βDocsExternal PWA and Telegram channels
Publish PWAs to external domains and run Telegram channels as a traffic source.
Read guide βDocsPostbacks and conversions
Incoming postbacks, conversion statuses and types, and outgoing S2S postbacks to your traffic source.
Read guide βDocsCosts
Import spend from Facebook, TikTok and Google Ads, or update it via API and cron β and how the revenue aggregator works.
Read guide βDocsPush and pop networks
Working with push and pop traffic sources: feeds, zone optimization and the zone killer.
Read guide βDocsFacebook / Meta
Cost import from Meta Ads and the Conversions API: server-side events with deduplication.
Read guide βDocsDolphin / Fbtool
Receive Facebook costs through the Dolphin (Fbtool) API in real time.
Read guide βDocsFB comment cleaner
Bulk-moderate comments under Meta ads: hide, delete and filter by keywords.
Read guide βDocsTraffic sources and affiliate networks
Catalog of 50+ traffic sources and 440+ networks: templates, parameters and postback URLs.
Read guide βDocsReports, logs and metrics
The report builder, saved reports, click logs and every metric explained.
Read guide βDocsDomains and SSL
Add domains, DNS, free Let's Encrypt certificates, redirects, parking and every switch on the page.
Read guide βDocsCloudflare
How to run campaign domains through Cloudflare: DNS, SSL modes and what to turn off.
Read guide βDocsAdministration
Users, roles and permissions, security settings, geo databases, updates and system health.
Read guide βDocsTelegram bot
Manage the tracker from Telegram: stats, conversions and alerts in chat.
Read guide βDocsMCP: an AI assistant in the tracker
Connect Claude or any MCP client to Orbitra and manage campaigns with plain-language commands.
Read guide β