# Server Requirements

## Overview

WaDesk is a standard Laravel 12 application paired with a bundled Node.js helper service. If your host can run a modern Laravel app and a long-running Node process, it can run WaDesk. This page lists every requirement and why it is needed.

The web installer (next page) checks this list automatically, so you do not have to verify everything by hand — but knowing it up front helps you pick the right hosting plan.

> Quick read: PHP 8.2+, MySQL 8 (or MariaDB 10.6+), Composer, write access to two folders, and Node.js 18+. The Node helper service is required on every channel — it handles sending and runs the scheduler for bulk and scheduled messages (broadcasts, campaigns, flows).

## Requirements at a Glance

Use this table to size your hosting before you buy. The right-hand column tells you whether a requirement is universal or tied to one engine.

Component | Minimum | Recommended | Needed for
--- | --- | --- | ---
PHP | 8.2 | 8.3 / 8.4 | Always
MySQL | 8.0 | 8.0+ | Always
MariaDB (alternative) | 10.6 | 10.11+ | Always (instead of MySQL)
Composer | 2.x | Latest 2.x | Install / updates
Node.js | 18 LTS | 20 LTS | Required — the helper service + scheduler (all channels)
npm | 9.x | Latest | Helper service dependencies + asset build
RAM | 1 GB | 2 GB+ | Always (more if running the bridge)
Disk | 2 GB free | 10 GB+ | App, media, session files
HTTPS / SSL | Recommended | Required for production | Webhooks (Cloud API / Twilio)

## PHP Version

WaDesk requires PHP 8.2 or newer (Laravel 12's minimum). PHP 8.3 or 8.4 is recommended for better performance. The installer blocks the Continue button on its Requirements step if it detects an older runtime, so there is no way to install onto an unsupported version by accident.

On shared hosting, set the PHP version in your control panel (cPanel "Select PHP Version", Plesk "PHP Settings", etc.). On a VPS, install the matching `php8.x-fpm` package for your web server.

> Two PHP binaries: Some hosts run one PHP version for the web (FPM) and a different, older one on the command line (CLI). Composer and any maintenance commands use the CLI version, so confirm `php -v` also reports 8.2+.

## Required PHP Extensions

The installer's Requirements step checks for the following extensions and shows a green tick for each one that is loaded. All of them are required — most ship with a standard PHP install, but `gd` and `zip` sometimes need to be enabled explicitly on shared hosting.

Extension | Why WaDesk needs it
--- | ---
`bcmath` | Precise money / wallet and billing math
`ctype` | String validation used throughout Laravel
`curl` | Outbound calls to the helper service, Meta Graph API, Twilio, AI providers, payment gateways
`dom` | XML / HTML handling (also pulled in by `doctrine/dbal`)
`fileinfo` | MIME detection for media uploads
`gd` | Image processing for logos, QR rendering, media
`json` | API payloads and config (bundled in modern PHP)
`mbstring` | Multi-byte / Unicode message text (emoji, RTL languages)
`openssl` | Encryption, HTTPS, signed webhooks and tokens
`pdo` | Database access layer
`tokenizer` | Required by the Laravel framework
`xml` | XML parsing for several integrations
`zip` | Archive handling for updates and exports

You will also need the PDO MySQL driver (`pdo_mysql`). The installer lists detected PDO drivers separately and flags an error if `mysql` is missing — without it the database step cannot connect.

## Database (MySQL / MariaDB)

WaDesk stores everything — workspaces, contacts, messages, campaigns, plans, billing — in a relational database. MySQL 8.0+ is the primary target; MariaDB 10.6+ is fully supported as a drop-in alternative.

Before installing, create:

1. An empty database (for example `wadesk`).
2. A database user with a strong password.
3. Full privileges for that user on that database (the installer runs `CREATE TABLE` migrations).

Keep the host, port, database name, username, and password handy — you enter them on the installer's Database step, and it tests the connection live before saving.

> Default driver settings: The installer writes a `database`-driven session, cache, and queue configuration by default, so there is no separate Redis requirement. Redis is optional and can be configured later for higher throughput.

## Node.js — Required (the helper service)

WaDesk supports three interchangeable WhatsApp channels, and the bundled Node helper service handles sending for all of them. Node.js is required — not optional. It also runs the scheduler for bulk and scheduled messages (broadcasts, campaigns, flows) on every channel.

The service lives in the `node/` folder of the project. It holds the WhatsApp connections, renders pairing QR codes, sends messages, and runs its own scheduler for bulk campaigns and recurring sends.

- Node.js 18 LTS minimum; 20 LTS recommended.
- Install its dependencies once: `cd node && npm install`.
- Start it with `node index.js` (kept alive by PM2, Supervisor, or a systemd service on a VPS).
- It listens on the port set by `PORT` in `node/.env` (default `8888`).

This applies to the official channels too: WhatsApp Cloud API (Meta) and Twilio bulk/automated sends all run through the service. Only a single direct Twilio send can bypass it. In short, a working install must run the `node/` service — do not treat it as optional.

> Shared hosting note: Many entry-level shared plans cannot run a long-running Node process. Because the helper service is required for sending and scheduling on every channel, choose a VPS or a host that explicitly allows persistent Node apps. Entry-level shared hosting that cannot keep Node alive is not suitable for WaDesk.

## Web Server & Document Root

WaDesk runs behind Apache or Nginx (or PHP-FPM via either). Point your domain's document root at the project's `public/` directory — never the project root — so that only public assets are web-accessible.

- Apache: the bundled `public/.htaccess` handles URL rewriting. Ensure `mod_rewrite` is enabled.
- Nginx: use a standard Laravel `try_files $uri $uri/ /index.php?$query_string;` location block.
- HTTPS: strongly recommended in all cases, and effectively required if you use the Cloud API or Twilio engines, since Meta and Twilio only deliver inbound webhooks to HTTPS URLs.

## File Permissions

Laravel needs to write to two locations. The installer's Requirements step explicitly checks each of these and shows a tick or a cross:

- `storage/` — and its `app/` and `framework/` subfolders (logs, cache, compiled views, file sessions during install)
- `bootstrap/cache/` — the framework's bootstrap cache
- The project root / `.env` must be writable — the installer writes your configuration into `.env` during the install run
- `lang/` must be readable (translation files)

On a VPS, set the web-server user as owner and use `775` on those folders:

    chown -R www-data:www-data storage bootstrap/cache
    chmod -R 775 storage bootstrap/cache

> Tip: If the Requirements step shows a writability cross, fix permissions and simply reload the page — the check re-runs on every visit. You do not need to restart the wizard.