PLATCOM – Installation & Usage Guide

PLATCOM Installation & Usage Guide

Setup, Run, Deploy, Maintain

This guide explains how to install, configure, and run the PLATCOM platform. It follows the structure and styling of the official PLATCOM project page while presenting technical instructions clearly.

Download Latest Release

Download PLATCOM Latest

The package includes all scripts, configuration files, and setup utilities.

Note: The PLATCOM package is protected with basic authentication. If you would like to test PLATCOM, please email us at info@rinnoco.com to receive your access credentials.

What is PLATCOM?

PLATCOM uses machine learning to predict the optimal compression algorithm for your database columns. Instead of manually testing different compression schemes, PLATCOM analyzes your data's statistical characteristics and recommends the best compression for each column.

Your Data

→

Statistical Analysis

→

ML Prediction

→

Compression Recommendation

Supported compression schemes: GZIP, ZSTD, LZMA, BZIP2

What's in the Package

After extracting PLATCOM_v[version].zip, you'll see:

Folders

bins/

Compiled binaries (setup and deployment)

data/

CSV data files used by file mode or the Envmon demo installer

scripts/

Helper scripts for import, cleanup, CSV fixing

Main Scripts (Run These)

install_project.sh

Run first! Installs dependencies and cleans previous artifacts. Start PostgreSQL separately for database mode.

install_demo.sh

Prepares the Envmon demo by downloading CSVs, configuring PLATCOM, importing the schema, and loading demo data

run_platcom.sh

Main runner for training (--setup) and prediction (--deploy)

update_platcom.sh

Updates to newer version (creates backup first)

Configuration Files

db_config.txt

Database connection settings for setup (training)

deployment_config.txt

Database connection settings for deployment (prediction)

docker-compose.yml

PostgreSQL container configuration

envmon.sql

Database schema (tables structure)

Documentation & Info

FILE_MODE.md

Documentation for CSV file mode (no database required)

VERSION.txt

Current version information

State Files (Auto-generated)

.setup_state

Tracks installation progress (allows resuming if interrupted)

Requirements

Linux (Native)

Ubuntu 20.04+ / Debian 11+
Docker & Docker Compose
Python 3.8+
4GB RAM minimum

Windows

WSL2 (Windows Subsystem for Linux)
Docker Desktop with WSL2 backend
Run all commands inside WSL terminal

Native Project Dependencies

PLATCOM is a C++17 project and requires the following system packages when building or running the native binaries on Ubuntu/Debian:

Dependency	Ubuntu/Debian package
Build tools	`build-essential`, `cmake`
OpenMP	Provided by the system compiler toolchain
ZLIB	`zlib1g-dev`
BZip2	`libbz2-dev`
LZMA	`liblzma-dev`
libzip	`libzip-dev`
Zstandard	`libzstd-dev`
PostgreSQL client library	`libpq-dev`, `postgresql-client`
Boost	`libboost-all-dev`
Armadillo	`libarmadillo-dev`
mlpack	`libmlpack-dev`
Eigen	`libeigen3-dev`

sudo apt-get update
sudo apt-get install -y build-essential cmake curl jq pv wget unzip python3 \
  docker-compose-plugin postgresql-client zlib1g-dev libbz2-dev libzip-dev \
  liblzma-dev libzstd-dev libpq-dev libboost-all-dev libarmadillo-dev \
  libmlpack-dev libeigen3-dev

Windows Users: You must use WSL2. Open a WSL terminal (Ubuntu) and run all commands there. Native Windows/PowerShell is not supported.

Sudo Required: The installer downloads and installs system dependencies (curl, jq, python3, etc.), so you'll need sudo privileges. You may be prompted for your password during installation.

Quick Start

Install

Installs dependencies and cleans previous artifacts

bash install_project.sh

For database mode, start PostgreSQL before setup:

docker compose up -d

For the full Envmon demo dataset and database import, run:

bash install_demo.sh

Train (Setup)

Analyzes your data and trains ML models

bash run_platcom.sh --setup

Output: output_[version]/output/

Report: results_[version]/setup_report.txt

Predict (Deploy)

Uses trained models to predict optimal compression

bash run_platcom.sh --deploy

Output: output_[version]/output_deployment/

Report: results_[version]/deploy_report.txt

Done! Check the results_[version]/ folder for human-readable reports.

Where Output Goes

After running setup and deployment, these folders are created:

output_[version]/
|
+-- output/ ← Created by --setup
| +-- tables_statistics.csv Column stats from all tables
| +-- best_results.csv Best compression per table
| +-- models/ Trained ML models
| +-- [table_name]/ Per-table analysis files
|
+-- output_deployment/ ← Created by --deploy
| +-- deployment_labels/
| | +-- [table_name]/
| | +-- labels Predicted compression (one per column)
| +-- deployment_aggregated_stats/
results_[version]/ ← Human-readable reports
+-- setup_report.txt Training summary & statistics
+-- deploy_report.txt Prediction results & recommendations

Tip: The reports in results_[version]/ are the most useful outputs - they summarize everything in plain English.

Two Operating Modes

Feature	Database Mode (Default)	File Mode
Data Source	PostgreSQL database	CSV files in `data/`
Requires Docker	Yes	No
Primary/Foreign Keys	Detected from schema	Not available
Best For	Production, full accuracy	Quick testing, no Docker setups
Install Command	`bash install_project.sh`	`bash install_project.sh --file-mode`
Run Command	`bash run_platcom.sh --setup`	`bash run_platcom.sh --file-mode --setup`

When to use File Mode: If you don't have Docker, want to quickly test with CSV exports, or are developing/debugging. See FILE_MODE.md for details.

Command Reference

Installer (install_project.sh)

Use this installer for the project environment. It does not download or import the demo dataset, and it does not start PostgreSQL.

Command	Description
`bash install_project.sh`	Install dependencies and clean previous artifacts
`bash install_project.sh --file-mode`	Install for CSV mode only (no Docker)
`bash install_project.sh --no-clean`	Skip cleaning previous artifacts
`bash install_project.sh --help`	Show all options

Demo Installer (install_demo.sh)

Command	Description
`bash install_demo.sh`	Download the Envmon CSV files from Zenodo, configure setup/deployment, install requirements, start PostgreSQL, import `envmon.sql`, prepare CSVs, truncate existing Envmon tables, and import demo data

Runner (run_platcom.sh)

Command	Description
`bash run_platcom.sh --setup`	Train models (required first)
`bash run_platcom.sh --deploy`	Generate predictions
`bash run_platcom.sh --file-mode --setup`	Train using CSV files
`bash run_platcom.sh --file-mode --deploy`	Predict using CSV files
`bash run_platcom.sh --clean-setup`	Remove training artifacts
`bash run_platcom.sh --clean-deployment`	Remove deployment artifacts
`bash run_platcom.sh --reset-project`	Full reset (removes everything)
`bash run_platcom.sh --help`	Show all options

Updating PLATCOM

To update to a newer version:

bash update_platcom.sh

What happens during update:

Backup Created: Your current installation is backed up to PLATCOM_backup_[timestamp]/
Data Preserved: Your data/ folder and results are kept
New Version Downloaded: Latest binaries and scripts are installed
Configs Preserved: Your db_config.txt and deployment_config.txt settings are kept

Safe to Update: Your data and trained models are preserved. If something goes wrong, you can restore from the backup folder.

Manual Rollback

If you need to go back to a previous version:

# List backups
ls -la PLATCOM_backup_*
# Restore from backup
rm -rf bins scripts *.sh
cp -r PLATCOM_backup_[timestamp]/*.

Setup vs Deployment Explained

Setup (Training Phase)

Run this first. It analyzes your data and builds ML models.

Extracts column statistics from all tables
Groups similar columns using K-means clustering
Tests all compression algorithms on each group
Trains decision trees to predict best compression
Saves trained models for deployment

Output: output_[version]/output/

Report: results_[version]/setup_report.txt

Time: 5-30 minutes depending on data size

Deployment (Prediction Phase)

Run after setup. Uses trained models to predict.

Extracts column statistics (same as setup)
Loads pre-trained clustering configuration
Assigns columns to clusters
Uses decision trees to predict compression
Outputs recommendations per table/column

Output: output_[version]/output_deployment/

Report: results_[version]/deploy_report.txt

Time: 1-5 minutes

Understanding Results

Compression Labels

Predictions use numeric labels (0-3):

Label	Scheme	Best For
0	GZIP	Compatibility, web APIs, general purpose
1	ZSTD	Best ratio + speed balance, modern systems
2	LZMA	Maximum compression, archival
3	BZIP2	High compression, batch jobs

Configuration

Edit these files to customize behavior:

db_config.txt (Setup)

# Database connection
dbname=postgres
user=postgres
password=ChangeMe!123
hostaddr=127.0.0.1
port=5432
# Row limit for setup processing, including clustering and compression
limit=LIMIT 5000
# Tables to analyze (comma-separated)
table_names=measurements_basic,measurements_dust,battery,...
# File mode (set to true for CSV mode)
file_mode=false
csv_directory=data/

deployment_config.txt (Deployment)

Same format as db_config.txt. Keep settings consistent between both.

Tip: Use limit=LIMIT 5000 for faster test runs,

limit=LIMIT
 50000

for broader processing, or leave it empty to process all rows.

Troubleshooting

Docker not starting

# Check Docker is running
docker ps
# If not, start Docker Desktop (Windows) or:
sudo systemctl start docker # Linux

"sort_index(): detected NaN" error

Some columns have invalid data. This is handled automatically, but if it persists:

rm -rf output_*/
bash run_platcom.sh --setup

"data.n_cols must equal labels.n_elem" error

Corrupted training data. Clean and re-run:

rm -rf output_*/
bash run_platcom.sh --setup

Permission denied

chmod +x *.sh scripts/*.sh

CSV import errors

The fix_csvs.py script handles most issues. If problems persist, check your CSV format:

Must have header row
Comma-separated values
UTF-8 encoding
No embedded newlines in fields