Installation

Ebla consists of two components: a server that stores your files and coordinates sync, and a client that runs on each device. This guide covers all installation methods.

Server Installation

The Ebla server requires PostgreSQL 14+ for metadata storage. You can run the server via Docker, as a standalone binary, or build from source.

Option 1: Docker (Recommended)

The fastest way to get started. Our install script sets up PostgreSQL and Ebla server in Docker containers with secure defaults.

Prerequisites

Docker Engine 20.10+
Docker Compose v2
Linux server or macOS (Windows via WSL2)

One-Command Install

# Run as root or with sudo
curl -fsSL https://getebla.com/install.sh | sh

The installer:

Checks for Docker and Docker Compose
Creates /opt/ebla (or ~/.ebla for non-root)
Generates secure secrets (PostgreSQL password, JWT secret, bootstrap token)
Writes docker-compose.yml, .env, and server.toml
Starts PostgreSQL and Ebla server containers
Waits for health checks to pass
Displays the admin URL and bootstrap token

Save the Bootstrap Token

The installer displays a one-time bootstrap token for creating your admin account. Store it securely. If lost, check /opt/ebla/.env.

Manual Docker Setup

For more control, you can set up Docker manually:

# Create directory
sudo mkdir -p /opt/ebla
cd /opt/ebla

# Create docker-compose.yml
cat > docker-compose.yml <<'EOF'
version: '3.8'
services:
  postgres:
    image: postgres:16-alpine
    container_name: ebla-postgres
    environment:
      POSTGRES_USER: ebla
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ebla
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ebla"]
      interval: 5s
      timeout: 5s
      retries: 5

  server:
    image: ghcr.io/ebla-io/ebla-server:latest
    container_name: ebla-server
    ports:
      - "6333:6333"
    environment:
      - EBLA_CONFIG=/etc/ebla/server.toml
    volumes:
      - ./server.toml:/etc/ebla/server.toml:ro
      - blocks_data:/var/lib/ebla/blocks
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  postgres_data:
  blocks_data:
EOF

# Create .env file
cat > .env <<EOF
POSTGRES_PASSWORD=$(openssl rand -hex 32)
JWT_SECRET=$(openssl rand -hex 32)
BOOTSTRAP_TOKEN=$(openssl rand -hex 16)
EOF

# Create server.toml (see Configuration guide for full options)
source .env
cat > server.toml <<EOF
[server]
host = "0.0.0.0"
port = 6333

[database]
url = "postgres://ebla:${POSTGRES_PASSWORD}@postgres/ebla?sslmode=disable"

[storage]
backend = "filesystem"
path = "/var/lib/ebla/blocks"

[auth]
jwt_secret = "${JWT_SECRET}"
bootstrap_token = "${BOOTSTRAP_TOKEN}"
EOF

# Start services
docker compose up -d

# Check logs
docker compose logs -f server

Option 2: Binary

Run the server as a standalone binary. Requires an existing PostgreSQL instance.

Prerequisites

PostgreSQL 14+ (running and accessible)
Linux (amd64, arm64), macOS (amd64, arm64), or Windows

Download and Install

# Download latest release (Linux amd64 example)
curl -fsSL https://github.com/ebla-io/ebla/releases/latest/download/ebla-server-linux-amd64 \
  -o /usr/local/bin/ebla-server
chmod +x /usr/local/bin/ebla-server

# Verify installation
ebla-server --version

Set Up PostgreSQL

# Connect to PostgreSQL as superuser
sudo -u postgres psql

-- Create database and user
CREATE DATABASE ebla;
CREATE USER ebla WITH PASSWORD 'your-secure-password';
GRANT ALL PRIVILEGES ON DATABASE ebla TO ebla;
\q

Configure the Server

# Create config directory
sudo mkdir -p /etc/ebla

# Create configuration file
sudo tee /etc/ebla/server.toml <<'EOF'
[server]
host = "0.0.0.0"
port = 6333
base_url = "http://your-server:6333"

[database]
url = "postgres://ebla:your-secure-password@localhost/ebla?sslmode=disable"

[storage]
backend = "filesystem"
path = "/var/lib/ebla/blocks"

[auth]
jwt_secret = "generate-a-64-char-random-string-here"
bootstrap_token = "generate-another-random-string"
allow_signup = true

[logging]
level = "info"
format = "json"
EOF

# Create storage directory
sudo mkdir -p /var/lib/ebla/blocks
sudo chown -R $USER:$USER /var/lib/ebla

Run the Server

# Run directly
ebla-server --config /etc/ebla/server.toml

# Or run in background
nohup ebla-server --config /etc/ebla/server.toml > /var/log/ebla-server.log 2>&1 &

Run Server Diagnostics

# Check server configuration and connectivity
ebla-server doctor --config /etc/ebla/server.toml

# Expected output:
Ebla Server Doctor
==================
Config: /etc/ebla/server.toml

✓ Config: configuration file valid
✓ Database: database connection successful
✓ Storage: filesystem storage accessible and writable
✓ Garbage Collection: GC enabled (interval: 24h0m0s)
✓ Backup: backup enabled (interval: 24h0m0s, retention: 7)

Overall Status: ok

Option 3: From Source

Build and run the server from source code.

Prerequisites

Go 1.21 or later
Git
PostgreSQL 14+ (running and accessible)
Make (optional, for convenience)

Clone and Build

# Clone the repository
git clone https://github.com/ebla-io/ebla.git
cd ebla

# Build using Make
make build

# Or build directly with Go
go build -o bin/ebla-server ./cmd/ebla-server
go build -o bin/ebla ./cmd/ebla

# Verify the build
./bin/ebla-server --version

Configure and Run

# Use the example development config
cp configs/server.example.toml configs/server.dev.toml

# Edit configuration (update database URL, JWT secret, etc.)
vim configs/server.dev.toml

# Create storage directory
mkdir -p data/blocks

# Start PostgreSQL (if using Docker for just the database)
docker run -d --name ebla-postgres \
  -e POSTGRES_USER=ebla \
  -e POSTGRES_PASSWORD=ebla \
  -e POSTGRES_DB=ebla \
  -p 5432:5432 \
  postgres:16-alpine

# Run the server
./bin/ebla-server --config configs/server.dev.toml

Development Workflow

# Run tests
make test

# Run tests with race detection
go test -race ./...

# Run linter
make lint

# Build for all platforms
make build-all

# Start development database
make dev-db

# Run server in development mode
make run-server

Client Installation

The Ebla client is a single binary that runs on your local machine. It syncs files with the server and handles P2P transfers with other clients. No Docker required.

Option 1: Install Script (Recommended)

The fastest way to install the client:

# Linux and macOS
curl -fsSL https://getebla.com/client | sh

The script:

Detects your OS and architecture
Downloads the appropriate binary from GitHub releases
Verifies the checksum
Installs to ~/.local/bin/ebla
Adds to PATH if needed

PATH Configuration

The installer adds ~/.local/bin to your PATH. You may need to restart your shell or run source ~/.bashrc (or ~/.zshrc) for the changes to take effect.

Verify Installation

$ ebla --version
ebla version 0.56.0 (linux/amd64)

$ ebla --help
Ebla - File sync that respects your data

Usage:
  ebla [command]

Available Commands:
  login       Authenticate with an Ebla server
  logout      Clear stored credentials
  whoami      Show current user
  library     Manage libraries
  sync        Manage sync configurations
  daemon      Control the sync daemon
  status      Show sync status
  config      Manage configuration
  search      Search files and ask questions
  team        Manage teams
  p2p         P2P network settings
  log         Show commit history
  show        Show commit details
  diff        Compare changes
  checkout    Restore files from commits
  help        Help about any command

Option 2: Manual Binary Download

Download the binary directly from GitHub releases:

Linux

# AMD64 (Intel/AMD 64-bit)
curl -fsSL https://github.com/ebla-io/ebla/releases/latest/download/ebla-linux-amd64 \
  -o ~/.local/bin/ebla
chmod +x ~/.local/bin/ebla

# ARM64 (Apple Silicon, Raspberry Pi 4, etc.)
curl -fsSL https://github.com/ebla-io/ebla/releases/latest/download/ebla-linux-arm64 \
  -o ~/.local/bin/ebla
chmod +x ~/.local/bin/ebla

macOS

# Apple Silicon (M1/M2/M3)
curl -fsSL https://github.com/ebla-io/ebla/releases/latest/download/ebla-darwin-arm64 \
  -o /usr/local/bin/ebla
chmod +x /usr/local/bin/ebla

# Intel Mac
curl -fsSL https://github.com/ebla-io/ebla/releases/latest/download/ebla-darwin-amd64 \
  -o /usr/local/bin/ebla
chmod +x /usr/local/bin/ebla

Windows

# Download using PowerShell
Invoke-WebRequest -Uri "https://github.com/ebla-io/ebla/releases/latest/download/ebla-windows-amd64.exe" `
  -OutFile "$env:USERPROFILE\.local\bin\ebla.exe"

# Add to PATH (run as Administrator)
$path = [Environment]::GetEnvironmentVariable("PATH", "User")
$newPath = "$env:USERPROFILE\.local\bin;$path"
[Environment]::SetEnvironmentVariable("PATH", $newPath, "User")

Option 3: From Source

Build the client from source code:

# Clone and build (if not already done for server)
git clone https://github.com/ebla-io/ebla.git
cd ebla

# Build the client
make build
# or
go build -o bin/ebla ./cmd/ebla

# Install to PATH
cp bin/ebla ~/.local/bin/

# Verify
ebla --version

Running as a Service

For production use, run both server and client daemon as system services.

Server: systemd Service (Linux)

# Create service file
sudo tee /etc/systemd/system/ebla-server.service <<'EOF'
[Unit]
Description=Ebla File Sync Server
After=network.target postgresql.service
Wants=postgresql.service

[Service]
Type=simple
User=ebla
Group=ebla
ExecStart=/usr/local/bin/ebla-server --config /etc/ebla/server.toml
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/ebla

[Install]
WantedBy=multi-user.target
EOF

# Create ebla user
sudo useradd -r -s /bin/false ebla
sudo chown -R ebla:ebla /var/lib/ebla

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable ebla-server
sudo systemctl start ebla-server

# Check status
sudo systemctl status ebla-server
sudo journalctl -u ebla-server -f

Client: systemd User Service (Linux)

# Create user service directory
mkdir -p ~/.config/systemd/user

# Create service file
cat > ~/.config/systemd/user/ebla-daemon.service <<'EOF'
[Unit]
Description=Ebla Sync Daemon
After=network.target

[Service]
Type=simple
ExecStart=%h/.local/bin/ebla daemon start
Restart=always
RestartSec=10

[Install]
WantedBy=default.target
EOF

# Enable and start
systemctl --user daemon-reload
systemctl --user enable ebla-daemon
systemctl --user start ebla-daemon

# Enable lingering (run even when logged out)
sudo loginctl enable-linger $USER

# Check status
systemctl --user status ebla-daemon
journalctl --user -u ebla-daemon -f

Client: launchd Agent (macOS)

# Create launchd plist
cat > ~/Library/LaunchAgents/dev.ebla.daemon.plist <<'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>dev.ebla.daemon</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/ebla</string>
        <string>daemon</string>
        <string>start</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/ebla-daemon.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/ebla-daemon.error.log</string>
</dict>
</plist>
EOF

# Load the agent
launchctl load ~/Library/LaunchAgents/dev.ebla.daemon.plist

# Check status
launchctl list | grep ebla

# View logs
tail -f /tmp/ebla-daemon.log

Upgrading

Server (Docker)

cd /opt/ebla

# Pull latest images
docker compose pull

# Restart with new version
docker compose up -d

# Verify
docker compose logs -f server

Server (Binary)

# Stop the server
sudo systemctl stop ebla-server

# Download new version
curl -fsSL https://github.com/ebla-io/ebla/releases/latest/download/ebla-server-linux-amd64 \
  -o /usr/local/bin/ebla-server
chmod +x /usr/local/bin/ebla-server

# Start the server
sudo systemctl start ebla-server

# Verify
ebla-server --version

Client

# Stop daemon
systemctl --user stop ebla-daemon  # Linux
# or: launchctl unload ~/Library/LaunchAgents/dev.ebla.daemon.plist  # macOS

# Re-run install script
curl -fsSL https://getebla.com/client | sh

# Restart daemon
systemctl --user start ebla-daemon  # Linux
# or: launchctl load ~/Library/LaunchAgents/dev.ebla.daemon.plist  # macOS

# Verify
ebla --version

Uninstalling

Server (Docker)

cd /opt/ebla

# Stop and remove containers (keeps data)
docker compose down

# Remove containers AND data (destructive!)
docker compose down -v

# Remove installation directory
sudo rm -rf /opt/ebla

Server (Binary)

# Stop and disable service
sudo systemctl stop ebla-server
sudo systemctl disable ebla-server
sudo rm /etc/systemd/system/ebla-server.service
sudo systemctl daemon-reload

# Remove binary and config
sudo rm /usr/local/bin/ebla-server
sudo rm -rf /etc/ebla

# Remove data (destructive!)
sudo rm -rf /var/lib/ebla

Client

# Stop daemon
systemctl --user stop ebla-daemon
systemctl --user disable ebla-daemon
rm ~/.config/systemd/user/ebla-daemon.service

# Remove binary
rm ~/.local/bin/ebla

# Remove config and cache
rm -rf ~/.ebla

Installation

On This Page

Server Installation

Option 1: Docker (Recommended)

Prerequisites

One-Command Install

Manual Docker Setup

Option 2: Binary

Prerequisites

Download and Install

Set Up PostgreSQL

Configure the Server

Run the Server

Run Server Diagnostics

Option 3: From Source

Prerequisites

Clone and Build

Configure and Run

Development Workflow

Client Installation

Option 1: Install Script (Recommended)

Verify Installation

Option 2: Manual Binary Download

Linux

macOS

Windows

Option 3: From Source

Running as a Service

Server: systemd Service (Linux)

Client: systemd User Service (Linux)

Client: launchd Agent (macOS)

Upgrading

Server (Docker)

Server (Binary)

Client

Uninstalling

Server (Docker)

Server (Binary)

Client