Skip to content

InstallationDocumentation.md

Latest commit

 

History

History
503 lines (399 loc) · 12.7 KB

InstallationDocumentation.md

File metadata and controls

503 lines (399 loc) · 12.7 KB
Raw

Documentation: Installation and Configuration of OpenHalo

Table of Contents

  1. Prerequisites
  2. Downloading and Compiling OpenHalo
  3. Server Configuration
  4. Environment Variables Setup
  5. Security and Permissions
  6. Database Initialization
  7. OpenHalo/PostgreSQL Configuration
  8. MySQL Extension Activation
  9. Architecture Overview
  10. Final Verification
  11. Troubleshooting Tips
  12. Logging
  13. Stopping and Restarting OpenHalo
  14. Creating Additional Users
  15. Loading a PostgreSQL Database into OpenHalo
  16. Loading a MySQL Database into OpenHalo
  17. Backup and Restore
  18. Updating OpenHalo

Prerequisites

You need a Linux environment (for example, WSL on Windows, Ubuntu, or a Linux-based Chromebook).

Open a terminal, update your system, and install the required build tools for OpenHalo:

sudo apt-get update
sudo apt install build-essential gcc g++ make cmake autoconf uuid-dev libicu-dev zlib1g-dev libreadline-dev -y

Note: libicu-dev provides Unicode support, libreadline-dev enables command-line editing in psql, and uuid-dev is used for unique IDs in OpenHalo.

This installs a C compiler and necessary libraries for OpenHalo.

Make sure you have Git installed to clone the OpenHalo repository:

sudo apt install git

You also need to have the MySQL client installed. Here’s how to install it:

sudo apt install mysql-client-core-8.0

You may also need the PostgreSQL client to test connections independently of pg_ctl:

sudo apt install postgresql-client

Note for beginners: On some systems (Mac, Chromebook, or restricted Linux accounts), you may need to use sudo with more commands if you encounter "permission denied" errors.

Downloading and Compiling OpenHalo

Clone the OpenHalo repository from GitHub:

git clone https://github.com/HaloTech-Co-Ltd/openHalo.git

The files are cloned to your computer. Now, go into the repository directory and prepare the compilation:

cd openHalo
./configure --prefix=/home/halo/openhalo/1.0 --enable-debug --with-uuid=ossp --with-icu CFLAGS=-O2

Explanation: This checks your system for necessary libraries and creates Makefiles. Errors will be logged in config.log.

Compile and install OpenHalo:

make && make install

To compile additional modules, navigate to the contrib directory:

cd contrib
make && make install

Server Configuration

Create the halo group with ID 1000:

groupadd -g 1000 halo

Tip: If ID 1000 is already used, pick another number (for example, 1500).

Add the halo user to this group:

useradd -u 1000 -g halo halo

Check that the user and group were created:

id halo

Expected output:

uid=1000(halo) gid=1000(halo) groups=1000(halo)

Note: OpenHalo should run as halo to avoid permission issues. For extra security, you can lock halo from SSH login.

Switch to the halo user:

su - halo

If prompted for a password, create one first with:

sudo passwd halo

Environment Variables Setup

Create a persistent directory for sockets.

Since /var/run is cleared on each reboot, we need to create a systemd configuration to recreate the directory automatically.

Switch to the root user:

exit

Create a tmpfiles configuration:

sudo nano /etc/tmpfiles.d/openhalo.conf

Add this line:

d /var/run/openhalo 0755 halo halo -

Save and exit: Ctrl+O, Enter, Ctrl+X.

Apply the configuration immediately:

sudo systemd-tmpfiles --create

This will:

  • Create /var/run/openhalo with permissions 755
  • Set owner to halo:halo
  • Recreate it automatically at each system boot

Verify the directory was created:

ls -ld /var/run/openhalo

You should see:

drwxr-xr-x 2 halo halo 40 Oct 16 10:00 /var/run/openhalo

Now, switch again to the halo user:

su - halo

Set the environment variables so that the shell knows where OpenHalo binaries and data are located, and where to find libraries.

$\Rightarrow$ Option 1: Using ~/.bashrc

Edit the file:

nano ~/.bashrc

Add the following lines:

export HALO_HOME=/home/halo/openhalo/1.0 # OpenHalo binaries and libraries
export PGDATA=/home/halo/ohdata # PostgreSQL data directory
export PATH=$HALO_HOME/bin:$PATH # Add OpenHalo binaries to PATH
export LD_LIBRARY_PATH=$HALO_HOME/lib:$LD_LIBRARY_PATH # Add OpenHalo libs
export PGHOST=/var/run/openhalo # PostgreSQL socket location
alias pg_ctl='/home/halo/openhalo/1.0/bin/pg_ctl -D /home/halo/ohdata'

Save and exit: Ctrl+O, Enter, Ctrl+X.

Apply the changes:

. ~/.bashrc

$\Rightarrow$ Option 2: Using direnv (recommended if you want automatic loading in the directory)

Install direnv if not already installed:

sudo apt install direnv

Activate direnv in your shell:

echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
source ~/.bashrc

Create a .envrc file in the OpenHalo directory:

cd /home/halo/openhalo/1.0
nano .envrc

Add the same environment variable lines as above:

export HALO_HOME=/home/halo/openhalo/1.0 # OpenHalo binaries and libraries
export PGDATA=/home/halo/ohdata # PostgreSQL data directory
export PATH=$HALO_HOME/bin:$PATH # Add OpenHalo binaries to PATH
export LD_LIBRARY_PATH=$HALO_HOME/lib:$LD_LIBRARY_PATH # Add OpenHalo libs
export PGHOST=/var/run/openhalo # PostgreSQL socket location
alias pg_ctl='/home/halo/openhalo/1.0/bin/pg_ctl -D /home/halo/ohdata'

Allow direnv to load the file:

direnv allow

Note for beginners: With direnv, every time you enter this directory, variables and aliases are applied automatically. They are removed when you leave the directory.

$\Rightarrow$ Check if the environment variables are set correctly:

echo $PATH
echo $PGDATA
which pg_ctl

Note: If you encounter "permission denied" errors, try prepending sudo to commands that interact with system directories.

Security and Permissions

Never run OpenHalo as root except for installation or system commands.

Ensure proper ownership and permissions on data directories:

chown -R halo:halo /home/halo/ohdata
chmod 700 /home/halo/ohdata

Database Initialization

Initialize the database:

pg_ctl init -D $PGDATA

Explanation: Creates necessary system tables and directories for PostgreSQL.

Check status, start, stop, or restart the server:

pg_ctl status
pg_ctl start
pg_ctl restart
pg_ctl stop

Warning: Existing data in $PGDATA will be overwritten.

OpenHalo/PostgreSQL Configuration

Edit the postgresql.conf file:

nano $PGDATA/postgresql.conf

Add or modify the following lines:

listen_addresses = '*' # Listen on all IP addresses
port = 5432 # Default PostgreSQL port
database_compat_mode = 'mysql' # Enable MySQL compatibility mode
mysql.listener_on = true # Enable MySQL listener
mysql.port = 3306 # MySQL-compatible port

Save and exit: Ctrl+O, Enter, Ctrl+X.

Edit pg_hba.conf:

nano $PGDATA/pg_hba.conf

Add or modify the following lines:

# IPv4 local connections:
host    all             all             127.0.0.1/32            trust # Local IPv4 connections without password (useful for internal scripts)
host    all             all             0.0.0.0/0               scram-sha-256 # IPv4 connections from any IP with SCRAM-SHA-256 authentication

Save and exit: Ctrl+O, Enter, Ctrl+X.

Restart the server (or start it if not yet running):

pg_ctl restart

Check status:

pg_ctl status

Tip: Ensure firewall allows ports 5432 and 3306.

MySQL Extension Activation

Connect to PostgreSQL:

psql -p 5432

Create the MySQL extension:

CREATE EXTENSION aux_mysql CASCADE;

Create a MySQL-compatible user:

SET password_encryption = 'caching_sha2_password';  # Recommended for MySQL 8.0+ for stronger security. For older clients, use 'mysql_native_password'.
CREATE USER test PASSWORD 'test';
SELECT * FROM pg_shadow WHERE usename='test';

Security note: This is an example. Change the password in production for better security.

Exit PostgreSQL:

\q

Test MySQL connection:

mysql -P 3306 -h 127.0.0.1

Exit MySQL:

\q

Here are some tests to understand how the link between MySQL and PostgreSQL works:

Example

Architecture Overview

Here’s a simplified diagram showing how OpenHalo interacts with PostgreSQL and MySQL:

                 +----------------+
                 |    OpenHalo    |
                 +----------------+
                    |          |
                    |          |
                    v          v
           +----------------+  +----------------+
           |  PostgreSQL    |  |     MySQL      |
           | Port: 5432     |  | Port: 3306     |
           | Stores data    |  | MySQL Extension|
           +----------------+  +----------------+

Explanation:

  • OpenHalo acts as a middleware and can interact with both databases.
  • PostgreSQL (5432) holds the main data.
  • MySQL (3306) is used through OpenHalo’s MySQL extension for compatibility and MySQL queries.

Final Verification

Check if PostgreSQL listens on 5432 and MySQL on 3306:

pg_ctl status
ss -tlnp | grep 5432    # sudo may be required to see all processes
ss -tlnp | grep 3306

Troubleshooting Tips

  • permission denied errors → make sure you are using the halo user and check folder permissions.
  • Port already in use → check with:
ss -tlnp | grep 5432
ss -tlnp | grep 3306
  • MySQL extension not found → make sure aux_mysql is compiled and installed correctly.
  • Logs can help diagnose issues (see below).

Logging

OpenHalo/PostgreSQL logs can help debug issues. By default, logs are stored in $PGDATA.

To monitor logs in real time:

tail -f $PGDATA/logfile

You can also configure logging in postgresql.conf:

logging_collector = on
log_directory = 'pg_log'
log_filename = 'openhalo-%Y-%m-%d.log'

Stopping and Restarting OpenHalo

Stop PostgreSQL/OpenHalo at the end of a session:

pg_ctl stop

Verify the server is no longer listening:

pg_ctl status
ss -tlnp | grep 5432
ss -tlnp | grep 3306

For the next session, switch to the halo user:

su - halo

Reload environment variables if using ~/.bashrc:

. ~/.bashrc

If using direnv, just navigate to the OpenHalo directory.

Start the server and check status:

pg_ctl start
pg_ctl status

Access PostgreSQL:

psql -p 5432

Access MySQL:

mysql -P 3306 -h 127.0.0.1

Creating Additional Users

Create additional MySQL-compatible users in PostgreSQL:

psql -p 5432
SET password_encryption = 'caching_sha2_password';
CREATE USER username PASSWORD 'your_password';  # Modify as needed
CREATE DATABASE projectdb OWNER username;   # Modify as needed
\q
mysql -P 3306 -h 127.0.0.1 -uusername -p    # Modify as username

Tip: Assign privileges using GRANT ALL PRIVILEGES ON DATABASE projectdb TO username;

Loading a PostgreSQL Database into OpenHalo

psql -p 5432 -U halo -d postgres -f path/to/backup.sql

Loading a MySQL Database into OpenHalo

mysql -P 3306 -h 127.0.0.1 -utest -p < path/to/backup.sql   # Password is the one used for the MySQL user (test in this example)

Tip for beginners: If you get permission errors, try using sudo for MySQL commands.

Backup and Restore

It is recommended to backup your databases before making major changes:

  • PostgreSQL backup
pg_dump -U halo -F c -b -v -f /home/halo/backup/openhalo_backup.pgsql postgres
  • MySQL backup
mysqldump -P 3306 -h 127.0.0.1 -utest -p your_database > /home/halo/backup/mysql_backup.sql

To restore, simply use:

  • PostgreSQL restore
pg_restore -U halo -d postgres /home/halo/backup/openhalo_backup.pgsql
  • MySQL restore
mysql -P 3306 -h 127.0.0.1 -utest -p your_database < /home/halo/backup/mysql_backup.sql

Updating OpenHalo

Stop server before updating:

pg_ctl stop

To update OpenHalo to the latest version from GitHub:

cd /home/halo/openhalo
git pull
./configure --prefix=/home/halo/openhalo/1.0 --enable-debug --with-uuid=ossp --with-icu CFLAGS=-O2
make && make install