installation.md
1 # Installation Guide 2 3 This guide walks you through installing and setting up Planar on your system. 4 5 ## Prerequisites 6 7 ### System Requirements 8 9 - **Operating System**: Linux, macOS, or Windows 10 - **Julia**: Version 1.11 or later 11 - **Memory**: 8GB RAM minimum (16GB+ recommended) 12 - **Storage**: 10GB+ free space for data and dependencies 13 - **Network**: Stable internet connection for exchange APIs 14 15 ### Julia Installation 16 17 1. Download Julia 1.11+ from [julialang.org](https://julialang.org/downloads/) 18 2. Follow the platform-specific installation instructions 19 3. Verify installation: 20 ```bash 21 julia --version 22 ``` 23 24 ## Installation Methods 25 26 ### Method 1: Git Clone (Recommended) 27 28 ```bash 29 # Clone the repository with submodules 30 git clone --recurse-submodules https://github.com/defnlnotme/Planar.jl 31 cd Planar.jl 32 33 # Allow direnv (if using) 34 direnv allow 35 36 # Start Julia with the project 37 julia --project=Planar 38 ``` 39 40 ### Method 2: Docker 41 42 ```bash 43 # Pull pre-built image 44 docker pull docker.io/bubbleparticles/planar-sysimage 45 46 # Or build locally 47 scripts/build.sh 48 ``` 49 50 ## Project Setup 51 52 ### 1. Install Dependencies 53 54 55 ### 2. Create User Directory 56 57 ```bash 58 # Create user configuration directory 59 mkdir -p user/logs user/keys 60 ``` 61 62 ### 3. Configuration Files 63 64 Create `user/planar.toml`: 65 ```toml 66 [general] 67 name = "My Trading Bot" 68 log_level = "INFO" 69 70 [exchanges] 71 default = "binance" 72 73 [exchanges.binance] 74 enabled = true 75 sandbox = true # Start with testnet 76 77 [strategies] 78 # Add your strategies here 79 ``` 80 81 Create `user/secrets.toml`: 82 ```toml 83 [exchanges.binance] 84 api_key = "your_api_key_here" 85 secret = "your_secret_key_here" 86 ``` 87 88 ## API Configuration 89 90 ### Exchange API Keys 91 92 1. **Binance**: 93 - Go to [Binance API Management](https://www.binance.com/en/my/settings/api-management) 94 - Create new API key 95 - Enable "Enable Reading" and "Enable Spot & Margin Trading" 96 - Add IP restrictions for security 97 98 2. **Coinbase Pro**: 99 - Go to [Coinbase Pro API](https://pro.coinbase.com/profile/api) 100 - Create new API key with trading permissions 101 - Note the passphrase requirement 102 103 3. **Other Exchanges**: 104 - Follow exchange-specific API documentation 105 - Ensure proper permissions for trading 106 107 ### API Security 108 109 - **Never commit API keys to version control** 110 - Use IP restrictions when possible 111 - Start with sandbox/testnet environments 112 - Use separate API keys for different bots 113 - Regularly rotate API keys 114 115 ## Environment Configuration 116 117 ### Environment Variables 118 119 ```bash 120 # Set Julia project 121 export JULIA_PROJECT=Planar 122 123 # Set thread count (recommended: CPU cores - 2) 124 export JULIA_NUM_THREADS=6 125 126 # Enable precompilation 127 export JULIA_PRECOMP=1 128 129 # Set data directory (optional) 130 export PLANAR_DATA_DIR=/path/to/data 131 ``` 132 133 ### Using direnv (Optional) 134 135 Create `.envrc`: 136 ```bash 137 export JULIA_PROJECT=Planar 138 export JULIA_NUM_THREADS=6 139 export JULIA_PRECOMP=1 140 ``` 141 142 ## Verification 143 144 ### Test Installation 145 146 147 ### Run Example Strategy 148 149 150 ## Docker Setup 151 152 ### Using Pre-built Image 153 154 ```bash 155 # Run with interactive features 156 docker run -it \ 157 -v $(pwd)/user:/app/user \ 158 docker.io/psydyllic/planar-sysimage-interactive 159 160 # Run production image 161 docker run -d \ 162 -v $(pwd)/user:/app/user \ 163 docker.io/psydyllic/planar-sysimage 164 ``` 165 166 ### Building Custom Image 167 168 ```bash 169 # Build development image 170 scripts/build.sh 171 172 # Build with custom Julia version 173 JULIA_VERSION=1.11.1 scripts/build.sh 174 ``` 175 176 ## Performance Optimization 177 178 ### Precompilation 179 180 181 ### Memory Settings 182 183 ```bash 184 # Increase Julia heap size if needed 185 export JULIA_HEAP_SIZE_HINT=8G 186 187 # Optimize garbage collection 188 export JULIA_GC_THREADS=2 189 ``` 190 191 ## Troubleshooting 192 193 ### Common Issues 194 195 1. **Package Installation Fails**: 196 197 2. **Permission Errors**: 198 ```bash 199 # Fix directory permissions 200 chmod -R 755 user/ 201 ``` 202 203 3. **API Connection Issues**: 204 - Verify API keys and permissions 205 - Check network connectivity 206 - Test with sandbox environment first 207 208 4. **Memory Issues**: 209 - Increase system RAM 210 - Use swap file if necessary 211 - Reduce data cache size 212 213 ### Getting Help 214 215 - Check [troubleshooting guide](../troubleshooting/index.md) 216 - Review [installation issues](../troubleshooting/installation-issues.md) 217 - Search [GitHub Issues](https://github.com/defnlnotme/Planar.jl/issues) 218 219 ## Next Steps 220 221 After successful installation: 222 223 1. [Configure your first strategy](../guides/strategy-development.md) 224 2. [Set up exchange connections](../exchanges.md) 225 3. [Run your first backtest](../guides/execution-modes.md) 226 4. [Explore optimization features](../optimization.md) 227 228 ## Security Considerations 229 230 - Store API keys securely in `user/secrets.toml` 231 - Use IP restrictions on exchange APIs 232 - Start with sandbox/testnet environments 233 - Regular security audits of API permissions 234 - Monitor for unusual trading activity 235 236 ## Updates and Maintenance 237 238 ```bash 239 # Update Planar 240 git pull origin main 241 git submodule update --recursive 242 243 # Update Julia packages 244 julia --project=Planar -e "using Pkg; Pkg.update()" 245 246 # Rebuild if needed 247 julia --project=Planar -e "using Pkg; Pkg.build()" 248 ```