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 (downloaded during install)

scripts/

Helper scripts for import, cleanup, CSV fixing

Main Scripts (Run These)

install_project.sh

Run first! Downloads data, sets up database, installs dependencies

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

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

Downloads data, sets up PostgreSQL, installs dependencies

bash install_project.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
|   +-- decision_trees/ Trained ML models (SUM/AVG/MIN/MAX)
|   +-- [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)

Command	Description
`bash install_project.sh`	Full install: download data + setup PostgreSQL
`bash install_project.sh --file-mode`	Install for CSV mode only (no Docker)
`bash install_project.sh --skip-download`	Skip data download (use existing data/)
`bash install_project.sh --force-download`	Re-download data even if exists
`bash install_project.sh --help`	Show all options

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

# How many rows to analyze (more = slower but more accurate)
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 testing,

limit=LIMIT
                            50000

or empty for production.

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