Docker Easy Install — Troubleshooting

Docker Desktop must be open and showing Running in your menu bar (Mac) or system tray (Windows) before you run any installer or start script.

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 automatically on supported versions

Windows IoT / LTSC editions

Specialist Windows editions such as IoT LTSC may require WSL 2 to be enabled manually before installing Docker Desktop. Open PowerShell as administrator and run:

wsl --install

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.

Cause

Windows PowerShell execution policy is blocking the installer script, or it needs administrator privileges.

Fix

1. Right-click Install CrystalSolutions.bat
2. Choose Run as administrator
3. Click Yes on any User Account Control prompt

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.

Fix

1. Make sure Docker Desktop is running first
2. Right-click start.bat → Run as administrator
3. If errors appear, leave the window open and note the error message

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.

Fix

1. Right-click (or Ctrl+click) the .app installer
2. Choose Open from the menu
3. Click Open in the dialog that appears

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

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.

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

1. Stop and remove everything including volumes:

docker compose down -v

2. Wait 10 seconds
3. Start again:

docker compose up -d

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, from the install folder:

docker exec -i crystalsolutions_db mysql --force \
  -u csuser -pcs_pass_2026 crystalsolutions \
  < docker/initdb/02_migrations.sql

Then refresh your browser.

Cause

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

Fix

Use the full URL including the application path:

Cause

The config.php file is missing or was not created correctly during install.

Fix

Do a fresh reinstall — see the reinstalling section below. Make sure you are using the latest Docker zip from soul-trade.com/downloads/

Using the installer menu

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

• Windows: Install [Product].bat (right-click → Run as administrator)
• Mac: Setup [Product].command

Choose option 2 — Reinstall after a failed attempt. The installer will warn you, ask you to type YES to confirm, then remove everything and start a fresh install automatically. Nothing else needed.

Using the installer menu

Double-click Install [Product].bat (Windows) or Setup [Product].command (Mac) and choose option 3 — Update app files only. Your existing records will not be touched.

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 database credentials
4. Start again in Docker Desktop

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 after a failed attempt. This clears everything cleanly before reinstalling.

Default login for all products: admin / changeme — change immediately in Setup → Password.