Installation Guide

This guide walks you through installing and setting up Planar on your system.

Prerequisites

System Requirements

• Operating System: Linux, macOS, or Windows
• Julia: Version 1.11 or later
• Memory: 8GB RAM minimum (16GB+ recommended)
• Storage: 10GB+ free space for data and dependencies
• Network: Stable internet connection for exchange APIs

Julia Installation

1. Download Julia 1.11+ from julialang.org
2. Follow the platform-specific installation instructions
3. Verify installation:

julia --version

Installation Methods

Method 1: Git Clone (Recommended)

# Clone the repository with submodules
git clone --recurse-submodules https://github.com/defnlnotme/Planar.jl
cd Planar.jl

# Allow direnv (if using)
direnv allow

# Start Julia with the project
julia --project=Planar

Method 2: Docker

# Pull pre-built image
docker pull docker.io/bubbleparticles/planar-sysimage

# Or build locally
scripts/build.sh

Project Setup

1. Install Dependencies

2. Create User Directory

# Create user configuration directory
mkdir -p user/logs user/keys

3. Configuration Files

Create user/planar.toml:

[general]
name = "My Trading Bot"
log_level = "INFO"

[exchanges]
default = "binance"

[exchanges.binance]
enabled = true
sandbox = true  # Start with testnet

[strategies]
# Add your strategies here

Create user/secrets.toml:

[exchanges.binance]
api_key = "your_api_key_here"
secret = "your_secret_key_here"

API Configuration

Exchange API Keys

1. Binance:

   • Go to Binance API Management
   • Create new API key
   • Enable "Enable Reading" and "Enable Spot & Margin Trading"
   • Add IP restrictions for security

2. Coinbase Pro:

   • Go to Coinbase Pro API
   • Create new API key with trading permissions
   • Note the passphrase requirement

3. Other Exchanges:

   • Follow exchange-specific API documentation
   • Ensure proper permissions for trading

API Security

• Never commit API keys to version control
• Use IP restrictions when possible
• Start with sandbox/testnet environments
• Use separate API keys for different bots
• Regularly rotate API keys

Environment Configuration

Environment Variables

# Set Julia project
export JULIA_PROJECT=Planar

# Set thread count (recommended: CPU cores - 2)
export JULIA_NUM_THREADS=6

# Enable precompilation
export JULIA_PRECOMP=1

# Set data directory (optional)
export PLANAR_DATA_DIR=/path/to/data

Using direnv (Optional)

Create .envrc:

export JULIA_PROJECT=Planar
export JULIA_NUM_THREADS=6
export JULIA_PRECOMP=1

Verification

Test Installation

Run Example Strategy

Docker Setup

Using Pre-built Image

# Run with interactive features
docker run -it \
  -v $(pwd)/user:/app/user \
  docker.io/psydyllic/planar-sysimage-interactive

# Run production image
docker run -d \
  -v $(pwd)/user:/app/user \
  docker.io/psydyllic/planar-sysimage

Building Custom Image

# Build development image
scripts/build.sh

# Build with custom Julia version
JULIA_VERSION=1.11.1 scripts/build.sh

Performance Optimization

Precompilation

Memory Settings

# Increase Julia heap size if needed
export JULIA_HEAP_SIZE_HINT=8G

# Optimize garbage collection
export JULIA_GC_THREADS=2

Troubleshooting

Common Issues

1. Package Installation Fails:

2. Permission Errors:

   # Fix directory permissions
   chmod -R 755 user/

3. API Connection Issues:

   • Verify API keys and permissions
   • Check network connectivity
   • Test with sandbox environment first

4. Memory Issues:

   • Increase system RAM
   • Use swap file if necessary
   • Reduce data cache size

Getting Help

• Check troubleshooting guide
• Review installation issues
• Search GitHub Issues

Next Steps

After successful installation:

1. Configure your first strategy
2. Set up exchange connections
3. Run your first backtest
4. Explore optimization features

Security Considerations

• Store API keys securely in user/secrets.toml
• Use IP restrictions on exchange APIs
• Start with sandbox/testnet environments
• Regular security audits of API permissions
• Monitor for unusual trading activity

Updates and Maintenance

# Update Planar
git pull origin main
git submodule update --recursive

# Update Julia packages
julia --project=Planar -e "using Pkg; Pkg.update()"

# Rebuild if needed
julia --project=Planar -e "using Pkg; Pkg.build()"