Most GSM X Tool installs take less than half an hour. The ones that take a day almost always fail for the same few reasons, and none of them are in the software: a nested folder, a database user without privileges, or a cron job that was never added. This guide walks through the whole install on ordinary cPanel hosting and points out where each of those traps sits.
Before you start
Have these ready, because the installer asks for them in one go:
- A domain or subdomain pointed at your hosting, with an SSL certificate on it. Free AutoSSL from cPanel is enough.
- Hosting that meets the requirements: PHP 8.2 or newer, MySQL 8.0+ or MariaDB 10.6+, and cron access. Free hosting will not work, because it blocks the outbound connections and the cron job the automation depends on.
- Your GSM X Tool licence.
1. Activate the licence and download your copy
Log in to your account on gsmxtool.com, open Licenses and activate the licence against the exact domain you are installing on. The download unlocks as soon as the domain is registered, and the build you receive is already keyed to it. If you later move the shop to a different domain, the licence has to be moved too, so pick the address you mean to keep.
2. Upload and extract it in the document root
In cPanel open File Manager, go to the document root of the domain (for an addon domain this is usually a folder named after the domain), upload the archive and choose Extract.
Extract the contents, not a folder that contains them. If you end up withyourdomain.com/GsmXtool/appinstead ofyourdomain.com/app, the first page will be a 404. This is the single most common install problem.
3. Create an empty database
Open MySQL Databases in cPanel and create three things: a database, a user, and the link between them with All Privileges ticked. Write down the database name, the user name and the password exactly as cPanel shows them, including the account prefix (for example shopuser_gsm, not just gsm). A user that was created but never added to the database is the second most common reason an install stops.
4. Run the installer
Open your domain in a browser. On the first visit the installer takes over and works through four screens:
- It checks the PHP version, the required extensions and the folder permissions, and tells you exactly what is missing.
- It asks for the database details from step 3.
- It asks for your licence key.
- It creates the first admin account.
If the extension check fails, open Select PHP Version (or MultiPHP) in cPanel and tick what is missing. The usual suspects are bcmath, intl, zip and gd.
5. Add the cron jobs
This step is not optional and the installer cannot do it for you. Without it, orders are accepted and then never completed, because nothing is asking your suppliers for results.
In your admin panel open Supplier APIs › Cron Jobs. It lists a System line and one line for every active supplier API, each with a copy button. A line looks like this:
curl -s "https://yourdomain.com/cron/system-configuration" > /dev/null 2>&1In cPanel open Cron Jobs, choose Once Per Minute, and add each line as its own cron job. Read how to set up cron jobs for what each one does and what to do if your host has no cron.
6. Make it yours and prove the loop
Sign in to the admin panel and work down Settings in this order: site title and logo, currency, one payment gateway, and then the API key of one supplier. Then do the one test that matters:
- Add a single cheap service from that supplier.
- Register as a test customer and add a little balance.
- Place an order and watch it complete without touching anything.
When that order completes by itself, the whole chain works: storefront, balance, supplier API and cron. Everything after that is adding more services and making the shop look the way you want.
If something goes wrong
- Blank page or 404 after upload: check for the nested folder from step 2.
- Database connection error: check the prefix on the database and user names, and that the user has privileges on the database.
- Orders stuck on "In process": the cron job for that supplier API is missing. Check Supplier APIs › Cron Jobs.
Still stuck? Contact support with the domain and a screenshot of the step you are on.