Introduction
Marketix is a self-hostable, multi-tenant URL shortener and QR code management platform. This Administration Manual covers installing, deploying, configuring, and operating Marketix in production — it is written for the person running the instance, not the day-to-day user.
What Marketix is
Section titled “What Marketix is”Marketix lets teams create and manage short links, custom QR codes, and tracking pixels under their own domains, all from a clean React-based web interface. Multiple isolated teams (called Projects) can share a single Marketix instance — each with its own domains, links, and statistics — with no data leakage between them.
Everything runs inside a Docker Compose stack with no external cloud service dependency beyond optional object storage and a MaxMind account for geolocation.
Architecture
Section titled “Architecture”| Layer | Technology |
|---|---|
| Application framework | Laravel 13 / PHP 8.3+ (Docker image ships 8.4) |
| Frontend | React 19 + TypeScript via Inertia.js (custom UI — no Filament) |
| HTTP server | Laravel Octane on FrankenPHP |
| Queue worker | Laravel Horizon (Redis-backed) |
| Database | MariaDB (default); SQLite supported |
| Cache / queue backend | Redis |
| File storage | Local disk or S3-compatible object storage |
| QR code generation | bacon/bacon-qr-code (server-side) + qr-code-styling (client preview) |
| PDF reports | spatie/laravel-pdf |
| Geolocation | MaxMind GeoLite2-City database (via geoip2/geoip2) |
| Activity logging | spatie/laravel-activitylog |
| 2FA / passkeys | pragmarx/google2fa-qrcode + laravel/passkeys |
| Edge router | Traefik v3 (TLS, custom-domain routing) |
The Octane server runs on port 8000 inside the container. Traefik sits in front and handles TLS termination and routing — including dynamic per-project custom-domain routing written by the app at runtime.
Tenancy model
Section titled “Tenancy model”The central organisational unit is the Project. Every resource in Marketix belongs to a Project.
- Users belong to Projects via a many-to-many join table (
project_user) that carries arolecolumn and anactiveflag. - Authenticated requests to project-scoped routes are intercepted by
ProjectBindingMiddleware, which resolves the{project}path segment and verifies that the requesting user belongs to that project (or is a super-admin). - The resolved project is shared with all Inertia pages via
HandleInertiaRequests, making it available to every frontend component ascurrentProject.
| Role | Scope | Capabilities |
|---|---|---|
| super-admin | Global | Full access to the /admin area: manage all users, all projects, mailer, branding, and storage configuration; access any project directly |
| project-admin | Per-project | Manage project members, send and revoke invitations |
| member | Per-project | Create and manage links, QR codes, pixels, domains, and view statistics within the project |
Super-admin status is a boolean flag (super_admin) on the user record rather than a project role. It is set via the marketix:create-admin Artisan command.
What a Project owns
Section titled “What a Project owns”| Resource | Description |
|---|---|
| Domains | Custom short-link domains; each domain has a root redirect and a 404 redirect |
| URLs (short links) | Slugs pointing to target URLs; support password protection, expiry dates, status toggle, and targeting rules |
| QR codes | Styled, versioned QR codes; can be static or dynamic; linked optionally to a short link |
| Pixels | Tracking pixel definitions attachable to short links |
| Statistics | Per-click records capturing IP, geo, device, and referrer; aggregated per URL |
| Activity log | Audit trail of create/update/delete events within the project |
Feature tour
Section titled “Feature tour”Short links
Section titled “Short links”Each URL record has a slug (the short code), a target URL, and optional controls:
- Password protection — visitors must enter the correct password before being redirected.
- Expiry date — the link deactivates automatically after a configurable
expired_attimestamp. - Targeting rules — route visitors to different destinations based on geographic location (
targeting_geo), device type (targeting_device), browser language (targeting_language), or A/B weighting (targeting_ab). - Status toggle — enable or disable a link instantly without deleting it.
Links are always served through a custom domain belonging to the same project.
Custom domains
Section titled “Custom domains”Each project can manage multiple custom domains. When you add a domain, Marketix verifies reachability by checking the /.well-known/marketix endpoint (which returns {"app":"marketix"}). Verified domains are written dynamically into Traefik’s file provider configuration (custom-domains.yml) so Let’s Encrypt certificates are issued automatically.
QR codes
Section titled “QR codes”QR codes are versioned: every edit creates a new QrCodeVersion record so you can restore a previous design. Codes can encode URLs, vCards, plain text, and other content types. Dynamic QR codes are linked to a short link, meaning you can update the destination without reprinting.
Tracking pixels
Section titled “Tracking pixels”Pixel definitions are attachable to short links. When a visitor hits a link, any attached pixels fire, enabling integration with advertising and analytics platforms.
Statistics and PDF reports
Section titled “Statistics and PDF reports”Every click on a short link is recorded as a Statistic entry capturing the visitor’s IP address, geo coordinates (resolved via the GeoLite2-City database), device, and referrer. Statistics are aggregated and displayed per-link and per-project. Projects and individual links can export statistics as a PDF report via spatie/laravel-pdf.
Team management
Section titled “Team management”Project admins can invite team members by email. Invitations carry a secure token and expire if not accepted. Members can be promoted, demoted, or removed. Super-admins can manage team membership across all projects from the /admin/projects area.
Authentication and security
Section titled “Authentication and security”- Email/password login with rate-limited 2FA challenge.
- TOTP two-factor authentication — users can enable TOTP-based 2FA with recovery codes.
- Passkeys — users can register hardware passkeys (WebAuthn) as an alternative second factor.
- Password reset via email.
- Force-password-change flag on user accounts (set by admins; user is prompted on next login).
White-label branding
Section titled “White-label branding”The super-admin area exposes a Branding settings page for customising the application name and visual identity. Mailer and storage settings are also configurable from the admin panel without touching .env.
What this manual covers
Section titled “What this manual covers”| Section | Content |
|---|---|
| Requirements | PHP, database, Redis, Node, and storage prerequisites |
| Docker deployment | Compose services, Traefik setup, custom-domain wiring |
| Environment configuration | All .env groups explained with deployment guidance |
| First run | Running setup, creating the first admin user, GeoIP database |
The user manual (working with links, QR codes, and statistics as a project member) and the reference section (complete env-var table, CLI command reference) are covered in their respective parts of this documentation site.