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.
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.
| 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 |
一条命令,自动完成全部工作:检测系统 → 配置源 → 安装包 → 创建用户 → 部署集群 → 启动服务。
# 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 个步骤:
- ✅ 检测操作系统(自动识别 Ubuntu/Debian/Rocky/Alma/CentOS/openEuler)
- ✅ 配置软件源 + 安装依赖(包括 libpqxx)
- ✅ 创建 opentenbase 用户 + SSH 免密
- ✅ 生成集群配置(GTM + Coordinator + Datanode)
- ✅ 部署并启动集群
- ✅ 验证安装(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 --yesThis 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.0What the script does automatically on EulerOS/openEuler:
- Installs
sshpass(CentOS Vault RPM fallback — EulerOS has nosshpassin its repos) - Creates the mandatory
opentenbasesystem user and configures SSH trust (home:/var/lib/opentenbase) - Pre-seeds
known_hostswith the local host key (required bypgxc_ctl's internal SSH) - For v5.0, switches to the
pgxc_ctlstartup path to avoid theopentenbase_ctlport-allocation bug
See docs/EulerOS-Deployment-Issues.md for full details.
The installation scripts automatically detect and use the fastest available mirror:
- Cloudflare CDN (
repo.blackevil217.com/scripts/for scripts,repo.blackevil217.com/aptfor APT,repo.blackevil217.com/rpmfor RPM) — global acceleration, free forever - GitHub Pages (
cduestc-openatom-open-source-club.github.io/OpenTenBase-Packages/) — direct fallback
Recommended: Use
https://repo.blackevil217.com/scripts/opentenbase.shCDN path for faster and more stable script downloads.
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.
| 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 |
| 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 | 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 |
| 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.
# 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 stopDeploy 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 -vNote 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
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/currentVersioned 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)
┌─────────────────────────────────────────────────────────────────┐
│ 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│ │
│ └───────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
| 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) |
| 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.
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 | 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.
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.
- 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)
- 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)
- RPM package support (RHEL/CentOS/Rocky/Fedora/openEuler)
- Automated CI/CD pipeline
- Standardize packaging specifications
- Code quality review and upstream contribution
| 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 |
| 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.
All 15 distros pass CI verification (install + cluster + SQL + advanced tests).
| 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 |
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| Limitation | Description |
|---|---|
| Multiple clusters on same machine | Not supported due to port conflicts; each machine runs one cluster (GTM + Coordinator + Datanode) |
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 opentenbaseCause: 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.
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 bashCause: 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.
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_ctlCause: 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 # RPMContributions are welcome — code, bug reports, and improvement suggestions!
- Fork this repository
- Create a feature branch:
git checkout -b feature/your-feature - Commit and push your changes
- Create a Pull Request
See Contributing Guide for details.
Same as OpenTenBase — Apache License 2.0.
| 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 |
Maintainer: muzimu217 Last Updated: 2026-06-29 (v5.0-p32, GTM 2-core fix + CN port 11003)