Installation Guide

1. Overview & Platform Options

CrystalSolutions 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 CrystalSolutions with dummy records on any server. However, once you begin entering real patient data, the system must be on a secure, private server.

Internet vs intranet

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

What CrystalSolutions does and doesn't do

• Patient data is stored only on your own hardware — it never leaves your server
• No data is sent to CrystalSolutions, 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

4. Synology NAS — 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.

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 crystalsolutions → 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 cspractice. Full path: /volume1/web/cspractice.

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 CrystalSolutions files

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

10 Run the installer

Open a browser on your network and go to http://[nas-ip]/cspractice/cs_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

CrystalSolutions works on most PHP shared hosting. Check your host provides PHP 8.0+ and MySQL 5.7+.

1. In your hosting control panel, create a MySQL database and note the database name, hostname, username and password
2. Upload all CrystalSolutions files to your web folder (e.g. public_html/cspractice/)
3. Visit https://yourdomain.com/cspractice/cs_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 cs_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 CrystalSolutions files to C:\xampp\htdocs\cspractice\
4. Open phpMyAdmin at http://localhost/phpmyadmin → create database crystalsolutions with collation utf8mb4_unicode_ci
5. Visit http://localhost/cspractice/cs_install.php — use localhost as database host, root as username, leave password blank (XAMPP default)
6. Delete cs_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 CrystalSolutions files to /Applications/MAMP/htdocs/cspractice/
4. Open phpMyAdmin at http://localhost:8888/phpmyadmin (or via MAMP's Start Page) → create database crystalsolutions with collation utf8mb4_unicode_ci
5. Visit http://localhost:8888/cspractice/cs_install.php — use localhost as host, root as username, root as password (MAMP default)
6. Delete cs_install.php after installation

8. Raspberry Pi

A Raspberry Pi 4 (2GB RAM, ~£55) makes an ideal always-on practice 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 crystalsolutions CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   EXIT;

6. Copy CrystalSolutions files to /var/www/html/cspractice/
7. Set permissions: sudo chown -R www-data:www-data /var/www/html/cspractice
8. Visit http://[pi-ip]/cspractice/cs_install.php — use localhost as database host, root as username
9. Delete cs_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

CrystalSolutions includes two installation options:

Option A — cs_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

After installation

Log in with your admin credentials. Go to Setup → Practice to configure your practice 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: crystalsolutions
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 crystalsolutions CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'csuser'@'localhost' IDENTIFIED BY 'your-password';
GRANT ALL PRIVILEGES ON crystalsolutions.* 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/cspractice/attachments
chown http:http /volume1/web/cspractice/attachments

Linux / Raspberry Pi

chmod 755 /var/www/html/cspractice/attachments
chown www-data:www-data /var/www/html/cspractice/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 crystalsolutions 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 cs_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 crystalsolutions CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;