Skip to content

About

OpenTenBase 分布式数据库跨平台软件包仓库 — DEB/RPM for 15+ Linux distros, x86_64 & ARM64

Resources

Contributing

Stars

118 stars

Watchers

0 watching

Forks

Repository files navigation

OpenTenBase Packages

GitHub Stars GitHub Downloads GitHub Release License

English | 中文

Official cross-platform package repository for OpenTenBase — Enterprise-grade multi-format, multi-distro packaging and distribution for the OpenTenBase distributed SQL database.

Quick Start Guide (快速开始) — 5 minutes to install and run.


Overview

OpenTenBase Packages is the official packaging and distribution project for OpenTenBase, a distributed SQL database based on PostgreSQL. We provide standardized binary packages for major Linux distributions, supporting both DEB (Debian/Ubuntu) and RPM (RHEL/CentOS/Fedora) packaging systems across x86_64 and ARM64 architectures.

Goal: Build a long-term maintained, auto-built, multi-version coexisting official package repository for OpenTenBase — like PostgreSQL's apt.postgresql.org and Docker's download.docker.com.


Features

Feature Description
Multi-format DEB (.deb) + RPM (.rpm) dual format support
Multi-distro 14+ distros: Ubuntu/Debian (7), Rocky/Alma/CentOS/Fedora/openEuler/EulerOS (8) — including Huawei Cloud EulerOS (HCE) 2.0
Multi-arch x86_64 (amd64) + ARM64 (aarch64)
Multi-version coexistence Install v5.0 / v2.6 / v2.5 and dev versions side-by-side, switch with opentenbase-switch-version
Self-contained Bundles all runtime dependencies (libpq, libpqxx, libssh2) — works on any bare-metal server without pre-installed PostgreSQL
APT/RPM repository Official repository hosted on GitHub Pages — apt install opentenbase / dnf install opentenbase
One-line install curl -sSL ... | sudo bash — auto-configures repository, detects OS, resolves dependencies
CI/CD automation GitHub Actions for automated build, sign, and publish
GPG signed packages All release packages are GPG-signed (RSA 4096-bit) for authenticity verification
systemd integration Native systemd service units, managed via systemctl
Official cluster management Built-in opentenbase_ctl C++ binary — install/start/stop/status/expand/shrink via INI config
Cloudflare CDN acceleration Global CDN acceleration mirror: repo.blackevil217.com

Quick Install

一键安装(推荐)

一条命令,自动完成全部工作:检测系统 → 配置源 → 安装包 → 创建用户 → 部署集群 → 启动服务。

# CDN 加速(推荐,国内速度快 150-200 倍)
curl -sSL https://repo.blackevil217.com/scripts/opentenbase.sh | sudo bash

# GitHub 直连(备选)
curl -sSL https://raw.githubusercontent.com/CDUESTC-OpenAtom-Open-Source-Club/OpenTenBase-Packages/main/scripts/opentenbase.sh | sudo bash

# 全自动模式(无需交互,适合自动化部署)
curl -sSL https://repo.blackevil217.com/scripts/opentenbase.sh | sudo bash -s -- install --yes

脚本会自动完成 6 个步骤:

  1. ✅ 检测操作系统(自动识别 Ubuntu/Debian/Rocky/Alma/CentOS/openEuler)
  2. ✅ 配置软件源 + 安装依赖(包括 libpqxx)
  3. ✅ 创建 opentenbase 用户 + SSH 免密
  4. ✅ 生成集群配置(GTM + Coordinator + Datanode)
  5. ✅ 部署并启动集群
  6. ✅ 验证安装(SQL 测试)

运行结束后,集群已就绪,可以直接连接:

psql -h 127.0.0.1 -p 5432 -U opentenbase -d postgres

分步安装(可选)

如果你只想安装软件包,之后再手动配置集群:

第一步:配置软件源并安装包

# Ubuntu / Debian
curl -sSL https://raw.githubusercontent.com/CDUESTC-OpenAtom-Open-Source-Club/OpenTenBase-Packages/main/scripts/setup-apt.sh | sudo bash
sudo apt install -y opentenbase

# Rocky / Alma / CentOS / openEuler
curl -sSL https://raw.githubusercontent.com/CDUESTC-OpenAtom-Open-Source-Club/OpenTenBase-Packages/main/scripts/setup-rpm.sh | sudo bash
sudo dnf install -y opentenbase

第二步:部署集群

opentenbase_ctl install -c /tmp/otb_config.ini
opentenbase_ctl start
opentenbase_ctl status

卸载

# CDN 加速
curl -sSL https://repo.blackevil217.com/scripts/uninstall.sh | sudo bash

# 彻底卸载(含数据,无需确认)
curl -sSL https://repo.blackevil217.com/scripts/uninstall.sh | sudo bash -s -- --purge --yes

openEuler / EulerOS (Huawei Cloud) Support

This repository fully supports openEuler and Huawei Cloud EulerOS (HCE) 2.0 on both aarch64 (ARM64) and x86_64. The one-click script has been verified end-to-end on HCE 2.0 (aarch64):

# One-click deploy on EulerOS / openEuler (any version)
curl -sSL https://raw.githubusercontent.com/CDUESTC-OpenAtom-Open-Source-Club/OpenTenBase-Packages/main/scripts/opentenbase.sh \
  | sudo bash -s -- install --yes --version 2.6.0   # pgxc_ctl path, fully verified

# Or v5.0 — the script auto-detects EulerOS and uses pgxc_ctl to bypass the
# opentenbase_ctl port bug
curl -sSL https://raw.githubusercontent.com/CDUESTC-OpenAtom-Open-Source-Club/OpenTenBase-Packages/main/scripts/opentenbase.sh \
  | sudo bash -s -- install --yes --version 5.0

What the script does automatically on EulerOS/openEuler:

  • Installs sshpass (CentOS Vault RPM fallback — EulerOS has no sshpass in its repos)
  • Creates the mandatory opentenbase system user and configures SSH trust (home: /var/lib/opentenbase)
  • Pre-seeds known_hosts with the local host key (required by pgxc_ctl's internal SSH)
  • For v5.0, switches to the pgxc_ctl startup path to avoid the opentenbase_ctl port-allocation bug

See docs/EulerOS-Deployment-Issues.md for full details.


Mirror Acceleration (China-Optimized)

The installation scripts automatically detect and use the fastest available mirror:

  1. Cloudflare CDN (repo.blackevil217.com/scripts/ for scripts, repo.blackevil217.com/apt for APT, repo.blackevil217.com/rpm for RPM) — global acceleration, free forever
  2. GitHub Pages (cduestc-openatom-open-source-club.github.io/OpenTenBase-Packages/) — direct fallback

Recommended: Use https://repo.blackevil217.com/scripts/opentenbase.sh CDN path for faster and more stable script downloads.

China Speed Test (2026-06-02)

Test Environment: Huawei Cloud EulerOS 2.0 aarch64 (East China region)

Test Cloudflare CDN GitHub Pages Speedup
Download GPG Key 0.6s 2m12s ~200x
Download Packages index 0.3s 45s ~150x
Download opentenbase-server RPM (5.5MB) 1.2s 3m30s ~175x

Conclusion: Cloudflare CDN works in China without VPN, with ~150-200x speedup. Scripts auto-detect: CDN first, fallback to GitHub Pages on timeout.

China Installation Verification (EulerOS 2.0 aarch64)

Test Result Notes
setup-rpm.sh execution ✅ Auto-selected CDN mirror
dnf install opentenbase ✅ Installed from CDN repo
Installed versions ✅ v5.0, v2.6.0, v2.5.0 co-existing
Version switching ✅ opentenbase-switch-version works
Cluster startup ✅ GTM + Coordinator + Datanode all normal

System Requirements

Resource Minimum Recommended Notes
RAM 4 GB 4 GB+ OpenTenBase Coordinator requires ~4GB shared memory (SPM cache + connection pool + workfile manager). This is a hard requirement — cannot be reduced by tuning.
Disk 2 GB 10 GB+ Binary packages (~500MB) + data directory
CPU 1 core 2+ cores GTM thread count auto-detected from CPU cores
OS Ubuntu 20.04+, Debian 11+, RHEL 8+, Fedora 40+ See platform matrix below

Important:

  • 2GB servers cannot run OpenTenBase — Coordinator's shared memory (~4GB) exceeds available resources. This includes 2GB Cloud Studio containers.
  • Containers (Docker/K8s) have a hard cgroup memory limit and cannot add swap. Use 4GB+ containers only.
  • The setup script automatically detects memory and container environment, and will abort with clear guidance if requirements are not met.
  • On real VMs with 3-4GB RAM, the script can add swap to supplement available memory.

Package Inventory

Package Format Description
opentenbase DEB / RPM Metapackage — depends on server + client
opentenbase-server DEB / RPM Server binaries (postgres, gtm, pg_ctl) + service driver + cluster management
opentenbase-client DEB / RPM Client utilities (psql, pg_dump, pg_restore, etc.)
opentenbase-contrib DEB / RPM Extensions (pgbench, pg_stat_statements, postgres_fdw, etc.)
libopentenbase-dev DEB / RPM Development headers + static libraries + pg_config
opentenbase-doc DEB / RPM Documentation

Platform Support Matrix (CI Verified)

Distribution Version DEB RPM x86_64 aarch64
Ubuntu 20.04 / 22.04 / 24.04 / 25.04 ✅ — ✅ ✅
Debian 11 / 12 / 13 ✅ — ✅ ✅
Rocky Linux 8 / 9 — ✅ ✅ ✅
AlmaLinux 8 / 9 — ✅ ✅ ✅
CentOS Stream 8 / 9 — ✅ ✅ ✅
Fedora 40 — ✅ ✅ ✅
openEuler 22.03 / 24.03 — ✅ ✅ ✅

Total: 16 distros, 192 packages per release — 3 versions × 16 distros × 2 architectures (576 packages total)

Coverage: 100% ✅ — All distros support both x86_64 and aarch64 architectures.

ARM64 Verified: openEuler 22.03/24.03, CentOS Stream 8/9, Rocky/Alma 8/9 aarch64 — full cluster deployment confirmed on GitHub Actions arm64 runners.


Quick Start

# 1. Install cluster (GTM + Coordinator + Datanode) — -c specifies topology
opentenbase_ctl install -c /tmp/otb_config.ini

# 2. Start cluster (cluster state is persisted after install, no -c needed)
opentenbase_ctl start

# 3. Check cluster status
opentenbase_ctl status

# 4. Connect to database
opentenbase-psql -h 127.0.0.1 -p 11003 -U opentenbase -d postgres

# 5. Stop cluster
opentenbase_ctl stop

Docker Compose Deployment

Deploy a complete OpenTenBase cluster (GTM + Coordinator + 2 Datanodes) with Docker Compose:

# Download the deployment script
curl -sLO https://raw.githubusercontent.com/CDUESTC-OpenAtom-Open-Source-Club/OpenTenBase-Packages/main/docker/test-docker.sh
bash test-docker.sh

# Start the cluster
cd /tmp/otb-docker/compose
docker compose up -d --build

# Connect to the database
docker compose exec coordinator psql -h 127.0.0.1 -U opentenbase -d postgres

# Stop the cluster
docker compose down -v

Note for users in China: Docker Hub is not directly accessible from mainland China. You need to configure a Docker registry mirror. Edit /etc/docker/daemon.json:

{
  "registry-mirrors": ["https://docker.m.daocloud.io"]
}

Then restart Docker: sudo systemctl restart docker

Multi-Version Management

OpenTenBase supports multiple versions installed side-by-side, similar to PostgreSQL's postgresql-14, postgresql-15 model. Each version has its own isolated directory tree.

# List installed versions
opentenbase-switch-version

# Switch to a specific version
opentenbase-switch-version 5.0

# Switch to another version
opentenbase-switch-version 2.6.0

# Verify current version
readlink /etc/opentenbase/current

Versioned directory structure:

Path Purpose
/usr/lib/opentenbase/<version>/ Binaries and libraries per version
/etc/opentenbase/<version>/ Configuration per version
/var/lib/opentenbase/<version>/ Data directory per version
/var/log/opentenbase/<version>/ Logs per version
/etc/opentenbase/current Symlink to active version

Supported versions: 5.0 (stable), 2.6.0, 2.5.0 (historical), master-{sha} (development), latest (alias)


Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                    OpenTenBase Packages                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ┌───────────────┐   ┌───────────────┐   ┌──────────────┐     │
│   │  DEB Packages │   │  RPM Packages │   │   Docker     │     │
│   │  Ubuntu/Debian│   │  RHEL/CentOS  │   │   Images     │     │
│   │  (14 targets) │   │  (14 targets) │   │              │     │
│   └───────┬───────┘   └───────┬───────┘   └──────┬───────┘     │
│           │                   │                   │             │
│           └───────────────────┼───────────────────┘             │
│                               │                                 │
│                     ┌─────────▼─────────┐                       │
│                     │   GPG Signature   │                       │
│                     └─────────┬─────────┘                       │
│                               │                                 │
│                     ┌─────────▼─────────┐                       │
│                     │  Version Manager  │                       │
│                     │  v5.0 / v2.6 / …  │                       │
│                     └─────────┬─────────┘                       │
│                               │                                 │
│                     ┌─────────▼─────────┐                       │
│                     │  GitHub Actions   │                       │
│                     │  Auto Build & Ship│                       │
│                     └───────────────────┘                       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Installation Paths

Path Purpose
/usr/lib/opentenbase/<version>/ Binaries and libraries (isolated from system PostgreSQL)
/etc/opentenbase/<version>/ Configuration files (includes opentenbase_config.ini.example)
/var/lib/opentenbase/<version>/ Data directory
/var/log/opentenbase/<version>/ Log directory
/usr/bin/opentenbase-ctl Cluster management binary (symlink → official opentenbase_ctl)

Deployment Options

Aspect Pre-built Packages
Deploy time ~2 minutes
Image size ~500 MB
Best for Production, quick testing, evaluation

For developers who want to build from source, see source-build-guide.md.


Directory Structure

OpenTenBase-Packages/
├── README.md                # English documentation
├── README_zh.md             # Chinese documentation
├── CHANGELOG.md             # Release history
├── TEST-PLAN.md             # Test matrix and results
├── config/                  # Configuration templates
├── debian/                  # DEB packaging rules
├── rpm/                     # RPM packaging rules
├── docker/                  # Docker build environments
├── scripts/                 # Build, release, setup scripts
├── patches/                 # Source patches
├── test/                    # Automated tests
│   └── advanced/            # Advanced test suites
└── docs/                    # Guides and references
    ├── CONTRIBUTING.md      # Contributing guide
    ├── source-build-guide.md # Build from source
    ├── 01-quickstart.md     # Tutorial: quick start
    ├── 02-basic-ops.md      # Tutorial: basic operations
    ├── 03-architecture.md   # Tutorial: architecture
    ├── 04-advanced.md       # Tutorial: advanced usage
    ├── 05-troubleshoot.md   # Tutorial: troubleshooting
    ├── 06-best-practices.md # Tutorial: best practices
    ├── 07-deployment.md     # Tutorial: deployment
    └── archive/             # Archived planning docs

Release History

Release Date Assets Notes
v5.0-p32 2026-06-29 156 GTM ≤2-core crash fix (global noaffinity.so injection) + CN port 11003 + one-click deploy script e2e verification + DEB build fixes
v5.0-p31 2026-06-28 156 Official opentenbase_ctl C++ binary, CLI11/libpqxx bundling
v5.0-p11 2026-06-02 156 Cloudflare CDN acceleration documentation
v5.0-p10 2026-06-02 156 ARM64 native builds + Docker E2E + version switch fix
v5.0-p9 2026-06-01 150 Multi-version end-to-end verification on ARM64
v5.0-p8 2026-06-01 150 Stress test (7/7), cross-machine deployment, dh_install fix
v5.0-p4 2026-05-30 150 Advanced test suite (31/31), all 14 distros
v5.0-p3 2026-05-29 150 Multi-version (5.0+2.6.0+2.5.0), 15 distros
v5.0-p2 2026-05-28 50 Fix lib/postgresql path, all 15 distros
v5.0 2026-05-18 7 First release

See GitHub Releases for all releases.


Roadmap

Vision: Build a long-term maintained, auto-built, multi-version coexisting official package repository for OpenTenBase, like PostgreSQL's apt.postgresql.org and Docker's download.docker.com.

Phase 1: Foundation (1-2 weeks) -- Completed

  • Docker build environments for all target distros
  • CI workflows: 30 build targets (16 DEB + 14 RPM)
  • x86_64 + aarch64 dual architecture support
  • Multi-version coexistence (versioned paths + symlink switching)
  • Automated release pipeline (tag triggers build + test + publish)

Phase 2: Official APT Repository (1-2 months) -- Completed

  • Multi-version management (opentenbase-switch-version)
  • One-click installation script
  • GPG signing integration (RSA 4096-bit, CI automated)
  • APT/RPM repository hosting (GitHub Pages, free)

Phase 3: Cross-Platform Ecosystem (3-6 months)

  • RPM package support (RHEL/CentOS/Rocky/Fedora/openEuler)
  • Automated CI/CD pipeline
  • Standardize packaging specifications
  • Code quality review and upstream contribution

Full Distribution Support Matrix

DEB Packages (16 build targets)

Distribution Version Codename x86_64 aarch64
Ubuntu 18.04 bionic yes -
Ubuntu 18.10 cosmic yes -
Ubuntu 19.04 disco yes -
Ubuntu 19.10 eoan yes -
Ubuntu 20.04 focal yes yes
Ubuntu 22.04 jammy yes yes
Ubuntu 22.10 kinetic yes -
Ubuntu 23.10 mantic yes -
Ubuntu 24.04 noble yes yes
Ubuntu 24.10 oracular yes -
Ubuntu 25.04 plucky yes yes
Debian 9 stretch yes -
Debian 10 buster yes -
Debian 11 bullseye yes yes
Debian 12 bookworm yes yes
Debian 13 trixie yes yes

RPM Packages (18 build targets)

Distribution Version x86_64 aarch64
CentOS Stream 8 yes yes
CentOS Stream 9 yes yes
Rocky Linux 8 yes yes
Rocky Linux 9 yes yes
AlmaLinux 8 yes yes
AlmaLinux 9 yes yes
Fedora 40 yes yes
openEuler 22.03 yes yes
openEuler 24.03 yes yes

Total: 36 build targets (9 distros × 2 arch × 2 versions), x86_64 + aarch64 fully covered.

ARM64 Note: All aarch64 packages are built on GitHub Actions arm64 runners (ubuntu-24.04-arm) and verified via smoke tests. No manual build required.


Testing

All 15 distros pass CI verification (install + cluster + SQL + advanced tests).

Test Suites (38 tests total)

Suite Tests Content
Basic SQL 1 CREATE TABLE, INSERT, SELECT
Transactions 6 COMMIT/ROLLBACK, isolation, SAVEPOINT
Connection Pool 6 Concurrent connections, pool reload
Data Types 7 int, text, jsonb, timestamp, array
Performance 6 Bulk INSERT, JOIN, index effectiveness
Failover 7 Cluster health, stress R/W, data consistency
Stress Test 7 100-row INSERT, batch UPDATE/DELETE, aggregation

Cross-Machine Deployment

Verified on real hardware: devenv (ARM64, GTM+Coordinator) + 47.108 (x86_64, Datanode) connected via SSH reverse tunnel.

# Run cross-machine test
./test/cross-machine-test.sh

# Trigger stress test in CI
gh workflow run stress-test.yml

Known Limitations

Limitation Description
Multiple clusters on same machine Not supported due to port conflicts; each machine runs one cluster (GTM + Coordinator + Datanode)

Troubleshooting

Unable to locate package opentenbase

Cause: The APT source was not updated, or the unsigned repository was skipped by apt update.

Solution:

# 1. Re-run the setup script (auto-detects signing status)
curl -sSL https://raw.githubusercontent.com/CDUESTC-OpenAtom-Open-Source-Club/OpenTenBase-Packages/main/scripts/setup-apt.sh | sudo bash

# 2. Manually update
sudo apt update
sudo apt install opentenbase

The repository '... noble Release' is not signed

Cause: The repository is missing GPG signature files (Release.gpg / InRelease). The setup script will automatically fall back to trusted=yes mode. If the error persists, re-run the setup script.

GPG key download failed

Cause: Your network cannot reach the Cloudflare CDN or GitHub Pages.

Solution:

# Option 1: Retry (may be a transient network issue)
curl -sSL https://raw.githubusercontent.com/CDUESTC-OpenAtom-Open-Source-Club/OpenTenBase-Packages/main/scripts/setup-apt.sh | sudo bash

# Option 2: Manually download and install the key
curl -sSL https://repo.blackevil217.com/apt/gpg-key.asc -o /tmp/key.asc
sudo gpg --batch --dearmor -o /usr/share/keyrings/opentenbase-archive-keyring.gpg < /tmp/key.asc

# Option 3: Use a proxy
export https_proxy=http://your-proxy:port
curl -sSL https://raw.githubusercontent.com/CDUESTC-OpenAtom-Open-Source-Club/OpenTenBase-Packages/main/scripts/setup-apt.sh | sudo bash

Third-party repository 404 errors during apt-get update

Cause: A third-party repository on your system is no longer available (e.g. dl.modular.com). This is unrelated to OpenTenBase.

Solution: Check files under /etc/apt/sources.list.d/ and remove or disable the broken sources.

opentenbase-ctl: command not found after installation

Cause: The installation did not complete, or /usr/bin is not in your PATH.

Solution:

# Check if installation succeeded
dpkg -l | grep opentenbase

# Reinstall
sudo apt install --reinstall opentenbase

# Verify the binary exists (it's a symlink to the official opentenbase_ctl)
ls -la /usr/bin/opentenbase-ctl
ls -la /usr/lib/opentenbase/5.0/bin/opentenbase_ctl

error while loading shared libraries: libpqxx-6.4.so

Cause: The libpqxx runtime library is missing. This was fixed in v5.0-p30 (library is now bundled).

Solution:

# Check if the library is bundled
ls -la /usr/lib/opentenbase/5.0/lib/libpqxx*

# If missing, install from system or upgrade to v5.0-p31+
sudo apt install -y libpqxx-dev  # DEB
sudo dnf install -y libpqxx-devel  # RPM

Contributing

Contributions are welcome — code, bug reports, and improvement suggestions!

  1. Fork this repository
  2. Create a feature branch: git checkout -b feature/your-feature
  3. Commit and push your changes
  4. Create a Pull Request

See Contributing Guide for details.


License

Same as OpenTenBase — Apache License 2.0.


Links

Resource Link
This project https://github.com/CDUESTC-OpenAtom-Open-Source-Club/OpenTenBase-Packages
Upstream repo https://github.com/OpenTenBase/OpenTenBase
OpenTenBase docs https://github.com/OpenTenBase/OpenTenBase/wiki
Issue tracker Issues

Stats

Star History Chart


Maintainer: muzimu217 Last Updated: 2026-06-29 (v5.0-p32, GTM 2-core fix + CN port 11003)

About

OpenTenBase 分布式数据库跨平台软件包仓库 — DEB/RPM for 15+ Linux distros, x86_64 & ARM64

Resources

Contributing

Stars

118 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages