Skip to main content

​
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:
  1. Detects your operating system and architecture
  2. Downloads the appropriate Proton binary
  3. Installs it to your system
  4. 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)

1

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
2

Install LLVM 19

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

Clone and Build

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

Run Proton

# Start server
./programs/proton server start

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

​
macOS (Apple Silicon)

1

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
2

Install Dependencies

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

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++
4

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).
  • CPU: 4+ vCPUs
  • Memory: 8+ GB RAM
  • Disk: 50+ GB SSD
  • Network: 1 Gbps network interface

​
Supported Platforms

PlatformArchitectureStatus
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:
1

Check Version

proton server --version
Should output version information.
2

Start Server

proton server start
Look for log messages indicating successful startup.
3

Connect Client

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

Run Test Query

SELECT 'Hello, Proton!' as message;
Should return:
┌─message─────────┐
│ Hello, Proton!  │
└─────────────────┘

​
Network Ports

Proton uses the following ports by default:
PortProtocolPurpose
8123HTTPHTTP interface, JDBC driver (batch mode)
8463TCPNative protocol for clients
3218HTTPHTTP 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:
  1. Proton server is running
  2. Firewall allows connections on port 8123/8463
  3. 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: