12.3. (MANUAL) Installing CamCOPS on the server

Note

These instructions relate to manual server installation. For a simpler Docker-based system, see here.

12.3.1. Hardware and operating system requirements

The CamCOPS server is cross-platform software written in Python. It’s been tested primarily under Linux with MySQL.

12.3.2. URLs for CamCOPS source code

Todo

https://pypi.io/project/XXX/ (for pip install XXX)

12.3.3. Installing CamCOPS

See Linux flavours for a reminder of some common differences between Linux operating systems.

12.3.3.1. Ubuntu installation from the CamCOPS Debian package

To install CamCOPS and all its dependencies, download the Debian package from https://github.com/ucam-department-of-psychiatry/camcops/releases and use gdebi:

$ sudo gdebi camcops-VERSION.deb

where VERSION is the CamCOPS version you’re installing. (If you don’t have gdebi, install it with sudo apt-get install gdebi.)

CamCOPS will now be installed in /usr/share/camcops.

You should be able to type camcops_server and see something relevant.

12.3.3.2. CentOS/RHEL installation from the CamCOPS RPM package

First of all, check the prerequisites for RHEL 8.6.

sudo yum install camcops_VERSION.noarch.rpm

# Or, for more verbosity and to say yes to everything, use this command instead:
# sudo yum --assumeyes --verbose --rpmverbosity=debug install camcops_VERSION.noarch.rpm
# ... but, curiously, yum temporarily swallows the output from the post-install
#     scripts and only spits it out at the end. This makes it look like the
#     installation has got stuck (because packages like numpy are very slow
#     to install); use "watch pstree" or "top" to reassure yourself
#     that progress is indeed happening.

# If accessing the internet through a proxy, where the https_proxy environment variable is
# defined, use:
# sudo -E yum install camcops_VERSION.noarch.rpm

You should be able to type camcops_server and see something relevant.

12.3.3.3. Windows installation (or: generic OS installation)

  • Install Python (see Installing Python for Windows).

  • Install ImageMagick (see Installing ImageMagick for Windows).

  • Install RabbitMQ, or another suitable AMQP broker.

  • Create and activate a Python 3.6+ virtual environment:

    export CAMCOPS_VENV=~/dev/camcops_venv
    python3 -m venv $CAMCOPS_VENV
    . $CAMCOPS_VENV/bin/activate
    pip install --upgrade pip  # just in case you have an old version of pip
    
  • Install the CamCOPS server package into that virtual environment:

    pip install camcops-server
    

Todo

sort out MySQL dependencies and/or provide database driver advice

Todo

implement Windows service

12.3.4. Installing other prerequisites

For example, you might be running Ubuntu and want to use Apache as your front-end web server and MySQL as your database:

sudo apt-get install apache2 mysql-client mysql-server

See also the more detailed MySQL configuration tips.

12.4. (MANUAL) Specimen installations

Note

These instructions relate to manual server installation. For a simpler Docker-based system, see here.

12.4.1. Ubuntu 18.04 LTS

Todo

write Ubuntu specimen installation

Starting with a bare Ubuntu 18.04 LTS installation (which comes with Python 3.6), you will need:

sudo apt install gcc  # or x86_64-linux-gnu-gcc will be missing
sudo apt install python3-dev  # or <Python.h> will be missing

You may also want MySQL, e.g.

wget -c https://dev.mysql.com/get/mysql-apt-config_0.8.10-1_all.deb
sudo dpkg -i mysql-apt-config_0.8.10-1_all.deb  # and follow on-screen instructions
sudo apt update
sudo apt install mysql-server  # and enter a root password when prompted

12.4.2. Windows 10

  • Install Python (see Installing Python for Windows).

  • Install ImageMagick (see Installing ImageMagick for Windows).

  • Install a database package, create a database, and create an ODBC connection to that database.

  • Install the CamCOPS server and a suitable database driver.

    REM -----------------------------------------------------------------------
    REM Make and activate a Python virtual environment
    REM (Note that old versions of pip may fail, so upgrade just in case.)
    REM -----------------------------------------------------------------------
    \python36\python.exe -m venv \some_path\camcops_venv
    \some_path\camcops_venv\Scripts\activate.bat
    python -m pip install --upgrade pip
    
    REM -----------------------------------------------------------------------
    REM Install the CamCOPS server
    REM -----------------------------------------------------------------------
    REM pip install camcops_server
    REM or install from a cloned git repository:
    cd \some_path
    git clone <REPOSITORY_URL>
    cd camcops\server
    pip install -e .
    
    REM -----------------------------------------------------------------------
    REM Install suitable database drivers
    REM -----------------------------------------------------------------------
    pip install pyodbc
    
    REM -----------------------------------------------------------------------
    REM Create/edit a default config file
    REM -----------------------------------------------------------------------
    camcops_server demo_camcops_config > \some_path\my_camcops_config.ini
    

    Note

    If you get the error ImportError: No module named 'tkinter', then you probably said no to installing tk/tkinter when installing Python. Run the installer again and say yes (e.g. Python 3.6.7 (64-bit) Setup ‣ Modify ‣ [✓] tcl/tk and IDLE: Installs tkinter and the IDLE development environment ‣ Next ‣ Install).

  • Edit the configuration file. In particular, as an absolute minimum you must set:

    • DB_URL

  • Create the database structure:

    camcops_server upgrade_db --config \some_path\my_camcops_config.ini
    

    You should specify this filename as an absolute path (Alembic does some directory changing that makes relative filenames fail!).

    Todo

    Current Windows problems: SQL DELETE taking forever during upgrade_db. See DELETE takes forever. Probably to do with constraints/triggers. Temporary workaround: use create_db instead. (However, the reindex command works fine.)

  • Create a superuser

    camcops_server make_superuser
    
  • Create a dummy (“snake oil”) SSL certificate and key, with some variation on this theme:

    openssl req ^
        -nodes ^
        -new ^
        -x509 ^
        -keyout dummy_ssl_private_key.key ^
        -out dummy_ssl_certificate.cert ^
        -subj "/C=UK/ST=my_state/L=my_location/O=CamCOPS testing/CN=Forename Surname"
    
    REM Note that the country code (in this case "UK") must be 2 characters max.
    
  • Launch a test server like this (directly or via a batch file):

    @echo off
    
    set IP_ADDR=127.0.0.1
    set PORT=8088
    set SSL_CERTIFICATE=C:\some_path\dummy_ssl_certificate.cert
    set SSL_KEY=C:\some_path\dummy_ssl_private_key.key
    set CAMCOPS_CONFIG_FILE=C:\some_path\test_camcops_config.ini
    
    REM Config location will be read directly from environment variable.
    REM Could also specify it with --config.
    
    camcops_server serve_cherrypy ^
        --host %IP_ADDR% ^
        --port %PORT% ^
        --debug_toolbar ^
        --verbose ^
        --ssl_certificate %SSL_CERTIFICATE% ^
        --ssl_private_key %SSL_KEY%
    
  • Browse to https://127.0.0.1:8088/ to test it.

  • Create some ID number definitions, and a group. Ensure you have a user that is uploading to that group.

  • Install the CamCOPS client. Configure and register it. Test settings:

    • Server address: 127.0.0.1

    • Server port: 8088

    • Path on server: database

    • Validate HTTPS certificates? No