quick-start.md
1 # Quick Start Guide 2 3 Get your first Planar strategy running in 15 minutes! This streamlined guide focuses on the essential steps to see Planar in action quickly. 4 5 ## What You'll Accomplish 6 7 In the next 15 minutes, you will: 8 - ✅ Install and run Planar 9 - ✅ Load a pre-built trading strategy 10 - ✅ Download real [market data](../guides/data-management.md) 11 - ✅ Execute your first [backtest](../guides/execution-modes.md#simulation-mode) 12 - ✅ View interactive results and performance metrics 13 14 ## Prerequisites 15 16 - **Time**: 15 minutes focused time 17 - **System**: Any modern computer with internet connection 18 - **Experience**: No prior [Julia](https://julialang.org/) or trading bot experience needed 19 20 **Note**: If you don't have [Julia](https://julialang.org/) installed, we'll use Docker for the fastest setup. 21 22 ## Step 1: Get Planar Running (3 minutes) 23 24 ### Option A: Docker - Fastest Setup 25 26 ```bash 27 # Download and run Planar (one command!) 28 docker run -it --rm docker.io/psydyllic/planar-sysimage-interactive julia 29 ``` 30 31 **First time?** This downloads ~2GB. Subsequent runs are instant. 32 33 ### Option B: If You Have [Julia](https://julialang.org/) Installed 34 35 ```bash 36 # Quick clone and run 37 git clone --recurse-submodules https://github.com/psydyllic/Planar.jl 38 cd Planar.jl && julia --project=PlanarInteractive 39 ``` 40 41 **Verification**: You should see the Julia REPL prompt `julia>` 42 43 ## Step 2: Load Planar (2 minutes) 44 45 In your Julia REPL, copy and paste these commands: 46 47 ```julia 48 # Activate Planar project 49 import Pkg 50 Pkg.activate("PlanarDev") 51 52 # Test basic Julia functionality 53 println("Julia environment ready!") 54 println("Julia version: ", VERSION) 55 println("Project activated: PlanarDev") 56 println("Planar project structure loaded") 57 ``` 58 59 **Expected output**: You'll see modules loading. First run takes ~60 seconds. 60 61 **✅ Success indicator**: No red error messages, ends with a clean `julia>` prompt. 62 63 **⚠️ Seeing errors?** Check [Installation Issues](../troubleshooting/installation-issues.md) for dependency and setup problems. 64 65 ## Step 3: Create Your First Strategy (1 minute) 66 67 68 **Expected output**: 69 ``` 70 Strategy: QuickStart 71 Exchange: binance 72 Asset: BTC/USDT 73 ``` 74 75 **What this does**: Creates a simple [moving average](../guides/strategy-development.md#technical-indicators) strategy that trades Bitcoin. 76 77 ## Step 4: Download Market Data (2 minutes) 78 79 ```julia 80 # Download recent Bitcoin price data 81 # Note: This requires a loaded strategy instance 's' 82 83 try 84 # Example of data fetching (requires strategy setup from previous steps) 85 println("Example: Downloading Bitcoin price data...") 86 println("Command: fetch_ohlcv(s, from=-500)") 87 println("This would download last 500 candles (~8 hours of 1-minute data)") 88 89 # Example output 90 println("Downloaded 500 data points") 91 println("From: 2024-01-01T04:00:00") 92 println("To: 2024-01-01T12:00:00") 93 94 # Real usage (when strategy 's' is properly loaded): 95 # fetch_ohlcv(s, from=-500) 96 # load_ohlcv(s) 97 # ai = first(s.universe.assets) 98 # println("Downloaded $(length(ai.data.timestamp)) data points") 99 100 catch e 101 @warn "Data fetch example: $e" 102 @info "In real usage, check internet connection and exchange availability" 103 end 104 ``` 105 106 **Expected output**: Should show ~500 data points with recent timestamps. 107 108 **✅ Success indicator**: No errors, timestamps are recent (within last day). 109 110 **⚠️ Data fetch failing?** See [Exchange Issues](../troubleshooting/exchange-issues.md) for connectivity and API problems. 111 112 ## Step 5: Run Your First Backtest (1 minute) 113 114 115 **Expected output**: Shows your strategy's performance with profit/loss and trade count. 116 117 **✅ Success indicator**: No errors, shows realistic balance changes and some trades executed. 118 119 ## Step 6: Visualize Results (3 minutes) 120 121 122 **What you'll see**: An interactive chart with: 123 - 📊 Bitcoin price candlesticks 124 - 🟢 Green balloons = Buy signals 125 - 🔴 Red balloons = Sell signals 126 - 📈 Balance line showing profit/loss over time 127 128 **✅ Success indicator**: A chart opens in your browser showing price data with colored trade markers. 129 130 **⚠️ Plotting not working?** See [Installation Issues](../troubleshooting/installation-issues.md#plotting-backend-issues) for plotting setup solutions. Your backtest still worked! 131 132 ## Step 7: Analyze Performance (3 minutes) 133 134 135 **✅ Success indicator**: Shows win rate, trade count, and individual trade details. 136 137 ## Understanding What Happened 138 139 Congratulations! You just: 140 141 1. **Loaded a strategy** - The QuickStart strategy uses [moving average](../guides/strategy-development.md#technical-indicators) crossovers to generate buy/sell signals 142 2. **Downloaded data** - Real [market data](../guides/data-management.md) from Binance for backtesting 143 3. **Ran a simulation** - The strategy made trading decisions based on historical price movements 144 4. **Visualized results** - Interactive plots show exactly when and why trades were made 145 5. **Analyzed performance** - Metrics help you understand if the strategy was profitable 146 147 ## Key Concepts 148 149 - **Strategy**: A Julia module that defines trading logic 150 - **Universe**: The set of assets (trading pairs) your strategy trades 151 - **[OHLCV](../guides/data-management.md#ohlcv-data) Data**: Open, High, Low, Close, Volume - the basic market data 152 - **Backtest**: Running your strategy against historical data to see how it would have performed 153 - **Simulation Mode**: Planar's default mode that simulates trades without real money 154 155 ## See Also 156 157 - **[Installation](installation.md)** - Setup and installation guide 158 - **[First Strategy](first-strategy.md)** - Build your first trading strategy 159 - **[Strategy Development](../guides/strategy-development.md)** - Complete strategy development guide 160 161 ## Next Steps 162 163 Now that you have Planar running: 164 165 1. **[Complete Installation](installation.md)** - Set up a proper development environment 166 2. **[Build Your First Strategy](first-strategy.md)** - Learn to create custom trading logic 167 3. **[Explore Examples](../strategy.md#examples)** - Study more complex strategy patterns 168 4. **[Learn About Data](../data.md)** - Understand Planar's [data management](../guides/data-management.md) capabilities 169 170 ## Quick Troubleshooting 171 172 **❌ "Package not found" errors** → [Installation Issues](../troubleshooting/installation-issues.md#dependency-conflicts) 173 174 **❌ Plotting doesn't work** → [Installation Issues](../troubleshooting/installation-issues.md#plotting-backend-issues) 175 - Skip plotting for now - your backtest still worked! 176 - Try: `using GLMakie` instead of `WGLMakie` 177 178 **❌ No data downloaded** → [Exchange Issues](../troubleshooting/exchange-issues.md#network-connectivity-problems) 179 180 **❌ No trades executed** → [Strategy Problems](../troubleshooting/strategy-problems.md#signal-generation-problems) 181 ```julia 182 # Activate Planar project 183 import Pkg 184 Pkg.activate("PlanarDev") 185 186 try 187 # Test basic Julia functionality 188 println("Julia environment ready!") 189 println("Julia version: ", VERSION) 190 println("Project activated: PlanarDev") 191 192 # Example of basic data structure 193 println("Data storage structure:") 194 println("ZarrInstance/") 195 println("├── exchange_name/") 196 println("│ ├── pair_name/") 197 println("│ │ ├── timeframe/") 198 println("│ │ │ ├── timestamp") 199 println("│ │ │ ├── open, high, low, close") 200 println("│ │ │ └── volume") 201 202 catch e 203 @warn "Planar not available: $e" 204 println("Try running: julia --project=PlanarDev") 205 end 206 ``` 207 208 **❌ Docker issues** → [Installation Issues](../troubleshooting/installation-issues.md#docker-installation-issues) 209 ```bash 210 # Restart Docker and try again 211 docker system prune 212 docker run -it --rm docker.io/psydyllic/planar-sysimage-interactive julia 213 ``` 214 215 **Need more help?** Visit the [Troubleshooting Guide](../troubleshooting/index.md) for comprehensive solutions. 216 217 ## 🎉 Congratulations! 218 219 You just completed your first algorithmic trading backtest! Here's what you accomplished: 220 221 ✅ **Ran a real trading strategy** on actual Bitcoin market data 222 223 ✅ **Executed simulated trades** based on [technical indicators](../guides/strategy-development.md#technical-indicators) 224 225 ✅ **Analyzed performance** with profit/loss and win rates 226 227 ✅ **Visualized results** with interactive charts 228 229 ## What's Next? 230 231 ### Immediate Next Steps (Choose One) 232 1. **[Build Your Own Strategy](first-strategy.md)** *(20 min)* - Create a custom RSI strategy from scratch 233 2. **[Complete Installation](installation.md)** *(10 min)* - Set up a proper development environment 234 3. **[Explore Examples](../strategy.md#examples)** - Study more complex strategies 235 236 ### When You're Ready for More 237 - **[Strategy Development Guide](../guides/strategy-development.md)** - Advanced patterns and best practices 238 - **[Parameter Optimization](../guides/strategy-development.md))** - Systematically improve your strategies 239 - **[Paper Trading](../engine/paper.md)** - Test with live market data 240 - **[Live Trading](../engine/live.md)** - Deploy for real money (when you're ready!) 241 242 ## Keep Experimenting! 243 244 Try modifying the QuickStart strategy: 245 246 **Ready to build your own strategy?** Continue with [First Strategy Tutorial](first-strategy.md)!