Installation Guide

1. Overview & Platform Options

SoleTrader runs on any server that supports PHP 8.0+ and MySQL/MariaDB. You don't need a dedicated server — it runs happily on a Synology NAS, an old Mac or PC, a Raspberry Pi, or shared web hosting.

2. Technical Requirements

3. Data Protection & GDPR

Testing vs live use

You may test SoleTrader with dummy records on any server. However, once you begin entering real client data, the system must be on a secure, private server.

Internet vs intranet

An intranet installation runs only on your business network — client data never leaves your building. This is the recommended approach. An internet installation is accessible from anywhere — convenient for multi-location businesses, but requires stronger security measures.

Field-level encryption (recommended for shared hosting)

SoleTrader includes optional AES-256 field-level encryption for sensitive client data — email, phone, address, notes and background history. When enabled, these fields are stored as encrypted ciphertext in the database. A stolen database dump is unreadable without the encryption key.

Enable it in Setup → Security after installation. It is off by default — read the warnings carefully before enabling.

Shared hosting security checklist

• HTTPS / SSL — free via Let's Encrypt, usually one click in your host's control panel. Without it, data travels in plain text between browser and server.
• config.php permissions — set to 644 or 600 via FTP or cPanel File Manager. Prevents other users on the shared server from reading your database credentials.
• Directory listing disabled — without this, anyone visiting yoursite.com/soletrader/attachments/ could browse and download all uploaded client files. Add a file called .htaccess to your attachments/ folder containing just:
  Options -Indexes
  Most shared hosts have this on by default — check under Security or Apache settings in your control panel.
• Restricted database user — the username in config.php is what PHP uses to connect to MySQL. Create a dedicated MySQL user with only SELECT, INSERT, UPDATE and DELETE permissions (not DROP or ALTER). This means a SQL injection attack can read/write data but cannot destroy the database structure.
  This is separate from your cPanel or phpMyAdmin admin account — you retain full access as the server owner.
• Delete installer files — remove st_install.php and setup_wizard.php immediately after installation.
• Regular backups — export your database monthly via phpMyAdmin. Store backups off-server. HMRC requires records for 5+ years.

What SoleTrader does and doesn't do

• Client data is stored only on your own hardware — it never leaves your server
• No data is sent to SoleTrader, SoulTrade, or any third party
• There is no cloud backup — you are responsible for your own backups
• Access is controlled by user accounts with tiered permissions
• With encryption enabled: sensitive fields are AES-256 encrypted at rest

4. Synology NAS or QNAP— Step by Step

Most modern Synology NAS devices (DSM 7.x, 2018 onwards) support PHP and MariaDB through Package Center. Minimum 1GB RAM, 2GB recommended.
(QNAP NAS: The process is very similar — use Web Server and phpMyAdmin from the QNAP App Center, and MySQL/MariaDB for the database. The setup wizard runs identically once files are in place. )

1 Install Web Station

Package Center → search Web Station → Install.

2 Install PHP 8.2

Package Center → search PHP 8.2 → Install. Then in Web Station → Script Language Settings → click your PHP 8.2 user defined profile (not the package based profile) → Extensions tab → enable pdo_mysql, mysqli, gd. (pdo, mbstring and fileinfo are built in — they won't appear in the list and that's fine.)

3 Install MariaDB 10

Package Center → search MariaDB 10 → Install. Set a strong root password when prompted — write it down carefully. You'll need it for phpMyAdmin.

4 Install phpMyAdmin

Package Center → search phpMyAdmin → Install. To log in: username root, password is your MariaDB root password set above.

5 Enable TCP/IP in MariaDB

In Package Center → MariaDB 10 → Settings → tick Enable TCP/IP connection and note the port (default 3306). This is required for PHP to connect to the database.

6 Create the database

Open phpMyAdmin → log in as root → click New in the left panel → name the database soletrader → select collation utf8mb4_unicode_ci (scroll to the bottom of the collation dropdown — it's near the end) → click Create.

7 Create a web folder

In File Station → navigate to the web folder → create a new folder called soletrader. Full path: /volume1/web/soletrader.

8 Configure Web Station

Web Station → Web Service Portal → edit the Default Server (port 80) → set the backend to your PHP 8.2 service. If it's not already set up: Web Station → Web Service → Create → name it PHP82 → select Apache → PHP 8.2 → Save. Then assign it to the Default Server portal.

9 Upload SoleTrader files

Mount the NAS volume on your Mac/PC (or use File Station) and copy all SoleTrader files into /volume1/web/soletrader/. Make sure the attachments/ folder is included.

10 Run the installer

Open a browser on your network and go to http://[nas-ip]/soletrader/st_install.php. Fill in the form — use 127.0.0.1 as the database host. Delete the installer file after use.

5. Shared Web Hosting

SoleTrader works on most PHP shared hosting. Check your host provides PHP 8.0+ and MySQL 5.7+. Shared hosting is a convenient and affordable option — from around £3–5/month — and with the security steps below provides solid GDPR-compliant protection for client data.

1. In your hosting control panel (cPanel, Plesk etc.), create a MySQL database and note the database name, hostname, username and password
2. Upload all SoleTrader files to your web folder (e.g. public_html/soletrader/)
3. Visit https://yourdomain.com/soletrader/st_install.php
4. Enter your database details — use the full MySQL hostname from your hosting panel (e.g. mysql-200-xxx.mysql.yourhostname.net), not localhost
5. Delete st_install.php after installation

6. Windows PC — XAMPP

1. Download XAMPP from apachefriends.org — choose PHP 8.x version
2. Run installer, accept defaults. Open XAMPP Control Panel → Start Apache and MySQL
3. Copy all SoleTrader files to C:\xampp\htdocs\soletrader\
4. Open phpMyAdmin at http://localhost/phpmyadmin → create database soletrader with collation utf8mb4_unicode_ci
5. Visit http://localhost/soletrader/st_install.php — use localhost as database host, root as username, leave password blank (XAMPP default)
6. Delete st_install.php after installation

7. Apple Mac — MAMP

1. Download MAMP (free version) from mamp.info → install and open
2. Click Start — Apache and MySQL indicators should turn green
3. Copy all SoleTrader files to /Applications/MAMP/htdocs/soletrader/
4. Open phpMyAdmin at http://localhost:8888/phpmyadmin (or via MAMP's Start Page) → create database soletrader with collation utf8mb4_unicode_ci
5. Visit http://localhost:8888/soletrader/st_install.php — use localhost as host, root as username, root as password (MAMP default)
6. Delete st_install.php after installation

7b. Apple Mac — Production server (Homebrew)

For a permanent always-on business server, Homebrew gives you a proper production setup that starts automatically on boot. Recommended for a dedicated Mac Mini.

Step 1 — Install Homebrew

Open Terminal (Applications → Utilities → Terminal) and paste:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow the prompts. On Apple Silicon (M1/M2/M3) it installs to /opt/homebrew. On Intel Macs it installs to /usr/local.

Step 2 — Install PHP, MySQL and Caddy

brew install php mysql caddy

This installs PHP 8.3, MySQL 8 and Caddy (a modern web server).

Step 3 — Start MySQL and set root password

brew services start mysql
mysql_secure_installation

Set a strong root password when prompted — write it down.

Step 4 — Create the database

mysql -u root -p
CREATE DATABASE soletrader CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'csuser'@'localhost' IDENTIFIED BY 'your-password';
GRANT ALL PRIVILEGES ON soletrader.* TO 'csuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Step 5 — Configure Caddy

Create a file called Caddyfile in your home folder with this content — replace your-local-ip with your Mac's local IP address:

http://your-local-ip {
    root * /Users/Shared/www
    php_fastcgi unix//opt/homebrew/var/run/php-fpm.sock
    file_server
}

Then start Caddy and PHP-FPM:

brew services start php
brew services start caddy

Step 6 — Copy files and install

1. Create folder: mkdir -p /Users/Shared/www/soletrader
2. Copy all SoleTrader files into /Users/Shared/www/soletrader/
3. Visit http://[your-mac-ip]/soletrader/st_install.php
4. Use your database credentials from Step 4
5. Delete st_install.php after installation

Step 7 — Auto-start on boot

brew services already configures everything to start on boot. Also set: System Settings → Energy → Options → Start up automatically after a power failure.

8. Raspberry Pi

A Raspberry Pi 4 (2GB RAM, ~£55) makes an ideal always-on business server — silent, uses 3W, and fits in a pocket.

1. Install Raspberry Pi OS Lite (64-bit) using Raspberry Pi Imager. Enable SSH in the imager settings.
2. Connect to your Pi via SSH: ssh pi@[pi-ip-address]
3. Install the required software:

   sudo apt update && sudo apt upgrade -y
   sudo apt install -y apache2 php8.2 php8.2-mysql php8.2-gd \
     php8.2-mbstring php8.2-xml mariadb-server libapache2-mod-php8.2

4. Secure MariaDB: sudo mysql_secure_installation — set a root password
5. Create the database:

   sudo mysql -u root -p
   CREATE DATABASE soletrader CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   EXIT;

6. Copy SoleTrader files to /var/www/html/soletrader/
7. Set permissions: sudo chown -R www-data:www-data /var/www/html/soletrader
8. Visit http://[pi-ip]/soletrader/st_install.php — use localhost as database host, root as username
9. Delete st_install.php after installation
Total cost estimate (Raspberry Pi intranet setup):
Raspberry Pi 4 (2GB): £55–80 · SD card: £10 · Case and power supply: £15–20 · Ongoing: £0/month.
The Pi runs silently 24/7 using only 3W — less than a phone charger. Pocket-sized and tucked away in a drawer.
Kit recommendation: The official Raspberry Pi starter kit (Pi 4, case, power supply, MicroSD) costs around £80–£90 and includes everything you need. Available from raspberrypi.com, Pimoroni, or The Pi Hut.

9. Running the Installer

SoleTrader includes two installation options:

Option A — st_install.php (recommended)

A single-page installer — fill in your database details, practice name and admin credentials on one form and click Install. No sessions, no multi-step — works reliably on all platforms including Synology NAS. Full installation log shown. Delete after use.

Option B — setup_wizard.php

A 7-step guided wizard. Better for less technical users once everything is set up. Walks through licence key, pre-flight checks, database, practice details, admin account and installation in sequence.

Database host — what to enter

• Synology NAS — use 127.0.0.1 (not localhost)
• Shared hosting — use the full MySQL hostname from your hosting panel (e.g. mysql-200-xxx.mysql.host.net)
• XAMPP / MAMP / Raspberry Pi — use localhost

config.php on Synology NAS

The installer may not be able to write config.php on a Synology NAS due to folder permissions. If you see "Could not write config.php", create the file manually:

1. Create a file called config.php on your Mac/PC in a text editor
2. Paste in the full contents (all constants are required — a partial file will cause a white page)
3. Drag it into the web/soletrader/ folder via Finder or File Station
4. Re-run the installer — it will detect the existing file and skip the write step

The full list of required constants is shown in the troubleshooting section below.

After installation

Log in with your admin credentials. Go to Setup → Practice to configure your business details. The system is in trial mode — limited to 10 patients. When ready, purchase a licence and activate it in Setup → Licence.

10. Database Setup

Before running the installer you need an empty MySQL/MariaDB database.

Via phpMyAdmin (easiest)

1. Open phpMyAdmin and log in (root user + MariaDB root password on NAS/local; hosting credentials on shared hosting)
2. Click New in the left panel
3. Enter database name: soletrader
4. Select collation: utf8mb4_unicode_ci — this is near the bottom of the dropdown, scroll past all the latin/ascii entries
5. Click Create

Creating a database user (optional — not needed for root)

For production use, create a dedicated user rather than using root:

phpMyAdmin → User accounts → Add user account → enter username and password → set Host to localhost → scroll down to Global privileges → click Check all → Go.

Via command line

mysql -u root -p
CREATE DATABASE soletrader CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'csuser'@'localhost' IDENTIFIED BY 'your-password';
GRANT ALL PRIVILEGES ON soletrader.* TO 'csuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;

11. File Permissions

The attachments/ folder must be writable by the web server. It's included in the zip but may need its permissions set after uploading.

Synology NAS

File Station → right-click attachments folder → Properties → Permission → ensure the http user has Read/Write. Or via SSH:

chmod 755 /volume1/web/soletrader/attachments
chown http:http /volume1/web/soletrader/attachments

Linux / Raspberry Pi

chmod 755 /var/www/html/soletrader/attachments
chown www-data:www-data /var/www/html/soletrader/attachments

Windows (XAMPP)

No action usually needed — XAMPP runs as your Windows user which has full access.

12. Troubleshooting

500 Internal Server Error on all PHP pages

• PHP is not being served — check Web Station is using your PHP profile, not "Static website only"
• On Synology: restart Web Station after changing PHP settings
• Check the .htaccess file — on Synology it may cause issues; try removing it if pages won't load

Database connection refused

• On Synology: make sure TCP/IP connection is enabled in MariaDB settings
• Try 127.0.0.1 instead of localhost
• On shared hosting: use the full MySQL hostname from your hosting panel
• Check the database user has privileges on the soletrader database

Access denied for user

• Check the username and password are correct
• On shared hosting: the database user may need to be assigned to the database in your hosting control panel — look for "Add user to database"

Installation completes but tables aren't created

• Use st_install.php rather than the wizard — it handles SQL parsing more robustly
• Check the database is empty before running the installer (drop and recreate if needed)

Can't connect from other devices on the network

• Confirm both devices are on the same WiFi network
• Use the server's local IP address (e.g. 192.168.1.x) not localhost
• Assign a static IP to the server in your router so it doesn't change
• On Synology: check DSM Firewall allows port 80 from LAN

File uploads not working

• Check attachments/ folder exists and is writable (see File Permissions above)
• Check PHP upload_max_filesize and post_max_size in php.ini — set to at least 20M

utf8mb4_unicode_ci not found in dropdown

It's at the very bottom of the collation list in phpMyAdmin — scroll past all the latin/ascii entries. Alternatively use the SQL command: CREATE DATABASE soletrader CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

White page or 500 error after installation

• Usually means config.php is missing constants — the installer-generated file may be incomplete
• Temporarily set define('DEV_MODE', true); in config.php to show the actual PHP error
• Replace with a complete config.php containing all required constants:

  define('DB_HOST',         '127.0.0.1');
  define('DB_NAME',         'soletrader');
  define('DB_USER',         'root');
  define('DB_PASS',         'your_password');
  define('DB_CHARSET',      'utf8mb4');
  define('APP_NAME',        'SoleTrader');
  define('APP_VERSION',     '1.0');
  define('APP_ROOT',        __DIR__);
  define('BASE_URL',        'http://your-server-ip/soletrader');
  define('SESSION_NAME',    'st_session');
  define('SESSION_TIMEOUT', 7200);
  define('DATE_DISPLAY',    'd M Y');
  define('DATE_SHORT',      'd/m/Y');
  define('DATE_DB',         'Y-m-d');
  define('DEMO_MODE',       false);
  define('DEMO_MAX',        50);
  define('DEV_MODE',        false);
  define('LICENCE_SALT',    'your_salt_from_includes/licence.php');

• Revert DEV_MODE to false once resolved

Installer stalls or times out

• Use your browser Back button to return to the installer form
• It is safe to re-run — the SQL files use IF NOT EXISTS and ON DUPLICATE KEY so no data will be lost or duplicated
• Check database host — on Synology NAS use 127.0.0.1 not localhost

1451 foreign key error when dropping tables for re-installation

Run the following as a single block in phpMyAdmin SQL tab:

SET FOREIGN_KEY_CHECKS = 0;
DROP TABLE IF EXISTS invoice_lines;
DROP TABLE IF EXISTS invoices;
DROP TABLE IF EXISTS mileage_log;
DROP TABLE IF EXISTS sessions;
DROP TABLE IF EXISTS appointments;
DROP TABLE IF EXISTS letters;
DROP TABLE IF EXISTS attachments;
DROP TABLE IF EXISTS treatment_plans;
DROP TABLE IF EXISTS treatment_plan_items;
DROP TABLE IF EXISTS cpd_entries;
DROP TABLE IF EXISTS diary_settings;
DROP TABLE IF EXISTS income;
DROP TABLE IF EXISTS expenditure;
DROP TABLE IF EXISTS value_lists;
DROP TABLE IF EXISTS contacts;
DROP TABLE IF EXISTS patients;
DROP TABLE IF EXISTS practices;
DROP TABLE IF EXISTS users;
DROP TABLE IF EXISTS settings;
SET FOREIGN_KEY_CHECKS = 1;

Or simpler: phpMyAdmin → Operations tab → Drop database, then recreate fresh.