INSTALL

////////////////////////////
// Tidy Duck Installation //
////////////////////////////

============
Dependencies
============

    - MySQL  (5.5+)
    - Java   (1.8+)

===========
MySQL Setup
===========

    ----------------------
    Database Configuration
    ----------------------
        Put the connection details in the file:

            conf/server.conf

    ------------------
    Enable Strict Mode
    ------------------
        Edit /etc/mysql/my.cnf, add the following line below the 'query-cache-size' property (under the [mysqld] heading):

            sudo vim /etc/mysql/my.cnf
                sql_mode = TRADITIONAL

        (This will enable strict mode in order to enforce data integrity constraints.)

    ------------------
    Create MySQL User
    ------------------

        Create the application sql-account (with limited access)
        Be sure to modify the command below to use the password set within conf/server.conf

            mysql -u root -p tidy_duck -e "CREATE USER 'tidy_duck'@'%' IDENTIFIED BY '__PASSWORD__'; GRANT SELECT, INSERT, UPDATE, DELETE ON tidy_duck.* TO 'tidy_duck'@'%'; FLUSH PRIVILEGES;"

        If the above command fails the tidy_duck user already exist and needs re-created, the following command will delete it:

            mysql -u root -p tidy_duck -e "DROP USER tidy_duck;"

====================
Create User Accounts
====================

    1. Update the accounts sql-script:

        The default password provided is "quack quack".

            vim sql/init-accounts.sql

    2. From the tidy-duck directory, connect to MySQL and run the sql script:

            mysql -u root -p
            use tidy_duck;
            source sql/init-accounts.sql

===========
Compilation
===========

    Tidy Duck uses Java with Gradle to compile the application.
    Be sure a java-jdk is installed for your system.
    It may be a wise choice to compile the project on your local machine instead of the server.
    A convenience script is located at:

        scripts/make.sh

    This script will output all of the necessary application files to the local out directory.

==========
Deployment
==========

    After building the application with the make.sh script, upload the contents of the out directory to a desired
    location on your server.

    You may start the application using the generated run.sh. Alternatively, you may setup a systemctl service or
    daemon of your choice to run the run.sh script or emulate the script's behavior.

==========
Web Access
==========

    Tidy Duck uses a lightweight Java servlet that is configured to listen on port 8080 by default.
    Depending on your network configuration, it may be best to setup a reverse proxy.

    Alternatively, you may configure Tidy Duck to listen on the port of your choice by adding the server.httpPort
    property to the conf/server.conf file. You may also specify the TLS port with the server.tlsPort property.

===============
Troubleshooting
===============

    Depending on the server setup prior to installation you may need to take some additional steps to get started.

    -------------------------------------------
    Can't access application on configured port
    -------------------------------------------

        It's possible that a firewall setting is preventing traffic to the configured port.  Try temporarily disabling
        iptables or working with a system administrator to check any other firewall or network settings that might be
        preventing access.

    ---------------------------------------------------
    Permission denied error when accessing the database
    ---------------------------------------------------

        This can be caused by SELinux not allowing name-based resolution of the database server or some other restriction.
        Have a system administrator check the SELinux logs to determine if it is getting in the way.  Exceptions may need to
        added in order to get the application working.

        Alternatively, or at least temporarily, disable SELinux to ensure that it is not causing the problem.

    ---------------------------------------------------
    Application fails to connect to embedded database
    ---------------------------------------------------

        This can occur when running the application as root server user. It is recommended to start the application as
        another user.