Installation - Timeplus Proton

Installation Methods

Timeplus Proton can be installed using several methods depending on your platform and preferences.

Single Binary

Fastest way to get started - one command installation

Docker

Run Proton in a container with no system dependencies

Homebrew

Native macOS installation via Homebrew

Build from Source

Compile Proton yourself for custom configurations

Single Binary Installation

The easiest way to install Timeplus Proton:

curl https://install.timeplus.com/oss | sh

This script:

Detects your operating system and architecture
Downloads the appropriate Proton binary
Installs it to your system
Makes proton available in your PATH

Starting Proton

Once installed, start the server:

proton server

By default, Proton creates a proton-data folder in your current directory for configuration, logs, and data.

In another terminal, connect with the client:

proton client

Docker Installation

Run Timeplus Proton in a Docker container:

docker run -d --pull always \
  -p 8123:8123 \
  -p 8463:8463 \
  --name proton \
  d.timeplus.com/timeplus-io/proton:latest

Port Mapping

8123: HTTP interface (used by JDBC driver, batch mode by default)
8463: Native TCP protocol (used by native clients)

Make sure these ports are available and not blocked by your firewall.

Connecting to Docker Container

Start the SQL client inside the container:

docker exec -it proton proton-client

Or connect from your host machine using the HTTP interface:

curl http://localhost:8123

Persisting Data

To persist data outside the container:

docker run -d --pull always \
  -p 8123:8123 \
  -p 8463:8463 \
  -v $PWD/proton-data:/var/lib/proton \
  --name proton \
  d.timeplus.com/timeplus-io/proton:latest

Docker Compose

For a complete stack with Proton and Kafka/Redpanda:

docker-compose.yml

version: '3.8'

volumes:
  redpanda: null

services:
  proton:
    image: d.timeplus.com/timeplus-io/proton:latest
    pull_policy: always
    ports:
      - "8123:8123"  # HTTP interface
      - "8463:8463"  # Native TCP

  redpanda:
    image: docker.redpanda.com/redpandadata/redpanda:latest
    command:
      - redpanda start
      - --kafka-addr internal://0.0.0.0:9092,external://0.0.0.0:19092
      - --advertise-kafka-addr internal://redpanda:9092,external://localhost:19092
      - --smp 1
      - --memory 1G
      - --mode dev-container
    ports:
      - "19092:19092"
    volumes:
      - redpanda:/var/lib/redpanda/data

Start the stack:

docker compose up -d

Check out the ecommerce example for a complete Docker Compose setup with sample data.

Homebrew (macOS)

For Mac users, install via Homebrew:

brew install timeplus-io/timeplus/proton

Starting Proton

proton server

Updating Proton

brew upgrade timeplus-io/timeplus/proton

Uninstalling

brew uninstall proton

Build from Source

For developers who want to build Proton from source or contribute to the project.

Prerequisites

Required tools:

clang-19 or higher (clang++-19)
cmake 3.20 or higher
ninja build system
git with submodule support

Ubuntu/Debian (x86_64 or ARM64)

Install Dependencies

apt install git cmake ccache python3 ninja-build wget \
  apt-transport-https apt-utils ca-certificates dnsutils \
  gnupg iputils-ping lsb-release gpg curl software-properties-common

Install LLVM 19

wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
sudo ./llvm.sh 19

Clone and Build

git clone --recurse-submodules git@github.com:timeplus-io/proton.git
cd proton
mkdir -p build && cd build
cmake ..
ninja

Run Proton

# Start server
./programs/proton server start

# In another terminal, start client
./programs/proton client

macOS (Apple Silicon)

Verify Xcode Version

Ensure you have Xcode 14.3.1 or any version newer than 15.1 Beta 1:

/Applications/Xcode.app/Contents/Developer/usr/bin/xcodebuild -version

Expected output:

Xcode 14.3.1
Build version 14E300c

Install Dependencies

brew update
brew install ccache cmake ninja libtool gettext llvm@19 gcc \
  binutils grep findutils libiconv

Set Environment Variables

export PATH=$(brew --prefix llvm@19)/bin:$PATH
export CC=$(brew --prefix llvm@19)/bin/clang
export CXX=$(brew --prefix llvm@19)/bin/clang++

Clone and Build

git clone --recurse-submodules git@github.com:timeplus-io/proton.git
cd proton
mkdir -p build && cd build
cmake ..
ninja

Build with Docker

Build Proton using a Docker container (works on any platform):

./docker/packager/packager \
  --package-type binary \
  --docker-image-version clang-19 \
  --proton-build \
  --enable-proton-local \
  --output-dir $(pwd)/build_output

The compiled binary will be in build_output/.

Optional Build Configuration

Disable JavaScript (V8) Engine

For smaller binaries or constrained builds:

cmake -DENABLE_V8=OFF ..
ninja

Disabling V8 will remove JavaScript UDF support.

System Requirements

Minimum Requirements

CPU: 1 vCPU (x86_64 or ARM64)
Memory: 512 MB RAM
Disk: 1 GB available space
OS: Linux, macOS, or Windows (WSL2)

Proton can run on an AWS t2.nano instance (1 vCPU, 0.5 GiB memory).

Recommended Requirements

CPU: 4+ vCPUs
Memory: 8+ GB RAM
Disk: 50+ GB SSD
Network: 1 Gbps network interface

Supported Platforms

Platform	Architecture	Status
Ubuntu 20.04+	x86_64	✅ Fully Supported
Ubuntu 20.04+	ARM64	✅ Fully Supported
Debian 11+	x86_64	✅ Fully Supported
Debian 11+	ARM64	✅ Fully Supported
macOS 12+	x86_64 (Intel)	✅ Fully Supported
macOS 12+	ARM64 (Apple Silicon)	✅ Fully Supported
RHEL 8+	x86_64	✅ Fully Supported
RHEL 8+	ARM64	✅ Fully Supported
Windows 10+	WSL2	✅ Supported

Verifying Installation

After installation, verify Proton is working correctly:

Check Version

proton server --version

Should output version information.

Start Server

proton server start

Look for log messages indicating successful startup.

Connect Client

proton client

Should connect and show the proton-client :) prompt.

Run Test Query

SELECT 'Hello, Proton!' as message;

Should return:

┌─message─────────┐
│ Hello, Proton!  │
└─────────────────┘

Network Ports

Proton uses the following ports by default:

Port	Protocol	Purpose
8123	HTTP	HTTP interface, JDBC driver (batch mode)
8463	TCP	Native protocol for clients
3218	HTTP	HTTP streaming mode (optional)

Ensure these ports are not blocked by firewalls when connecting from external tools like DBeaver or Grafana.

For more details, see the Server Ports documentation.

Troubleshooting

Port Already in Use

If port 8123 or 8463 is already in use:

# Check what's using the port
sudo lsof -i :8123

# Kill the process or change Proton's port in config

Permission Denied

If you get permission errors:

# Ensure the proton-data directory is writable
chmod -R 755 ./proton-data

Docker Container Won’t Start

Check Docker logs:

docker logs proton

Connection Refused

Ensure:

Proton server is running
Firewall allows connections on port 8123/8463
You’re connecting to the correct host/port

Next Steps

Quick Start

Get your first streaming query running

Kafka Integration

Connect to Apache Kafka or Redpanda

SQL Reference

Learn Proton’s SQL syntax

Examples

Explore real-world use cases

Getting Help

If you encounter issues during installation:

GitHub Issues: Report a bug
Discussions: Ask questions
Slack: Join the community
Documentation: Full docs

Get Started

Core Concepts

Query Guide

Integration

Operations

Documentation Index

​Installation Methods

Single Binary

Docker

Homebrew

Build from Source

​Single Binary Installation

​Starting Proton

​Docker Installation

​Port Mapping

​Connecting to Docker Container

​Persisting Data

​Docker Compose

​Homebrew (macOS)

​Starting Proton

​Updating Proton

​Uninstalling

​Build from Source

​Prerequisites

​Ubuntu/Debian (x86_64 or ARM64)

​macOS (Apple Silicon)

​Build with Docker

​Optional Build Configuration

​Disable JavaScript (V8) Engine

​System Requirements

​Minimum Requirements

​Recommended Requirements

​Supported Platforms

​Verifying Installation

​Network Ports

​Troubleshooting

​Port Already in Use

​Permission Denied

​Docker Container Won’t Start

​Connection Refused

​Next Steps

Quick Start

Kafka Integration

SQL Reference

Examples

​Getting Help

Build docs developers (and LLMs) love

Installation Methods

Single Binary Installation

Starting Proton

Docker Installation

Port Mapping

Connecting to Docker Container

Persisting Data

Docker Compose

Homebrew (macOS)

Starting Proton

Updating Proton

Uninstalling

Build from Source

Prerequisites

Ubuntu/Debian (x86_64 or ARM64)

macOS (Apple Silicon)

Build with Docker

Optional Build Configuration

Disable JavaScript (V8) Engine

System Requirements

Minimum Requirements

Recommended Requirements

Supported Platforms

Verifying Installation

Network Ports

Troubleshooting

Port Already in Use

Permission Denied

Docker Container Won’t Start

Connection Refused

Next Steps

Getting Help