WemX

Deploy WemX to Laravel Cloud, with a managed database, background workers and the scheduler.

Laravel Cloud is a fully managed platform for Laravel applications. It builds WemX from your GitHub repository, runs it on autoscaling compute, and provides the database, queue workers, scheduler and TLS for you.

Before you start

Laravel Cloud works differently from a traditional server in a few ways that matter for WemX:

Laravel Cloud behaviour	What it means for WemX
The filesystem is ephemeral. It's reset on every deployment, and each replica has its own disk.	Configuration lives in Cloud's environment variables, not in `.env`. Install extensions by committing them to your repository, not from the in-app marketplace, and update by deploying, not with the in-app updater. Images uploaded in the admin area don't survive a deployment.
Environment variables are written to `.env` on every deployment.	After running the web installer, copy `APP_INSTALLED` and `LICENSE_KEY` into Cloud's environment variables.
SQLite isn't supported in production.	Use Laravel MySQL or Laravel Serverless Postgres.

You need a WemX license key and a Laravel Cloud account. The license is validated against your domain, so decide whether you'll use the free *.laravel.cloud domain or your own domain first.

Deployment

Fork WemX on GitHub. Fork wemxnet/wemx to your account or organization. Laravel Cloud deploys from your fork, so this is also where you'll add extensions and customizations.

Create the application. In Laravel Cloud, choose New application, connect GitHub, select your fork and the main branch, and pick a region close to your customers. Select PHP 8.3 or newer as the runtime in the environment's General settings.

Add a database. On the environment's canvas, click Add database and create a Laravel MySQL (or Laravel Serverless Postgres) database in the same region. Cloud injects DB_HOST, DB_DATABASE, DB_USERNAME, DB_PASSWORD and the rest automatically.

Set environment variables. In the environment's settings, add:

APP_NAME=WemX
APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-app.laravel.cloud
FORCE_HTTPS=true
APP_INSTALLED=false

CACHE_STORE=database
SESSION_DRIVER=database
QUEUE_CONNECTION=database

Also make sure APP_KEY is set. If your environment doesn't have one yet, generate it locally with php artisan key:generate --show and add it. Keep a copy of it. WemX encrypts your gateway and server credentials with it, and changing it later makes them unreadable.

Configure the build commands. In Deployments → Build commands, use:

APP_INSTALLED=false composer install --no-dev --optimize-autoloader --no-interaction
npm ci --no-audit
npm run build

composer install runs WemX's post-install scripts, which publish the client and admin theme assets. Prefixing it with APP_INSTALLED=false keeps those scripts from connecting to the database during the build.

Don't add php artisan optimize or config:cache. WemX reads APP_INSTALLED at runtime, and a cached configuration would keep the web installer from finishing.

Configure the deploy command. In Deployments → Deploy commands, use:

php artisan migrate --force

On the very first deployment the database is still empty, which is fine: the installer creates the tables in the next step.

Deploy and run the web installer. Click Deploy. When it's live, open your APP_URL. The web installer opens:

Requirements: all should pass.
Database: choose MySQL (or Postgres). The connection details from Cloud are already filled in. Continue to create the tables.
Settings, admin account and license: complete the remaining steps.

Make sure your App cluster runs one replica while you complete the installer. Each replica has its own filesystem, and the installer keeps its progress in .env.

Make the installation permanent. The installer saved APP_INSTALLED=true and your license key to .env, which Cloud replaces on the next deployment. Add them as environment variables:

APP_INSTALLED=true
LICENSE_KEY=WMX-your-license-key

Then redeploy.

Enable background processing. WemX needs a queue worker and the scheduler (see what runs in the background).

Scheduler: turn on the Scheduler toggle on your App cluster. Cloud runs schedule:run every minute. If you run more than one replica, enable the scheduler on a single worker cluster instead, so suspensions and renewals don't run more than once.
Queue worker: add a background process to your App cluster, or to a worker cluster, with the command:
```
php artisan queue:work --sleep=3 --tries=3 --max-time=3600
```

Cloud restarts workers on every deployment. Redeploy, then check the admin dashboard: the Queue worker is not running alert should be gone.

Add your domain (optional). In the environment's Domains settings, add your own domain and follow the DNS instructions. Cloud issues the TLS certificate. Then update APP_URL, make sure your license allows the new domain, and redeploy.

WemX is live. Continue with First steps, starting with SMTP and a payment gateway.

Extensions on Laravel Cloud

Anything installed from the in-app marketplace is written to the filesystem, and disappears on the next deployment. Instead:

Download the extension and place it in your fork, for example extensions/Servers/Pterodactyl/.
WemX's .gitignore ignores extensions that aren't bundled, so allow it explicitly:
.gitignore
```
!/extensions/Servers/Pterodactyl/
!/extensions/Servers/Pterodactyl/**
```
Commit, push and let Cloud deploy.
Enable it under Admin → Installed Extensions, Gateways or Servers. Its enabled state is stored in the database, so it survives deployments.

If the extension has its own migrations, they run with php artisan migrate --force in your deploy command.

Uploads and branding

The Images library, the application logo and the favicon are stored in public/assets/common/img, which is reset on every deployment. To make branding permanent, commit your images to public/assets/common/img/ in your fork and select them under Admin → Settings → Branding.

Updating WemX

Don't use the in-app updater on Laravel Cloud. Update your fork instead:

git remote add upstream https://github.com/wemxnet/wemx.git   # once
git fetch upstream --tags
git merge v3-beta-0.1.1        # or the release you want
git push

Cloud builds and deploys the new version, and your deploy command runs the new migrations. Review the release notes first.

Troubleshooting

Problem	Fix
The installer appears again after a deployment	`APP_INSTALLED=true` isn't set in Cloud's environment variables. Add it and redeploy.
Staff are sent to the license page	Add `LICENSE_KEY` to the environment variables, and check that your license allows the current domain.
Build fails while running Composer scripts	Make sure the build command starts with `APP_INSTALLED=false`.
Suspensions or emails happen twice	The scheduler runs on several replicas. Enable it on one worker cluster only.
Orders stay in `pending`	No queue worker is running. Add the `queue:work` background process.
An installed extension disappeared	It was installed from the marketplace at runtime. Commit it to your repository instead.