Common errors and how to fix them. If your issue isn't listed here, email jol@soul-trade.com or visit the support forum.
Docker Desktop must be open and running before you run any installer or start script: on a Mac it shows Running in the menu bar; on Windows its window shows the Containers page.
winver and press Enter.Specialist Windows editions such as IoT LTSC may require WSL 2 to be enabled manually before installing Docker Desktop. Double-click Prepare Windows for Docker.bat (in your extracted download) and click Yes, or right-click the Start button, choose Terminal (Admin) and run:
wsl --install --no-distribution
Then restart your computer before installing Docker Desktop.
If Docker Desktop reports that virtualisation is not available, you need to enable it in your BIOS/UEFI settings. Restart your PC, enter BIOS (usually F2, F10 or Delete during startup), find the Virtualisation or Intel VT-x / AMD-V setting and enable it, then save and restart.
You chose Per-user installation in Docker's installer. On a new PC that option can't switch on a Windows feature Docker needs.
Close the message, run the Docker Desktop installer again, and choose All-users installation with WSL 2. Leave "Allow Windows Containers" unticked.
After Docker installs, a black window asks you to "Press any key to install Windows Subsystem for Linux". It's easy to miss behind Docker's terms screen, and if it's closed, WSL never gets installed.
Prepare Windows for Docker.bat and click Yes when Windows asks to allow changeswsl --install --no-distribution, then restart. If a "Welcome to WSL" window appears afterwards, it worked: just close it.You've opened the zip and are looking inside it, rather than at an extracted folder. (A giveaway is the Compressed size and Password protected columns.)
Click Extract all, then Extract, and run Install [Product] from the new folder that opens. You'll then have a zip and a folder with the same name: use the plain yellow folder (Type: File folder).
Usually the installer is being run from inside the zip, or the download is an older one.
You chose 1. First install, but the product is already installed in the folder you picked. The installer never overwrites an existing install, so your records are safe.
Run the installer again and choose 3. Update to this version to keep your records, or 2. Reinstall from scratch to start again (this deletes everything).
Close the black installer window (or press any key in it) and any File Explorer window showing that folder, then click Try Again.
Tick Private networks, untick Public networks, and click Allow. Windows ticks Public by default; the software only needs your own PC and your home or office network.
Docker Desktop requires hardware virtualisation to be enabled in your PC's BIOS/UEFI settings.
Alternatively, in Docker Desktop Settings → General, try switching between WSL2 and Hyper-V backends.
start.bat in your install folder (not in the download)docker compose up -dClick Allow — this is expected. The installer needs this permission to show progress dialogs and the folder picker. It is not accessing any personal data.
The steps differ depending on your macOS version — the old right-click trick stopped working on newer Macs:
macOS Sequoia (15) and later:
macOS Sonoma (14) and earlier:
.app installerNote: Full signing and notarisation requires a paid Apple Developer account and will be added in a future release.
start.command → OpenOr use the Start button in Docker Desktop instead — it does the same thing.
The database container didn't start in time on the first run, or there's a leftover volume from a previous failed install.
First just try again: on a slow computer the database can take a while the first time. Run docker compose up -d in the install folder, or start it from Docker Desktop. Current downloads give the database up to five minutes before giving up.
If it still fails on a fresh install with no records:
docker compose down -v
docker compose up -d
-v flag removes the database volume. Only use this on a fresh install where you have no data to keep. If you have existing data, omit -v.On a first install, the database spends a minute or two setting itself up. Older downloads could open your browser before it was ready.
Wait a minute and reload the page. Downloads from 14 November 2026 onwards wait for the database before opening your browser.
The database migrations didn't all run on first startup. This can happen if the DB container wasn't fully ready when the SQL init scripts ran.
Run the migrations manually. In a terminal (on Windows, a Command Prompt, not PowerShell), from the install folder:
docker exec -i crystalsolutions_db mysql --force -u csuser -pcs_pass_2026 crystalsolutions < docker/initdb/01_init.sql
Then refresh your browser.
crystalsolutions with soletrader or praxisclinic and adjust the username/password accordingly for other products. See the quick reference below.You're visiting the root URL instead of the application subfolder.
Use the full URL including the application path:
| Product | Correct URL |
|---|---|
| CrystalSolutions | http://localhost:8080/cspractice |
| SoleTrader | http://localhost:8081/soletrader |
| PraxisClinic | http://localhost:8082/praxis |
localhost:8080 to the correct URL. If you still see 403, download the latest zip from soul-trade.com/downloads/Mac installers from before 15 November 2026 replaced the folder without restarting the software, so it was still looking at the old, deleted folder. Your records are fine. Open Terminal, type cd and a space, drag your install folder onto the window, press Return, then run:
docker compose up -d --force-recreate
Wait about 30 seconds and reload the page. Current Mac installers do this for you.
The config.php inside your Docker download is missing the BASE_URL setting. This affected some SoleTrader and CrystalSolutions Docker downloads built before 1 November 2026. Reinstalling from the same download will not fix it.
Download the latest Docker installer or zip from soul-trade.com/downloads/ and reinstall — see the reinstalling section below. With this error the software never opened, so you will not have lost any records. If you did have a working install with records, email jol@soul-trade.com before reinstalling.
The installer has a built-in menu. Double-click:
Install [Product] (just double-click; no need for Run as administrator)Setup [Product].commandChoose option 2 (Reinstall from scratch on Windows; Reinstall after a failed attempt on Mac). The installer warns you, asks you to type YES to confirm, then removes everything and starts a fresh install. On Windows, when it asks where to install, choose the folder that contains your existing install.
PHP released important security fixes on 21 October 2026. Docker keeps the copy of PHP it downloaded first, so an older install does not pick up newer PHP by itself.
cd and a space, drag your install folder onto the window and press Return. Windows: open the install folder in File Explorer, click in the address bar, type cmd and press Enter.docker compose build --pull
docker compose up -d
docker exec crystalsolutions_app php -v docker exec soletrader_app php -v docker exec praxisclinic_app php -v
-v to a down command for this — that deletes your records.Docker names your database storage after the install folder. If the folder is renamed, Docker starts a new, empty database. Your original records are still there, stored under the old name.
Rename the folder back to its original name (for example SoleTrader), then start the software again. Your records should reappear. Moving the folder to a different place is fine as long as its name stays the same.
Download and extract the new version, double-click Install [Product] in it, and choose 3. Update to this version. When it asks, choose the folder that contains your installed copy (usually Documents). It copies in the new program files, keeps your config.php, records and attachments, rebuilds, and applies any database changes.
Download and unzip the new version, double-click [Product]_Installer.app, and when it asks where to install, choose the same place as before (the folder that contains your [Product] folder, usually Documents). It says your product is already installed there: click Overwrite. It replaces the program files and keeps your records, config.php and attachments, then tells you when it's ready.
Or double-click Setup [Product].command and choose option 3 — Update app files only.
app/ folder with the new versionsconfig.php — it has your settings, database details and encryption keyA previous install left containers or database volumes behind. Simply deleting the install folder does not remove these — they live inside Docker.
Run the installer and choose option 2 (Reinstall from scratch on Windows; Reinstall after a failed attempt on Mac). This clears everything cleanly before reinstalling.
| Product | URL | DB name | DB user | DB password |
|---|---|---|---|---|
| CrystalSolutions | localhost:8080/cspractice |
crystalsolutions |
csuser |
cs_pass_2026 |
| SoleTrader | localhost:8081/soletrader |
soletrader |
stuser |
st_pass_2026 |
| PraxisClinic | localhost:8082/praxis |
praxisclinic |
praxisuser |
praxis_pass_2026 |
Default login for all products: admin / changeme — change immediately in Setup → Password.
Issue not listed here?
Email jol@soul-trade.com · Support forum · Full install guide · Step-by-step guides with screenshots