Docker

The WemX repository ships with a production-ready Docker setup. One docker compose up gives you:

All data lives in named Docker volumes, so you can rebuild or update the containers without losing anything.

Requirements

• Docker Engine 24+ with the Compose plugin (docker compose version)
• 1 GB of RAM or more
• A domain name and a reverse proxy for HTTPS in production (see HTTPS)

Installation

git clone https://github.com/wemxnet/wemx.git
cd wemx

cp docker/wemx.env.example docker/wemx.env
nano docker/wemx.env

docker compose up -d --build

docker compose logs -f app

docker compose restart app

How it works

Configuration and the .env file

WemX reads its configuration from two places:

1. Container environment variables from docker/wemx.env. These always win.
2. The .env file, which the web installer and the license page write to. It's stored on the wemx-config volume at /config/.env and linked into the application.

On first start the container creates /config/.env and generates a unique APP_KEY. This key encrypts your gateway and server credentials, so back it up:

docker compose cp app:/config/.env ./wemx-env-backup

Volumes

On every start the container refreshes the extensions and theme assets that ship with the image, and leaves everything you installed or uploaded alone.

Background processes

The app container runs the queue worker and scheduler for you, so there's no cron or systemd setup. The admin dashboard warns you if the queue worker stops.

To run them in separate containers instead, set WEMX_RUN_QUEUE=false or WEMX_RUN_SCHEDULER=false and start extra containers from the same image with php artisan queue:work or php artisan schedule:work as the command. They need the same volumes and environment.

Database migrations

Once WemX is installed, the container runs php artisan migrate --force on every start, so new database tables are created automatically after an update. Set WEMX_AUTO_MIGRATE=false to do this yourself.

HTTPS and reverse proxies

The app container serves plain HTTP on port 8080 on the host (change it with WEMX_HTTP_PORT). In production, put a reverse proxy in front of it to handle TLS, and set FORCE_HTTPS=true and an https:// APP_URL in wemx.env. WemX already trusts forwarded headers from proxies.

billing.example.com {
    reverse_proxy 127.0.0.1:8080
}

server {
    listen 443 ssl http2;
    server_name billing.example.com;
    # ssl_certificate / ssl_certificate_key …

    client_max_body_size 32m;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

services:
    app:
        labels:
            - traefik.enable=true
            - traefik.http.routers.wemx.rule=Host(`billing.example.com`)
            - traefik.http.routers.wemx.entrypoints=https
            - traefik.http.routers.wemx.tls.certresolver=letsencrypt
            - traefik.http.services.wemx.loadbalancer.server.port=80
        networks: [proxy, default]

networks:
    proxy:
        external: true

Updating

In Docker, update by rebuilding the image rather than with the in-app updater. Changes made by the updater inside a container are lost when the container is recreated.

# 1. Back up the database
docker compose exec db sh -c 'mariadb-dump -u root -p"$MARIADB_ROOT_PASSWORD" "$MARIADB_DATABASE"' > wemx-backup.sql

# 2. Get the new version and rebuild
git pull
docker compose up -d --build

Migrations run automatically on start-up. To pin a release, check out its tag first (for example git checkout v3-beta-0.1.1) and pass the version to the build so it shows in the admin area:

docker compose build --build-arg WEMX_VERSION=v3-beta-0.1.1 && docker compose up -d

Useful commands

docker compose ps                                  # status and health
docker compose logs -f app                         # application, queue and scheduler logs
docker compose exec -u www-data app php artisan …  # run any Artisan command
docker compose exec -u www-data app php artisan extension:list
docker compose down                                # stop (data is kept in volumes)

Using an external database

To use a managed MySQL or PostgreSQL server instead of the bundled MariaDB, remove the db service and the depends_on block from docker-compose.yml, and point the DB_* variables in wemx.env at your server, for example DB_CONNECTION=pgsql and DB_PORT=5432.

Troubleshooting