Docs

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):

Sizing by traffic volume (a guideline):

Clicks per dayRAMCPUDisk
up to ~100,0001–2 GB1–2 vCPU20 GB SSD
~100,000 – 500,0002–4 GB2 vCPU40 GB SSD
~500,000 – 1,000,0004–8 GB4 vCPU80 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.

  1. Make sure you have a "clean" Linux server (Ubuntu 22.04+ or Debian 12+).
  2. 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.

  1. 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

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).

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

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.

← Previous
Quick start: your first campaign
Next β†’
Migrating from Keitaro
View source on GitHub: github.com/fenjo26/Orbitra.link/wiki
All guides
Docs

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 β†’
Docs

Installation and updates

Install Orbitra on a fresh Ubuntu or Debian server with one command, and update to new versions safely.

Read guide β†’
Docs

Migrating from Keitaro

Move campaigns, offers, sources and domains from Keitaro to Orbitra in one click β€” what transfers and what to check.

Read guide β†’
Docs

Migrating from Binom

Move campaigns and streams from Binom to Orbitra: what transfers automatically and what to set up by hand.

Read guide β†’
Docs

Feature overview

Everything Orbitra can do: campaigns and streams, cloaking, landings, PWA, postbacks, costs, reports and integrations.

Read guide β†’
Docs

Campaigns and streams

The complete reference: campaign settings, stream types, schemas, rotation, filters, test links and every option explained.

Read guide β†’
Docs

Cloaking

Full cloaking reference: detection layers, global settings, per-stream filters, verdicts and reports.

Read guide β†’
Docs

Browser check

How the JS check catches bots, VMs and emulators through contradictions in the browser environment.

Read guide β†’
Docs

Landing pages

Landing types, the {offer} macro, the JS adapter, LeadForge and multi-offer landings β€” the complete reference.

Read guide β†’
Docs

PWA and Web Push

Build installable PWA apps and collect push subscribers: settings, icons, events and notifications.

Read guide β†’
Docs

PWA Funnel

A multi-step PWA funnel: install prompts, event tracking and re-engagement notifications.

Read guide β†’
Docs

Conversion popups

Show real conversion events as on-page popups: setup, triggers and placement.

Read guide β†’
Docs

Session recordings and heatmaps

Replay real visits and see click and scroll maps. Storage limits and privacy notes.

Read guide β†’
Docs

Content gallery

Central storage for icons, screenshots and creatives used across PWAs and landings.

Read guide β†’
Docs

Creatives library

Store creatives with subid tracking and test them across campaigns.

Read guide β†’
Docs

External PWA and Telegram channels

Publish PWAs to external domains and run Telegram channels as a traffic source.

Read guide β†’
Docs

Postbacks and conversions

Incoming postbacks, conversion statuses and types, and outgoing S2S postbacks to your traffic source.

Read guide β†’
Docs

Costs

Import spend from Facebook, TikTok and Google Ads, or update it via API and cron β€” and how the revenue aggregator works.

Read guide β†’
Docs

Push and pop networks

Working with push and pop traffic sources: feeds, zone optimization and the zone killer.

Read guide β†’
Docs

Facebook / Meta

Cost import from Meta Ads and the Conversions API: server-side events with deduplication.

Read guide β†’
Docs

Dolphin / Fbtool

Receive Facebook costs through the Dolphin (Fbtool) API in real time.

Read guide β†’
Docs

FB comment cleaner

Bulk-moderate comments under Meta ads: hide, delete and filter by keywords.

Read guide β†’
Docs

Traffic sources and affiliate networks

Catalog of 50+ traffic sources and 440+ networks: templates, parameters and postback URLs.

Read guide β†’
Docs

Reports, logs and metrics

The report builder, saved reports, click logs and every metric explained.

Read guide β†’
Docs

Domains and SSL

Add domains, DNS, free Let's Encrypt certificates, redirects, parking and every switch on the page.

Read guide β†’
Docs

Cloudflare

How to run campaign domains through Cloudflare: DNS, SSL modes and what to turn off.

Read guide β†’
Docs

Administration

Users, roles and permissions, security settings, geo databases, updates and system health.

Read guide β†’
Docs

Telegram bot

Manage the tracker from Telegram: stats, conversions and alerts in chat.

Read guide β†’
Docs

MCP: an AI assistant in the tracker

Connect Claude or any MCP client to Orbitra and manage campaigns with plain-language commands.

Read guide β†’