.. _installation: MCS Installation doc file ============================ Installation & Configuration ============================ .. index:: prerequisites, requirements, pipeline Requirements and Supported Platforms #################################### System Requirements ******************* * 64-bit Intel/AMD processor (x86_64) * Minimum 6 GB disk space to download and install. * 64-bit Linux (glibc >= 2.12) * BASH or ZSH as your default shell environment (T/CSH is NOT supported) Software Requirements ********************* Because MCS is written mostly in Python_ and ANSI C, it can run on any platform that has the required Python modules and GCC compilier. However, it has been developed and deeply tested under `CentOS`_ 7.7 and `Ubuntu`_ 19.1 x86_64 Linux OS. `Python 3.7 `_ or higher and the following packages are required: * `Astropy `_ (4.x) * `NumPy `_ (> v1.18) * `SciPy `_ (> v1.4) * `Matplotlib `_ (> v3.1) * `PyQt5 `_ * `Astroplan `_ (v0.6) * `Pyserial `_ for Serial communications * `Scikit-image `_ * `SQLAlchemy `_ The above packages are automatically included in the `Anaconda3`_ package, and then you do not need to install them manually. However, next tools need to be installed by the user following the instructions included in each package: * `SAO DS9 and XPA `_ (> v8.x) * `qimage2ndarray `_ * `sphinx`_ to build the documentation Additional packages for specific control of the FLI_ devices are required: * `fliusb `_ Finger Lakes Linux Kernel module * `libfli `_ Finger Lakes SDK library * `python-FLI `_ Python bindings for Finger Lakes Instrumentation (FLI) cameras and peripherals .. index:: installing, building, source, downloading System Installation ################### First, you need to prepare your system environment with the software components and its configuration that are required by MCS. It includes: OS Setup ******** Concerning the OS, you need to setup next steps on the OS: * UTC time: On CentOS, the system’s timezone is set during the install, but it can be easily changed at a later time, running the following command as sudo user:: $ sudo timedatectl set-timezone UTC Then, run the `timedatectl` command to verify the changes:: $ timedatectl * NTP config: On CentOS, you should run the following commands as sudo user:: $ yum install ntp $ ntpdate -s hora.roa.es (to force the update **before** ntpd is launched!) $ timedatectl $ systemctl enable ntpd $ systemctl start ntpd $ ntpstat -- To force sync no matter the current offset -- $ systemctl stop ntpd $ ntpd -gq $ systemctl start ntpd -- .. note:: Due to some compatibility problem between our CPU and CentOS kernel (3.10.0-1062), we had to tweak the clock source in the kernel as `clocksource=hpet` as follow:: Add to `/etc/default/grub` the next line:: GRUB_CMDLINE_LINUX="crashkernel=auto rd.lvm.lv=centos/root rd.lvm.lv=centos/swap rhgb quiet clocksource=hpet" And then run:: $ grub2-mkconfig $ shutdown -r now However, likely you should not need to modify you clocksource in the the kernel of your OS. Watchdog ******** MIMA instrument is an instrument to be run every night when the observing constrains are met. Thus, *MCS* must be always running properly in the control computer. In order to re-start *MCS* in case of a crash or failure, a Watchdog monitoring service must be installed in system as follow: #. Copy the file ``MCS/scripts/mcs_watchdog.sh`` to /usr/local/bin #. Edit the crontab file and add next line:: */5 * * * * bash -c "export DISPLAY=:1; export PATH=$PATH:/home/mima/anaconda3/bin; /usr/local/bin/mcs_watchdog.sh" Then, it will monitor MCS for: * It is launched * It is running properly, detecting a hangup or freeze. FLI Software ************ .. note:: We encourage to update the kernel verion and fliusb kernel module as described below. * `fliusb `_ Finger Lakes Linux Kernel module (v1.3) To install the kernel module, follow the next steps:: First you need to install next modules required for those third party tools:: $ yum install kernel-headers.x86_64 (or apt install linux-headers-amd64 linux-headers-4.9.0-3-all) $ mkdir ~/Software/MCS/; cd ~/Software/MCS/ $ wget http://www.flicamera.com/downloads/sdk/fliusb-1.3.2.tgz $ tar -xvzf fliusb-1.3.2.tgz $ cd fliusb-1.3.2 $ make $ sudo modprobe fliusb (to check the module is loaded without problems) Then, to install in the system, do the next as root: 1. Create the file /etc/modules-load.d/fli.conf and add the name of the module `fliusb`(without the .ko extension) on its first line. On boot the kernel will try to load all the modules named in this file. 2. Copy the module to a suitable folder in /lib/modules/`uname -r`/kernel/drivers. In our case this was /lib/modules/`uname -r`/kernel/drivers/fliusb/fliusb.ko. This will place the module in modprobe's database. I don't know if this can be a link. 3. Run depmod. This will find all the dependencies of your module. At this point, reboot and then run `lsmod | grep module-name` to confirm that the module was loaded at boot. Once the module is installed, you need to give access the users to /dev/fliusbX devices. For this, you have to follow the next steps: 1. Config the udev-rules file for /dev/fliusbX devices creating the next file content: /etc/udev/rules.d/52-fliusb.rules # Attempt to have FLI camera and filter_wheel device nodes (/dev/fliusbX) created with global read/write permissions KERNEL=="fliusb?" SUBSYSTEM=="usbmisc", ATTRS{idVendor}=="0f18", ATTRS{idProduct}=="0007", MODE="0666", GROUP="plugdev" KERNEL=="fliusb?" SUBSYSTEM=="usbmisc", ATTRS{idVendor}=="0f18", ATTRS{idProduct}=="000a", MODE="0666", GROUP="plugdev" The above KERNEL, SUBSYSTEM and ATTRS attributes are obtained typing: > udevadm info -a -n /dev/fliusb1 > udevadm info -a -n /dev/fliusb2 And, to re-load the rule files: > sudo udevadm control --reload-rules && udevadm trigger Now, you are ready to connect the FLI devices (CCD, Filter Wheel) to the USB ports. * `fliusb `_ Finger Lakes Linux Kernel module (v1.5) To install the kernel module, follow the next steps:: On CentOS 7.7 and kernel 3.10.x, we found some problems with the fliusb-1.3 that provoke a crash of the OS when a FLI USB device (CCD or Filter Wheel) is disconnected. So encourage to install the lastest version of the fliusb (1.5) with the kernel 5.4.156; however, it could also work in the kernel 4.x as advised by FLI. In our case (CentOS 7.7, kernel 5.4.156 + fliusb-1.5), we had to update the GCC version in order to be able to compile the fliusb kernel module. The steps we followed were: > sudo rpm --import https://www.elrepo.org/RPM-GPG-KEY-elrepo.org > sudo rpm -Uvh https://www.elrepo.org/elrepo-release-7.0-3.el7.elrepo.noarch.rpm > yum list available --disablerepo='*' --enablerepo=elrepo-kernel > yum --enablerepo=elrepo-kernel install kernel-lt > grub2-set-default 0 Install kernel sources from: > rpm -ivh https://elrepo.org/linux/kernel/el7/x86_64/RPMS/kernel-lt-devel-5.4.156-1.el7.elrepo.x86_64.rpm > rpm -ivh https://elrepo.org/linux/kernel/el7/x86_64/RPMS/kernel-lt-headers-5.4.156-1.el7.elrepo.x86_64.rpm Install GCC v9 and enable it: > yum --enablerepo=extras install centos-release-scl-rh > yum install devtoolset-9-gcc > scl enable devtoolset-9 bash Once you have updated the kernel and installed the GCC v9, you must compile and install the fliusb kernel module as described above for kernel module v1.3. * `libfli `_ Finger Lakes SDK library This SDK library is required in order python-FLI package can provide access to the C library. The SDK library should be built as a shared object, named 'libfli.so', and located in a standard library path, such as /usr/local/lib, or placed in the Python package folder after installation:: $ mkdir ~/Software/MCS/; cd ~/Software/MCS/ $ wget http://www.flicamera.com/downloads/sdk/libfli-1.104.zip $ tar -xvzf libfli-1.104.zip $ cd libfli-1.104 $ make -f Makefile.so $ cp libfli.so /usr/lib Now depending on the target Linux system /usr/local/lib might not be on the dynamic libraries path. There are many ways to get this library found, but I have a few suggestions in order of least hacky first. On Ubuntu and similar, that path could be added to the end of file /etc/ld.so.conf, which is updated next by running ldconfig. If that doesn't seem to work, you could create a symbolic link like this: sudo ln -s /usr/local/lib/libfli.so /usr/lib If ctypes is still having trouble finding the library, you could always just drop it into the python package folder (probably somewhere like: /usr/local/lib/python2.7/dist-packages/FLI-dev-py2.7.egg/FLI/ * `python-FLI `_ python-FLI binding This is the Python bindings for Finger Lakes Instrumentation (FLI) cameras and peripherals. To install:: > git clone https://github.com/SydneyAstrophotonicInstrumentationLab/python-FLI > cd python-FLI > python setup.py install .. note:: The https://github.com/cversek/python-FLI is not ready for Python3, so you must use the updated version for Python3 https://github.com/SydneyAstrophotonicInstrumentationLab/python-FLI Python environment (Anaconda) ***************************** The MCS package can be installed into a virtualenv or `Conda`_ (prefered) environment manager via pip. We recommend a fresh environment with only python installed. Via Conda: 1. Install `Anaconda3`_ (for Python 3.7), which include Conda manager:: $ sh Anaconda3-2019.10-Linux-x86_64.sh 2. Create environment (mcsenv):: $ conda create -n mcsenv python=3.7 After the installation is complete go ahead and activate the “papienv” environment. This command only needs to be executed one time per terminal session:: $ conda activate mcsenv 3. Install main Python staff not included in Anaconda:: $ conda install -c astropy $ pip install pyserial $ pip install sphinx_rtd_theme texlive-formats-extra sphinxcontrib-bibtex $ pip install pyds9 $ pip install scikit-image $ pip install qimage2ndarray $ pip install specutils .. note:: These external dependences could also be installed automatically when installing MCS due to the setup.py requirements. 4. Install Third Party tools: * DS9:: $ wget http://ds9.si.edu/download/centos7/ds9.centos7.8.1.tar.gz $ tar -xvzf ds9.centos7.8.1.tar.gz $ cp ds9 /usr/local/bin/ * XPA:: $ git clone https://github.com/ericmandel/xpa.git $ ./configure $ make install or $ yum install xpa.x86_64 Then, set XPA_METHOD=local in your .bashrc profile MCS Installation ################# The latest stable version of MCS can be downloaded from `GitHub repository `_ . To install a released (tagged) version, you can install directly from Github. To install tagged release ``mcs 2.1.0``:: $ pip install git+https://github.com/ppmim/MCS.git@2.1.0 The latest development version (from ``master``) can also be installed from Github:: $ pip install git+https://github.com/ppmim/MCS.git Also, you can install a particular commit hash:: $ pip install git+https://github.com/ppmim/MCS.git@3f03323c Installing for developers ************************* To obtain the full code, including examples and tests, you can clone the git repository:: $ git clone https://github.com/ppmim/MCS.git $ cd MCS Install from your local checked out copy as an "editable" install:: $ pip install -e . The former command will also install the dependences found in setup.py. If you want to run the tests and/or build the docs, you can make sure those dependencies are installed too:: $ pip install -e .[test] $ pip install -e .[docs] $ pip install -e .[test,docs] Note: If you wish to install directly from github, but also include the extra dependencies, the syntax is as follows:: $ pip install "papi[test] @ git+https://github.com/ppmim/MCS.git" Need other useful packages in your development environment:: $ pip install ipython flake8 pytest-xdist Edit the mcs_setup.sh and set the right values to MCS_CONFIG, and then run the script as an user:: $ ./mcs_setup.sh .. warning:: The script mcs_setup.sh is currently implemented **only** for the Bash shell, and will modify your .bashrc file adding a new line at the end. Configuring the system ********************** Once MCS is installed, you need to setup the system, that basically consists of: #. Edit ~/.mcs/config.ini with your preferences #. Create the data directories as especified in the config file Autostart of MCS GUI after login: ********************************* The computer system must to be configured for autologin and autostarup the MCS application after the system boot. For this, next steps need to be followed: - Enable user autologin: If you’re using GNOME in a single user environment, and you’re confident that nobody else will use your system, you can enable auto-logins without the password questions like this: 1. Login to GNOME as usual 2. Find your name at the top right and click on it 3. Now select Settings 4. In the new window that opens, find Users 5. Click on Unlock at the top right 6. Select your own user and turn on Automatic Logins You need supervisor privileges to make this change. Next time you restart your system, you’re logged in automatically. - Add MCS to autostartup applications: $ gnome-session-properties This will add a .desktop file in ~/.config/autostart/. You can also alternatively copy the .desktop file yourself. Building the documentation ########################## The MCS documentation is base on `sphinx`_. With the package installed, the html documentation can be built from the `doc` directory:: $ cd mcs/doc $ make html The documentation will be copied to a directory under `build/sphinx`. The documentation can be built in different formats. The complete list will appear if you type `make`. Bug reports *********** Please submit issues with the `issue tracker`_ on github. .. _MIMA: http://gapt.iaa.es/content/mima .. _sphinx: https://pypi.org/project/Sphinx/ .. _pdf: https://www.iaa.csic.es/~jmiguel/MCS/mcs.pdf .. _CentOS: http://www.centos.org/ .. _Ubuntu: https://ubuntu.com/download/desktop .. _Conda: https://docs.conda.io/projects/conda/en/latest/index.html .. _Anaconda3: https://www.anaconda.com/distribution/#download-section .. _issue tracker: https://github.com/ppmim/MCS/issues .. _Python: http://www.python.org .. _NoMachine: https://www.nomachine.com/getting-started-with-nomachine .. _ConfigParser: https://docs.python.org/3/library/configparser.html#configparser.ConfigParser .. _DS9: https://sites.google.com/cfa.harvard.edu/saoimageds9 .. _FLI: http://www.flicamera.com/software/index.html