File README.SUSE of Package RackTables

General information about RackTables on (open)SUSE
==================================================

Configuration: /etc/RackTables
               while RackTables PHP Code is aware of the location, 
               we recommend to create Symlinks into the corresponding 
               directories from /etc/RackTables (which is done already 
               by the package and listed here just for completeness):

               #~ cd /usr/share/RackTables/wwwroot/
               #~ ln -s /etc/RackTables/config.php .
               #~ ln -s /etc/RackTables/secret.php .
               #~ ln -s /etc/RackTables/RackTables-search.xml .

    Beside config.php, no other file in /etc/RackTables will
    be overwritten by an update and probably all others need 
    some adaption to fit into your environment.

    Please check all configuration files in /etc/RackTables and 
    adapt them to your needs (RackTables-search.xml for example contains 
    the URL of your Racktables installation).

    RackTables decides depending on the version number in config.php 
    if it needs to run an update of the database. So this configuration 
    file will get overwritten during an update.

Apache:      /etc/apache2/vhosts.d/RackTables.conf
             As you might expect, we think the best way to run
             RackTables is as an own VHOST. Please adapt the 
             configuration to your needs, as it will not be overwritten
             during an update.

             Please note that RackTables can also be run via php-fpm.
             Feel free to use/configure it that way.             

Apparmor:    /etc/apparmor.d/abstractions/RackTables
             Currently just a single file and not very useful if not 
             loaded by Apache's mod_apparmor. The file should allow
             you to run under the 'racktables' hat.

Application: /usr/share/RackTables
             this directory, together with all the sub-directories, 
             contains the main application. Please be aware that any of 
             the files in this directory is intended to change during 
             an update.


Installation
============

= Pre-Installation =

The RackTables package should require everything that is needed to run 
RackTables on your local machine - if you have a MySQL/MariaDB database
up and running already. 

If you want to host everything on the same host, simply do something like:
~# zypper install mariadb-server
~# systemctl enable mysql
~# systemctl start mysql
~# /usr/bin/mysql_secure_installation 

==> Secure your database, if you set a database password for the root user
    (which is a good idea!), just create /root/.my.cnf with the following 
    content:

    [client]
    user = root
    password = password

    As result, 'root' should be able to login without your 'password' again.


== Adapt the Apache configuration file ==

Depending on the PHP version you choose, either do:
~# a2enmod php7
==> for PHP version 7 or:
~# a2enmod php5
==> for PHP version 5

Now you need to choose:
* if you want to run RackTables in a subdirectory like
  http://localhost/racktables/ 
  (the default), you don't need to change anything.
* if you want to run RackTables as virtual host, please have a look at
  /etc/apache2/vhosts.d/RackTables.conf.in
  => adapt it to your needs and rename it to something like:
  /etc/apache2/vhosts.d/RackTables.conf
  (the ending .conf is important)
  Don't forget to enable mod_rewrite (a2enmod rewrite) if you take the 
  example and want to redirect users to the SSL encrypted variant.


Now you are ready to start and enable apache:
~# systemctl enable apache2
~# systemctl start apache2


= Initial setup of your Racktables installation =

Visit http://localhost/racktables/ or the virtual host your created in the 
steps before. 

This should check your enviroment and ask you to do:
touch '/usr/share/RackTables/wwwroot/inc/secret.php'; chmod a=rw '/usr/share/RackTables/wwwroot/inc/secret.php'

== MySQL ==

As described in the installer, please think about a secure password for your new database user and run
the following commands on the command line of your machine:
~# mysql
MariaDB [(none)]> CREATE DATABASE racktables_db CHARACTER SET utf8 COLLATE utf8_general_ci;
MariaDB [(none)]> CREATE USER racktables_user@localhost IDENTIFIED BY 'MY_SECRET_PASSWORD';
MariaDB [(none)]> GRANT ALL PRIVILEGES ON racktables_db.* TO racktables_user@localhost;
MariaDB [(none)]> FLUSH PRIVILEGES;
MariaDB [(none)]> QUIT

Back to the Installer in your browser, please enter the 'MY_SECRET_PASSWORD' into the correct field.

Note: The standard MariaDB socket has been moved to '/run/mysql/mysql.sock' - you might need to adapt
      the default suggestion of the installer, if you want to connect to the MariaDB socket.

Please note ### SECURITY ### :
 We strongly recommend to do the following steps once you finished the initial setup:
 ~# mv /usr/share/RackTables/wwwroot/inc/secret.php /etc/RackTables/
 ~# chown root:www /etc/RackTables/secret.php
 ~# chmod 0640 /etc/RackTables/secret.php

Now choose one of the two solutions (we recommend number 1):
1) Adapt the path that RackTables uses to seach for secret.php

Edit /usr/share/RackTables/wwwroot/index.php and add the following line at the beginning of the file:
  $path_to_secret_php='/etc/RackTables/secret.php';

Somewhere before the:
  require_once 'inc/pre-init.php';
line. 

Note: that bad news here is that you need to do this again once you update the package. The good news is 
that this should save you from accidentally showing the content of this file via the webserver.


2) Create a Symlink back to the original place of secret.php
 ~# ln -s /etc/RackTables/secret.php /usr/share/RackTables/wwwroot/inc/secret.php

After that, you should be ready to proceed and finish the installer successful.
Places

File README.SUSE of Package RackTables

Places
