=================================================================
SOULTRADE SOFTWARE -- VPS SETUP GUIDE
For a technically confident friend or developer
=================================================================
This document tells you everything you need to install one or
more SoulTrade applications on a fresh Linux VPS. It should take
under an hour for anyone comfortable with a Linux server.

The applications are standard PHP/MySQL on Apache -- nothing
unusual or proprietary about the stack.
=================================================================


WHAT YOU'RE INSTALLING
=================================================================

One or more of these three applications (owner to confirm which):

  CrystalSolutions (CS)   -- holistic practice management
    App folder:  /cspractice

  PraxisClinic (Praxis)   -- practice management (streamlined)
    App folder:  /praxis

  SoleTrader (ST)         -- business accounts & invoicing
    App folder:  /soletrader

Database names, usernames and passwords are shown in the
Easy Install guide -- see GETTING THE APPLICATION FILES below.

Default login for all products after install: admin / changeme
The owner should change this immediately after setup.


RECOMMENDED VPS SPEC
=================================================================

Provider:  eg Hetzner Cloud (hetzner.com) -- good value, EU-based
                     hetzner.com/cloud
Plan:       CX22 (~4 euros/month) is ample for a small practice
OS:         Ubuntu 24.04 LTS
Location:   Helsinki or Nuremberg (owner's preference)

The owner will need a domain or subdomain pointed at the
server's IP address before SSL can be configured.
e.g. practice.theirdomain.com -> server IP (A record)
Allow 10-30 minutes for DNS to propagate after setting.


SERVER SETUP
=================================================================

SSH in as root, then run the following:

-- 1. Update the system
  apt update && apt upgrade -y

-- 2. Install Apache, PHP 8.3, MySQL 8.0
  apt install -y apache2 mysql-server
  apt install -y php8.3 php8.3-mysql php8.3-mbstring php8.3-xml \
    php8.3-curl php8.3-zip php8.3-gd libapache2-mod-php8.3

-- 3. Enable Apache modules
  a2enmod rewrite headers
  systemctl restart apache2

-- 4. Install Certbot for free SSL
  apt install -y certbot python3-certbot-apache


DATABASE SETUP
=================================================================

The database names, usernames and passwords are shown in the
Easy Install guide at:
  https://soul-trade.com/install_guide.html

Run mysql -u root and execute the following for each product,
substituting the credentials from the Easy Install guide:

  CREATE DATABASE [dbname] CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
  CREATE USER '[dbuser]'@'localhost' IDENTIFIED BY '[dbpassword]';
  GRANT ALL PRIVILEGES ON [dbname].* TO '[dbuser]'@'localhost';
  FLUSH PRIVILEGES;

Then exit MySQL and import the SQL file for each product:

  mysql -u [dbuser] -p [dbname] < /tmp/01_init.sql

The 01_init.sql file is found inside the Docker zip (see below).
It is a single self-contained file that creates all tables and
seeds the default data. Safe to run with --force if needed.


GETTING THE APPLICATION FILES
=================================================================

Request the relevant Easy Install Docker zip(s) via the
download forms below. These also contain the install guide
with database credentials:

  CrystalSolutions:  https://soul-trade.com/cs_download.php?product=cs
  SoleTrader:        https://soul-trade.com/st_download.php?product=st
  PraxisClinic:      https://soul-trade.com/praxis_download.php?product=praxis

Full Easy Install guide (recommended reading before starting):
  https://soul-trade.com/install_guide.html

Each zip contains:
  ProductName/
    app/          <- the PHP application files you need
    docker/
      initdb/
        01_init.sql   <- the SQL file for database import
      apache.conf     <- reference for vhost config (see below)
      php.ini         <- reference for PHP settings

You only need the app/ folder and the docker/initdb/01_init.sql
on a VPS. The Docker files (Dockerfile, docker-compose.yml etc.)
are not used.

Upload the app/ folder contents to:
  /var/www/html/cspractice/    (CS)
  /var/www/html/praxis/        (Praxis)
  /var/www/html/soletrader/    (ST)

Set ownership:
  chown -R www-data:www-data /var/www/html/cspractice/
  chmod -R 755 /var/www/html/cspractice/
  chmod -R 775 /var/www/html/cspractice/attachments/


CONFIG FILE
=================================================================

Each app has a config.php in its root folder. Edit it to set
the database credentials (from the Easy Install guide) and
the BASE_URL:

  define('DB_HOST', 'localhost');
  define('DB_NAME', '[dbname from Easy Install guide]');
  define('DB_USER', '[dbuser from Easy Install guide]');
  define('DB_PASS', '[dbpassword from Easy Install guide]');
  define('BASE_URL', 'https://practice.theirdomain.com/cspractice');

The BASE_URL must match exactly how the app will be accessed.
No trailing slash.


APACHE VIRTUAL HOST
=================================================================

Create /etc/apache2/sites-available/soultrade.conf
The docker/apache.conf in the zip is a useful reference.
A basic working vhost looks like this:

  <VirtualHost *:80>
    ServerName practice.theirdomain.com
    DocumentRoot /var/www/html

    <Directory /var/www/html>
      AllowOverride All
      Require all granted
    </Directory>

    RedirectMatch ^/$ /cspractice/
  </VirtualHost>

Then enable it:
  a2ensite soultrade.conf
  a2dissite 000-default.conf
  systemctl reload apache2

If installing multiple products on the same server, they all
sit under /var/www/html/ as subfolders -- no separate vhosts
needed, just add more RedirectMatch lines or leave the redirect
out entirely and link from a landing page.


SSL CERTIFICATE
=================================================================

Once DNS is pointing at the server:

  certbot --apache -d practice.theirdomain.com

Follow the prompts. Certbot will obtain the certificate and
update the Apache config automatically. Auto-renewal is set up
by default -- no annual manual renewal needed.

After this, update BASE_URL in config.php to use https:// if
you set it to http:// initially.


PHP SETTINGS
=================================================================

The docker/php.ini in the zip shows the recommended settings.
Key ones to check in /etc/php/8.3/apache2/php.ini:

  upload_max_filesize = 32M
  post_max_size = 32M
  max_execution_time = 120
  memory_limit = 256M

Restart Apache after any php.ini changes:
  systemctl restart apache2


ATTACHMENTS FOLDER PERMISSIONS
=================================================================

Each app has an attachments/ folder for file uploads.
It contains a .htaccess that blocks PHP execution (security).
Make sure it is present and that the folder is writable:

  ls /var/www/html/cspractice/attachments/.htaccess
  chmod 775 /var/www/html/cspractice/attachments/

The .htaccess content should be:
  php_flag engine off
  Options -ExecCGI
  AddHandler cgi-script .php .pl .py .jsp .asp .htm .shtml .sh .cgi


FIREWALL
=================================================================

  ufw allow OpenSSH
  ufw allow 'Apache Full'
  ufw enable


FIRST LOGIN & HANDOVER
=================================================================

Once everything is running, visit:
  https://practice.theirdomain.com/cspractice

Log in with: admin / changeme

Ask the owner to:
  1. Change the admin password immediately (Setup -> Password)
  2. Enter their practice/business details (Setup -> Practice)
  3. Enable field-level encryption if desired (Setup -> Security)
     -- strongly recommended for internet-accessible installs


WHAT THE FIELD ENCRYPTION DOES (worth knowing)
=================================================================

The apps have optional AES-256-CBC field-level encryption for
sensitive patient/client records. When enabled via Setup ->
Security, sensitive fields (name, address, phone, email, notes)
are stored as ciphertext in the database. A stolen database
dump is unreadable without the encryption key, which is stored
in config.php -- never in the database itself.

This is what makes the apps suitable for GDPR-compliant
internet-accessible deployment.


IF SOMETHING ISN'T WORKING
=================================================================

  Apache error log:   tail -f /var/log/apache2/error.log
  PHP errors:         check the app's config.php -- set
                      error_reporting(E_ALL) temporarily
  DB connection:      check DB_HOST, DB_NAME, DB_USER, DB_PASS
                      in config.php match what you created
  Permissions:        most issues are www-data ownership
                      chown -R www-data:www-data /var/www/html/

For further help, post on the forum:
  https://soul-trade.com/CSForum/

=================================================================
END OF GUIDE
=================================================================