SoulTrade Software

Installation Guide

Not very technical?

Use the Easy Install (Docker) tab -- a double-click installer that sets everything up automatically. No databases, no server configuration.

Easy Install information →
Step-by-step guides with screenshots for Mac, Windows, Linux and NAS:   Machine & product specific install guides →
Having problems?   Docker troubleshooting guide →

Easy Install -- Docker version

The Easy Install version uses Docker to set up everything automatically. No technical knowledge required.
Our Docker easy installs fetch the latest PHP security release when you first install

Applies to: CrystalSolutions Easy Install, PraxisClinic Easy Install, SoleTrader Easy Install (also ShelfMate & BookBinder )

Step 1 -- Install Docker Desktop

Download and install Docker Desktop from docker.com/products/docker-desktop -- it's free. Start it and wait until it shows Running in your Mac's menu bar, or on Windows until its window shows the Containers page. (On Windows, choose All-users installation with WSL 2 when Docker's installer asks; the Windows guide has screenshots.)

Docker Desktop requires approximately 4GB of RAM. It runs quietly in the background and can be set to start automatically with your computer.

Step 2 -- Run the installer

Mac may show a warning the first time you open it -- something like "cannot be opened" or "Apple could not verify" this app. This is normal for any app downloaded outside the App Store, not a sign anything's wrong.

macOS Sequoia (15) and later: click Done on the warning, then go to System Settings → Privacy & Security, scroll down, and click Open Anyway.

macOS Sonoma (14) and earlier: right-click (or Ctrl+click) the .app, choose Open, then click Open again 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 needed once -- after the first open, it starts normally from then on. More detail here if you get stuck.

Double-click the installer .app (Mac). When macOS asks "would like to access your [folder name]" -- click Allow. This just lets the installer put the software in the folder you choose.

Choose your install location when prompted -- Downloads, Documents, or anywhere you like. The installer handles everything else automatically.

Windows: right-click the zip and choose Extract All, open the extracted folder, and double-click Install [product name]. If Windows warns that the publisher could not be verified, click Run. Type 1 and press Enter, then choose where to install (Documents is fine). Windows guide with screenshots →

That's it! The installer sets up the database, configures everything and opens your browser automatically.

Step 3 -- Log in

Default login: username admin password changeme. Change your password immediately in Setup → Password.

Managing via Docker Desktop

After installation, open Docker Desktop and you'll see your software listed with Start and Stop buttons. You can start and stop from there at any time.(or just quit Docker to stop)

Starting after first install

Open Docker Desktop and click Start next to your product — this is the easiest method on any platform.

Mac

Or double-click start.command in your install folder — this starts the container and opens your browser automatically.

Windows

Or double-click start.bat in your install folder.

Accessing the software in your browser

Once the container is running, go to:

The URL only works when the container is running. If you see a "can’t connect" error, open Docker Desktop first and check the container shows as running.

Stopping the software

Use the Stop button in Docker Desktop, double-click stop.command (Mac), or simply quit Docker Desktop.

Full Easy Install README

The complete README covering Mac, Windows, login details, data storage and updating is available at: easy_install_readme.txt

NAS / Linux (Synology, Raspberry Pi etc.)

The Docker zip works directly on any Linux-based NAS or server. No Mac or Windows installer needed.

Synology NAS (Container Manager)

Once set up, start and stop the software directly from Container Manager in your Synology browser interface -- no command line needed after initial setup.

  1. Install Container Manager from Synology Package Centre
  2. Copy and unzip the Docker zip to your NAS (e.g. via File Station)
  3. In Container Manager go to Project → Create
  4. Point it at the docker-compose.yml in the unzipped folder
  5. Start the project -- database sets up automatically
  6. Access from any device on your network via http://[NAS-IP]:8080/cspractice
  7. To start/stop in future -- use the Start/Stop button in Container Manager
Not comfortable with SSH or command line? Ask your IT person to do the initial setup, or use the Mac or Windows installer instead.

Linux VPS or Raspberry Pi (SSH)

  1. Copy and unzip the Docker zip to your server
  2. Install Docker: curl -fsSL https://get.docker.com | sh
  3. Run: docker compose up -d from the install folder
  4. Access via http://[server-IP]:8080/cspractice
  5. For internet access add HTTPS via Let's Encrypt / Nginx reverse proxy
The start.command and start.bat scripts are Mac/Windows only. On Linux just use docker compose up -d and docker compose down.

Your data

Your records are stored in a Docker volume on your computer and persist between restarts. Your settings (config.php) and attachments are in the install folder. Back up regularly using Setup → Backup.

Updating

Mac: unzip the new download, double-click the new Installer.app and choose the same place as before (the folder that contains your installed copy, usually Documents). When it says your product is already installed there, click Overwrite. Your records, settings and attachments are kept.

Windows: extract the new download, double-click Install [product name] and choose 3. Update to this version. When it asks, choose the folder that contains your installed copy (usually Documents). Your records, settings and attachments are kept.

Linux & NAS: see the update steps in the Linux guide on the machine-specific install guides page.

To update files only: replace files directly in the app/ subfolder of your install folder. Changes take effect immediately — no Docker restart needed. Don't replace config.php: it holds your settings, database details and encryption key.

Standard Self-Install

The standard version requires a PHP/MySQL server. The most common setup on a Mac or PC is MAMP.

Applies to: CrystalSolutions, PraxisClinic, SoleTrader (standard zip versions)

Full product-specific installation guides:

CrystalSolutions → PraxisClinic → SoleTrader →

Requirements

Using MAMP (recommended for Mac/PC)

Mac & Windows

  1. Download and install MAMP (the free version is fine)
  2. Start MAMP and click Start Servers
  3. Open phpMyAdmin from the MAMP start page and create a new database (e.g. crystalsolutions), with collation utf8mb4_unicode_ci
  4. Unzip the software into MAMP's htdocs folder, copying the whole folder in one go so the hidden .htaccess files come too:
    Mac: /Applications/MAMP/htdocs/cspractice
    Windows: C:\MAMP\htdocs\cspractice
  5. Open the web installer in your browser, e.g. http://localhost:8888/cspractice/cs_install.php on a Mac (SoleTrader: st_install.php, PraxisClinic: praxis_install.php). It sets up the database and config.php for you. Use host localhost, username root, password root (MAMP's defaults), and choose your own admin username and password.
  6. When it finishes, delete the installer file, as it reminds you

Prefer XAMPP on Windows? See the Windows guide.

On a web server (Fasthosts, SiteGround etc.)

  1. Create a MySQL database in your hosting control panel
  2. Upload the software files via FTP to a subfolder (e.g. public_html/cspractice), including the hidden .htaccess files
  3. Open the web installer, e.g. https://yourdomain.com/cspractice/cs_install.php, and enter the database details from your hosting panel. It creates the tables and config.php for you.
  4. Delete the installer file when it finishes
  5. Visit your URL (e.g. https://yourdomain.com/cspractice) and log in
Keep your installation in a private subfolder or protect it with .htaccess. This software is designed for intranet/private use, not as a public website.

Folder names

These match the BASE_URL already set in config.php. If you use a different folder name, update BASE_URL to match.

First Run & Licence

First login

Standard install (MAMP/XAMPP/hosting):
You choose your own admin username and password (at least 6 characters) in the web installer. Write them down.

Easy Install (Docker):
Username: admin   Password: changeme

For the Easy Install, change the password immediately in Setup → Password.

Trial mode

Without a licence the software runs in trial mode -- up to 10 patients/clients. All features are available in trial mode.

Entering your licence key

  1. Go to Setup → Licence
  2. Enter your licence key (format: XXXX-XXXX-XXXX-XXXX-XXX)
  3. Click Activate
  4. Unlimited records are unlocked immediately
Your licence key was emailed to you after purchase. Check your spam folder if you can't find it. Contact jol@soul-trade.com if you need it resent.

Initial setup

  1. Setup → Practice -- enter your practice name and details
  2. Setup → Users -- add any additional users
  3. Setup → Value Lists -- customise treatment types and other lists
  4. Setup → Backup -- configure regular backups

MTD (Making Tax Digital)

The MTD module for direct HMRC quarterly submissions is built in. Go to Setup → MTD / HMRC to connect your HMRC account. You'll need your own HMRC developer credentials -- see the in-software help for full instructions.

Frequently Asked Questions

Can I run this on a shared practice computer?

Yes -- the software is designed for intranet use. Multiple users can connect from different computers on the same network by pointing their browsers at the server's IP address.

Is my data safe?

All data is stored on your own computer or server -- it never leaves your machine. There is no cloud storage or third-party access. Back up regularly using Setup → Backup.

Can I move to a different computer?

Yes -- use Setup → Backup to create a backup, install the software on the new machine, then restore the backup there. This works for every kind of install.

For the Easy Install (Docker), copying the install folder on its own does not move your records: they're kept in Docker's own database storage, not in the folder. Use Backup and restore.

The software shows a blank page or error

Check that your web server (MAMP or Docker) is running. Check that the database credentials in config.php are correct. Check that all SQL files were run in order.

I've forgotten my admin password

Update the password directly in the database via phpMyAdmin -- find your user in the users table and update the password field with a new SHA-256 hash. Or email jol@soul-trade.com for help.

Can I use this on a Mac and Windows at the same time?

Yes -- install on one machine as the server, then access from other machines on the same network via the server's IP address in a browser.

Full installation guides

CrystalSolutions install guide
PraxisClinic install guide
SoleTrader install guide
Easy install guides
Machine & product specific install guides (Mac, Windows, Linux, NAS)

Support

Email: jol@soul-trade.com
Forum: soul-trade.com/CSForum/