.. docs/source/administrator/server_installation.rst .. Copyright (C) 2012, University of Cambridge, Department of Psychiatry. Created by Rudolf Cardinal (rnc1001@cam.ac.uk). . This file is part of CamCOPS. . CamCOPS is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. . CamCOPS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. . You should have received a copy of the GNU General Public License along with CamCOPS. If not, see . .. _AMQP: https://en.wikipedia.org/wiki/Advanced_Message_Queuing_Protocol .. _RabbitMQ: https://www.rabbitmq.com/ .. _server_installation: (MANUAL) Installing CamCOPS on the server ========================================= .. include:: include_this_is_manual_see_docker.rst .. contents:: :local: :depth: 3 Hardware and operating system requirements ------------------------------------------ The CamCOPS server is cross-platform software written in Python. It’s been tested primarily under Linux with MySQL. URLs for CamCOPS source code ---------------------------- - https://github.com/ucam-department-of-psychiatry/camcops (for source) .. todo:: https://pypi.io/project/XXX/ (for pip install XXX) Installing CamCOPS ------------------ See :ref:`Linux flavours ` for a reminder of some common differences between Linux operating systems. 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``: .. code-block:: bash $ sudo gdebi camcops-VERSION.deb where :code:`VERSION` is the CamCOPS version you're installing. (If you don’t have gdebi, install it with :code:`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. CentOS/RHEL installation from the CamCOPS RPM package ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ First of all, :ref:`check the prerequisites for RHEL 8.6 `. .. code-block:: bash 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. Windows installation (or: generic OS installation) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Install Python (see :ref:`Installing Python for Windows `). - Install ImageMagick (see :ref:`Installing ImageMagick for Windows `). - Install RabbitMQ_, or another suitable AMQP_ broker. - Create and activate a Python 3.6+ virtual environment: .. code-block:: bash 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: .. code-block:: bash pip install camcops-server .. todo:: sort out MySQL dependencies and/or provide database driver advice .. todo:: implement Windows service 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: .. code-block:: bash sudo apt-get install apache2 mysql-client mysql-server See also the :ref:`more detailed MySQL configuration tips `. (MANUAL) Specimen installations =============================== .. include:: include_this_is_manual_see_docker.rst 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: .. code-block:: bash sudo apt install gcc # or x86_64-linux-gnu-gcc will be missing sudo apt install python3-dev # or will be missing You may also want MySQL, e.g. .. code-block:: bash 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 .. _server_installation_win10_specimen: Windows 10 ---------- - Install Python (see :ref:`Installing Python for Windows `). - Install ImageMagick (see :ref:`Installing ImageMagick for Windows `). - Install a database package, create a database, and create an ODBC connection to that database. - For SQL Server, see :ref:`Creating an SQL Server database `. - Install the CamCOPS server and a suitable database driver. .. code-block:: bat 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 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. :menuselection:`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: .. code-block:: bat 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 :ref:`DELETE takes forever `. Probably to do with constraints/triggers. Temporary workaround: use ``create_db`` instead. (However, the ``reindex`` command works fine.) - Create a superuser .. code-block:: bat camcops_server make_superuser - Create a dummy ("snake oil") SSL certificate and key, with some variation on this theme: .. code-block:: bat 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): .. code-block:: bat @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``