CLI Installation

CLI Installation

This guide covers installing and setting up the OstrichDB CLI on Unix-based systems (macOS and Linux). The CLI is written in Odin and provides a powerful terminal-based interface to OstrichDB.

Prerequisites

Before installing the OstrichDB CLI, ensure your system meets these requirements:

System Requirements

• Operating System: Unix-based system (macOS or Linux)
• Memory: At least 512MB RAM available
• Storage: 100MB+ free disk space
• Terminal: Command-line interface access

Required Dependencies

1. Go Programming Language

The OstrichDB CLI requires Go to be installed and properly configured:

Installation:

1. Visit https://go.dev/
2. Download the appropriate version for your system
3. Follow the installation instructions
4. Recommended version: go1.23.1 or later

Verify Installation:

go version
# Should output: go version go1.23.1 [system] [arch]

PATH Configuration: Ensure Go is in your system PATH:

echo $PATH
# Should include Go's bin directory (usually /usr/local/go/bin)

# If not in PATH, add to your shell profile (.bashrc, .zshrc, etc.):
export PATH=$PATH:/usr/local/go/bin

2. Odin Programming Language

OstrichDB is written in Odin, so the Odin compiler is required:

Installation:

1. Visit https://odin-lang.org/
2. Follow the Odin Installation Guide
3. Recommended version: dev-2024-11:764c32fd3 or later

Quick Installation (Linux/macOS):

# Clone the Odin repository
git clone https://github.com/odin-lang/Odin.git
cd Odin

# Build Odin (Linux)
make release

# Build Odin (macOS)
make release_native

# Move to system PATH location
sudo mv odin /usr/local/bin/

Verify Installation:

odin version
# Should output version information

PATH Configuration: Ensure Odin is accessible from anywhere:

which odin
# Should output: /usr/local/bin/odin (or similar)

# If not found, add Odin to your PATH
export PATH=$PATH:/path/to/odin

Installation Methods

Method 1: Local Build (Recommended)

This method builds OstrichDB directly on your system for optimal performance.

Step 1: Clone the Repository

git clone https://github.com/Solitude-Software-Solutions/OstrichDB.git
cd OstrichDB

Step 2: Make Scripts Executable

chmod +x scripts/local_build_run.sh
chmod +x scripts/local_build.sh
chmod +x scripts/restart.sh

Step 3: Build and Run

# Build and immediately run OstrichDB
./scripts/local_build_run.sh

Alternative: Build Only

# Just build without running
./scripts/local_build.sh

# Then run manually
./main.bin

Verify Local Installation

After building, you should see:

OstrichDB CLI v[version]
Welcome to OstrichDB!
Type 'HELP' for assistance.

OstrichDB>

Method 2: Docker Container

For isolated environments or systems where dependencies are difficult to install.

Prerequisites for Docker

1. Install Docker: Visit https://docs.docker.com/engine/install/
2. Verify Docker: docker --version

Step 1: Navigate to Project

cd /path/to/OstrichDB

Step 2: Build Docker Container

# Build the container
docker compose build

# Alternative: Build and run in detached mode
docker compose up -d

Step 3: Run OstrichDB CLI

# Connect to the running container and start CLI
docker exec -it ostrichdb /app/main.bin

Docker Configuration

Port Mapping: The default Docker setup uses port 8080. To change this, edit docker-compose.yml:

# Change from default 8080 to 8089
ports:
  - "8089:8080"

Data Persistence: OstrichDB data is stored in .ostrichdb/data on your host machine, mapped to /data in the container.

Verify Docker Installation

You should see the OstrichDB CLI prompt inside the container:

OstrichDB CLI v[version]
Welcome to OstrichDB!
Type 'HELP' for assistance.

OstrichDB>

Post-Installation Setup

Initial Configuration

After successful installation, perform initial setup:

1. Create Your First User

# Start OstrichDB
./main.bin

# Create a user account
OstrichDB> NEW USER
# Follow the prompts to set up username and password

2. Test Basic Operations

# Create test data
OstrichDB> NEW test.sample.hello OF_TYPE STRING WITH "Hello, OstrichDB!"

# Fetch the data
OstrichDB> FETCH test.sample.hello

# View data structure
OstrichDB> TREE

# Get help
OstrichDB> HELP

3. Configure Settings (Optional)

# Enable verbose help
OstrichDB> SET CONFIG HELP_IS_VERBOSE TO true

# Configure auto-server startup
OstrichDB> SET CONFIG AUTO_SERVE TO true

# Set session time limits
OstrichDB> SET CONFIG LIMIT_SESSION_TIME TO false

Environment Variables

Set up optional environment variables for easier access:

# Add to your shell profile (.bashrc, .zshrc, etc.)

# OstrichDB installation path
export OSTRICHDB_HOME="/path/to/OstrichDB"

# Add OstrichDB to PATH for global access
export PATH="$PATH:$OSTRICHDB_HOME"

# OstrichDB data directory
export OSTRICHDB_DATA="$OSTRICHDB_HOME/.ostrichdb/data"

Reload your shell:

source ~/.bashrc  # or ~/.zshrc

Directory Structure

After installation, your OstrichDB directory structure will look like:

OstrichDB/
├── main.bin                 # Compiled executable
├── scripts/
│   ├── local_build.sh      # Build script
│   ├── local_build_run.sh  # Build and run script
│   └── restart.sh          # Restart script
├── .ostrichdb/
│   ├── data/               # Database files (.ostrichdb)
│   ├── logs/               # System logs
│   ├── configs/            # Configuration files
│   └── backups/            # Database backups
├── src/                    # Source code (Odin files)
├── docker-compose.yml      # Docker configuration
└── README.md               # Documentation

Troubleshooting Installation

Common Issues

Go Not Found

# Error: go: command not found
# Solution: Install Go and add to PATH
which go
echo $PATH
export PATH=$PATH:/usr/local/go/bin

Odin Not Found

# Error: odin: command not found
# Solution: Install Odin and add to PATH
which odin
# If not found, reinstall Odin or fix PATH

Permission Denied

# Error: Permission denied when running scripts
# Solution: Make scripts executable
chmod +x scripts/*.sh

Build Failures

# Check dependencies are installed
go version
odin version

# Try rebuilding
./scripts/local_build.sh

# Check for error messages in output

Docker Issues

# Docker daemon not running
sudo systemctl start docker  # Linux
open -a Docker               # macOS

# Permission issues
sudo docker compose build
# Or add user to docker group (Linux)
sudo usermod -aG docker $USER

System-Specific Issues

macOS Issues

Rosetta 2 (Apple Silicon):

# If running on Apple Silicon with Rosetta
arch -x86_64 ./scripts/local_build.sh

Xcode Command Line Tools:

# Install if missing
xcode-select --install

Linux Issues

Missing Development Tools:

# Ubuntu/Debian
sudo apt update
sudo apt install build-essential git

# CentOS/RHEL/Fedora
sudo yum groupinstall "Development Tools"
# or
sudo dnf groupinstall "Development Tools"

Library Dependencies:

# If you encounter library errors
sudo apt install libc6-dev gcc  # Ubuntu/Debian
sudo yum install glibc-devel gcc  # CentOS/RHEL

Performance Optimization

For Development

# Use the build-and-run script for frequent testing
./scripts/local_build_run.sh

For Production

# Build optimized version
./scripts/local_build.sh

# Run with specific memory limits if needed
ulimit -m 1048576  # 1GB memory limit
./main.bin

Getting Help

If you encounter issues:

1. Check Prerequisites: Ensure Go and Odin are properly installed
2. Review Error Messages: Look for specific error details in output
3. Check File Permissions: Ensure scripts are executable
4. Verify System Resources: Ensure adequate memory and disk space
5. Consult Documentation: Review the README and documentation
6. Community Support: Join the OstrichDB community for help

Verification Checklist

After installation, verify everything works:

• OstrichDB CLI starts without errors
• Can create users with NEW USER
• Can create and fetch records
• TREE command shows data structure
• HELP command provides information
• VERSION shows correct version
• Server mode works with SERVE (if needed)

Next Steps

With OstrichDB CLI installed:

1. Learn Query Structure - Understand the CLP system
2. Explore Commands - Master all available operations
3. Configure Your Setup - Customize OstrichDB settings
4. Try Examples - Practice with real-world scenarios

You’re now ready to start using OstrichDB CLI for your database management needs!