← Easy Install

Docker Easy Install — Troubleshooting

Common errors and how to fix them. If your issue isn't listed here, email jol@soul-trade.com or visit the support forum.

Before you start

CHECK
Docker Desktop must be running before installing or starting
Mac & Windows

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.

If Docker Desktop is not running, start it from your Applications folder (Mac) or Start menu (Windows) and wait 30–60 seconds for it to fully start before proceeding.
Good to know: our Docker easy installs fetch the latest PHP security release when you first install. See Keeping PHP up to date for how to refresh an install you made earlier.
The first start downloads and sets up PHP and the database, so it can take a few minutes (longer on a slow internet connection). Please leave the installer window open until your browser opens.

Windows requirements

CHECK
Windows minimum requirements for Docker Easy Install
Windows only

Requirements

  • Windows 10 version 2004 or later (Build 19041+), or Windows 11
  • 64-bit processor with hardware virtualisation enabled in BIOS
  • 4GB RAM minimum — 8GB recommended
  • WSL 2 (Windows Subsystem for Linux) — Docker Desktop installs this for you (see WSL not installed if it doesn't)
Not sure which Windows version you have? Press Windows key + R, type winver and press Enter.

Windows IoT / LTSC editions

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.

Virtualisation not enabled

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.

Windows issues

WIN
Docker Desktop: "Installation failed. One prerequisite is not fulfilled"
Windows only
Docker Desktop requires the "Virtual Machine Platform" Windows feature, which is not enabled on this machine

Cause

You chose Per-user installation in Docker's installer. On a new PC that option can't switch on a Windows feature Docker needs.

Fix

Close the message, run the Docker Desktop installer again, and choose All-users installation with WSL 2. Leave "Allow Windows Containers" unticked.

WIN
Docker says "WSL not installed"
Windows only
Windows Subsystem for Linux (WSL) is not installed

Cause

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.

Fix

  1. Click Quit on Docker's message
  2. In your extracted download, double-click Prepare Windows for Docker.bat and click Yes when Windows asks to allow changes
  3. Wait for it to say Finished, then restart your computer and open Docker Desktop again
Comfortable typing a command? Right-click the Start button, choose Terminal (Admin), run wsl --install --no-distribution, then restart. If a "Welcome to WSL" window appears afterwards, it worked: just close it.
WIN
"This application may depend on other compressed files in this folder"
Windows only
Compressed (zipped) Folders: Extract all / Run / Cancel

Cause

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.)

Fix

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).

WIN
Installer window appears briefly then disappears
Windows only
Install CrystalSolutions opens a window that immediately closes

Cause

Usually the installer is being run from inside the zip, or the download is an older one.

Fix

  1. Right-click the zip, choose Extract All, and double-click Install [Product] in the extracted folder
  2. Make sure Docker Desktop is running and showing its Containers page
  3. If it still closes, download the latest zip from soul-trade.com and try again
You don't need Run as administrator, and with older downloads it stops the installer finding its own files. Just double-click.
WIN
Installer says "SoleTrader is already installed … Nothing has been changed"
Windows only

Cause

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.

Fix

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).

WIN
"Folder In Use" when deleting or replacing the download
Windows only
The action can't be completed because the folder or a file in it is open in another program

Fix

Close the black installer window (or press any key in it) and any File Explorer window showing that folder, then click Try Again.

WIN
Windows Firewall asks about "Docker Desktop Backend"
Windows only

What to do

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.

WIN
Docker Desktop WSL2 virtualisation error
Windows only
Error: "Virtualisation support not detected" or WSL2 errors during Docker startup

Cause

Docker Desktop requires hardware virtualisation to be enabled in your PC's BIOS/UEFI settings.

Fix

  1. Restart your PC and enter BIOS/UEFI settings (usually by pressing F2, F10, or Delete during startup)
  2. Find the Virtualisation setting (may be called Intel VT-x, AMD-V, or SVM)
  3. Enable it and save
  4. Restart Windows, then try Docker Desktop again

Alternatively, in Docker Desktop Settings → General, try switching between WSL2 and Hyper-V backends.

WIN
start.bat closes immediately or shows errors
Windows only
Terminal window opens briefly then closes, or shows Docker errors

Fix

  1. Make sure Docker Desktop is running first
  2. Double-click start.bat in your install folder (not in the download)
  3. If errors appear, leave the window open and note the error message
Alternatively, open a Command Prompt in the install folder and run: docker compose up -d

Mac issues

MAC
macOS security prompt: "wants to control System Events"
Mac only
"CrystalSolutions Installer.app wants access to control System Events.app"

Fix

Click Allow — this is expected. The installer needs this permission to show progress dialogs and the folder picker. It is not accessing any personal data.

MAC
macOS won't open the installer: "cannot be opened" or "Apple could not verify"
Mac only
Gatekeeper blocks the .app installer the first time you open it

Fix

The steps differ depending on your macOS version — the old right-click trick stopped working on newer Macs:

macOS Sequoia (15) and later:

  1. Click Done on the warning (not "Move to Bin")
  2. Open System Settings → Privacy & Security
  3. Scroll down — you'll see a line saying the app was blocked, with an Open Anyway button next to it
  4. Click Open Anyway, then confirm once more if asked

macOS Sonoma (14) and earlier:

  1. Right-click (or Ctrl+click) the .app installer
  2. Choose Open from the menu
  3. Click Open in the dialog that appears
Prefer pictures? Follow the two "Open Anyway" steps with screenshots on the sample-data page (opens in new tab). Steps 2 & 3 there are the same for the installer as for the sample-data files. Then double-click the installer again.
Either way, this is only ever needed once — after the first open, macOS remembers and opens normally from then on.

Note: Full signing and notarisation requires a paid Apple Developer account and will be added in a future release.

MAC
start.command won't open: "cannot be opened"
Mac only

Fix

  1. Right-click start.command → Open
  2. Click Open in the dialog

Or use the Start button in Docker Desktop instead — it does the same thing.

Database errors

DB
Container crystalsolutions_db Error: dependency failed to start
Mac & Windows
✘ Container crystalsolutions_db   Error dependency failed to start

Cause

The database container didn't start in time on the first run, or there's a leftover volume from a previous failed install.

Fix

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:

  1. Stop and remove everything including volumes:
docker compose down -v
  1. Wait 10 seconds
  2. Start again:
docker compose up -d
The -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.
DB
"Database connection error. Please contact the administrator."
Mac, Windows & Linux

Cause

On a first install, the database spends a minute or two setting itself up. Older downloads could open your browser before it was ready.

Fix

Wait a minute and reload the page. Downloads from 14 November 2026 onwards wait for the database before opening your browser.

DB
Fatal error: show_welcome column not found after login
Mac & Windows
Fatal error: Uncaught PDOException: SQLSTATE[42S22]: Column not found: 1054 Unknown column 'show_welcome'

Cause

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.

Fix

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.

Replace crystalsolutions with soletrader or praxisclinic and adjust the username/password accordingly for other products. See the quick reference below.

Browser / URL issues

URL
403 Forbidden when visiting localhost:8080
Mac & Windows
403 Forbidden / You don't have permission to access this resource

Cause

You're visiting the root URL instead of the application subfolder.

Fix

Use the full URL including the application path:

ProductCorrect URL
CrystalSolutionshttp://localhost:8080/cspractice
SoleTraderhttp://localhost:8081/soletrader
PraxisClinichttp://localhost:8082/praxis
Newer Docker zips automatically redirect localhost:8080 to the correct URL. If you still see 403, download the latest zip from soul-trade.com/downloads/

Mac: 403 right after clicking Overwrite

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.

URL
BASE_URL or Undefined constant error on the login page
Mac & Windows
Fatal error: Uncaught Error: Undefined constant "BASE_URL"

Cause

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.

Fix

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.

Reinstalling & updating

HOW TO
Clean reinstall — remove everything and start fresh
Mac & Windows
This removes all your data. Only do this if you have no records to keep, or have backed up first via Setup → Backup.

Using the installer menu

The installer has a built-in menu. Double-click:

  • Windows: Install [Product] (just double-click; no need for Run as administrator)
  • Mac: Setup [Product].command

Choose 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.

If you want to keep your records, choose option 3 instead, or back up first via Setup → Backup before choosing option 2.
On a Mac, the installer app's Overwrite is not a clean reinstall: it keeps your records, settings and attachments. Use it to update or repair an install.
HOW TO
Keeping PHP up to date (security)
Mac & Windows
New Docker installs fetch the latest PHP security release when you first install. After that, your install keeps the PHP it was built with, so it is worth refreshing it now and then — and once if you installed before 1 November 2026.

Why

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.

To refresh PHP

  1. Open a terminal in your install folder. Mac: open Terminal, type 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.
  2. Run these two commands, one at a time:
docker compose build --pull
docker compose up -d
  1. To check, run the line for your product. The first line should show PHP 8.3.36 or newer:
docker exec crystalsolutions_app php -v
docker exec soletrader_app php -v
docker exec praxisclinic_app php -v
Your records are kept in a Docker volume and are not affected. Do not add -v to a down command for this — that deletes your records.
WIN
My records disappeared after I renamed or moved the install folder (older installs)
Mac & Windows
The software starts but looks brand new and empty

Cause

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.

Fix

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.

Downloads from 14 November 2026 onwards fix the database name inside the download, so renaming the folder no longer starts an empty database. It's still simplest not to rename or move it.
HOW TO
Update app files only — keep your existing data
Mac & Windows
Your data lives in a Docker volume, not in the app files. Updating files does not affect your records.
This updates the application, not PHP. To refresh PHP, see Keeping PHP up to date.

Windows: using the installer menu

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.

Mac: using the installer app

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.

Or manually:

  1. Stop the software in Docker Desktop
  2. Replace the files in the app/ folder with the new versions
  3. Keep config.php — it has your settings, database details and encryption key
  4. Start again in Docker Desktop
WIN
Previous install left over — new install won't start
Windows & Mac
Docker containers fail to start after a previous install attempt

Cause

A previous install left containers or database volumes behind. Simply deleting the install folder does not remove these — they live inside Docker.

Fix

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.

If you deleted the old install folder already, open Docker Desktop, go to Containers and delete any remaining containers, then go to Volumes and delete the matching volume.

Quick reference

REF
Database credentials and URLs for all three products
Mac & Windows
ProductURLDB nameDB userDB 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