# Development Setup This guide covers setting up a development environment for contributing to General Bots. ## Prerequisites ### Required Software - **Rust**: 1.70 or later ```bash curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh ``` - **PostgreSQL**: Installed automatically during bootstrap - **Git**: For version control ```bash git --version # Should be 2.0 or later ``` ### Optional Components - **Drive**: For S3-compatible storage (auto-installed by bootstrap) - **Cache (Valkey)**: For caching (auto-installed by bootstrap) - **LXC**: For containerized development ## Getting Started ### 1. Clone the Repository ```bash git clone https://github.com/GeneralBots/BotServer.git cd botserver ``` ### 2. Environment Setup The `.env` file is created automatically during bootstrap with secure random credentials. No manual configuration needed. ```bash # Bootstrap creates everything automatically ./botserver DRIVE_SECRET=minioadmin SERVER_HOST=127.0.0.1 SERVER_PORT=8080 ``` ### 3. Install Rust Dependencies ```bash cargo fetch ``` ### 4. Run Bootstrap The bootstrap process installs and configures all required services: ```bash cargo run ``` On first run, bootstrap will: - Install PostgreSQL (if needed) - Install drive (S3-compatible storage) - Install cache (Valkey) - Create database schema - Upload bot templates - Generate secure credentials ## Development Workflow ### Building the Project ```bash # Debug build (faster compilation) cargo build # Release build (optimized) cargo build --release ``` ### Running Tests ```bash # Run all tests cargo test # Run specific test cargo test test_name # Run with output cargo test -- --nocapture ``` ### Code Formatting ```bash # Format all code cargo fmt # Check formatting without changes cargo fmt -- --check ``` ### Linting ```bash # Run clippy for lint checks cargo clippy -- -D warnings ``` ## Project Structure ``` botserver/ ├── src/ │ ├── main.rs # Application entry point │ ├── lib.rs # Library root │ ├── api_router.rs # API routes │ ├── core/ # Core functionality │ │ ├── bootstrap/ # System initialization │ │ ├── bot/ # Bot management │ │ ├── config/ # Configuration │ │ ├── session/ # Session management │ │ └── shared/ # Shared utilities │ ├── basic/ # BASIC interpreter │ │ ├── compiler/ # Script compilation │ │ └── keywords/ # Keyword implementations │ ├── drive/ # Storage integration │ └── llm/ # LLM providers ├── templates/ # Bot templates ├── migrations/ # Database migrations ├── web/ # Web interface └── Cargo.toml # Dependencies ``` ## Database Setup ### Manual Database Creation If bootstrap doesn't create the database: ```bash # Connect to PostgreSQL psql -U postgres # Create user and database CREATE USER gbuser WITH PASSWORD 'SecurePassword123!'; CREATE DATABASE generalbots OWNER gbuser; \q ``` ### Running Migrations Migrations run automatically, but can be run manually: ```bash # Install diesel CLI cargo install diesel_cli --no-default-features --features postgres # Run migrations diesel migration run ``` ## Common Development Tasks ### Adding a New Keyword 1. Create new file in `src/basic/keywords/` 2. Implement the keyword function 3. Register in `src/basic/keywords/mod.rs` 4. Add tests ### Adding an API Endpoint 1. Define handler in appropriate module 2. Add route in `src/api_router.rs` 3. Update OpenAPI documentation 4. Write integration tests ### Modifying Database Schema 1. Create migration: ```bash diesel migration generate migration_name ``` 2. Edit `up.sql` and `down.sql` 3. Run migration: ```bash diesel migration run ``` 4. Update models in `src/core/shared/models.rs` ## Remote Development Setup ### SSH Configuration for Stable Connections When developing on remote Linux servers, configure SSH for stable monitoring connections: Edit `~/.ssh/config`: ``` Host * ServerAliveInterval 60 ServerAliveCountMax 5 ``` This configuration: - **ServerAliveInterval 60**: Sends keepalive packets every 60 seconds - **ServerAliveCountMax 5**: Allows up to 5 missed keepalives before disconnecting - Prevents SSH timeouts during long compilations or debugging sessions - Maintains stable connections for monitoring logs and services ### Remote Monitoring Tips ```bash # Monitor BotServer logs in real-time ssh user@server 'tail -f botserver.log' # Watch compilation progress ssh user@server 'cd /path/to/botserver && cargo build --release' # Keep terminal session alive ssh user@server 'tmux new -s botserver' ``` ## Debugging ### Debug Mode Run with verbose output to troubleshoot issues: ```bash RUST_LOG=trace cargo run ``` Check logs in the console output for debugging information. ### Using VS Code `.vscode/launch.json`: ```json { "version": "0.2.0", "configurations": [ { "type": "lldb", "request": "launch", "name": "Debug BotServer", "cargo": { "args": ["build"], "filter": { "name": "botserver", "kind": "bin" } }, "args": [], "cwd": "${workspaceFolder}" } ] } ``` ## Performance Profiling ### Using Flamegraph ```bash # Install flamegraph cargo install flamegraph # Profile the application cargo flamegraph --bin botserver ``` ### Memory Profiling ```bash # Install valgrind (Linux) sudo apt-get install valgrind # Run with memory profiling valgrind --tool=memcheck cargo run ``` ## Testing with Different Features ### Feature Flags ```bash # Build with specific features cargo build --features "llm,drive" # Build without default features cargo build --no-default-features # Test with all features cargo test --all-features ``` ## Troubleshooting ### Common Issues 1. **Database Connection Failed** - Check PostgreSQL is running - Verify DATABASE_URL is correct - Check user permissions 2. **Drive Connection Failed** - Ensure drive is running on port 9000 - Check DRIVE_ACCESSKEY and DRIVE_SECRET 3. **Port Already in Use** - Change SERVER_PORT in .env - Kill existing process: `lsof -i :8080` 4. **Compilation Errors** - Update Rust: `rustup update` - Clean build: `cargo clean` - Check dependencies: `cargo tree` ## LXC Development ### Using LXC Containers ```bash # Create development containers lxc-create -n botserver-dev-db -t download -- -d alpine -r 3.18 -a amd64 lxc-create -n botserver-dev-drive -t download -- -d alpine -r 3.18 -a amd64 lxc-create -n botserver-dev-cache -t download -- -d alpine -r 3.18 -a amd64 # Configure PostgreSQL container lxc-start -n botserver-dev-db lxc-attach -n botserver-dev-db -- sh -c " apk add postgresql14 postgresql14-client rc-service postgresql setup rc-service postgresql start psql -U postgres -c \"CREATE USER gbuser WITH PASSWORD 'password';\" psql -U postgres -c \"CREATE DATABASE botserver OWNER gbuser;\" " # Configure MinIO (Drive) container lxc-start -n botserver-dev-drive lxc-attach -n botserver-dev-drive -- sh -c " wget https://dl.min.io/server/minio/release/linux-amd64/minio chmod +x minio MINIO_ROOT_USER=driveadmin MINIO_ROOT_PASSWORD=driveadmin ./minio server /data --console-address ':9001' & " # Configure Redis (Cache) container lxc-start -n botserver-dev-cache lxc-attach -n botserver-dev-cache -- sh -c " apk add redis rc-service redis start " # Get container IPs DB_IP=$(lxc-info -n botserver-dev-db -iH) DRIVE_IP=$(lxc-info -n botserver-dev-drive -iH) CACHE_IP=$(lxc-info -n botserver-dev-cache -iH) echo "Database: $DB_IP:5432" echo "Drive: $DRIVE_IP:9000" echo "Cache: $CACHE_IP:6379" ``` Start all services: ```bash lxc-start -n botserver-dev-db lxc-start -n botserver-dev-drive lxc-start -n botserver-dev-cache ``` ## Contributing Guidelines See [Contributing Guidelines](./contributing-guidelines.md) for: - Code style requirements - Commit message format - Pull request process - Code review expectations ## Getting Help - Check existing issues on GitHub - Join the community discussions - Review the documentation - Ask questions in pull requests ## Next Steps - Read the [Architecture Overview](../chapter-06/architecture.md) - Explore the [BASIC Language Reference](../chapter-05/README.md) - Review [Code Standards](./standards.md) - Start with a [good first issue](https://github.com/GeneralBots/BotServer/labels/good%20first%20issue)