.. _getting-started:

*****************************
Getting Started with |scname|
*****************************

Once the Linux system is installed the |scname| modules need to be configured including
the :ref:`initial configuration and the connection to the database <getting-started-initial>`.
The central tool to configure and control the system is :program:`seiscomp` which
is explained more deeply in the :ref:`next chapter<system-management>`. A user-friendly
graphical frontend to :program:`seiscomp` is :ref:`scconfig`.


.. _getting-started-initial:

Database Configuration
======================

Once the database server is defined and optimized as described in the section
:ref:`database_configuration` you may configure |scname| with the database.
Initially execute the steps listed in this section. You will need to consider
differences in databases:

* :ref:`MySQL <getting-started-mysql>` (not recommended),
* :ref:`MariaDB <getting-started-mariadb>`,
* :ref:`PostgreSQL <getting-started-postgresql>`.


.. _getting-started-mysql:

MySQL
-----

The initial configuration by the :program:`seiscomp` script or the
wizard of :ref:`scconfig` allows to create and configure the MySQL database
for |scname|. If you want to use MySQL continue with the
:ref:`general setup <getting-started-setup>`.

.. warning ::

   * Using MySQL is currently not recommended. Preferably use MariaDB instead of MySQL
     as MariaDB is the default SQL flavor of most supported Linux systems!
   * As of MySQL 8.0 the password encryption and policy has changed resulting in
     errors when connecting to a MySQL server. In 04/2021 this
     does not seem to be fully supported in **Ubuntu 20.04**. Therefore, you need
     to use a native password on the MySQL server.

     .. code-block:: sh

        $ sudo mysql -u root -p

          ALTER USER 'sysop'@'%%' IDENTIFIED WITH mysql_native_password BY 'my_super_secret_password_matching_the_mysql_password_validation_policy';


.. _getting-started-mariadb:

MariaDB
-------

The initial configuration by the :program:`seiscomp` script or the
wizard of :ref:`scconfig` allows to create and configure the MySQL database
for |scname|.

For setting up the database manually with MariaDB follow the instructions
below.

.. note::

    With **Ubuntu 16.04** MariaDB has become the standard flavor of MySQL in
    Ubuntu and either MariaDB or MySQL can be installed. The implementation
    of MariaDB in Ubuntu requires additional steps. They must be taken
    **before** the initial configuration in order to allow |scname| to make
    use of MariaDB. Previously, the :ref:`scconfig` wizard and
    :command:`seiscomp setup` could not be used to set up the MariaDB database.
    **The option "Create database" had to be unchecked or answered with "no"**.
    The issue is resolved in this release and both, :ref:`scconfig` wizard and
    :command:`seiscomp setup` are now fully capable of the required actions.

The full procedure to create the seiscomp database:

.. code-block:: sh

   user@host:~$ sudo mysql -u root -p
        CREATE DATABASE seiscomp CHARACTER SET utf8mb4;
        grant usage on seiscomp.* to sysop@localhost identified by 'sysop';
        grant all privileges on seiscomp.* to sysop@localhost;
        grant usage on seiscomp.* to sysop@'%' identified by 'sysop';
        grant all privileges on seiscomp.* to sysop@'%';
        flush privileges;
        quit

   user@host:~$ mysql -u sysop -p seiscomp < ~/seiscomp/share/db/mysql.sql

.. note::

   If character set 'utf8mb4' is not supported by your specific database server
   version then use the old 'utf8' format. For historical reasons, SeisComP
   would use then the 'utf8_bin' collation. The full statement looks as
   follows: :code:`CREATE DATABASE seiscomp CHARACTER SET utf8 COLLATE utf8_bin`.

.. _getting-started-postgresql:

PostgreSQL
----------

The initial configuration allows configuring the PostgreSQL database parameters
for |scname|.
It also allows :ref:`creating the database <database_configuration_postgresql>`
and the database tables.

For a manual setup of the PostgreSQL database first :ref:`setup the database
server<database_configuration_postgresql>`, then create the user, the database
and the tables.


#. Create the user and the database

   :program:`CentOS`:

   .. code-block:: sh

      sudo@host:~$ sudo su
      root@host:~$ sudo -i -u postgres
      postgres@host:~$ psql

         postgres=# create database seiscomp;
         postgres=# create user sysop with encrypted password 'sysop';
         postgres=# grant all privileges on database seiscomp to sysop;
         postgres=# alter database seiscomp owner to sysop;
         postgres=# exit

      root@host:~$ exit

#. Create the database tables

   .. code-block:: sh

      user@host:~$ psql -f ~/seiscomp/share/db/postgres.sql -t seiscomp -U sysop

Continue with the :ref:`general setup <getting-started-setup>` considering the
created database but **do not create the database again**.


.. _getting-started-setup:

General |scname| Setup
======================

Use :command:`seiscomp setup` or the wizard from within :ref:`scconfig` (:kbd:`Ctrl+N`) for the
initial configuration including the database parameters. :command:`seiscomp setup` is the
successor of the former :program:`./setup` script.

In :command:`seiscomp setup` default values are given in brackets []: ::

   user@host:~$ seiscomp/bin/seiscomp setup

   ====================================================================
   seiscomp setup
   ====================================================================

   This initializes the configuration of your installation.
   If you already made adjustments to the configuration files
   be warned that this setup will overwrite existing parameters
   with default values. This is not a configurator for all
   options of your setup but helps to setup initial standard values.

   --------------------------------------------------------------------
   Hint: Entered values starting with a dot (.) are handled
         as commands. Available commands are:

         quit: Quit setup without modification to your configuration.
         back: Go back to the previous parameter.
         help: Show help about the current parameter (if available).

         If you need to enter a value with a leading dot, escape it
         with backslash, e.g. "\.value".
   --------------------------------------------------------------------

This will ask for initial settings as database (if package trunk is installed)
parameters and the logging backend.

----

.. code-block:: none

   Organization name []:

Sets the organisation name printed e.g. when you say *hello* to Seedlink
or Arclink.

----

.. code-block:: none

   Enable database storage [yes]:

Enables or disables the database for the system. This option should be left
enabled unless all modules should connect to remote processing machine which
is already available. The database is required to store inventory information
as well as processing results. The database is the central storage for all
trunk modules and the default request handler of Arclink.

----

.. code-block:: none

    0) mysql
         MySQL server.
    1) postgresql
         PostgreSQL server. There is currently no support in setup to create the
         database for you. You have to setup the database and user accounts on
         your own. The database schema is installed under share/db/postgresql.sql.
   Database backend [0]:

If the database is enable the database backend can be selected. |scname|
supports two main backends: MySQL and PostgreSQL. Select the backend to be used
here but be prepared that only for the MySQL backend the setup can help to
create the database and tables for you. If you are using PostgreSQL you have
to provide a working database with the correct schema. The schema files are
part of the distribution and can be found in :file:`seiscomp/share/db/postgresql.sql`.

.. note::

   As of PostgreSQL version 9 the default output encoding has changed to hex.
   In order to fix issues with seiscomp log in to your database and run the
   following command.

   .. code-block:: sql

      ALTER DATABASE seiscomp SET bytea_output TO 'escape';


----

.. code-block:: none

   Create database [yes]:

.. warning ::

   If MySQL is selected it is possible to let :command:`seiscomp setup` to create
   the database and all tables for you. Otherwise currently not and you need to set up the
   database manually following the :ref:`given instructions <getting-started-mysql>`.
   If the database has been created already, answer 'no' here.

----

.. code-block:: none

   MYSQL root password (input not echoed) []:

Give the MySQL root password for your database server to create the database
tables. This is only required if the last question has been answered with 'yes'.

----

.. code-block:: none

   Drop existing database [no]:

If a database with the same name (to be selected later) exists already and the
database should be created for you, an error is raised. To delete an existing
database with the same name, say 'yes' here.

----

.. code-block:: none

   Database name [seiscomp]:
   Database hostname [localhost]:
   Database read-write user [sysop]:
   Database read-write password [sysop]:
   Database public hostname [localhost]:
   Database read-only user [sysop]:
   Database read-only password [sysop]:

Setup the various database options valid for all database backends. Give
:command:`help` for more information.

----

If all question have been answered the final choice needs to be made to either
create the initial configuration, go back to the last question or to quit
without doing anything.

.. code-block:: none

   Finished setup
   --------------

   P) Proceed to apply configuration
   B) Back to last parameter
   Q) Quit without changes
   Command? [P]:


Environment variables
=====================

Commands can be used along with the :program:`seiscomp` script located in *seiscomp/bin/seiscomp*.
Read the section :ref:`sec-management-commands` for more details on :program:`seiscomp`.
E.g. |scname| modules can be executed like ::

   user@host:~$ seiscomp/bin/seiscomp exec scrttv

Calling :program:`seiscomp` with its full path, e.g.

.. code-block:: sh

   user@host:~$ seiscomp/bin/seiscomp [command]

will load the full |scname| environment.
Providing the full path allows starting other |scname| modules in a specific
|scname| environment. Thus, multiple SeisComP installations can be maintained
and referred to on the same machine.

:program:`seiscomp` can also be used for printing the considered |scname| environment ::

   user@host:~$ seiscomp/bin/seiscomp print env

resulting in ::

   export SEISCOMP_ROOT="/home/sysop/seiscomp"
   export PATH="/home/sysop/seiscomp/bin:$PATH"
   export LD_LIBRARY_PATH="/home/sysop/seiscomp/lib:$LD_LIBRARY_PATH"
   export PYTHONPATH="/home/sysop/seiscomp/lib/python:$PYTHONPATH"
   export MANPATH="/home/sysop/seiscomp/share/man:$MANPATH"
   source "/home/sysop/seiscomp/share/shell-completion/seiscomp.bash"

For convenience, the default |scname| installation can be referred to, when defining
the required system variables, e.g. in :file:`~/.bashrc`. Then, the |scname| environment
is known to the logged in user and |scname| modules can be
executed without the :program:`seiscomp` script.

For setting the environment

#. Use the :program:`seiscomp` script itself to generate the parameters and write
   the parameters to :file:`~/.bashrc` ::

      user@host:~$ seiscomp/bin/seiscomp print env >> ~/.bashrc

#. Load the environment or log out and in again ::

      user@host:~$ source ~/.bashrc

Thereafter, modules can be executed by their names without involving :program:`seiscomp`,
e.g. ::

   user@host:~$ scrttv


Activate/Enable Modules
=======================

After the installation all module are disabled for auto start. If :command:`seiscomp start`
is called, nothing will happen until modules are enabled. To enable a set of modules,
:command:`seiscomp enable` needs to be called with a list of modules.
For example, for a processing system with SeedLink for data acquisition,
you may use:

.. code-block:: sh

   user@host:~$ seiscomp/bin/seiscomp enable seedlink slarchive scautopick scautoloc scamp scmag scevent
   enabled seedlink
   enabled slarchive
   enabled scautopick
   enabled scautoloc
   enabled scamp
   enabled scmag
   enabled scevent

A successive call of :command:`seiscomp start` will then start all enabled
modules. This is also required to restart enabled modules with :command:`seiscomp check`.

Alternatively, :ref:`scconfig<scconfig>` can be used to enable/disable
and to start/stop/restart modules.

However, before starting seiscomp, station information (metadata) need to
be provided and the configuration needs to be updated.


Supply Station Metadata
=======================

|scname| requires the metadata from seismic network and stations including full responses
for data acquisition
and processing. The metadata can be obtained from network operators or
various other sources in different formats. The metadata include, e.g.:

- Network association
- Operation times
- Location
- Sensor and data logger specifications with full response information
- Data stream specifications

|scname| comes with various importers to add metadata
for networks and stations including full response information.

:ref:`import_inv` is the tool to import inventory data into |scname|.
Alternatively can be used.

.. code-block:: sh

   user@host:~$ seiscomp/bin/seiscomp exec import_inv dlsv inventory.dataless

This will import a dataless SEED volume into `etc/inventory/inventory.dataless.xml`.

Repeat this step for all inventory data you want to import.


Configure Station Bindings
==========================

The configuration of modules and bindings is explained in :ref:`global`. To
add bindings in a more convenient way, start :ref:`scconfig`.

.. code-block:: sh

   user@host:~$ seiscomp/bin/seiscomp exec scconfig

Typical binding profiles or station bindings involve bindings configurations for
data acquisition and processing modules:

* :ref:`seedlink`: Configure the plugin for the real-time data acquisition.
* :ref:`slarchive`: Configure the data archiving.
* :ref:`global <global>`: Configure :confval:`detecStream` and :confval:`detecLocid` to determine the
  default streams for phase detection and for showing stations and streams in GUIs
  like :ref:`scmv`, :ref:`scrttv` or :ref:`scolv`.
* :ref:`scautopick`: Configure the automatic phase detection. You may overwrite global
  binding parameters.


Update Configuration, Start Everything
======================================

To update the configuration when new stations have been added or modified,
:command:`seiscomp update-config` needs to be run. This creates configuration
files of modules that do not use the configuration directly, writes the trunk
bindings to the database and synchronizes the inventory with the database.

.. code-block:: sh

   user@host:~$ seiscomp/bin/seiscomp update-config
   [output]

After the configuration has been updated and the inventory has been synchronized,
call :command:`seiscomp start` to start all enabled modules:

.. code-block:: sh

   user@host:~$ seiscomp/bin/seiscomp start
   starting seedlink
   starting slarchive
   starting scautopick
   starting scautoloc
   starting scamp
   starting scmag
   starting scevent

Now the system should run. To check everything again, :command:`seiscomp check`
can be run which should print *is running* for all started modules.
If everything is working, the analysis tools can be started, e.g. MapView.

.. code-block:: sh

   user@host:~$ seiscomp/bin/seiscomp exec scmv
