diff --git a/docs/.gitbook.yaml b/docs/.gitbook.yaml deleted file mode 100644 index 1681f65..0000000 --- a/docs/.gitbook.yaml +++ /dev/null @@ -1,35 +0,0 @@ -# GitBook configuration for Starknode Kit documentation - -root: ./ -structure: - readme: README.md - summary: SUMMARY.md - -plugins: - - search - - sharing - - fontsettings - - highlight - - livereload - - expandable-chapters - - anchors - - github - - edit-link - - copy-code-button - -pluginsConfig: - github: - url: https://github.com/thebuidl-grid/starknode-kit - edit-link: - base: https://github.com/thebuidl-grid/starknode-kit/edit/main/docs - label: Edit This Page - sharing: - facebook: false - twitter: true - google: false - weibo: false - instapaper: false - vk: false - all: - - twitter - - linkedin diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md deleted file mode 100644 index d1b32aa..0000000 --- a/docs/DEPLOYMENT.md +++ /dev/null @@ -1,316 +0,0 @@ -# Documentation Deployment Guide - -This guide covers how to deploy the Starknode Kit documentation using GitBook and other platforms. - -## GitBook Deployment - -### Option 1: GitBook.com (Recommended) - -1. **Create GitBook Account** - - Go to [GitBook.com](https://www.gitbook.com) - - Sign up with your GitHub account - -2. **Import Repository** - - Click "New Space" - - Select "Import from GitHub" - - Choose `thebuidl-grid/starknode-kit` - - Select the `docs` folder as the root - -3. **Configure Settings** - - Set title: "Starknode Kit Documentation" - - Set description: "Complete guide for Ethereum and Starknet node management" - - Enable public access - -4. **Custom Domain (Optional)** - - Go to Space Settings > Domains - - Add your custom domain (e.g., `docs.starknode-kit.com`) - - Update DNS records as instructed - -### Option 2: Self-Hosted GitBook - -1. **Install GitBook CLI** - ```bash - npm install -g gitbook-cli - ``` - -2. **Install Dependencies** - ```bash - cd docs - npm install - gitbook install - ``` - -3. **Build Documentation** - ```bash - gitbook build - ``` - -4. **Serve Locally** - ```bash - gitbook serve - ``` - -5. **Deploy to Web Server** - ```bash - # Copy built files to web server - rsync -av _book/ user@server:/var/www/docs/ - ``` - -## GitHub Pages Deployment - -### Automatic Deployment with GitHub Actions - -1. **Create GitHub Action** - ```yaml - # .github/workflows/docs.yml - name: Deploy Documentation - - on: - push: - branches: [ main ] - paths: [ 'docs/**' ] - - jobs: - deploy: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - - name: Setup Node.js - uses: actions/setup-node@v3 - with: - node-version: '16' - - - name: Install GitBook - run: npm install -g gitbook-cli - - - name: Build Documentation - run: | - cd docs - gitbook install - gitbook build - - - name: Deploy to GitHub Pages - uses: peaceiris/actions-gh-pages@v3 - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./docs/_book - ``` - -2. **Enable GitHub Pages** - - Go to repository Settings > Pages - - Select "GitHub Actions" as source - - The documentation will be available at `https://thebuidl-grid.github.io/starknode-kit` - -## Netlify Deployment - -1. **Connect Repository** - - Go to [Netlify](https://netlify.com) - - Connect your GitHub repository - -2. **Build Settings** - - Build command: `cd docs && gitbook build` - - Publish directory: `docs/_book` - -3. **Deploy** - - Netlify will automatically build and deploy - - Custom domain can be configured in site settings - -## Vercel Deployment - -1. **Install Vercel CLI** - ```bash - npm install -g vercel - ``` - -2. **Configure Project** - ```json - // vercel.json - { - "builds": [ - { - "src": "docs/package.json", - "use": "@vercel/static-build", - "config": { - "distDir": "_book" - } - } - ] - } - ``` - -3. **Deploy** - ```bash - cd docs - vercel --prod - ``` - -## Docker Deployment - -1. **Create Dockerfile** - ```dockerfile - FROM node:16-alpine - - WORKDIR /app - - # Install GitBook - RUN npm install -g gitbook-cli - - # Copy documentation - COPY docs/ ./docs/ - - # Build documentation - WORKDIR /app/docs - RUN gitbook install && gitbook build - - # Serve with nginx - FROM nginx:alpine - COPY --from=0 /app/docs/_book /usr/share/nginx/html - EXPOSE 80 - ``` - -2. **Build and Run** - ```bash - docker build -t starknode-kit-docs . - docker run -p 8080:80 starknode-kit-docs - ``` - -## Continuous Integration - -### GitHub Actions Workflow - -```yaml -name: Documentation CI/CD - -on: - push: - branches: [ main ] - paths: [ 'docs/**' ] - pull_request: - branches: [ main ] - paths: [ 'docs/**' ] - -jobs: - test: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - - name: Setup Node.js - uses: actions/setup-node@v3 - with: - node-version: '16' - - - name: Install dependencies - run: | - cd docs - npm install - npm install -g gitbook-cli - - - name: Build documentation - run: | - cd docs - gitbook install - gitbook build - - - name: Test build - run: | - cd docs - ls -la _book/ - - deploy: - needs: test - runs-on: ubuntu-latest - if: github.ref == 'refs/heads/main' - steps: - - uses: actions/checkout@v3 - - - name: Deploy to production - run: | - # Add deployment commands here - echo "Deploying to production..." -``` - -## Monitoring and Analytics - -### Google Analytics - -Add to `book.json`: -```json -{ - "pluginsConfig": { - "google-analytics": { - "token": "GA_TRACKING_ID" - } - } -} -``` - -### Search Engine Optimization - -1. **Add meta tags** to `README.md` -2. **Create sitemap** for better indexing -3. **Use descriptive URLs** and headings -4. **Add structured data** for rich snippets - -## Maintenance - -### Regular Updates - -1. **Content Updates** - - Review and update documentation monthly - - Keep examples current with latest versions - - Update screenshots and diagrams - -2. **Technical Updates** - - Update GitBook plugins regularly - - Test builds on different platforms - - Monitor for broken links - -3. **Performance Monitoring** - - Monitor page load times - - Check for broken links - - Review user feedback - -### Backup Strategy - -1. **Repository Backup** - - Documentation is stored in Git repository - - Regular backups to multiple locations - -2. **Build Artifacts** - - Store built documentation as releases - - Keep multiple versions for rollback - -## Troubleshooting - -### Common Issues - -**Build Failures** -```bash -# Clear cache and rebuild -rm -rf node_modules -npm install -gitbook install -gitbook build -``` - -**Plugin Issues** -```bash -# Update plugins -gitbook update -``` - -**Deployment Issues** -- Check build logs -- Verify file permissions -- Test locally first - -## Getting Help - -For deployment issues: - -- Check GitBook documentation -- Review platform-specific guides -- Join our [Telegram community](https://t.me/+SCPbza9fk8dkYWI0) -- Open an issue on [GitHub](https://github.com/thebuidl-grid/starknode-kit/issues) diff --git a/docs/README.md b/docs/README.md index d394eff..7f484bd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,75 +1,71 @@ -# Starknode Kit Documentation +# starknode-kit Documentation -Welcome to the comprehensive documentation for **Starknode Kit** - a powerful CLI tool for setting up, managing, and maintaining Ethereum and Starknet nodes. +Official documentation for starknode-kit, built with Next.js. -## 🚀 Quick Start - -Get up and running with Starknode Kit in minutes: +## Quick Start ```bash -# Install Starknode Kit -curl -sSL https://raw.githubusercontent.com/thebuidl-grid/starknode-kit/main/install.sh | bash - -# Initialize configuration -starknode-kit init +# Install dependencies +npm install -# Add your first client -starknode-kit add --consensus_client lighthouse --execution_client geth - -# Start your node -starknode-kit start +# Run development server +npm run dev ``` -## 📚 Documentation Structure +Open [http://localhost:3000](http://localhost:3000) to view the documentation. -### Getting Started -- [Installation and Setup](getting-started/installation.md) -- [Hardware Requirements](getting-started/hardware-requirements.md) -- [Quick Start Guide](getting-started/quick-start.md) -- [Configuration](getting-started/configuration.md) +## Features -### Client Management -- [Adding Clients](client-management/adding-clients.md) -- [Ethereum Clients](client-management/ethereum-clients.md) -- [Starknet Clients](client-management/starknet-clients.md) -- [Client Configuration](client-management/client-configuration.md) +- 🎨 Light/Dark mode toggle +- 📱 Responsive design +- 🔍 Clean, simple navigation +- 📝 Comprehensive guides +- 💻 Code examples with copy button -### Operations -- [Running Nodes](operations/running-nodes.md) -- [Monitoring](operations/monitoring.md) -- [Updates and Maintenance](operations/updates.md) -- [Troubleshooting](operations/troubleshooting.md) +## Building -### Advanced Topics -- [Network Configuration](advanced/network-configuration.md) -- [Performance Optimization](advanced/performance.md) -- [Security Best Practices](advanced/security.md) -- [Custom Configurations](advanced/custom-configurations.md) +```bash +# Build for production +npm run build -### API Reference -- [Command Reference](api-reference/commands.md) -- [Configuration Schema](api-reference/configuration-schema.md) -- [Environment Variables](api-reference/environment-variables.md) +# Start production server +npm start +``` -## 🌟 Key Features +## Documentation Pages -- **🔧 Multi-Client Support**: Manage Ethereum (Geth, Reth, Lighthouse, Prysm) and Starknet (Juno) clients -- **⚡ Easy Setup**: One-command installation and configuration -- **📊 Real-time Monitoring**: Built-in monitoring dashboard -- **🔄 Auto-Updates**: Automatic client updates and maintenance -- **🌐 Network Flexibility**: Support for mainnet, testnets, and custom networks -- **🛡️ Production Ready**: Designed for both development and production environments +- **Introduction** - Overview and quick start +- **Getting Started** - Step-by-step setup guide +- **Installation** - Installation methods +- **Configuration** - Node configuration +- **Commands** - CLI command reference +- **Clients** - Supported clients (Geth, Reth, Lighthouse, Prysm, Juno) +- **Validator Setup** - Validator node setup +- **Requirements** - Hardware/software requirements +- **Contributing** - Contribution guidelines -## 🤝 Community and Support +## Project Structure -- **Telegram**: [Join our community](https://t.me/+SCPbza9fk8dkYWI0) -- **GitHub**: [Report issues and contribute](https://github.com/thebuidl-grid/starknode-kit) -- **Documentation**: This comprehensive guide +``` +docs/ +├── src/ +│ ├── app/ # Documentation pages +│ │ ├── page.tsx # Homepage +│ │ ├── layout.tsx # Root layout +│ │ ├── globals.css # Global styles +│ │ └── [pages]/ # Documentation pages +│ └── components/ # Reusable components +│ ├── Sidebar.tsx # Navigation sidebar +│ ├── Header.tsx # Top header +│ ├── ThemeToggle.tsx # Light/dark mode toggle +│ └── CodeBlock.tsx # Code block with copy +└── package.json +``` -## 📄 License +## Contributing -This project is licensed under the MIT License - see the [LICENSE](https://github.com/thebuidl-grid/starknode-kit/blob/main/LICENSE) file for details. +See the main [Contributing Guide](../README.md#contributing) for guidelines. ---- +## License -*Built with ❤️ by The Buidl Grid* \ No newline at end of file +MIT License - see LICENSE file for details. diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md deleted file mode 100644 index fa70d8b..0000000 --- a/docs/SUMMARY.md +++ /dev/null @@ -1,35 +0,0 @@ -# Table of Contents - -## Getting Started - -* [Installation and Setup](getting-started/installation.md) -* [Hardware Requirements](getting-started/hardware-requirements.md) -* [Quick Start Guide](getting-started/quick-start.md) -* [Configuration](getting-started/configuration.md) - -## Client Management - -* [Adding Clients](client-management/adding-clients.md) -* [Ethereum Clients](client-management/ethereum-clients.md) -* [Starknet Clients](client-management/starknet-clients.md) -* [Client Configuration](client-management/client-configuration.md) - -## Operations - -* [Running Nodes](operations/running-nodes.md) -* [Monitoring](operations/monitoring.md) -* [Updates and Maintenance](operations/updates.md) -* [Troubleshooting](operations/troubleshooting.md) - -## Advanced Topics - -* [Network Configuration](advanced/network-configuration.md) -* [Performance Optimization](advanced/performance.md) -* [Security Best Practices](advanced/security.md) -* [Custom Configurations](advanced/custom-configurations.md) - -## API Reference - -* [Command Reference](api-reference/commands.md) -* [Configuration Schema](api-reference/configuration-schema.md) -* [Environment Variables](api-reference/environment-variables.md) diff --git a/docs/api-reference/commands.md b/docs/api-reference/commands.md deleted file mode 100644 index ed53018..0000000 --- a/docs/api-reference/commands.md +++ /dev/null @@ -1,473 +0,0 @@ -# Command Reference - -Complete reference for all Starknode Kit commands, flags, and options. - -## Global Commands - -### `starknode-kit --help` - -Display help information for the Starknode Kit CLI. - -```bash -starknode-kit --help -``` - -**Output**: Shows available commands and global flags. - ---- - -## Core Commands - -### `init` - -Create a default configuration file. - -```bash -starknode-kit init -``` - -**Description**: Initializes a new configuration file with default settings. - -**Files Created**: -- `~/.starknode-kit/config.yaml` - -**Example**: -```bash -starknode-kit init -# Creates default configuration file -``` - ---- - -### `add` - -Add an Ethereum or Starknet client to the configuration. - -```bash -starknode-kit add [flags] -``` - -**Flags**: -- `-e, --execution_client string`: Execution client (geth, reth) -- `-c, --consensus_client string`: Consensus client (lighthouse, prysm) -- `-s, --starknet_client string`: Starknet client (juno) - -**Examples**: -```bash -# Add execution client -starknode-kit add --execution_client geth - -# Add consensus client -starknode-kit add --consensus_client lighthouse - -# Add Starknet client -starknode-kit add --starknet_client juno - -# Add client pair -starknode-kit add --execution_client geth --consensus_client lighthouse - -# Add all clients -starknode-kit add --execution_client geth --consensus_client lighthouse --starknet_client juno -``` - ---- - -### `config` - -Show and modify the current configuration. - -```bash -starknode-kit config [flags] [options] -``` - -**Flags**: -- `-n, --network string`: Set network (mainnet, sepolia, holesky) -- `--validate`: Validate configuration file - -**Options**: -- `el client= port=`: Configure execution client -- `cl client= port=`: Configure consensus client -- `starknet client= port=`: Configure Starknet client - -**Examples**: -```bash -# Show current configuration -starknode-kit config - -# Set network -starknode-kit config -n sepolia - -# Configure execution client -starknode-kit config el client=geth port=8545,8546 - -# Configure consensus client -starknode-kit config cl client=lighthouse port=9000,9001 - -# Validate configuration -starknode-kit config --validate -``` - ---- - -### `start` - -Start the configured Ethereum clients. - -```bash -starknode-kit start -``` - -**Description**: Starts execution and consensus clients. Does not start Starknet clients. - -**Examples**: -```bash -# Start all configured clients -starknode-kit start -``` - -**Note**: Use `starknode-kit run juno` to start Starknet clients. - ---- - -### `stop` - -Stop all running clients. - -```bash -starknode-kit stop -``` - -**Description**: Gracefully stops all running clients. - -**Examples**: -```bash -# Stop all clients -starknode-kit stop -``` - ---- - -### `run` - -Run local Starknet infrastructure services. - -```bash -starknode-kit run -``` - -**Subcommands**: -- `juno`: Run a Juno Starknet node - -**Examples**: -```bash -# Run Juno node -starknode-kit run juno -``` - ---- - -### `monitor` - -Launch the real-time monitoring dashboard. - -```bash -starknode-kit monitor [flags] -``` - -**Flags**: -- `--interval duration`: Refresh interval (default: 5s) -- `--basic`: Basic monitoring mode -- `--restart`: Restart monitoring service - -**Examples**: -```bash -# Start monitoring dashboard -starknode-kit monitor - -# Custom refresh interval -starknode-kit monitor --interval 10s - -# Basic monitoring mode -starknode-kit monitor --basic -``` - ---- - -### `remove` - -Remove a configured client. - -```bash -starknode-kit remove [flags] -``` - -**Flags**: -- `-e, --execution_client string`: Remove execution client -- `-c, --consensus_client string`: Remove consensus client -- `-s, --starknet_client string`: Remove Starknet client - -**Examples**: -```bash -# Remove execution client -starknode-kit remove --execution_client geth - -# Remove consensus client -starknode-kit remove --consensus_client lighthouse - -# Remove Starknet client -starknode-kit remove --starknet_client juno -``` - ---- - -### `update` - -Check for and install client updates. - -```bash -starknode-kit update [flags] -``` - -**Flags**: -- `-e, --execution_client string`: Update specific execution client -- `-c, --consensus_client string`: Update specific consensus client -- `-s, --starknet_client string`: Update specific Starknet client - -**Examples**: -```bash -# Update all clients -starknode-kit update - -# Update specific client -starknode-kit update --execution_client geth -starknode-kit update --consensus_client lighthouse -starknode-kit update --starknet_client juno -``` - ---- - -## Utility Commands - -### `completion` - -Generate shell completion scripts. - -```bash -starknode-kit completion -``` - -**Supported Shells**: -- `bash` -- `zsh` -- `fish` -- `powershell` - -**Examples**: -```bash -# Generate bash completion -starknode-kit completion bash - -# Install bash completion -starknode-kit completion bash > /etc/bash_completion.d/starknode-kit - -# Generate zsh completion -starknode-kit completion zsh > ~/.zsh/completions/_starknode-kit -``` - ---- - -## Global Flags - -### `-h, --help` - -Show help information for any command. - -```bash -starknode-kit --help -``` - -**Examples**: -```bash -starknode-kit add --help -starknode-kit config --help -starknode-kit start --help -``` - ---- - -## Command Combinations - -### Complete Setup Workflow - -```bash -# 1. Initialize configuration -starknode-kit init - -# 2. Add clients -starknode-kit add --execution_client geth --consensus_client lighthouse --starknet_client juno - -# 3. Configure network -starknode-kit config -n mainnet - -# 4. Start Ethereum clients -starknode-kit start - -# 5. Start Starknet client (in separate terminal) -starknode-kit run juno - -# 6. Monitor everything -starknode-kit monitor -``` - -### Development Workflow - -```bash -# 1. Set up testnet -starknode-kit config -n sepolia - -# 2. Add development clients -starknode-kit add --execution_client geth --consensus_client prysm - -# 3. Start clients -starknode-kit start - -# 4. Monitor progress -starknode-kit monitor -``` - -### Maintenance Workflow - -```bash -# 1. Check for updates -starknode-kit update - -# 2. Stop clients -starknode-kit stop - -# 3. Update clients -starknode-kit update - -# 4. Restart clients -starknode-kit start - -# 5. Verify status -starknode-kit monitor -``` - ---- - -## Exit Codes - -| Code | Description | -|------|-------------| -| `0` | Success | -| `1` | General error | -| `2` | Configuration error | -| `3` | Client error | -| `4` | Network error | -| `5` | Permission error | - ---- - -## Environment Variables - -### Configuration - -- `STARKNODE_CONFIG_PATH`: Custom config file path -- `STARKNODE_LOG_LEVEL`: Log level (debug, info, warn, error) -- `STARKNODE_DATA_DIR`: Custom data directory - -### Client Configuration - -- `GETH_CACHE`: Geth cache size -- `LIGHTHOUSE_MAX_PEERS`: Lighthouse max peers -- `JUNO_ETH_NODE`: Juno Ethereum node URL - -**Examples**: -```bash -# Set custom config path -export STARKNODE_CONFIG_PATH=/custom/path/config.yaml - -# Set log level -export STARKNODE_LOG_LEVEL=debug - -# Set Geth cache -export GETH_CACHE=4096 -``` - ---- - -## Configuration File Format - -The configuration file is in YAML format: - -```yaml -network: mainnet -execution_client: - name: geth - port: [8545, 8546] - execution_type: full - additional_args: [] -consensus_client: - name: lighthouse - port: [9000, 9001] - consensus_checkpoint: "" - additional_args: [] -starknet_client: - name: juno - port: [6060, 6061] - eth_node_url: "http://localhost:8545" - additional_args: [] -``` - ---- - -## Troubleshooting Commands - -### Debug Information - -```bash -# Show detailed configuration -starknode-kit config --validate - -# Check client status -starknode-kit config - -# Monitor with debug logs -starknode-kit monitor --interval 1s -``` - -### Log Analysis - -```bash -# View client logs -tail -f ~/.starknode-kit/logs/geth.log -tail -f ~/.starknode-kit/logs/lighthouse.log -tail -f ~/.starknode-kit/logs/juno.log - -# Search for errors -grep -i error ~/.starknode-kit/logs/*.log -``` - ---- - -## Getting Help - -For command-specific help: - -```bash -# General help -starknode-kit --help - -# Command help -starknode-kit --help - -# Subcommand help -starknode-kit run --help -``` - -For additional support: - -- Check the [Troubleshooting Guide](../operations/troubleshooting.md) -- Join our [Telegram community](https://t.me/+SCPbza9fk8dkYWI0) -- Open an issue on [GitHub](https://github.com/thebuidl-grid/starknode-kit/issues) diff --git a/docs/api-reference/configuration-schema.md b/docs/api-reference/configuration-schema.md deleted file mode 100644 index 0a6bac7..0000000 --- a/docs/api-reference/configuration-schema.md +++ /dev/null @@ -1,605 +0,0 @@ -# Configuration Schema - -Complete reference for the Starknode Kit configuration file format and all available options. - -## Configuration File Location - -- **Linux/macOS**: `~/.starknode-kit/config.yaml` -- **Windows**: `%USERPROFILE%\.starknode-kit\config.yaml` - -## Schema Overview - -```yaml -# Network configuration -network: string - -# Execution client configuration -execution_client: - name: string - port: [number, number] - execution_type: string - additional_args: [string] - env_vars: {string: string} - resource_limits: - memory: string - cpu: string - -# Consensus client configuration -consensus_client: - name: string - port: [number, number] - consensus_checkpoint: string - additional_args: [string] - env_vars: {string: string} - resource_limits: - memory: string - cpu: string - -# Starknet client configuration -starknet_client: - name: string - port: [number, number] - eth_node_url: string - additional_args: [string] - env_vars: {string: string} - resource_limits: - memory: string - cpu: string -``` - -## Network Configuration - -### `network` - -**Type**: `string` -**Required**: Yes -**Default**: `mainnet` - -**Valid Values**: -- `mainnet` - Ethereum mainnet -- `sepolia` - Sepolia testnet -- `holesky` - Holesky testnet -- `goerli` - Goerli testnet (deprecated) - -**Example**: -```yaml -network: mainnet -``` - -## Execution Client Configuration - -### `execution_client` - -**Type**: `object` -**Required**: No - -#### `execution_client.name` - -**Type**: `string` -**Required**: Yes - -**Valid Values**: -- `geth` - Go Ethereum client -- `reth` - Rust Ethereum client - -**Example**: -```yaml -execution_client: - name: geth -``` - -#### `execution_client.port` - -**Type**: `[number, number]` -**Required**: No -**Default**: `[8545, 8546]` - -**Description**: HTTP and WebSocket RPC ports - -**Example**: -```yaml -execution_client: - port: [8545, 8546] -``` - -#### `execution_client.execution_type` - -**Type**: `string` -**Required**: No -**Default**: `full` - -**Valid Values**: -- `full` - Full node with recent state -- `archive` - Complete historical data -- `light` - Minimal data, relies on peers - -**Example**: -```yaml -execution_client: - execution_type: full -``` - -#### `execution_client.additional_args` - -**Type**: `[string]` -**Required**: No -**Default**: `[]` - -**Description**: Additional command line arguments - -**Example**: -```yaml -execution_client: - additional_args: - - "--maxpeers" - - "50" - - "--cache" - - "4096" -``` - -#### `execution_client.env_vars` - -**Type**: `{string: string}` -**Required**: No -**Default**: `{}` - -**Description**: Environment variables for the client - -**Example**: -```yaml -execution_client: - env_vars: - GETH_CACHE: "4096" - GETH_MAXPEERS: "50" -``` - -#### `execution_client.resource_limits` - -**Type**: `object` -**Required**: No - -##### `execution_client.resource_limits.memory` - -**Type**: `string` -**Required**: No - -**Description**: Memory limit (e.g., "8Gi", "4G") - -**Example**: -```yaml -execution_client: - resource_limits: - memory: "8Gi" -``` - -##### `execution_client.resource_limits.cpu` - -**Type**: `string` -**Required**: No - -**Description**: CPU limit (e.g., "4", "2.5") - -**Example**: -```yaml -execution_client: - resource_limits: - cpu: "4" -``` - -## Consensus Client Configuration - -### `consensus_client` - -**Type**: `object` -**Required**: No - -#### `consensus_client.name` - -**Type**: `string` -**Required**: Yes - -**Valid Values**: -- `lighthouse` - Rust-based consensus client -- `prysm` - Go-based consensus client - -**Example**: -```yaml -consensus_client: - name: lighthouse -``` - -#### `consensus_client.port` - -**Type**: `[number, number]` -**Required**: No -**Default**: `[9000, 9001]` (Lighthouse), `[13000, 3500]` (Prysm) - -**Description**: P2P and HTTP API ports - -**Example**: -```yaml -consensus_client: - port: [9000, 9001] -``` - -#### `consensus_client.consensus_checkpoint` - -**Type**: `string` -**Required**: No -**Default**: `""` - -**Description**: Checkpoint URL for faster sync - -**Example**: -```yaml -consensus_client: - consensus_checkpoint: "https://mainnet.checkpoint.sigp.io" -``` - -#### `consensus_client.additional_args` - -**Type**: `[string]` -**Required**: No -**Default**: `[]` - -**Description**: Additional command line arguments - -**Example**: -```yaml -consensus_client: - additional_args: - - "--max-peers" - - "50" - - "--target-peers" - - "25" -``` - -#### `consensus_client.env_vars` - -**Type**: `{string: string}` -**Required**: No -**Default**: `{}` - -**Description**: Environment variables for the client - -**Example**: -```yaml -consensus_client: - env_vars: - LIGHTHOUSE_MAX_PEERS: "50" - LIGHTHOUSE_TARGET_PEERS: "25" -``` - -#### `consensus_client.resource_limits` - -**Type**: `object` -**Required**: No - -##### `consensus_client.resource_limits.memory` - -**Type**: `string` -**Required**: No - -**Description**: Memory limit (e.g., "4Gi", "2G") - -**Example**: -```yaml -consensus_client: - resource_limits: - memory: "4Gi" -``` - -##### `consensus_client.resource_limits.cpu` - -**Type**: `string` -**Required**: No - -**Description**: CPU limit (e.g., "2", "1.5") - -**Example**: -```yaml -consensus_client: - resource_limits: - cpu: "2" -``` - -## Starknet Client Configuration - -### `starknet_client` - -**Type**: `object` -**Required**: No - -#### `starknet_client.name` - -**Type**: `string` -**Required**: Yes - -**Valid Values**: -- `juno` - Go-based Starknet full node - -**Example**: -```yaml -starknet_client: - name: juno -``` - -#### `starknet_client.port` - -**Type**: `[number, number]` -**Required**: No -**Default**: `[6060, 6061]` - -**Description**: HTTP and WebSocket RPC ports - -**Example**: -```yaml -starknet_client: - port: [6060, 6061] -``` - -#### `starknet_client.eth_node_url` - -**Type**: `string` -**Required**: Yes - -**Description**: Ethereum node URL for L1 verification - -**Example**: -```yaml -starknet_client: - eth_node_url: "http://localhost:8545" -``` - -#### `starknet_client.additional_args` - -**Type**: `[string]` -**Required**: No -**Default**: `[]` - -**Description**: Additional command line arguments - -**Example**: -```yaml -starknet_client: - additional_args: - - "--max-peers" - - "50" - - "--log-level" - - "info" -``` - -#### `starknet_client.env_vars` - -**Type**: `{string: string}` -**Required**: No -**Default**: `{}` - -**Description**: Environment variables for the client - -**Example**: -```yaml -starknet_client: - env_vars: - JUNO_MAX_PEERS: "50" - JUNO_LOG_LEVEL: "info" -``` - -#### `starknet_client.resource_limits` - -**Type**: `object` -**Required**: No - -##### `starknet_client.resource_limits.memory` - -**Type**: `string` -**Required**: No - -**Description**: Memory limit (e.g., "4Gi", "2G") - -**Example**: -```yaml -starknet_client: - resource_limits: - memory: "4Gi" -``` - -##### `starknet_client.resource_limits.cpu` - -**Type**: `string` -**Required**: No - -**Description**: CPU limit (e.g., "2", "1.5") - -**Example**: -```yaml -starknet_client: - resource_limits: - cpu: "2" -``` - -## Complete Configuration Examples - -### Development Setup - -```yaml -network: sepolia -execution_client: - name: geth - port: [8545, 8546] - execution_type: full - additional_args: - - "--maxpeers" - - "25" - - "--cache" - - "2048" -consensus_client: - name: lighthouse - port: [9000, 9001] - additional_args: - - "--max-peers" - - "25" -starknet_client: - name: juno - port: [6060, 6061] - eth_node_url: "http://localhost:8545" - additional_args: - - "--max-peers" - - "25" -``` - -### Production Setup - -```yaml -network: mainnet -execution_client: - name: reth - port: [8545, 8546] - execution_type: full - additional_args: - - "--max-peers" - - "100" - - "--cache" - - "8192" - resource_limits: - memory: "16Gi" - cpu: "8" -consensus_client: - name: lighthouse - port: [9000, 9001] - consensus_checkpoint: "https://mainnet.checkpoint.sigp.io" - additional_args: - - "--max-peers" - - "50" - - "--target-peers" - - "25" - resource_limits: - memory: "8Gi" - cpu: "4" -starknet_client: - name: juno - port: [6060, 6061] - eth_node_url: "http://localhost:8545" - additional_args: - - "--max-peers" - - "50" - resource_limits: - memory: "8Gi" - cpu: "4" -``` - -### Archive Node Setup - -```yaml -network: mainnet -execution_client: - name: geth - port: [8545, 8546] - execution_type: archive - additional_args: - - "--cache" - - "16384" - - "--maxpeers" - - "100" - resource_limits: - memory: "32Gi" - cpu: "16" -consensus_client: - name: lighthouse - port: [9000, 9001] - execution_type: archive - additional_args: - - "--max-peers" - - "50" - resource_limits: - memory: "16Gi" - cpu: "8" -``` - -## Validation Rules - -### Required Fields - -- `network` - Must be a valid network name -- `execution_client.name` - Must be a valid execution client -- `consensus_client.name` - Must be a valid consensus client -- `starknet_client.name` - Must be a valid Starknet client -- `starknet_client.eth_node_url` - Must be a valid URL - -### Port Validation - -- Ports must be in range 1024-65535 -- Ports must not conflict with system ports -- HTTP and WebSocket ports must be different - -### Resource Limits - -- Memory must be in format "XGi" or "XG" -- CPU must be a positive number -- Limits must not exceed system resources - -## Environment Variables - -### Configuration Override - -Environment variables can override configuration file settings: - -```bash -# Override network -export STARKNODE_NETWORK=sepolia - -# Override execution client -export STARKNODE_EXECUTION_CLIENT=geth - -# Override consensus client -export STARKNODE_CONSENSUS_CLIENT=lighthouse -``` - -### Client-Specific Variables - -```bash -# Geth variables -export GETH_CACHE=4096 -export GETH_MAXPEERS=50 - -# Lighthouse variables -export LIGHTHOUSE_MAX_PEERS=50 -export LIGHTHOUSE_TARGET_PEERS=25 - -# Juno variables -export JUNO_MAX_PEERS=50 -export JUNO_LOG_LEVEL=info -``` - -## Configuration Management - -### Validation - -```bash -# Validate configuration -starknode-kit config --validate -``` - -### Backup - -```bash -# Backup configuration -cp ~/.starknode-kit/config.yaml ~/.starknode-kit/config.yaml.backup -``` - -### Reset - -```bash -# Reset to defaults -rm ~/.starknode-kit/config.yaml -starknode-kit init -``` - -## Getting Help - -For configuration issues: - -- Check the [Troubleshooting Guide](../operations/troubleshooting.md) -- Review client-specific documentation -- Join our [Telegram community](https://t.me/+SCPbza9fk8dkYWI0) -- Open an issue on [GitHub](https://github.com/thebuidl-grid/starknode-kit/issues) diff --git a/docs/api-reference/environment-variables.md b/docs/api-reference/environment-variables.md deleted file mode 100644 index 9fbd1e7..0000000 --- a/docs/api-reference/environment-variables.md +++ /dev/null @@ -1,323 +0,0 @@ -# Environment Variables - -Complete reference for all environment variables used by Starknode Kit and its clients. - -## Starknode Kit Variables - -### Configuration - -| Variable | Description | Default | Example | -|----------|-------------|---------|---------| -| `STARKNODE_CONFIG_PATH` | Custom config file path | `~/.starknode-kit/config.yaml` | `/custom/path/config.yaml` | -| `STARKNODE_LOG_LEVEL` | Log level for Starknode Kit | `info` | `debug`, `info`, `warn`, `error` | -| `STARKNODE_DATA_DIR` | Custom data directory | `~/.starknode-kit/` | `/custom/data/path/` | -| `STARKNODE_NETWORK` | Override network setting | From config | `mainnet`, `sepolia`, `holesky` | -| `STARKNODE_EXECUTION_CLIENT` | Override execution client | From config | `geth`, `reth` | -| `STARKNODE_CONSENSUS_CLIENT` | Override consensus client | From config | `lighthouse`, `prysm` | -| `STARKNODE_STARKNET_CLIENT` | Override Starknet client | From config | `juno` | - -### Monitoring - -| Variable | Description | Default | Example | -|----------|-------------|---------|---------| -| `STARKNODE_MONITOR_INTERVAL` | Monitoring refresh interval | `5s` | `10s`, `30s` | -| `STARKNODE_MONITOR_LOG_LEVEL` | Monitoring log level | `info` | `debug`, `info`, `warn` | -| `STARKNODE_MONITOR_METRICS` | Enable metrics collection | `true` | `true`, `false` | -| `STARKNODE_MONITOR_BASIC` | Use basic monitoring mode | `false` | `true`, `false` | - -## Execution Client Variables - -### Geth Variables - -| Variable | Description | Default | Example | -|----------|-------------|---------|---------| -| `GETH_CACHE` | Memory cache size (MB) | `1024` | `4096`, `8192` | -| `GETH_MAXPEERS` | Maximum number of peers | `50` | `100`, `25` | -| `GETH_LIGHTKDF` | Use light KDF for key derivation | `false` | `true`, `false` | -| `GETH_NETWORKID` | Network ID | `1` (mainnet) | `11155111` (sepolia) | -| `GETH_DATADIR` | Data directory | `~/.starknode-kit/data/geth/` | `/custom/path/` | -| `GETH_HTTP_PORT` | HTTP RPC port | `8545` | `8547` | -| `GETH_WS_PORT` | WebSocket RPC port | `8546` | `8548` | -| `GETH_P2P_PORT` | P2P networking port | `30303` | `30305` | -| `GETH_HTTP_ADDR` | HTTP RPC address | `localhost` | `0.0.0.0` | -| `GETH_WS_ADDR` | WebSocket RPC address | `localhost` | `0.0.0.0` | -| `GETH_HTTP_API` | HTTP RPC API modules | `eth,net,web3` | `eth,net,web3,admin` | -| `GETH_WS_API` | WebSocket RPC API modules | `eth,net,web3` | `eth,net,web3,admin` | -| `GETH_HTTP_CORS` | HTTP RPC CORS origins | `*` | `http://localhost:3000` | -| `GETH_WS_ORIGINS` | WebSocket RPC origins | `*` | `http://localhost:3000` | -| `GETH_HTTP_VHOSTS` | HTTP RPC virtual hosts | `localhost` | `localhost,example.com` | -| `GETH_WS_VHOSTS` | WebSocket RPC virtual hosts | `localhost` | `localhost,example.com` | -| `GETH_METRICS` | Enable metrics | `false` | `true`, `false` | -| `GETH_METRICS_ADDR` | Metrics address | `127.0.0.1` | `0.0.0.0` | -| `GETH_METRICS_PORT` | Metrics port | `6060` | `6061` | -| `GETH_PPROF` | Enable pprof | `false` | `true`, `false` | -| `GETH_PPROF_ADDR` | pprof address | `127.0.0.1` | `0.0.0.0` | -| `GETH_PPROF_PORT` | pprof port | `6060` | `6061` | - -### Reth Variables - -| Variable | Description | Default | Example | -|----------|-------------|---------|---------| -| `RETH_DATADIR` | Data directory | `~/.starknode-kit/data/reth/` | `/custom/path/` | -| `RETH_HTTP_PORT` | HTTP RPC port | `8545` | `8547` | -| `RETH_WS_PORT` | WebSocket RPC port | `8546` | `8548` | -| `RETH_P2P_PORT` | P2P networking port | `30303` | `30305` | -| `RETH_HTTP_ADDR` | HTTP RPC address | `127.0.0.1` | `0.0.0.0` | -| `RETH_WS_ADDR` | WebSocket RPC address | `127.0.0.1` | `0.0.0.0` | -| `RETH_MAX_PEERS` | Maximum number of peers | `50` | `100`, `25` | -| `RETH_TARGET_PEERS` | Target number of peers | `25` | `50`, `15` | -| `RETH_CACHE_SIZE` | Cache size (MB) | `1024` | `4096`, `8192` | -| `RETH_NETWORK` | Network name | `mainnet` | `sepolia`, `holesky` | -| `RETH_CHAIN` | Chain specification | `mainnet` | `sepolia`, `holesky` | -| `RETH_HTTP_CORS` | HTTP RPC CORS origins | `*` | `http://localhost:3000` | -| `RETH_WS_ORIGINS` | WebSocket RPC origins | `*` | `http://localhost:3000` | -| `RETH_METRICS` | Enable metrics | `false` | `true`, `false` | -| `RETH_METRICS_ADDR` | Metrics address | `127.0.0.1` | `0.0.0.0` | -| `RETH_METRICS_PORT` | Metrics port | `9001` | `9002` | - -## Consensus Client Variables - -### Lighthouse Variables - -| Variable | Description | Default | Example | -|----------|-------------|---------|---------| -| `LIGHTHOUSE_DATADIR` | Data directory | `~/.starknode-kit/data/lighthouse/` | `/custom/path/` | -| `LIGHTHOUSE_P2P_PORT` | P2P networking port | `9000` | `9002` | -| `LIGHTHOUSE_HTTP_PORT` | HTTP API port | `9001` | `9003` | -| `LIGHTHOUSE_P2P_ADDR` | P2P address | `0.0.0.0` | `127.0.0.1` | -| `LIGHTHOUSE_HTTP_ADDR` | HTTP API address | `127.0.0.1` | `0.0.0.0` | -| `LIGHTHOUSE_MAX_PEERS` | Maximum number of peers | `50` | `100`, `25` | -| `LIGHTHOUSE_TARGET_PEERS` | Target number of peers | `25` | `50`, `15` | -| `LIGHTHOUSE_NETWORK` | Network name | `mainnet` | `sepolia`, `holesky` | -| `LIGHTHOUSE_CHECKPOINT_SYNC` | Checkpoint sync URL | `""` | `https://mainnet.checkpoint.sigp.io` | -| `LIGHTHOUSE_HTTP_CORS` | HTTP API CORS origins | `*` | `http://localhost:3000` | -| `LIGHTHOUSE_METRICS` | Enable metrics | `false` | `true`, `false` | -| `LIGHTHOUSE_METRICS_ADDR` | Metrics address | `127.0.0.1` | `0.0.0.0` | -| `LIGHTHOUSE_METRICS_PORT` | Metrics port | `5054` | `5055` | -| `LIGHTHOUSE_LOG_LEVEL` | Log level | `info` | `debug`, `warn`, `error` | -| `LIGHTHOUSE_LOG_COLOR` | Colored log output | `true` | `true`, `false` | -| `LIGHTHOUSE_LOG_FILE` | Log file path | `~/.starknode-kit/logs/lighthouse.log` | `/custom/path/log.log` | - -### Prysm Variables - -| Variable | Description | Default | Example | -|----------|-------------|---------|---------| -| `PRYSM_DATADIR` | Data directory | `~/.starknode-kit/data/prysm/` | `/custom/path/` | -| `PRYSM_P2P_PORT` | P2P networking port | `13000` | `13002` | -| `PRYSM_HTTP_PORT` | HTTP API port | `3500` | `3502` | -| `PRYSM_P2P_ADDR` | P2P address | `0.0.0.0` | `127.0.0.1` | -| `PRYSM_HTTP_ADDR` | HTTP API address | `127.0.0.1` | `0.0.0.0` | -| `PRYSM_MAX_PEERS` | Maximum number of peers | `50` | `100`, `25` | -| `PRYSM_TARGET_PEERS` | Target number of peers | `25` | `50`, `15` | -| `PRYSM_NETWORK` | Network name | `mainnet` | `sepolia`, `holesky` | -| `PRYSM_CHECKPOINT_SYNC` | Checkpoint sync URL | `""` | `https://beaconstate.info/` | -| `PRYSM_HTTP_CORS` | HTTP API CORS origins | `*` | `http://localhost:3000` | -| `PRYSM_METRICS` | Enable metrics | `false` | `true`, `false` | -| `PRYSM_METRICS_ADDR` | Metrics address | `127.0.0.1` | `0.0.0.0` | -| `PRYSM_METRICS_PORT` | Metrics port | `8080` | `8081` | -| `PRYSM_LOG_LEVEL` | Log level | `info` | `debug`, `warn`, `error` | -| `PRYSM_LOG_FORMAT` | Log format | `text` | `text`, `json` | -| `PRYSM_LOG_FILE` | Log file path | `~/.starknode-kit/logs/prysm.log` | `/custom/path/log.log` | - -## Starknet Client Variables - -### Juno Variables - -| Variable | Description | Default | Example | -|----------|-------------|---------|---------| -| `JUNO_DATADIR` | Data directory | `~/.starknode-kit/data/juno/` | `/custom/path/` | -| `JUNO_HTTP_PORT` | HTTP RPC port | `6060` | `6062` | -| `JUNO_WS_PORT` | WebSocket RPC port | `6061` | `6063` | -| `JUNO_HTTP_ADDR` | HTTP RPC address | `127.0.0.1` | `0.0.0.0` | -| `JUNO_WS_ADDR` | WebSocket RPC address | `127.0.0.1` | `0.0.0.0` | -| `JUNO_ETH_NODE` | Ethereum node URL | `http://localhost:8545` | `https://eth-mainnet.alchemyapi.io/v2/KEY` | -| `JUNO_MAX_PEERS` | Maximum number of peers | `50` | `100`, `25` | -| `JUNO_TARGET_PEERS` | Target number of peers | `25` | `50`, `15` | -| `JUNO_NETWORK` | Network name | `mainnet` | `sepolia`, `holesky` | -| `JUNO_CHAIN` | Chain specification | `mainnet` | `sepolia`, `holesky` | -| `JUNO_HTTP_CORS` | HTTP RPC CORS origins | `*` | `http://localhost:3000` | -| `JUNO_WS_ORIGINS` | WebSocket RPC origins | `*` | `http://localhost:3000` | -| `JUNO_METRICS` | Enable metrics | `false` | `true`, `false` | -| `JUNO_METRICS_ADDR` | Metrics address | `127.0.0.1` | `0.0.0.0` | -| `JUNO_METRICS_PORT` | Metrics port | `9090` | `9091` | -| `JUNO_LOG_LEVEL` | Log level | `info` | `debug`, `warn`, `error` | -| `JUNO_LOG_COLOR` | Colored log output | `true` | `true`, `false` | -| `JUNO_LOG_FILE` | Log file path | `~/.starknode-kit/logs/juno.log` | `/custom/path/log.log` | -| `JUNO_DB_PATH` | Database path | `~/.starknode-kit/data/juno/db/` | `/custom/db/path/` | -| `JUNO_CACHE_SIZE` | Cache size (MB) | `1024` | `4096`, `8192` | -| `JUNO_SYNC_MODE` | Sync mode | `full` | `full`, `light` | -| `JUNO_VERIFY_L1` | Verify L1 state | `true` | `true`, `false` | - -## System Variables - -### Resource Limits - -| Variable | Description | Default | Example | -|----------|-------------|---------|---------| -| `STARKNODE_MEMORY_LIMIT` | Total memory limit | `16Gi` | `32Gi`, `8Gi` | -| `STARKNODE_CPU_LIMIT` | Total CPU limit | `4` | `8`, `2` | -| `STARKNODE_DISK_LIMIT` | Disk usage limit | `2Ti` | `4Ti`, `1Ti` | - -### Network - -| Variable | Description | Default | Example | -|----------|-------------|---------|---------| -| `STARKNODE_NETWORK_INTERFACE` | Network interface | `auto` | `eth0`, `wlan0` | -| `STARKNODE_BANDWIDTH_LIMIT` | Bandwidth limit | `unlimited` | `100Mbps`, `1Gbps` | -| `STARKNODE_FIREWALL` | Enable firewall | `false` | `true`, `false` | - -### Security - -| Variable | Description | Default | Example | -|----------|-------------|---------|---------| -| `STARKNODE_SSL_CERT` | SSL certificate path | `""` | `/path/to/cert.pem` | -| `STARKNODE_SSL_KEY` | SSL private key path | `""` | `/path/to/key.pem` | -| `STARKNODE_AUTH_TOKEN` | Authentication token | `""` | `your-secret-token` | -| `STARKNODE_RATE_LIMIT` | Rate limit (req/min) | `1000` | `500`, `2000` | - -## Usage Examples - -### Development Environment - -```bash -# Set development network -export STARKNODE_NETWORK=sepolia - -# Configure for development -export GETH_CACHE=2048 -export GETH_MAXPEERS=25 -export LIGHTHOUSE_MAX_PEERS=25 -export JUNO_MAX_PEERS=25 - -# Enable debug logging -export STARKNODE_LOG_LEVEL=debug -export GETH_LOG_LEVEL=debug -export LIGHTHOUSE_LOG_LEVEL=debug -export JUNO_LOG_LEVEL=debug -``` - -### Production Environment - -```bash -# Set production network -export STARKNODE_NETWORK=mainnet - -# Configure for production -export GETH_CACHE=8192 -export GETH_MAXPEERS=100 -export LIGHTHOUSE_MAX_PEERS=50 -export JUNO_MAX_PEERS=50 - -# Enable metrics -export GETH_METRICS=true -export LIGHTHOUSE_METRICS=true -export JUNO_METRICS=true - -# Set resource limits -export STARKNODE_MEMORY_LIMIT=32Gi -export STARKNODE_CPU_LIMIT=8 -``` - -### High-Performance Setup - -```bash -# Use Reth for better performance -export STARKNODE_EXECUTION_CLIENT=reth - -# Configure for high performance -export RETH_CACHE_SIZE=16384 -export RETH_MAX_PEERS=100 -export LIGHTHOUSE_MAX_PEERS=50 -export JUNO_MAX_PEERS=50 - -# Enable all optimizations -export RETH_METRICS=true -export LIGHTHOUSE_METRICS=true -export JUNO_METRICS=true -``` - -## Environment File - -Create a `.env` file in your home directory: - -```bash -# ~/.starknode-kit/.env -STARKNODE_NETWORK=mainnet -STARKNODE_LOG_LEVEL=info - -# Geth settings -GETH_CACHE=4096 -GETH_MAXPEERS=50 - -# Lighthouse settings -LIGHTHOUSE_MAX_PEERS=50 -LIGHTHOUSE_TARGET_PEERS=25 - -# Juno settings -JUNO_MAX_PEERS=50 -JUNO_ETH_NODE=http://localhost:8545 -``` - -Load environment variables: - -```bash -# Load from .env file -source ~/.starknode-kit/.env - -# Or use dotenv -export $(cat ~/.starknode-kit/.env | xargs) -``` - -## Validation - -### Check Environment Variables - -```bash -# List all Starknode Kit variables -env | grep STARKNODE - -# List all client variables -env | grep -E "(GETH|LIGHTHOUSE|JUNO|RETH|PRYSM)" -``` - -### Validate Configuration - -```bash -# Validate with environment variables -starknode-kit config --validate - -# Check if variables are being used -starknode-kit config -``` - -## Best Practices - -### Security - -- Never commit `.env` files to version control -- Use strong authentication tokens -- Restrict network access in production -- Regularly rotate secrets - -### Performance - -- Set appropriate cache sizes for your hardware -- Monitor resource usage -- Adjust peer counts based on network conditions -- Use metrics to optimize settings - -### Maintenance - -- Document custom environment variables -- Keep variables organized in `.env` files -- Test changes in development first -- Monitor for deprecated variables - -## Getting Help - -For environment variable issues: - -- Check the [Troubleshooting Guide](../operations/troubleshooting.md) -- Review client-specific documentation -- Join our [Telegram community](https://t.me/+SCPbza9fk8dkYWI0) -- Open an issue on [GitHub](https://github.com/thebuidl-grid/starknode-kit/issues) diff --git a/docs/book.json b/docs/book.json deleted file mode 100644 index 981927c..0000000 --- a/docs/book.json +++ /dev/null @@ -1,24 +0,0 @@ -{ - "title": "Starknode Kit Documentation", - "description": "Complete guide for setting up, managing, and maintaining Ethereum and Starknet nodes with Starknode Kit", - "author": "The Buidl Grid", - "language": "en", - "structure": { - "readme": "README.md", - "summary": "SUMMARY.md" - }, - "plugins": [ - "theme-default", - "search", - "fontsettings", - "highlight" - ], - "pluginsConfig": { - "theme-default": { - "showLevel": true, - "styles": { - "website": "styles/website.css" - } - } - } -} \ No newline at end of file diff --git a/docs/client-management/adding-clients.md b/docs/client-management/adding-clients.md deleted file mode 100644 index 94e8d8c..0000000 --- a/docs/client-management/adding-clients.md +++ /dev/null @@ -1,318 +0,0 @@ -# Adding Clients - -This guide covers how to add and configure different types of clients (Ethereum execution, consensus, and Starknet) to your Starknode Kit setup. - -## Overview - -Starknode Kit supports three types of clients: - -- **Execution Clients**: Handle transaction execution and state management -- **Consensus Clients**: Handle block validation and consensus -- **Starknet Clients**: Handle Starknet L2 operations - -## Adding Execution Clients - -### Supported Execution Clients - -| Client | Language | Description | -|--------|----------|-------------| -| **Geth** | Go | Most popular Ethereum client | -| **Reth** | Rust | High-performance Rust implementation | - -### Add Geth - -```bash -starknode-kit add --execution_client geth -``` - -### Add Reth - -```bash -starknode-kit add --execution_client reth -``` - -### Execution Client Features - -**Geth**: -- Mature and stable -- Extensive documentation -- Large community support -- Good for most use cases - -**Reth**: -- High performance -- Modern architecture -- Fast sync capabilities -- Growing ecosystem - -## Adding Consensus Clients - -### Supported Consensus Clients - -| Client | Language | Description | -|--------|----------|-------------| -| **Lighthouse** | Rust | High-performance consensus client | -| **Prysm** | Go | Feature-rich consensus client | - -### Add Lighthouse - -```bash -starknode-kit add --consensus_client lighthouse -``` - -### Add Prysm - -```bash -starknode-kit add --consensus_client prysm -``` - -### Consensus Client Features - -**Lighthouse**: -- Fast sync performance -- Low resource usage -- Strong security focus -- Good for production - -**Prysm**: -- Rich feature set -- Web UI included -- Extensive tooling -- Good for development - -## Adding Starknet Clients - -### Supported Starknet Clients - -| Client | Language | Description | -|--------|----------|-------------| -| **Juno** | Go | Full Starknet node implementation | - -### Add Juno - -```bash -starknode-kit add --starknet_client juno -``` - -### Juno Features - -- Complete JSON-RPC support -- Fast synchronization -- Small database footprint -- WebSocket interface -- Production-ready - -## Adding Client Pairs - -### Complete Ethereum Setup - -Add both execution and consensus clients together: - -```bash -# Geth + Lighthouse -starknode-kit add --execution_client geth --consensus_client lighthouse - -# Reth + Prysm -starknode-kit add --execution_client reth --consensus_client prysm - -# Geth + Prysm -starknode-kit add --execution_client geth --consensus_client prysm -``` - -### Full Stack Setup - -Add all three client types: - -```bash -starknode-kit add --execution_client geth --consensus_client lighthouse --starknet_client juno -``` - -## Client Installation Process - -When you add a client, Starknode Kit: - -1. **Downloads** the client binary -2. **Installs** it to the appropriate location -3. **Configures** default settings -4. **Updates** your configuration file -5. **Validates** the installation - -### Installation Locations - -- **Linux/macOS**: `~/.starknode-kit/bin/` -- **Windows**: `%USERPROFILE%\.starknode-kit\bin\` - -## Configuration After Adding - -### View Added Clients - -```bash -# Show all configured clients -starknode-kit config - -# Show specific client type -starknode-kit config el # Execution clients -starknode-kit config cl # Consensus clients -starknode-kit config starknet # Starknet clients -``` - -### Customize Client Settings - -After adding, you can customize settings: - -```bash -# Change ports -starknode-kit config el client=geth port=8545,8546 - -# Set execution type -starknode-kit config el client=geth execution_type=archive - -# Add custom arguments -starknode-kit config el client=geth additional_args="--maxpeers,50,--cache,4096" -``` - -## Client Compatibility - -### Recommended Combinations - -**Production**: -- Geth + Lighthouse + Juno -- Reth + Lighthouse + Juno - -**Development**: -- Geth + Prysm + Juno -- Reth + Prysm + Juno - -**High Performance**: -- Reth + Lighthouse + Juno - -### Network Compatibility - -All clients support: -- Ethereum Mainnet -- Sepolia Testnet -- Holesky Testnet -- Custom networks - -## Troubleshooting Client Addition - -### Common Issues - -**Download Fails** -```bash -# Check internet connection -ping google.com - -# Check available disk space -df -h -``` - -**Permission Denied** -```bash -# Fix permissions -chmod +x ~/.starknode-kit/bin/* -``` - -**Client Already Exists** -```bash -# Remove existing client first -starknode-kit remove --execution_client geth - -# Then add again -starknode-kit add --execution_client geth -``` - -### Verification - -Verify client installation: - -```bash -# Check if binary exists -ls -la ~/.starknode-kit/bin/ - -# Test client version -~/.starknode-kit/bin/geth version -~/.starknode-kit/bin/lighthouse --version -~/.starknode-kit/bin/juno --version -``` - -## Client Updates - -### Check for Updates - -```bash -starknode-kit update -``` - -### Update Specific Client - -```bash -# Update all clients -starknode-kit update - -# Update specific client type -starknode-kit update --execution_client geth -starknode-kit update --consensus_client lighthouse -starknode-kit update --starknet_client juno -``` - -## Removing Clients - -### Remove Execution Client - -```bash -starknode-kit remove --execution_client geth -``` - -### Remove Consensus Client - -```bash -starknode-kit remove --consensus_client lighthouse -``` - -### Remove Starknet Client - -```bash -starknode-kit remove --starknet_client juno -``` - -### Remove All Clients - -```bash -starknode-kit remove --execution_client geth --consensus_client lighthouse --starknet_client juno -``` - -## Best Practices - -### Client Selection - -**For Beginners**: -- Start with Geth + Lighthouse -- Use default configurations -- Focus on stability - -**For Production**: -- Use Reth + Lighthouse for performance -- Configure resource limits -- Set up monitoring - -**For Development**: -- Use Geth + Prysm for features -- Enable debug logging -- Use testnets - -### Configuration Management - -- Keep configurations in version control -- Document custom settings -- Test changes on testnets first -- Monitor performance after changes - -## Getting Help - -For client-related issues: - -- Check the [Troubleshooting Guide](../operations/troubleshooting.md) -- Review client-specific documentation -- Join our [Telegram community](https://t.me/+SCPbza9fk8dkYWI0) -- Open an issue on [GitHub](https://github.com/thebuidl-grid/starknode-kit/issues) diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md deleted file mode 100644 index 9ef6861..0000000 --- a/docs/getting-started/configuration.md +++ /dev/null @@ -1,361 +0,0 @@ -# Configuration - -Starknode Kit uses a YAML configuration file to manage your node setup. This guide covers all configuration options and how to customize them for your needs. - -## Configuration File Location - -The configuration file is located at: -- **Linux/macOS**: `~/.starknode-kit/config.yaml` -- **Windows**: `%USERPROFILE%\.starknode-kit\config.yaml` - -## Configuration Structure - -```yaml -network: mainnet # Network to connect to -execution_client: - name: geth - port: [8545, 8546] - execution_type: full -consensus_client: - name: lighthouse - port: [9000, 9001] - consensus_checkpoint: "" -starknet_client: - name: juno - port: [6060, 6061] - eth_node_url: "http://localhost:8545" -``` - -## Network Configuration - -### Supported Networks - -| Network | Description | Use Case | -|---------|-------------|----------| -| `mainnet` | Ethereum mainnet | Production | -| `sepolia` | Ethereum testnet | Testing | -| `goerli` | Ethereum testnet (deprecated) | Legacy testing | -| `holesky` | Ethereum testnet | Testing | - -### Setting Network - -```bash -# Set network via command line -starknode-kit config -n sepolia - -# Or edit config file directly -network: sepolia -``` - -## Execution Client Configuration - -### Supported Clients - -- **Geth**: Go Ethereum client -- **Reth**: Rust Ethereum client - -### Configuration Options - -```yaml -execution_client: - name: geth # or reth - port: [8545, 8546] # [HTTP, WebSocket] - execution_type: full # full, archive, light - additional_args: [] # Custom command line arguments -``` - -### Execution Types - -| Type | Description | Storage | Sync Speed | -|------|-------------|---------|------------| -| `full` | Full node with recent state | ~1.5 TB | Fast | -| `archive` | Complete historical data | ~3+ TB | Slow | -| `light` | Minimal data, relies on peers | ~50 GB | Very Fast | - -### Port Configuration - -```bash -# Set custom ports -starknode-kit config el client=geth port=8545,8546 - -# Default ports: -# Geth: 8545 (HTTP), 8546 (WebSocket) -# Reth: 8545 (HTTP), 8546 (WebSocket) -``` - -## Consensus Client Configuration - -### Supported Clients - -- **Lighthouse**: Rust-based consensus client -- **Prysm**: Go-based consensus client - -### Configuration Options - -```yaml -consensus_client: - name: lighthouse # or prysm - port: [9000, 9001] # [P2P, HTTP API] - consensus_checkpoint: "" # Optional checkpoint URL - additional_args: [] # Custom command line arguments -``` - -### Checkpoint Sync - -Speed up initial sync using a trusted checkpoint: - -```yaml -consensus_client: - name: lighthouse - consensus_checkpoint: "https://mainnet.checkpoint.sigp.io" -``` - -**Available checkpoints**: -- Lighthouse: `https://mainnet.checkpoint.sigp.io` -- Prysm: `https://beaconstate.info/` - -### Port Configuration - -```bash -# Set custom ports -starknode-kit config cl client=lighthouse port=9000,9001 - -# Default ports: -# Lighthouse: 9000 (P2P), 9001 (HTTP API) -# Prysm: 13000 (P2P), 3500 (HTTP API) -``` - -## Starknet Client Configuration - -### Supported Clients - -- **Juno**: Go-based Starknet full node - -### Configuration Options - -```yaml -starknet_client: - name: juno - port: [6060, 6061] # [HTTP, WebSocket] - eth_node_url: "http://localhost:8545" # Ethereum node URL - additional_args: [] # Custom command line arguments -``` - -### Ethereum Node Connection - -Juno requires an Ethereum node to verify L1 state: - -```yaml -starknet_client: - name: juno - eth_node_url: "http://localhost:8545" # Local Geth/Reth - # or - eth_node_url: "https://eth-mainnet.alchemyapi.io/v2/YOUR_KEY" # External provider -``` - -### Port Configuration - -```bash -# Set custom ports -starknode-kit config starknet client=juno port=6060,6061 - -# Default ports: -# Juno: 6060 (HTTP), 6061 (WebSocket) -``` - -## Advanced Configuration - -### Custom Command Line Arguments - -Add custom arguments to any client: - -```yaml -execution_client: - name: geth - additional_args: - - "--maxpeers" - - "50" - - "--cache" - - "4096" - -consensus_client: - name: lighthouse - additional_args: - - "--max-peers" - - "50" - - "--target-peers" - - "25" -``` - -### Environment Variables - -Set environment variables for clients: - -```yaml -execution_client: - name: geth - env_vars: - GETH_CACHE: "4096" - GETH_MAXPEERS: "50" -``` - -### Resource Limits - -Configure resource limits: - -```yaml -execution_client: - name: geth - resource_limits: - memory: "8Gi" - cpu: "4" -``` - -## Configuration Management - -### View Current Configuration - -```bash -# Show current config -starknode-kit config - -# Show specific client config -starknode-kit config el -starknode-kit config cl -starknode-kit config starknet -``` - -### Edit Configuration - -```bash -# Edit config file directly -nano ~/.starknode-kit/config.yaml - -# Or use command line -starknode-kit config -n sepolia -starknode-kit config el client=reth port=8545,8546 -``` - -### Validate Configuration - -```bash -# Check if config is valid -starknode-kit config --validate -``` - -## Configuration Examples - -### Development Setup - -```yaml -network: sepolia -execution_client: - name: geth - port: [8545, 8546] - execution_type: full -consensus_client: - name: lighthouse - port: [9000, 9001] -starknet_client: - name: juno - port: [6060, 6061] - eth_node_url: "http://localhost:8545" -``` - -### Production Setup - -```yaml -network: mainnet -execution_client: - name: reth - port: [8545, 8546] - execution_type: full - additional_args: - - "--max-peers" - - "100" -consensus_client: - name: lighthouse - port: [9000, 9001] - consensus_checkpoint: "https://mainnet.checkpoint.sigp.io" - additional_args: - - "--max-peers" - - "50" -starknet_client: - name: juno - port: [6060, 6061] - eth_node_url: "http://localhost:8545" -``` - -### Archive Node Setup - -```yaml -network: mainnet -execution_client: - name: geth - port: [8545, 8546] - execution_type: archive - additional_args: - - "--cache" - - "8192" -consensus_client: - name: lighthouse - port: [9000, 9001] - execution_type: archive -``` - -## Troubleshooting Configuration - -### Common Issues - -**Invalid YAML Syntax** -```bash -# Validate YAML syntax -starknode-kit config --validate -``` - -**Port Conflicts** -```bash -# Check port usage -netstat -tulpn | grep :8545 -``` - -**Missing Dependencies** -```bash -# Check if clients are installed -starknode-kit config -``` - -### Configuration Validation - -The configuration is validated when you run commands. Common validation errors: - -- Invalid network name -- Unsupported client combinations -- Port conflicts -- Missing required fields - -## Best Practices - -### Security -- Use non-default ports in production -- Restrict RPC access to localhost -- Use strong authentication for external access - -### Performance -- Match execution type to your use case -- Use checkpoint sync for faster initial sync -- Configure appropriate resource limits - -### Reliability -- Use stable network configurations -- Set up monitoring for configuration changes -- Keep backups of working configurations - -## Getting Help - -For configuration issues: - -- Check the [Troubleshooting Guide](../operations/troubleshooting.md) -- Review client-specific documentation -- Join our [Telegram community](https://t.me/+SCPbza9fk8dkYWI0) -- Open an issue on [GitHub](https://github.com/thebuidl-grid/starknode-kit/issues) diff --git a/docs/getting-started/hardware-requirements.md b/docs/getting-started/hardware-requirements.md deleted file mode 100644 index 0150a69..0000000 --- a/docs/getting-started/hardware-requirements.md +++ /dev/null @@ -1,193 +0,0 @@ -# Hardware Requirements - -This guide outlines the hardware requirements for running Ethereum and Starknet nodes with Starknode Kit. Requirements vary depending on your use case, from casual development to production-grade operations. - -## Minimum Requirements - -### Development/Testing Environment - -- **CPU**: 4+ cores (Intel i5/AMD Ryzen 5 or better) -- **RAM**: 16 GB -- **Storage**: 1 TB NVMe SSD -- **Network**: Stable broadband connection (10+ Mbps) - -### Production Environment - -- **CPU**: 8+ cores (Intel i7/AMD Ryzen 7 or better) -- **RAM**: 32+ GB -- **Storage**: 2+ TB NVMe SSD with DRAM cache -- **Network**: Stable broadband connection (50+ Mbps) - -## Detailed Hardware Specifications - -### CPU Requirements - -**Recommended**: Intel i7/AMD Ryzen 7 or better -- Node operation doesn't require heavy CPU power -- The BG Client has run well on both i3 and i5 models -- **Avoid**: Celeron processors due to limitations - -**Why CPU matters**: -- Consensus client operations -- Block processing and validation -- Network protocol handling - -### Memory (RAM) Requirements - -**Minimum**: 16 GB -**Recommended**: 32+ GB -**Production**: 64+ GB - -**Memory usage breakdown**: -- Base system: ~4 GB -- Ethereum execution client: ~8-16 GB -- Consensus client: ~4-8 GB -- Starknet client (Juno): ~4-8 GB -- Operating system overhead: ~4 GB - -### Storage Requirements - -**Critical**: Use NVMe SSD with DRAM cache -**Avoid**: QLC (Quad-Level Cell) NAND architecture - -#### Storage Size Requirements - -| Network | Execution Client | Consensus Client | Total (Approx.) | -|---------|------------------|------------------|-----------------| -| Mainnet | 1.5 TB | 500 GB | 2+ TB | -| Sepolia | 200 GB | 50 GB | 300+ GB | -| Goerli | 300 GB | 100 GB | 500+ GB | - -#### Recommended SSDs - -See this [SSD List Gist](https://gist.github.com/bkase/fab02c5b3c404e9ef8e5c2071ac1558c) for tested options. - -**Key specifications to look for**: -- NVMe interface -- DRAM cache -- High endurance rating -- Good random read/write performance - -### Network Requirements - -**Bandwidth**: -- Development: 10+ Mbps -- Production: 50+ Mbps -- High-performance: 100+ Mbps - -**Latency**: -- Low latency connection preferred -- Stable connection more important than speed - -**Data usage**: -- Initial sync: 1-2 TB -- Daily operation: 10-50 GB - -## Hardware Recommendations by Use Case - -### Home Development Setup - -``` -CPU: Intel i5-12400 / AMD Ryzen 5 5600X -RAM: 32 GB DDR4 -Storage: 2 TB NVMe SSD (Samsung 980 Pro, WD Black SN850) -Network: 50+ Mbps broadband -``` - -### Production Validator - -``` -CPU: Intel i7-12700K / AMD Ryzen 7 5800X -RAM: 64 GB DDR4 -Storage: 4 TB NVMe SSD (Samsung 980 Pro, WD Black SN850) -Network: 100+ Mbps dedicated connection -``` - -### Enterprise/High-Performance - -``` -CPU: Intel i9-12900K / AMD Ryzen 9 5900X -RAM: 128 GB DDR4 -Storage: 8 TB NVMe SSD (Enterprise grade) -Network: 1 Gbps dedicated connection -``` - -## Cloud Provider Recommendations - -### AWS -- **Instance**: c6i.2xlarge or larger -- **Storage**: gp3 or io2 volumes -- **Network**: Enhanced networking enabled - -### Google Cloud -- **Instance**: c2-standard-8 or larger -- **Storage**: SSD persistent disks -- **Network**: Premium tier - -### Azure -- **Instance**: Standard_D8s_v3 or larger -- **Storage**: Premium SSD -- **Network**: Accelerated networking - -## Performance Optimization Tips - -### Storage Optimization -- Use separate drives for different clients -- Enable TRIM for SSD maintenance -- Monitor disk health regularly - -### Memory Optimization -- Enable swap space (8-16 GB) -- Monitor memory usage patterns -- Consider memory overcommit settings - -### Network Optimization -- Use wired connections when possible -- Configure QoS for node traffic -- Monitor bandwidth usage - -## Monitoring Hardware Health - -### Key Metrics to Monitor -- CPU usage and temperature -- Memory usage and swap usage -- Disk I/O and available space -- Network bandwidth and latency - -### Recommended Tools -- `htop` for system monitoring -- `iotop` for disk I/O monitoring -- `nethogs` for network monitoring -- `smartctl` for SSD health - -## Troubleshooting Hardware Issues - -### Common Problems - -**High CPU Usage** -- Check for stuck processes -- Verify client configurations -- Monitor system logs - -**Memory Issues** -- Check for memory leaks -- Adjust client memory limits -- Consider adding swap space - -**Storage Problems** -- Monitor disk space -- Check for disk errors -- Verify SSD health - -**Network Issues** -- Test connection stability -- Check firewall settings -- Verify port configurations - -## Getting Help - -For hardware-specific questions: - -- Check our [Troubleshooting Guide](../operations/troubleshooting.md) -- Join our [Telegram community](https://t.me/+SCPbza9fk8dkYWI0) -- Review the [Rocket Pool Hardware Guide](https://docs.rocketpool.net/guides/node/hardware.html) for additional insights diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md deleted file mode 100644 index 996f39c..0000000 --- a/docs/getting-started/installation.md +++ /dev/null @@ -1,116 +0,0 @@ -# Installation and Setup - -This guide will walk you through installing Starknode Kit on your system. We provide multiple installation methods to suit different preferences and environments. - -## Prerequisites - -Before installing Starknode Kit, ensure you have the following installed: - -- **Go**: Version 1.24 or later ([Download](https://go.dev/dl/)) -- **Rust**: For building Starknet clients ([Install Rust](https://rustup.rs/)) -- **Make**: For building certain clients - - Ubuntu/Debian: `sudo apt install make` - - macOS: `brew install make` - - Windows (WSL): `sudo apt install make` - -## Installation Methods - -### Method 1: Install Script (Recommended) - -The easiest way to install Starknode Kit is using our installation script: - -```bash -curl -sSL https://raw.githubusercontent.com/thebuidl-grid/starknode-kit/main/install.sh | bash -``` - -Or download and run manually: - -```bash -wget https://raw.githubusercontent.com/thebuidl-grid/starknode-kit/main/install.sh -chmod +x install.sh -./install.sh -``` - -### Method 2: Go Install - -If you have Go installed, you can install directly: - -```bash -go install github.com/thebuidl-grid/starknode-kit@latest -``` - -### Method 3: Build from Source - -For development or custom builds: - -```bash -# Clone the repository -git clone https://github.com/thebuidl-grid/starknode-kit.git -cd starknode-kit - -# Build and install -go build -o starknode-kit . -sudo mv starknode-kit /usr/local/bin/ -``` - -## Verify Installation - -After installation, verify that Starknode Kit is working correctly: - -```bash -starknode-kit --help -``` - -You should see the help output with available commands. - -## Initialize Configuration - -Create your initial configuration file: - -```bash -starknode-kit init -``` - -This creates a default configuration file in your home directory that you can customize for your needs. - -## Next Steps - -Now that you have Starknode Kit installed: - -1. [Review Hardware Requirements](hardware-requirements.md) -2. [Follow the Quick Start Guide](quick-start.md) -3. [Configure your first client](configuration.md) - -## Troubleshooting Installation - -### Common Issues - -**Permission Denied Error** -```bash -sudo chmod +x /usr/local/bin/starknode-kit -``` - -**Command Not Found** -Ensure `/usr/local/bin` is in your PATH: -```bash -echo 'export PATH=$PATH:/usr/local/bin' >> ~/.bashrc -source ~/.bashrc -``` - -**Go Version Issues** -Update Go to version 1.24 or later: -```bash -# Check current version -go version - -# Update if needed -# Visit https://go.dev/dl/ for latest version -``` - -### Getting Help - -If you encounter issues during installation: - -- Check our [Troubleshooting Guide](../operations/troubleshooting.md) -- Join our [Telegram community](https://t.me/+SCPbza9fk8dkYWI0) -- Open an issue on [GitHub](https://github.com/thebuidl-grid/starknode-kit/issues) diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md deleted file mode 100644 index a1580bf..0000000 --- a/docs/getting-started/quick-start.md +++ /dev/null @@ -1,205 +0,0 @@ -# Quick Start Guide - -Get your first Ethereum and Starknet node running in under 10 minutes with this step-by-step guide. - -## Prerequisites - -Before starting, ensure you have: -- [Starknode Kit installed](installation.md) -- [Adequate hardware](hardware-requirements.md) -- Stable internet connection - -## Step 1: Initialize Configuration - -Create your initial configuration file: - -```bash -starknode-kit init -``` - -This creates a default configuration in your home directory that you can customize later. - -## Step 2: Add Your First Client Pair - -Add an Ethereum execution and consensus client pair: - -```bash -# Add Geth (execution) + Lighthouse (consensus) -starknode-kit add --execution_client geth --consensus_client lighthouse -``` - -**Alternative combinations**: -```bash -# Reth + Prysm -starknode-kit add --execution_client reth --consensus_client prysm - -# Geth + Prysm -starknode-kit add --execution_client geth --consensus_client prysm -``` - -## Step 3: Add a Starknet Client - -Add Juno for Starknet support: - -```bash -starknode-kit add --starknet_client juno -``` - -## Step 4: Verify Configuration - -Check your current configuration: - -```bash -starknode-kit config -``` - -You should see your configured clients listed. - -## Step 5: Start Your Ethereum Node - -Start the Ethereum execution and consensus clients: - -```bash -starknode-kit start -``` - -This will: -- Download and install the client binaries -- Start the execution client first -- Start the consensus client -- Begin syncing with the network - -## Step 6: Start Your Starknet Node - -In a separate terminal, start your Juno Starknet node: - -```bash -starknode-kit run juno -``` - -## Step 7: Monitor Your Nodes - -Launch the monitoring dashboard: - -```bash -starknode-kit monitor -``` - -This provides real-time information about: -- Client status and health -- Sync progress -- Resource usage -- Network connections - -## What Happens Next - -### Initial Sync Process - -**Ethereum Node**: -- Execution client syncs the blockchain state -- Consensus client syncs the beacon chain -- Full sync can take 1-3 days depending on hardware - -**Starknet Node (Juno)**: -- Syncs Starknet state from L1 -- Requires Ethereum node connection -- Typically faster than Ethereum sync - -### Expected Timeline - -| Phase | Duration | Description | -|-------|----------|-------------| -| Client Installation | 5-15 minutes | Download and setup binaries | -| Ethereum Sync Start | 1-2 hours | Begin blockchain synchronization | -| Partial Sync | 6-12 hours | Sync recent blocks | -| Full Sync | 1-3 days | Complete historical sync | -| Starknet Sync | 2-6 hours | Sync Starknet state | - -## Common First-Time Issues - -### Client Installation Fails - -**Problem**: Clients fail to download or install -**Solution**: Check internet connection and available disk space - -```bash -# Check disk space -df -h - -# Check internet connection -ping google.com -``` - -### Sync Stalls - -**Problem**: Sync progress stops or becomes very slow -**Solution**: Restart the clients - -```bash -# Stop clients -starknode-kit stop - -# Start again -starknode-kit start -``` - -### Port Conflicts - -**Problem**: Clients can't bind to required ports -**Solution**: Check for conflicting services - -```bash -# Check port usage -netstat -tulpn | grep :8545 # Geth default port -netstat -tulpn | grep :9000 # Lighthouse default port -``` - -## Next Steps - -Once your nodes are synced and running: - -1. **Configure Monitoring**: Set up alerts and monitoring -2. **Security Hardening**: Review security best practices -3. **Performance Tuning**: Optimize for your hardware -4. **Backup Strategy**: Implement backup procedures - -## Quick Commands Reference - -```bash -# Check status -starknode-kit config - -# Stop all clients -starknode-kit stop - -# Restart clients -starknode-kit stop && starknode-kit start - -# Update clients -starknode-kit update - -# Remove a client -starknode-kit remove --consensus_client lighthouse - -# Get help -starknode-kit --help -starknode-kit help -``` - -## Getting Help - -If you encounter issues: - -1. Check the [Troubleshooting Guide](../operations/troubleshooting.md) -2. Review client-specific logs -3. Join our [Telegram community](https://t.me/+SCPbza9fk8dkYWI0) -4. Open an issue on [GitHub](https://github.com/thebuidl-grid/starknode-kit/issues) - -## What's Next? - -Now that you have your first node running: - -- [Learn about client configuration](configuration.md) -- [Set up monitoring and alerts](../operations/monitoring.md) -- [Explore advanced features](../advanced/network-configuration.md) -- [Join the community](https://t.me/+SCPbza9fk8dkYWI0) diff --git a/docs/next.config.ts b/docs/next.config.ts new file mode 100644 index 0000000..e9ffa30 --- /dev/null +++ b/docs/next.config.ts @@ -0,0 +1,7 @@ +import type { NextConfig } from "next"; + +const nextConfig: NextConfig = { + /* config options here */ +}; + +export default nextConfig; diff --git a/docs/operations/monitoring.md b/docs/operations/monitoring.md deleted file mode 100644 index fdc4332..0000000 --- a/docs/operations/monitoring.md +++ /dev/null @@ -1,353 +0,0 @@ -# Monitoring - -Starknode Kit includes a built-in monitoring dashboard that provides real-time insights into your node's health, performance, and synchronization status. - -## Built-in Monitoring Dashboard - -### Launch the Dashboard - -```bash -starknode-kit monitor -``` - -This opens an interactive terminal-based dashboard showing: - -- **Client Status**: Running/stopped status of all clients -- **Sync Progress**: Current synchronization status -- **Resource Usage**: CPU, memory, and disk usage -- **Network Stats**: Peer connections and bandwidth -- **Logs**: Real-time log output from clients - -### Dashboard Features - -#### Real-time Updates -- Automatic refresh every few seconds -- Live log streaming -- Status change notifications - -#### Multi-client View -- Execution client status -- Consensus client status -- Starknet client status -- Combined system overview - -#### Resource Monitoring -- CPU usage per client -- Memory consumption -- Disk I/O statistics -- Network bandwidth - -## Monitoring Components - -### Client Status Monitoring - -**Execution Client (Geth/Reth)**: -- Sync status and progress -- Peer connections -- Block height -- Transaction pool status - -**Consensus Client (Lighthouse/Prysm)**: -- Beacon chain sync -- Validator status (if applicable) -- Attestation performance -- Finality status - -**Starknet Client (Juno)**: -- L2 sync progress -- L1 verification status -- Transaction processing -- State root updates - -### System Resource Monitoring - -**CPU Usage**: -- Per-client CPU consumption -- System-wide CPU usage -- Load average - -**Memory Usage**: -- RAM consumption per client -- Available memory -- Swap usage - -**Disk Usage**: -- Database size -- Available disk space -- I/O operations per second - -**Network Monitoring**: -- Inbound/outbound bandwidth -- Peer connections -- Latency measurements - -## Advanced Monitoring - -### Custom Monitoring Scripts - -Create custom monitoring scripts for specific needs: - -```bash -#!/bin/bash -# monitor_health.sh - -# Check if clients are running -if ! pgrep -f "geth" > /dev/null; then - echo "Geth is not running!" - exit 1 -fi - -if ! pgrep -f "lighthouse" > /dev/null; then - echo "Lighthouse is not running!" - exit 1 -fi - -# Check sync status -GETH_SYNC=$(curl -s -X POST -H "Content-Type: application/json" \ - --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' \ - http://localhost:8545 | jq -r '.result') - -if [ "$GETH_SYNC" != "false" ]; then - echo "Geth is still syncing" -fi - -echo "All systems healthy" -``` - -### Log Monitoring - -Monitor specific log patterns: - -```bash -# Monitor Geth logs -tail -f ~/.starknode-kit/logs/geth.log | grep -E "(ERROR|WARN|FATAL)" - -# Monitor Lighthouse logs -tail -f ~/.starknode-kit/logs/lighthouse.log | grep -E "(ERROR|WARN|FATAL)" - -# Monitor Juno logs -tail -f ~/.starknode-kit/logs/juno.log | grep -E "(ERROR|WARN|FATAL)" -``` - -### Performance Metrics - -Track key performance indicators: - -```bash -# Check sync speed -starknode-kit monitor --metrics sync-speed - -# Check peer count -starknode-kit monitor --metrics peers - -# Check resource usage -starknode-kit monitor --metrics resources -``` - -## External Monitoring Tools - -### Prometheus Integration - -Set up Prometheus metrics collection: - -```yaml -# prometheus.yml -global: - scrape_interval: 15s - -scrape_configs: - - job_name: 'starknode-kit' - static_configs: - - targets: ['localhost:9090'] - metrics_path: /metrics - scrape_interval: 5s -``` - -### Grafana Dashboards - -Create Grafana dashboards for visualization: - -**Key Metrics to Track**: -- Sync progress percentage -- Block height over time -- Peer connection count -- Resource usage trends -- Error rates - -### Alerting - -Set up alerts for critical issues: - -**Critical Alerts**: -- Client process down -- Sync stalled for > 1 hour -- Disk space < 10% -- Memory usage > 90% -- High error rate - -**Warning Alerts**: -- Sync progress slow -- Low peer count -- High CPU usage -- Network connectivity issues - -## Monitoring Best Practices - -### Regular Health Checks - -**Daily Checks**: -- Verify all clients are running -- Check sync progress -- Review error logs -- Monitor resource usage - -**Weekly Checks**: -- Review performance trends -- Check disk space usage -- Update monitoring configurations -- Test alerting systems - -### Log Management - -**Log Rotation**: -```bash -# Set up log rotation -sudo logrotate -f /etc/logrotate.d/starknode-kit -``` - -**Log Analysis**: -```bash -# Analyze error patterns -grep -E "(ERROR|WARN)" ~/.starknode-kit/logs/*.log | \ - awk '{print $1}' | sort | uniq -c | sort -nr -``` - -### Performance Optimization - -**Based on Monitoring Data**: -- Adjust client configurations -- Optimize resource allocation -- Tune network settings -- Update hardware if needed - -## Troubleshooting Monitoring Issues - -### Dashboard Not Loading - -**Problem**: Monitor dashboard fails to start -**Solutions**: -```bash -# Check if clients are configured -starknode-kit config - -# Restart monitoring -starknode-kit monitor --restart - -# Check for port conflicts -netstat -tulpn | grep :9090 -``` - -### Missing Metrics - -**Problem**: Some metrics not showing -**Solutions**: -```bash -# Verify client status -starknode-kit config - -# Check client logs -tail -f ~/.starknode-kit/logs/*.log - -# Restart clients -starknode-kit stop && starknode-kit start -``` - -### High Resource Usage - -**Problem**: Monitoring consumes too many resources -**Solutions**: -```bash -# Reduce monitoring frequency -starknode-kit monitor --interval 30s - -# Disable detailed metrics -starknode-kit monitor --basic - -# Use external monitoring instead -``` - -## Monitoring Configuration - -### Customize Monitoring Settings - -```yaml -# ~/.starknode-kit/monitoring.yaml -monitoring: - refresh_interval: 5s - log_level: info - metrics_enabled: true - alerts_enabled: true - - clients: - geth: - metrics_port: 6060 - log_level: info - lighthouse: - metrics_port: 5054 - log_level: info - juno: - metrics_port: 9090 - log_level: info -``` - -### Environment Variables - -```bash -# Set monitoring environment variables -export STARKNODE_MONITOR_INTERVAL=10s -export STARKNODE_MONITOR_LOG_LEVEL=debug -export STARKNODE_MONITOR_METRICS=true -``` - -## Integration with External Tools - -### System Monitoring - -**htop/btop**: -```bash -# Monitor system resources -htop -btop -``` - -**iotop**: -```bash -# Monitor disk I/O -sudo iotop -``` - -**nethogs**: -```bash -# Monitor network usage -sudo nethogs -``` - -### Log Aggregation - -**ELK Stack**: -- Elasticsearch for log storage -- Logstash for log processing -- Kibana for visualization - -**Fluentd**: -- Lightweight log collector -- Easy integration with Starknode Kit - -## Getting Help - -For monitoring issues: - -- Check the [Troubleshooting Guide](troubleshooting.md) -- Review client-specific monitoring docs -- Join our [Telegram community](https://t.me/+SCPbza9fk8dkYWI0) -- Open an issue on [GitHub](https://github.com/thebuidl-grid/starknode-kit/issues) diff --git a/docs/operations/running-nodes.md b/docs/operations/running-nodes.md deleted file mode 100644 index 0687eee..0000000 --- a/docs/operations/running-nodes.md +++ /dev/null @@ -1,383 +0,0 @@ -# Running Nodes - -This guide covers how to run and manage your Ethereum and Starknet nodes using Starknode Kit. - -## Starting Your Nodes - -### Start Ethereum Clients - -Start your configured execution and consensus clients: - -```bash -starknode-kit start -``` - -This command will: -1. Check your configuration -2. Start the execution client first -3. Start the consensus client -4. Begin the synchronization process - -### Start Starknet Client - -Start your Juno Starknet node: - -```bash -starknode-kit run juno -``` - -**Note**: Juno requires an Ethereum node connection to verify L1 state. - -## Node Startup Process - -### Execution Client Startup - -**Geth**: -```bash -# Geth starts with these default settings: -# - HTTP RPC on port 8545 -# - WebSocket RPC on port 8546 -# - P2P networking on port 30303 -# - Full sync mode -``` - -**Reth**: -```bash -# Reth starts with these default settings: -# - HTTP RPC on port 8545 -# - WebSocket RPC on port 8546 -# - P2P networking on port 30303 -# - Full sync mode -``` - -### Consensus Client Startup - -**Lighthouse**: -```bash -# Lighthouse starts with these default settings: -# - P2P networking on port 9000 -# - HTTP API on port 9001 -# - Beacon node mode -# - Mainnet network -``` - -**Prysm**: -```bash -# Prysm starts with these default settings: -# - P2P networking on port 13000 -# - HTTP API on port 3500 -# - Beacon node mode -# - Mainnet network -``` - -### Starknet Client Startup - -**Juno**: -```bash -# Juno starts with these default settings: -# - HTTP RPC on port 6060 -# - WebSocket RPC on port 6061 -# - Ethereum node connection required -# - Mainnet network -``` - -## Synchronization Process - -### Initial Sync - -When you first start your nodes, they will begin synchronizing with the network: - -**Execution Client Sync**: -- Downloads and verifies all blocks -- Builds the state trie -- Can take 1-3 days depending on hardware - -**Consensus Client Sync**: -- Downloads beacon chain data -- Verifies consensus rules -- Typically faster than execution sync - -**Starknet Client Sync**: -- Syncs L2 state from L1 -- Requires Ethereum node connection -- Usually completes in 2-6 hours - -### Sync Progress Monitoring - -Monitor sync progress using the built-in dashboard: - -```bash -starknode-kit monitor -``` - -Key metrics to watch: -- **Block height**: Current synced block number -- **Sync percentage**: Progress towards full sync -- **Peer count**: Number of connected peers -- **Sync speed**: Blocks per second - -### Checkpoint Sync - -Speed up initial sync using trusted checkpoints: - -```bash -# Configure checkpoint sync for Lighthouse -starknode-kit config cl client=lighthouse consensus_checkpoint="https://mainnet.checkpoint.sigp.io" - -# Configure checkpoint sync for Prysm -starknode-kit config cl client=prysm consensus_checkpoint="https://beaconstate.info/" -``` - -## Node Management - -### Stop Nodes - -Stop all running clients: - -```bash -starknode-kit stop -``` - -This gracefully shuts down all clients. - -### Restart Nodes - -Restart all clients: - -```bash -starknode-kit stop -starknode-kit start -``` - -### Check Node Status - -Check if nodes are running: - -```bash -# Check configuration -starknode-kit config - -# Check running processes -ps aux | grep -E "(geth|lighthouse|juno)" - -# Check ports -netstat -tulpn | grep -E "(8545|9000|6060)" -``` - -## Network Configuration - -### Mainnet - -Run on Ethereum mainnet: - -```bash -starknode-kit config -n mainnet -starknode-kit start -``` - -### Testnets - -Run on testnets for development: - -```bash -# Sepolia testnet -starknode-kit config -n sepolia -starknode-kit start - -# Holesky testnet -starknode-kit config -n holesky -starknode-kit start -``` - -### Custom Networks - -Configure custom network settings: - -```yaml -# config.yaml -network: custom -execution_client: - name: geth - additional_args: - - "--networkid" - - "12345" - - "--genesis" - - "/path/to/genesis.json" -``` - -## Performance Optimization - -### Resource Allocation - -Optimize resource usage for your hardware: - -```bash -# High-memory system (32GB+) -starknode-kit config el client=geth additional_args="--cache,8192,--maxpeers,100" - -# Low-memory system (16GB) -starknode-kit config el client=geth additional_args="--cache,2048,--maxpeers,25" - -# High-performance system -starknode-kit config el client=reth additional_args="--max-peers,100" -``` - -### Network Optimization - -Optimize network settings: - -```bash -# Increase peer connections -starknode-kit config el client=geth additional_args="--maxpeers,100" - -# Optimize for low bandwidth -starknode-kit config el client=geth additional_args="--maxpeers,25,--lightserv,0" -``` - -### Storage Optimization - -Optimize storage usage: - -```bash -# Use light client mode -starknode-kit config el client=geth execution_type=light - -# Use archive mode for complete data -starknode-kit config el client=geth execution_type=archive -``` - -## Monitoring and Logs - -### Real-time Monitoring - -Use the built-in monitoring dashboard: - -```bash -starknode-kit monitor -``` - -Features: -- Real-time sync progress -- Resource usage statistics -- Peer connection status -- Live log streaming - -### Log Files - -Access client log files: - -```bash -# Geth logs -tail -f ~/.starknode-kit/logs/geth.log - -# Lighthouse logs -tail -f ~/.starknode-kit/logs/lighthouse.log - -# Juno logs -tail -f ~/.starknode-kit/logs/juno.log -``` - -### Log Analysis - -Analyze logs for issues: - -```bash -# Search for errors -grep -i error ~/.starknode-kit/logs/*.log - -# Monitor sync progress -grep -i "sync" ~/.starknode-kit/logs/geth.log - -# Check peer connections -grep -i "peer" ~/.starknode-kit/logs/*.log -``` - -## Troubleshooting - -### Common Issues - -**Nodes Won't Start** -```bash -# Check configuration -starknode-kit config --validate - -# Check port conflicts -netstat -tulpn | grep -E "(8545|9000|6060)" - -# Check disk space -df -h -``` - -**Sync Stalls** -```bash -# Restart nodes -starknode-kit stop && starknode-kit start - -# Check network connectivity -ping 8.8.8.8 - -# Use checkpoint sync -starknode-kit config cl client=lighthouse consensus_checkpoint="https://mainnet.checkpoint.sigp.io" -``` - -**High Resource Usage** -```bash -# Check resource usage -htop -iotop - -# Reduce resource allocation -starknode-kit config el client=geth additional_args="--cache,2048,--maxpeers,25" -``` - -### Performance Issues - -**Slow Sync** -- Check disk I/O performance -- Verify network connection -- Consider using checkpoint sync -- Optimize client settings - -**High Memory Usage** -- Reduce cache size -- Use light client mode -- Add swap space -- Monitor for memory leaks - -**High CPU Usage** -- Reduce peer count -- Use lighter execution type -- Check for stuck processes -- Monitor system load - -## Best Practices - -### Security - -- Run nodes behind a firewall -- Use non-default ports in production -- Restrict RPC access to localhost -- Keep clients updated - -### Reliability - -- Use stable network configurations -- Monitor system resources -- Set up automated restarts -- Keep backups of configuration - -### Performance - -- Match execution type to use case -- Optimize for your hardware -- Use checkpoint sync for faster initial sync -- Monitor and tune settings - -## Getting Help - -For node operation issues: - -- Check the [Troubleshooting Guide](troubleshooting.md) -- Review client-specific documentation -- Join our [Telegram community](https://t.me/+SCPbza9fk8dkYWI0) -- Open an issue on [GitHub](https://github.com/thebuidl-grid/starknode-kit/issues) diff --git a/docs/operations/troubleshooting.md b/docs/operations/troubleshooting.md deleted file mode 100644 index 46dbf55..0000000 --- a/docs/operations/troubleshooting.md +++ /dev/null @@ -1,538 +0,0 @@ -# Troubleshooting - -This guide helps you diagnose and resolve common issues with Starknode Kit. - -## Common Issues - -### Installation Problems - -#### Command Not Found - -**Problem**: `starknode-kit: command not found` - -**Solutions**: -```bash -# Check if binary exists -ls -la /usr/local/bin/starknode-kit - -# Add to PATH -echo 'export PATH=$PATH:/usr/local/bin' >> ~/.bashrc -source ~/.bashrc - -# Reinstall if missing -curl -sSL https://raw.githubusercontent.com/thebuidl-grid/starknode-kit/main/install.sh | bash -``` - -#### Permission Denied - -**Problem**: Permission denied when running commands - -**Solutions**: -```bash -# Fix permissions -sudo chmod +x /usr/local/bin/starknode-kit - -# Check ownership -sudo chown $USER:$USER /usr/local/bin/starknode-kit -``` - -#### Go Version Issues - -**Problem**: Go version too old - -**Solutions**: -```bash -# Check current version -go version - -# Update Go (Ubuntu/Debian) -sudo apt update -sudo apt install golang-go - -# Update Go (macOS) -brew install go - -# Update Go (manual) -# Visit https://go.dev/dl/ for latest version -``` - ---- - -### Configuration Issues - -#### Invalid Configuration - -**Problem**: Configuration validation fails - -**Solutions**: -```bash -# Validate configuration -starknode-kit config --validate - -# Reset to defaults -rm ~/.starknode-kit/config.yaml -starknode-kit init - -# Check YAML syntax -yamllint ~/.starknode-kit/config.yaml -``` - -#### Missing Configuration File - -**Problem**: Configuration file not found - -**Solutions**: -```bash -# Create default configuration -starknode-kit init - -# Check file location -ls -la ~/.starknode-kit/ - -# Set custom path -export STARKNODE_CONFIG_PATH=/custom/path/config.yaml -``` - ---- - -### Client Installation Issues - -#### Download Failures - -**Problem**: Client binaries fail to download - -**Solutions**: -```bash -# Check internet connection -ping google.com - -# Check available disk space -df -h - -# Check GitHub access -curl -I https://github.com - -# Manual download -wget https://github.com/ethereum/go-ethereum/releases/download/v1.13.5/geth-linux-amd64-1.13.5-916d9836.tar.gz -``` - -#### Installation Permissions - -**Problem**: Cannot install client binaries - -**Solutions**: -```bash -# Check directory permissions -ls -la ~/.starknode-kit/ - -# Fix permissions -chmod 755 ~/.starknode-kit/ -chmod 755 ~/.starknode-kit/bin/ - -# Create directories if missing -mkdir -p ~/.starknode-kit/bin/ -``` - ---- - -### Client Runtime Issues - -#### Port Conflicts - -**Problem**: Clients cannot bind to required ports - -**Solutions**: -```bash -# Check port usage -netstat -tulpn | grep :8545 # Geth -netstat -tulpn | grep :9000 # Lighthouse -netstat -tulpn | grep :6060 # Juno - -# Kill conflicting processes -sudo kill -9 $(lsof -t -i:8545) - -# Use different ports -starknode-kit config el client=geth port=8547,8548 -``` - -#### Sync Stalls - -**Problem**: Blockchain sync stops or becomes very slow - -**Solutions**: -```bash -# Check client status -starknode-kit monitor - -# Restart clients -starknode-kit stop -starknode-kit start - -# Check disk space -df -h - -# Check network connectivity -ping 8.8.8.8 - -# Use checkpoint sync -starknode-kit config cl client=lighthouse consensus_checkpoint="https://mainnet.checkpoint.sigp.io" -``` - -#### High Resource Usage - -**Problem**: Clients consume too much CPU/memory - -**Solutions**: -```bash -# Check resource usage -htop -iotop - -# Reduce client resources -starknode-kit config el client=geth additional_args="--cache,2048,--maxpeers,25" - -# Use lighter execution type -starknode-kit config el client=geth execution_type=light -``` - ---- - -### Network Issues - -#### Connection Problems - -**Problem**: Cannot connect to network - -**Solutions**: -```bash -# Check network connectivity -ping google.com - -# Check DNS resolution -nslookup google.com - -# Check firewall -sudo ufw status - -# Test specific ports -telnet 8.8.8.8 53 -``` - -#### Low Peer Count - -**Problem**: Few or no peer connections - -**Solutions**: -```bash -# Check peer count -starknode-kit monitor - -# Increase max peers -starknode-kit config el client=geth additional_args="--maxpeers,100" - -# Check network configuration -starknode-kit config -n mainnet - -# Restart clients -starknode-kit stop && starknode-kit start -``` - ---- - -### Monitoring Issues - -#### Dashboard Not Loading - -**Problem**: Monitor dashboard fails to start - -**Solutions**: -```bash -# Check if clients are running -starknode-kit config - -# Restart monitoring -starknode-kit monitor --restart - -# Check for port conflicts -netstat -tulpn | grep :9090 - -# Use basic monitoring -starknode-kit monitor --basic -``` - -#### Missing Metrics - -**Problem**: Some metrics not showing in dashboard - -**Solutions**: -```bash -# Verify client status -starknode-kit config - -# Check client logs -tail -f ~/.starknode-kit/logs/*.log - -# Restart clients -starknode-kit stop && starknode-kit start - -# Check monitoring configuration -starknode-kit monitor --interval 10s -``` - ---- - -## Diagnostic Commands - -### System Information - -```bash -# Check system resources -free -h -df -h -lscpu - -# Check network interfaces -ip addr show -ip route show - -# Check running processes -ps aux | grep -E "(geth|lighthouse|juno)" -``` - -### Client Status - -```bash -# Check client processes -pgrep -f geth -pgrep -f lighthouse -pgrep -f juno - -# Check client logs -tail -f ~/.starknode-kit/logs/geth.log -tail -f ~/.starknode-kit/logs/lighthouse.log -tail -f ~/.starknode-kit/logs/juno.log - -# Check client configuration -starknode-kit config -``` - -### Network Diagnostics - -```bash -# Test connectivity -ping -c 4 8.8.8.8 -ping -c 4 google.com - -# Check DNS -nslookup google.com -dig google.com - -# Test specific ports -nc -zv 8.8.8.8 53 -nc -zv localhost 8545 -``` - ---- - -## Log Analysis - -### Common Log Patterns - -#### Geth Logs - -**Sync Issues**: -```bash -grep -i "sync" ~/.starknode-kit/logs/geth.log -grep -i "peer" ~/.starknode-kit/logs/geth.log -``` - -**Memory Issues**: -```bash -grep -i "memory" ~/.starknode-kit/logs/geth.log -grep -i "cache" ~/.starknode-kit/logs/geth.log -``` - -#### Lighthouse Logs - -**Consensus Issues**: -```bash -grep -i "consensus" ~/.starknode-kit/logs/lighthouse.log -grep -i "beacon" ~/.starknode-kit/logs/lighthouse.log -``` - -**Network Issues**: -```bash -grep -i "network" ~/.starknode-kit/logs/lighthouse.log -grep -i "connection" ~/.starknode-kit/logs/lighthouse.log -``` - -#### Juno Logs - -**L1 Verification Issues**: -```bash -grep -i "l1" ~/.starknode-kit/logs/juno.log -grep -i "ethereum" ~/.starknode-kit/logs/juno.log -``` - -**Sync Issues**: -```bash -grep -i "sync" ~/.starknode-kit/logs/juno.log -grep -i "block" ~/.starknode-kit/logs/juno.log -``` - ---- - -## Performance Issues - -### Slow Sync - -**Causes**: -- Insufficient disk I/O -- Low memory -- Poor network connection -- High CPU usage - -**Solutions**: -```bash -# Check disk I/O -iotop -iostat -x 1 - -# Check memory usage -free -h -htop - -# Optimize client settings -starknode-kit config el client=geth additional_args="--cache,4096,--maxpeers,50" -``` - -### High Memory Usage - -**Causes**: -- Large cache settings -- Memory leaks -- Insufficient swap - -**Solutions**: -```bash -# Check memory usage -free -h -htop - -# Reduce cache size -starknode-kit config el client=geth additional_args="--cache,2048" - -# Add swap space -sudo fallocate -l 8G /swapfile -sudo chmod 600 /swapfile -sudo mkswap /swapfile -sudo swapon /swapfile -``` - -### High CPU Usage - -**Causes**: -- Intensive sync process -- High peer count -- Resource contention - -**Solutions**: -```bash -# Check CPU usage -htop -top - -# Reduce peer count -starknode-kit config el client=geth additional_args="--maxpeers,25" - -# Use lighter execution type -starknode-kit config el client=geth execution_type=light -``` - ---- - -## Recovery Procedures - -### Complete Reset - -```bash -# Stop all clients -starknode-kit stop - -# Remove configuration -rm -rf ~/.starknode-kit/ - -# Reinstall -curl -sSL https://raw.githubusercontent.com/thebuidl-grid/starknode-kit/main/install.sh | bash - -# Reinitialize -starknode-kit init -``` - -### Client Reset - -```bash -# Stop specific client -starknode-kit stop - -# Remove client -starknode-kit remove --execution_client geth - -# Reinstall client -starknode-kit add --execution_client geth - -# Restart -starknode-kit start -``` - -### Database Reset - -```bash -# Stop clients -starknode-kit stop - -# Remove database (WARNING: This will require full resync) -rm -rf ~/.starknode-kit/data/geth/ -rm -rf ~/.starknode-kit/data/lighthouse/ -rm -rf ~/.starknode-kit/data/juno/ - -# Restart clients -starknode-kit start -``` - ---- - -## Getting Help - -### Before Asking for Help - -1. **Check logs**: Review client logs for error messages -2. **Verify configuration**: Ensure configuration is valid -3. **Check system resources**: Verify adequate disk space and memory -4. **Test network**: Ensure stable internet connection -5. **Try restart**: Restart clients and check if issue persists - -### Information to Provide - -When seeking help, include: - -- **Operating system**: Linux distribution, macOS version, etc. -- **Hardware specs**: CPU, RAM, storage -- **Starknode Kit version**: `starknode-kit --version` -- **Configuration**: `starknode-kit config` -- **Error messages**: Full error output -- **Logs**: Relevant log excerpts -- **Steps to reproduce**: What you did before the issue occurred - -### Support Channels - -- **Telegram**: [Join our community](https://t.me/+SCPbza9fk8dkYWI0) -- **GitHub Issues**: [Report bugs and request features](https://github.com/thebuidl-grid/starknode-kit/issues) -- **Documentation**: This troubleshooting guide - -### Community Resources - -- **Discord**: Real-time community support -- **Reddit**: r/ethereum, r/starknet -- **Stack Overflow**: Tag questions with `starknode-kit` -- **GitHub Discussions**: Community discussions and Q&A diff --git a/docs/operations/updates.md b/docs/operations/updates.md deleted file mode 100644 index 1805b5b..0000000 --- a/docs/operations/updates.md +++ /dev/null @@ -1,503 +0,0 @@ -# Updates and Maintenance - -This guide covers how to keep your Starknode Kit installation and clients up to date, along with best practices for maintenance. - -## Client Updates - -### Check for Updates - -```bash -# Check for updates to all clients -starknode-kit update - -# Check for updates to specific client -starknode-kit update --execution_client geth -starknode-kit update --consensus_client lighthouse -starknode-kit update --starknet_client juno -``` - -### Update Process - -When you run `starknode-kit update`, the following happens: - -1. **Check versions**: Compare current vs. latest available versions -2. **Download updates**: Download new client binaries if available -3. **Backup current**: Backup existing binaries -4. **Install updates**: Replace old binaries with new ones -5. **Validate installation**: Verify new binaries work correctly - -### Automatic Updates - -Enable automatic update checking: - -```bash -# Set up cron job for daily updates -echo "0 2 * * * /usr/local/bin/starknode-kit update" | crontab - - -# Or weekly updates -echo "0 2 * * 0 /usr/local/bin/starknode-kit update" | crontab - -``` - ---- - -## Update Strategies - -### Rolling Updates - -Update clients one at a time to minimize downtime: - -```bash -# 1. Update execution client -starknode-kit stop -starknode-kit update --execution_client geth -starknode-kit start - -# 2. Wait for sync, then update consensus client -starknode-kit stop -starknode-kit update --consensus_client lighthouse -starknode-kit start - -# 3. Update Starknet client -starknode-kit stop -starknode-kit update --starknet_client juno -starknode-kit run juno -``` - -### Maintenance Windows - -Schedule updates during low-activity periods: - -```bash -# Create maintenance script -cat > ~/maintenance.sh << 'EOF' -#!/bin/bash -echo "Starting maintenance window..." - -# Stop clients -starknode-kit stop - -# Update all clients -starknode-kit update - -# Clean up old logs -find ~/.starknode-kit/logs -name "*.log" -mtime +30 -delete - -# Restart clients -starknode-kit start - -echo "Maintenance complete" -EOF - -chmod +x ~/maintenance.sh -``` - ---- - -## Version Management - -### Check Current Versions - -```bash -# Check Starknode Kit version -starknode-kit --version - -# Check client versions -~/.starknode-kit/bin/geth version -~/.starknode-kit/bin/lighthouse --version -~/.starknode-kit/bin/juno --version -``` - -### Version Compatibility - -| Starknode Kit | Geth | Lighthouse | Prysm | Juno | -|---------------|------|------------|-------|------| -| 1.0.0 | 1.13.5+ | 4.5.0+ | 4.0.0+ | 0.14.0+ | -| 1.1.0 | 1.13.8+ | 4.6.0+ | 4.1.0+ | 0.14.5+ | -| 1.2.0 | 1.14.0+ | 4.7.0+ | 4.2.0+ | 0.15.0+ | - -### Downgrade if Needed - -```bash -# Stop clients -starknode-kit stop - -# Remove current version -rm ~/.starknode-kit/bin/geth - -# Download specific version -wget https://github.com/ethereum/go-ethereum/releases/download/v1.13.5/geth-linux-amd64-1.13.5-916d9836.tar.gz -tar -xzf geth-linux-amd64-1.13.5-916d9836.tar.gz -mv geth ~/.starknode-kit/bin/ - -# Restart clients -starknode-kit start -``` - ---- - -## Maintenance Tasks - -### Regular Maintenance - -#### Daily Tasks - -```bash -# Check client status -starknode-kit monitor - -# Check disk space -df -h - -# Check logs for errors -grep -i error ~/.starknode-kit/logs/*.log -``` - -#### Weekly Tasks - -```bash -# Update clients -starknode-kit update - -# Clean old logs -find ~/.starknode-kit/logs -name "*.log" -mtime +7 -delete - -# Check system resources -htop -iotop -``` - -#### Monthly Tasks - -```bash -# Full system update -sudo apt update && sudo apt upgrade - -# Clean package cache -sudo apt autoremove -sudo apt autoclean - -# Check disk health -sudo smartctl -a /dev/sda -``` - -### Log Management - -#### Log Rotation - -```bash -# Set up logrotate -sudo tee /etc/logrotate.d/starknode-kit << 'EOF' -/home/*/.starknode-kit/logs/*.log { - daily - missingok - rotate 7 - compress - delaycompress - notifempty - create 644 $USER $USER -} -EOF -``` - -#### Log Analysis - -```bash -# Analyze error patterns -grep -E "(ERROR|WARN|FATAL)" ~/.starknode-kit/logs/*.log | \ - awk '{print $1}' | sort | uniq -c | sort -nr - -# Check sync performance -grep -i "sync" ~/.starknode-kit/logs/geth.log | tail -20 - -# Monitor peer connections -grep -i "peer" ~/.starknode-kit/logs/*.log | tail -20 -``` - ---- - -## Backup and Recovery - -### Configuration Backup - -```bash -# Backup configuration -cp ~/.starknode-kit/config.yaml ~/.starknode-kit/config.yaml.backup - -# Backup to cloud storage -rclone copy ~/.starknode-kit/config.yaml remote:backups/ - -# Version control -cd ~/.starknode-kit/ -git init -git add config.yaml -git commit -m "Initial configuration" -``` - -### Database Backup - -```bash -# Create backup script -cat > ~/backup_databases.sh << 'EOF' -#!/bin/bash -BACKUP_DIR="/backup/starknode-kit/$(date +%Y%m%d)" -mkdir -p "$BACKUP_DIR" - -# Stop clients -starknode-kit stop - -# Backup databases -tar -czf "$BACKUP_DIR/geth_data.tar.gz" ~/.starknode-kit/data/geth/ -tar -czf "$BACKUP_DIR/lighthouse_data.tar.gz" ~/.starknode-kit/data/lighthouse/ -tar -czf "$BACKUP_DIR/juno_data.tar.gz" ~/.starknode-kit/data/juno/ - -# Restart clients -starknode-kit start - -echo "Backup completed: $BACKUP_DIR" -EOF - -chmod +x ~/backup_databases.sh -``` - -### Recovery Procedures - -```bash -# Restore configuration -cp ~/.starknode-kit/config.yaml.backup ~/.starknode-kit/config.yaml - -# Restore database -starknode-kit stop -tar -xzf /backup/starknode-kit/20240101/geth_data.tar.gz -C ~/.starknode-kit/data/ -starknode-kit start -``` - ---- - -## Performance Monitoring - -### System Metrics - -```bash -# Monitor system resources -htop -iotop -nethogs - -# Check disk usage -du -sh ~/.starknode-kit/data/* - -# Monitor network -iftop -``` - -### Client Metrics - -```bash -# Monitor sync progress -starknode-kit monitor - -# Check peer count -curl -X POST -H "Content-Type: application/json" \ - --data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}' \ - http://localhost:8545 - -# Check block height -curl -X POST -H "Content-Type: application/json" \ - --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \ - http://localhost:8545 -``` - ---- - -## Security Updates - -### System Security - -```bash -# Update system packages -sudo apt update && sudo apt upgrade - -# Check for security updates -sudo apt list --upgradable - -# Update kernel if needed -sudo apt install linux-image-generic -``` - -### Client Security - -```bash -# Update clients regularly -starknode-kit update - -# Check for security advisories -# Monitor client GitHub repositories for security releases - -# Use latest stable versions -starknode-kit config --validate -``` - ---- - -## Troubleshooting Updates - -### Update Failures - -**Problem**: Update process fails - -**Solutions**: -```bash -# Check internet connection -ping google.com - -# Check disk space -df -h - -# Check permissions -ls -la ~/.starknode-kit/bin/ - -# Manual update -wget https://github.com/ethereum/go-ethereum/releases/download/v1.14.0/geth-linux-amd64-1.14.0.tar.gz -tar -xzf geth-linux-amd64-1.14.0.tar.gz -mv geth ~/.starknode-kit/bin/ -``` - -### Version Conflicts - -**Problem**: New version causes issues - -**Solutions**: -```bash -# Rollback to previous version -starknode-kit stop -rm ~/.starknode-kit/bin/geth -# Restore previous version from backup - -# Check compatibility -starknode-kit config --validate - -# Report issue -# Open GitHub issue with version information -``` - -### Sync Issues After Update - -**Problem**: Sync problems after updating - -**Solutions**: -```bash -# Check client logs -tail -f ~/.starknode-kit/logs/geth.log - -# Restart clients -starknode-kit stop && starknode-kit start - -# Use checkpoint sync -starknode-kit config cl client=lighthouse consensus_checkpoint="https://mainnet.checkpoint.sigp.io" -``` - ---- - -## Automation - -### Update Automation - -```bash -# Create update script -cat > ~/auto_update.sh << 'EOF' -#!/bin/bash -LOG_FILE="/var/log/starknode-kit-updates.log" - -echo "$(date): Starting automatic update" >> "$LOG_FILE" - -# Check for updates -if starknode-kit update --check-only; then - echo "$(date): Updates available, proceeding" >> "$LOG_FILE" - - # Stop clients - starknode-kit stop - - # Update clients - starknode-kit update - - # Restart clients - starknode-kit start - - echo "$(date): Update completed successfully" >> "$LOG_FILE" -else - echo "$(date): No updates available" >> "$LOG_FILE" -fi -EOF - -chmod +x ~/auto_update.sh - -# Schedule weekly updates -echo "0 3 * * 0 /home/$USER/auto_update.sh" | crontab - -``` - -### Monitoring Automation - -```bash -# Create health check script -cat > ~/health_check.sh << 'EOF' -#!/bin/bash -ALERT_EMAIL="admin@example.com" - -# Check if clients are running -if ! pgrep -f "geth" > /dev/null; then - echo "Geth is not running!" | mail -s "Starknode Kit Alert" "$ALERT_EMAIL" -fi - -if ! pgrep -f "lighthouse" > /dev/null; then - echo "Lighthouse is not running!" | mail -s "Starknode Kit Alert" "$ALERT_EMAIL" -fi - -# Check disk space -DISK_USAGE=$(df / | awk 'NR==2 {print $5}' | sed 's/%//') -if [ "$DISK_USAGE" -gt 90 ]; then - echo "Disk usage is ${DISK_USAGE}%" | mail -s "Starknode Kit Alert" "$ALERT_EMAIL" -fi -EOF - -chmod +x ~/health_check.sh - -# Schedule hourly health checks -echo "0 * * * * /home/$USER/health_check.sh" | crontab - -``` - ---- - -## Best Practices - -### Update Strategy - -1. **Test on testnets first**: Always test updates on testnets before mainnet -2. **Schedule maintenance windows**: Update during low-activity periods -3. **Keep backups**: Always backup before major updates -4. **Monitor after updates**: Watch for issues after updating -5. **Document changes**: Keep track of what was updated and when - -### Maintenance Schedule - -- **Daily**: Check client status and logs -- **Weekly**: Update clients and clean logs -- **Monthly**: Full system maintenance and security updates -- **Quarterly**: Review and optimize configurations - -### Monitoring - -- Set up alerts for critical issues -- Monitor resource usage trends -- Track sync performance -- Watch for security updates - ---- - -## Getting Help - -For update and maintenance issues: - -- Check the [Troubleshooting Guide](troubleshooting.md) -- Review client-specific update documentation -- Join our [Telegram community](https://t.me/+SCPbza9fk8dkYWI0) -- Open an issue on [GitHub](https://github.com/thebuidl-grid/starknode-kit/issues) diff --git a/docs/package.json b/docs/package.json index 60823cd..e0da70a 100644 --- a/docs/package.json +++ b/docs/package.json @@ -1,33 +1,23 @@ { "name": "starknode-kit-docs", "version": "1.0.0", - "description": "Documentation for Starknode Kit - A CLI tool for managing Ethereum and Starknet nodes", - "main": "README.md", + "private": true, "scripts": { - "serve": "honkit serve", - "build": "honkit build", - "pdf": "honkit pdf . ./starknode-kit-docs.pdf", - "epub": "honkit epub . ./starknode-kit-docs.epub" + "dev": "next dev", + "build": "next build", + "start": "next start" }, - "repository": { - "type": "git", - "url": "https://github.com/thebuidl-grid/starknode-kit.git" + "dependencies": { + "react": "19.1.0", + "react-dom": "19.1.0", + "next": "15.5.4" }, - "keywords": [ - "ethereum", - "starknet", - "blockchain", - "node", - "cli", - "documentation", - "gitbook" - ], - "author": "The Buidl Grid", - "license": "MIT", "devDependencies": { - "honkit": "^4.0.0" - }, - "engines": { - "node": ">=16.0.0" + "typescript": "^5", + "@types/node": "^20", + "@types/react": "^19", + "@types/react-dom": "^19", + "@tailwindcss/postcss": "^4", + "tailwindcss": "^4" } -} \ No newline at end of file +} diff --git a/docs/postcss.config.mjs b/docs/postcss.config.mjs new file mode 100644 index 0000000..c7bcb4b --- /dev/null +++ b/docs/postcss.config.mjs @@ -0,0 +1,5 @@ +const config = { + plugins: ["@tailwindcss/postcss"], +}; + +export default config; diff --git a/docs/public/file.svg b/docs/public/file.svg new file mode 100644 index 0000000..004145c --- /dev/null +++ b/docs/public/file.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/public/globe.svg b/docs/public/globe.svg new file mode 100644 index 0000000..567f17b --- /dev/null +++ b/docs/public/globe.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/public/next.svg b/docs/public/next.svg new file mode 100644 index 0000000..5174b28 --- /dev/null +++ b/docs/public/next.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/public/vercel.svg b/docs/public/vercel.svg new file mode 100644 index 0000000..7705396 --- /dev/null +++ b/docs/public/vercel.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/public/window.svg b/docs/public/window.svg new file mode 100644 index 0000000..b2b2a44 --- /dev/null +++ b/docs/public/window.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/src/app/clients/page.tsx b/docs/src/app/clients/page.tsx new file mode 100644 index 0000000..e83e87c --- /dev/null +++ b/docs/src/app/clients/page.tsx @@ -0,0 +1,254 @@ +import Link from 'next/link'; + +export default function Clients() { + return ( +
+

Supported Clients

+ +

+ starknode-kit supports multiple client implementations for both Ethereum + and Starknet networks. +

+ +

Why Multiple Clients?

+ +

+ Running diverse client implementations is crucial for network health and + resilience. Client diversity prevents single points of failure and + reduces the impact of bugs in any one implementation. +

+ +

Ethereum Clients

+ +

+ To run an Ethereum node, you need both an{" "} + execution client and a consensus client + . They work together to validate and process Ethereum blocks post-merge. +

+ +
+
+

Execution Clients

+

Handle transaction execution and state management

+
    +
  • • Geth (Go)
    • +
  • • Reth (Rust)
    • +
+
+ +
+

Consensus Clients

+

Handle proof-of-stake consensus mechanism

+
    +
  • • Lighthouse (Rust)
    • +
  • • Prysm (Go)
    • +
+
+
+ +

Starknet Clients

+ +

+ Starknet clients allow you to run a Starknet full node, enabling interaction with the Starknet Layer 2 network. +

+ +
+
+

Starknet Clients

+

Full node implementations for Starknet

+
    +
  • • Juno (Go) - Full node client
    • +
  • • Starknet Validator - Validator client for staking
    • +
+
+
+ +

Client Combinations

+ +

Popular client combinations for Ethereum nodes:

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ExecutionConsensusCharacteristics
GethLighthouseMost popular, well-tested
RethLighthouseHigh performance, modern
GethPrysmStable, feature-rich
RethPrysmPerformance-focused
+
+ +

Choosing Clients

+ +

Execution Clients

+ +

Geth

+
    +
  • ✅ Most widely used and tested
    • +
  • ✅ Excellent documentation
    • +
  • ✅ Large community support
    • +
  • ✅ Stable and reliable
    • +
  • ⚠️ Higher resource usage
    • +
  • ⚠️ Larger disk footprint
    • +
+ +

Reth

+
    +
  • ✅ Excellent performance
    • +
  • ✅ Lower disk usage
    • +
  • ✅ Modern codebase (Rust)
    • +
  • ✅ Fast sync times
    • +
  • ⚠️ Newer, less battle-tested
    • +
  • ⚠️ Smaller community
    • +
+ +

Consensus Clients

+ +

Lighthouse

+
    +
  • ✅ Fast and efficient
    • +
  • ✅ Low resource usage
    • +
  • ✅ Great documentation
    • +
  • ✅ Active development
    • +
  • ✅ Written in Rust
    • +
+ +

Prysm

+
    +
  • ✅ Feature-rich
    • +
  • ✅ Good performance
    • +
  • ✅ Strong community
    • +
  • ✅ Comprehensive tooling
    • +
  • ✅ Written in Go
    • +
+ +

Starknet Clients

+ +

Juno

+
    +
  • ✅ Official full node client
    • +
  • ✅ Well-maintained
    • +
  • ✅ Fast sync
    • +
  • ✅ Active community
    • +
  • ✅ Required for Starknet validator
    • +
+ +

Resource Requirements by Client

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ClientRAMDiskCPU
Geth16+ GB~1.2 TB4+ cores
Reth16+ GB~900 GB4+ cores
Lighthouse8+ GB~200 GB2+ cores
Prysm8+ GB~250 GB2+ cores
Juno8+ GB~300 GB2+ cores
+
+ +
+

💡 Recommendation

+

+ For most users, we recommend Reth + Lighthouse for Ethereum (best performance) + and Juno for Starknet. +

+
+ +

Client Diversity

+ +

+ Client diversity is critical for network health. If a single client has a bug and it's used by the majority of nodes, + it could cause network issues or even finality problems. +

+ +

Current client distribution matters! Consider using minority clients to help decentralize the network.

+ +

Switching Clients

+ +

You can switch clients at any time:

+ +
    +
  1. Stop your current clients: starknode-kit stop
    2. +
  2. Remove old client: starknode-kit remove --execution_client geth
    3. +
  3. Add new client: starknode-kit add --execution_client reth
    4. +
  4. Start nodes: starknode-kit start
    5. +
+ +
+

⚠️ Note

+

+ Switching clients may require re-syncing from scratch, which can take several days. + Plan accordingly and ensure you have sufficient disk space. +

+
+ +
+

📖 Next Steps

+

+ Ready to dive deeper? Check out our validator guide: +

+
+ Validator Guide +
+
+
+ ); +} + diff --git a/docs/src/app/commands/page.tsx b/docs/src/app/commands/page.tsx new file mode 100644 index 0000000..3fd0b4f --- /dev/null +++ b/docs/src/app/commands/page.tsx @@ -0,0 +1,157 @@ +import Link from 'next/link'; +import CodeBlock from '@/components/CodeBlock'; + +export default function Commands() { + return ( +
+

Commands Reference

+ +

+ Complete reference for all starknode-kit commands. Each command helps + you manage different aspects of your Ethereum and Starknet nodes. +

+ +

Command Overview

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandDescription
addAdd an Ethereum or Starknet client to the config
completionGenerate the autocompletion script for the specified shell
configCreate, show, and update your Starknet node configuration
monitorLaunch real-time monitoring dashboard
removeRemove a specified resource
runRun a specific local infrastructure service
startRun the configured Ethereum clients
statusDisplay status of running clients
stopStop the configured Ethereum clients
updateCheck for and install client updates
validatorManage the Starknet validator client
versionShow version of starknode-kit or a specific client
+
+ +

Quick Examples

+ +

Add Clients

+ + +

Configure Network

+ + +

+ Start Ethereum Clients +

+ + +

Monitor Nodes

+ + +

Check Status

+ + +

+ Run Individual Client +

+ + +

+ Stop Ethereum Clients +

+ + +

Check Version

+ + +

Getting Help

+ +

+ For any command, you can use the --help flag to get + detailed usage information: +

+ + + +

Shell Completion

+ +

+ Generate autocompletion scripts for your shell: +

+ + /etc/bash_completion.d/starknode-kit + +# Zsh +starknode-kit completion zsh > "\${fpath[1]}/_starknode-kit" + +# Fish +starknode-kit completion fish > ~/.config/fish/completions/starknode-kit.fish`} + /> + +
+

📖 Next Steps

+

+ Ready to dive deeper? Check out our comprehensive guides: +

+
+ Supported Clients +
+
+
+ ); +} + diff --git a/docs/src/app/configuration/page.tsx b/docs/src/app/configuration/page.tsx new file mode 100644 index 0000000..3cee155 --- /dev/null +++ b/docs/src/app/configuration/page.tsx @@ -0,0 +1,331 @@ +import CodeBlock from '@/components/CodeBlock'; +import Link from 'next/link'; + +export default function Configuration() { + return ( +
+

Configuration

+ +

+ Learn how to configure starknode-kit for your Ethereum and Starknet + nodes. +

+ +

Configuration File

+ +

+ starknode-kit stores its configuration in a YAML file located at: +

+ + + +

+ Creating a Configuration +

+ +

+ Generate a new configuration file with default settings: +

+ + + +

+ Viewing Configuration +

+ +

View your entire configuration:

+ + + +

View specific sections:

+ + + +

+ Configuration Structure +

+ +

+ The configuration file has the following structure: +

+ + + +

+ Modifying Configuration +

+ +

Change Network

+ +

+ Switch between mainnet, sepolia, or custom networks: +

+ + + +

+ Configure Execution Client +

+ +

Set execution client and ports:

+ + + +

+ Configure Consensus Client +

+ +

Set consensus client and checkpoint:

+ + + +

+ Configure Juno (Starknet) +

+ +

Configure your Juno Starknet client:

+ + + +

Network Settings

+ +

starknode-kit supports multiple networks:

+ +
    +
  • + mainnet - Ethereum and Starknet mainnet +
    • +
  • + sepolia - Ethereum Sepolia and Starknet Sepolia + testnet +
    • +
+ +
+

⚠️ Important

+

+ Changing the network will affect all clients. Make sure to stop your + nodes before changing networks. +

+
+ +

+ Port Configuration +

+ +

Default Ports

+ +

Default ports for each client:

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ClientPortsPurpose
Geth8545, 8546, 30303HTTP RPC, WS RPC, P2P
Reth8545, 8546, 30303HTTP RPC, WS RPC, P2P
Lighthouse5052, 9000HTTP API, P2P
Prysm4000, 13000HTTP API, P2P
Juno6060RPC
+
+ +

+ Validator Configuration +

+ +

+ For validator nodes, additional configuration is required. See the + Validator Setup page for details. +

+ +

+ Environment Variables +

+ +

+ Some sensitive data can be stored as environment variables: +

+ +
    +
  • + STARKNET_WALLET - Wallet address +
    • +
  • + STARKNET_PRIVATE_KEY - Private key +
    • +
  • + STARKNET_PUBLIC_KEY - Public key +
    • +
  • + STARKNET_CLASS_HASH - Class hash +
    • +
  • + STARKNET_SALT - Salt value +
    • +
+ +

+ Configuration Best Practices +

+ +
    +
  1. + Backup your config - Keep a backup of your + configuration file +
    2. +
  2. + Use environment variables - Store sensitive data in + environment variables +
    3. +
  3. + Document changes - Keep notes of any custom + configurations +
    4. +
  4. + Test on testnet - Always test configuration changes + on a testnet first +
    5. +
+ +

Troubleshooting

+ +

+ Configuration not loading +

+ +

+ If your configuration isn't loading, check: +

+ +
    +
  • + File exists at ~/.starknode-kit/starknode.yml +
    • +
  • File has correct YAML syntax
    • +
  • + File has correct permissions (readable by your user) +
    • +
+ +

Port conflicts

+ +

If you get port conflicts:

+ +
    +
  • + Check if ports are already in use: lsof -i :[port] +
    • +
  • Configure different ports in your config
    • +
  • Stop conflicting services
    • +
+ +
+

📖 Next Steps

+

+ Ready to dive deeper? Check out our comprehensive guides: +

+
+ Commands Reference +
+
+
+ ); +} + diff --git a/docs/src/app/contributing/page.tsx b/docs/src/app/contributing/page.tsx new file mode 100644 index 0000000..d003597 --- /dev/null +++ b/docs/src/app/contributing/page.tsx @@ -0,0 +1,265 @@ +import CodeBlock from '@/components/CodeBlock'; +import Link from 'next/link'; + +export default function Contributing() { + return ( +
+

Contributing

+ +

+ We welcome contributions to starknode-kit! This guide will help you get + started with contributing to the project. +

+ +

Ways to Contribute

+ +

There are many ways to contribute to starknode-kit:

+ +
    +
  • 🐛 Report bugs - Help us identify and fix issues
    • +
  • 💡 Suggest features - Share your ideas for improvements
    • +
  • 📝 Improve documentation - Help others understand and use the tool
    • +
  • 💻 Write code - Implement new features or fix bugs
    • +
  • 🧪 Test - Test new releases and provide feedback
    • +
  • 🌍 Community support - Help other users in issues and discussions
    • +
+ +

Getting Started

+ +

1. Fork the Repository

+ +

Start by forking the repository on GitHub:

+ + + +

2. Clone Your Fork

+ + + +

3. Set Up Development Environment

+ +

Make sure you have the required tools:

+ +
    +
  • Go 1.24 or later
    • +
  • Make
    • +
  • Git
    • +
+ + + +

4. Create a Branch

+ +

Create a branch for your changes:

+ + + +

Development Workflow

+ +

Project Structure

+ + + +

Making Changes

+ +
    +
  1. Write your code - Implement your feature or fix
    2. +
  2. Follow Go conventions - Use gofmt and follow Go best practices
    3. +
  3. Add tests - Write tests for your changes when applicable
    4. +
  4. Update documentation - Update README or add docs as needed
    5. +
+ +

Testing

+ +

Run tests before submitting:

+ + + +

Code Style

+ +

Format your code with gofmt:

+ + + +

Submitting Changes

+ +

1. Commit Your Changes

+ +

Write clear, descriptive commit messages:

+ + + +

2. Push to Your Fork

+ + + +

3. Create a Pull Request

+ +
    +
  1. Go to the original repository on GitHub
    2. +
  2. Click "New Pull Request"
    3. +
  3. Select your fork and branch
    4. +
  4. Fill out the PR template with: +
      +
    • Description of changes
      • +
    • Related issues
      • +
    • Testing performed
      • +
    • Screenshots (if UI changes)
      • +
    +
    5. +
  5. Submit the pull request
    6. +
+ +

Pull Request Guidelines

+ +

To increase the chances of your PR being accepted:

+ +
    +
  • ✅ Make focused, single-purpose changes
    • +
  • ✅ Write clear commit messages
    • +
  • ✅ Include tests for new features
    • +
  • ✅ Update documentation as needed
    • +
  • ✅ Follow existing code style
    • +
  • ✅ Respond to review feedback promptly
    • +
  • ❌ Don't include unrelated changes
    • +
  • ❌ Don't submit untested code
    • +
  • ❌ Don't break existing functionality
    • +
+ +

Reporting Bugs

+ +

When reporting bugs, include:

+ +
    +
  1. Description - Clear description of the bug
    2. +
  2. Steps to reproduce - How to trigger the bug
    3. +
  3. Expected behavior - What should happen
    4. +
  4. Actual behavior - What actually happens
    5. +
  5. Environment - OS, Go version, starknode-kit version
    6. +
  6. Logs - Relevant log output or error messages
    7. +
+ + + +

Suggesting Features

+ +

When suggesting features, include:

+ +
    +
  • Clear description of the feature
    • +
  • Use case and motivation
    • +
  • Proposed implementation (if applicable)
    • +
  • Potential impact on existing functionality
    • +
+ +

Code of Conduct

+ +

We are committed to providing a welcoming and inclusive environment. Please:

+ +
    +
  • ✅ Be respectful and considerate
    • +
  • ✅ Welcome newcomers and help them learn
    • +
  • ✅ Accept constructive criticism gracefully
    • +
  • ✅ Focus on what's best for the community
    • +
  • ❌ Don't harass or discriminate
    • +
  • ❌ Don't be disruptive or disrespectful
    • +
+ +

Getting Help

+ +

If you need help with contributing:

+ + + +

Resources

+ + + +
+

🎉 Thank You!

+

+ Thank you for considering contributing to starknode-kit! Your contributions help make this tool better for everyone. +

+
+ + +
+ ); +} + diff --git a/docs/src/app/favicon.ico b/docs/src/app/favicon.ico new file mode 100644 index 0000000..718d6fe Binary files /dev/null and b/docs/src/app/favicon.ico differ diff --git a/docs/src/app/getting-started/page.tsx b/docs/src/app/getting-started/page.tsx new file mode 100644 index 0000000..f7e0251 --- /dev/null +++ b/docs/src/app/getting-started/page.tsx @@ -0,0 +1,228 @@ +import Link from "next/link"; +import CodeBlock from "@/components/CodeBlock"; + +export default function GettingStarted() { + return ( +
+

Getting Started

+ +

+ Welcome to starknode-kit! This guide will help you get up and running + with your Ethereum and Starknet nodes in just a few minutes. +

+ +

Prerequisites

+ +

Before you begin, make sure you have:

+ +
    +
  • + Operating System: Linux or macOS (Windows via WSL) +
    • +
  • + Go: Version 1.24 or later (if building from source) +
    • +
  • + Storage: At least 2TB of free SSD space +
    • +
  • + RAM: Minimum 32GB recommended +
    • +
  • + Network: Stable internet connection +
    • +
+ +
+

📝 Note

+

+ For detailed hardware requirements, check out our{" "} + + Requirements page + + . +

+
+ +

Installation

+ +

+ The quickest way to install starknode-kit is using the installation + script: +

+ + + +

This script will:

+
    +
  • + Download the latest version of starknode-kit +
    • +
  • + Install it to /usr/local/bin/ +
    • +
  • + Create necessary configuration directories +
    • +
+ +

+ Initial Configuration +

+ +

+ After installation, generate your initial configuration file: +

+ + + +

+ This creates a configuration file at{" "} + ~/.starknode-kit/starknode.yml with default settings. +

+ +

+ Add Your First Clients +

+ +

+ Ethereum Clients (Execution + Consensus) +

+ +

+ To run an Ethereum node, you need both an execution client and a + consensus client: +

+ + + +

Or with Reth and Prysm:

+ + + +

Starknet Client

+ +

To add a Starknet client (Juno):

+ + + +

Configure Network

+ +

+ By default, starknode-kit is configured for mainnet. To change to a + test network: +

+ + + +

Start Your Nodes

+ +

+ Start Ethereum Clients +

+ +

+ To start your configured Ethereum execution and consensus clients: +

+ + + +
+

⚠️ Important

+

+ The start command only launches Ethereum clients + (execution + consensus). It does not start Starknet clients. +

+
+ +

+ Run Individual Clients +

+ +

To run a specific client:

+ + + +

Monitor Your Nodes

+ +

+ Launch the real-time monitoring dashboard to see the status of your + nodes: +

+ + + +

The monitoring dashboard provides real-time insights:

+ +
+
+
+ 🔄 +
+

Node Sync Status

+

Real-time synchronization progress and health

+
+
+
+ +
+
+ 📊 +
+

Current Block Height

+

Latest block number and sync progress

+
+
+
+ +
+
+ 🌐 +
+

Network Statistics

+

Peer connections and network performance

+
+
+
+ +
+
+ 💻 +
+

System Resources

+

CPU, RAM, and disk usage metrics

+
+
+
+
+ +

Check Status

+ +

+ For a quick status check of all running clients: +

+ + + +
+

📖 Next Steps

+

+ Ready to dive deeper? Check out our installation guide: +

+
+ Installation Guide +
+
+
+ ); +} + diff --git a/docs/src/app/globals.css b/docs/src/app/globals.css new file mode 100644 index 0000000..b60e14f --- /dev/null +++ b/docs/src/app/globals.css @@ -0,0 +1,93 @@ +@import "tailwindcss"; + +body { + font-family: var(--font-inter), system-ui, -apple-system, sans-serif; + line-height: 1.7; +} + +/* Scrollbar styling */ +::-webkit-scrollbar { + width: 8px; + height: 8px; +} + +::-webkit-scrollbar-track { + background: transparent; +} + +::-webkit-scrollbar-thumb { + background: #cbd5e0; + border-radius: 4px; +} + +::-webkit-scrollbar-thumb:hover { + background: #a0aec0; +} + +/* Prose styling for documentation */ +.prose { + max-width: none; + line-height: 1.8; +} + +.prose p { + margin-bottom: 1.5rem; +} + +.prose h2 { + margin-top: 3rem; + margin-bottom: 1.5rem; +} + +.prose h3 { + margin-bottom: 1.25rem; +} + +.prose a { + color: #2563eb; + text-decoration: none; + transition: color 0.2s; +} + +.prose a:hover { + color: #1d4ed8; + text-decoration: none; +} + +.prose code { + background: #f3f4f6; + padding: 0.2em 0.4em; + border-radius: 0.25rem; + font-size: 0.875em; + font-family: 'Courier New', monospace; +} + +.prose pre { + background: #1a202c !important; + padding: 1rem; + border-radius: 0.5rem; + overflow-x: auto; +} + +.prose pre code { + background: transparent; + padding: 0; + color: #e2e8f0; +} + +.prose table { + width: 100%; + border-collapse: collapse; +} + +.prose th { + text-align: left; + font-weight: 600; +} + +.prose blockquote { + border-left: 4px solid #e5e7eb; + padding-left: 1rem; + font-style: italic; + color: #6b7280; +} diff --git a/docs/src/app/installation/page.tsx b/docs/src/app/installation/page.tsx new file mode 100644 index 0000000..9dcd313 --- /dev/null +++ b/docs/src/app/installation/page.tsx @@ -0,0 +1,179 @@ +import Link from 'next/link'; +import CodeBlock from '@/components/CodeBlock'; + +export default function Installation() { + return ( +
+

Installation

+ +

+ There are multiple ways to install starknode-kit. Choose the method that + best suits your needs. +

+ +

+ Option 1: Install Script (Recommended) +

+ +

+ The easiest and recommended way to install starknode-kit: +

+ + + +

+ Or download the script first and then run it: +

+ + + +

+ Option 2: Install using Go +

+ +

+ If you have Go installed (version 1.24 or later), you can install + starknode-kit directly: +

+ + + +

+ This installs the latest version from the main branch. +

+ +

+ Option 3: Manual Installation from Source +

+ +

+ 1. Clone the Repository +

+ + + +

2. Build and Install

+ + + +

Verify Installation

+ +

+ After installation, verify that starknode-kit is working correctly: +

+ + + +

You should see output similar to:

+ + + +

Initial Setup

+ +

+ After successful installation, generate your configuration file: +

+ + + +

+ This creates a configuration file at{" "} + ~/.starknode-kit/starknode.yml. +

+ +

Uninstallation

+ +

+ To uninstall starknode-kit, remove the binary and configuration + directory: +

+ + + +
+

⚠️ Note

+

+ This will not remove any client data (e.g., blockchain data). The data + is stored in the locations specified in your{" "} + ~/.starknode-kit/starknode.yml file. +

+
+ +

Troubleshooting

+ +

Command not found

+ +

+ If you get a "command not found" error, make sure{" "} + /usr/local/bin is in your PATH: +

+ + + +

+ Add this to your ~/.bashrc or ~/.zshrc to make + it permanent. +

+ +

Permission denied

+ +

+ If you encounter permission issues during installation, make sure you + have sudo access or contact your system administrator. +

+ +
+

📖 Next Steps

+

+ Ready to dive deeper? Check out our configuration guide: +

+
+ Configuration Guide +
+
+
+ ); +} + diff --git a/docs/src/app/layout.tsx b/docs/src/app/layout.tsx new file mode 100644 index 0000000..66099db --- /dev/null +++ b/docs/src/app/layout.tsx @@ -0,0 +1,40 @@ +import type { Metadata } from "next"; +import { Inter, Source_Code_Pro } from "next/font/google"; +import "./globals.css"; +import Sidebar from "@/components/Sidebar"; +import Header from "@/components/Header"; + +const inter = Inter({ + subsets: ["latin"], + variable: "--font-inter", +}); + +const source_code_pro = Source_Code_Pro({ + subsets: ["latin"], + variable: "--font-source-code" +}) + +export const metadata: Metadata = { + title: "starknode-kit Documentation", + description: "Complete documentation for starknode-kit - A CLI tool for setting up and managing Ethereum and Starknet nodes", +}; + +export default function RootLayout({ + children, +}: Readonly<{ + children: React.ReactNode; +}>) { + return ( + + + +
+
+
+ {children} +
+
+ + + ); +} diff --git a/docs/src/app/page.tsx b/docs/src/app/page.tsx new file mode 100644 index 0000000..ea7a66d --- /dev/null +++ b/docs/src/app/page.tsx @@ -0,0 +1,144 @@ +import Link from "next/link"; +import CodeBlock from "@/components/CodeBlock"; + +export default function Home() { + return ( +
+

Welcome to starknode-kit

+ +

+ A powerful command-line tool to help developers and node operators + easily set up, manage, and maintain Ethereum and Starknet nodes. +

+ +
+ +

+ 🚀 Getting Started +

+

+ Learn how to install and configure starknode-kit for your node + setup. +

+ + + +

+ 📘 Commands +

+

+ Explore all available commands and their usage. +

+ + + +

+ ⚙️ Configuration +

+

+ Configure your Ethereum and Starknet clients. +

+ + + +

+ 🔐 Validator Setup +

+

+ Set up and manage your Starknet validator node. +

+ +
+ +

Quick Start

+ +

Install starknode-kit with a single command:

+ + + +

Generate your configuration file:

+ + + +

Add your first client pair:

+ + + +

Key Features

+ +
    +
  • + ✅ Easy Setup - Get your node running in minutes +
    • +
  • + ✅ Multi-Client Support - Works with Geth, Reth, + Lighthouse, Prysm, and Juno +
    • +
  • + ✅ Real-time Monitoring - Built-in dashboard to + monitor your nodes +
    • +
  • + ✅ Auto Updates - Keep your clients up to date + automatically +
    • +
  • + ✅ Validator Management - Simplified Starknet + validator operations +
    • +
  • + ✅ Network Flexibility - Support for mainnet, + sepolia, and custom networks +
    • +
+ +

Supported Clients

+ +
+
+

Execution Layer

+
    +
  • • Geth
    • +
  • • Reth
    • +
+
+
+

Consensus Layer

+
    +
  • • Lighthouse
    • +
  • • Prysm
    • +
+
+
+

Starknet

+
    +
  • • Juno
    • +
  • • Starknet Validator
    • +
+
+
+ +
+

📖 Next Steps

+

+ Ready to dive deeper? Check out our comprehensive guides: +

+
+ Installation Guide +
+
+
+ ); +} diff --git a/docs/src/app/requirements/page.tsx b/docs/src/app/requirements/page.tsx new file mode 100644 index 0000000..8ef1256 --- /dev/null +++ b/docs/src/app/requirements/page.tsx @@ -0,0 +1,319 @@ +import Link from 'next/link'; +import CodeBlock from '@/components/CodeBlock'; + +export default function Requirements() { + return ( +
+

Requirements

+ +

+ Hardware and software requirements for running Ethereum and Starknet + nodes with starknode-kit. +

+ +

Hardware Requirements

+ +
+

📚 Reference

+

+ For a detailed breakdown of node hardware requirements, see the Rocket Pool Hardware Guide. +

+
+ +

Minimum Requirements

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ComponentRequirementNotes
CPU4+ coresIntel i3/i5 or AMD equivalent. Avoid Celeron.
RAM32 GBMinimum 16GB, 32GB recommended for comfort
Storage2+ TB NVMe SSDMust have DRAM cache, no QLC NAND
Network100+ MbpsStable connection, unlimited data preferred
Power24/7 uptimeUPS recommended for validators
+
+ +

Recommended Specifications

+ +
    +
  • CPU: Intel i5/i7 or AMD Ryzen 5/7 (6+ cores)
    • +
  • RAM: 64 GB DDR4
    • +
  • Storage: 4 TB NVMe SSD with DRAM cache
    • +
  • Network: 1 Gbps fiber connection
    • +
  • Backup Power: UPS with 30+ minutes runtime
    • +
+ +

Storage Requirements

+ +

Storage is the most critical component for node operation.

+ +

Storage Size

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ClientCurrent SizeGrowth Rate
Ethereum (Geth)~1.2 TB~150 GB/year
Ethereum (Reth)~900 GB~120 GB/year
Lighthouse~200 GB~50 GB/year
Prysm~250 GB~60 GB/year
Juno (Starknet)~300 GB~100 GB/year
+
+ +

SSD Requirements

+ +

Your SSD must have:

+ +
    +
  • ✅ DRAM cache - Essential for performance
    • +
  • ✅ TLC or better NAND - No QLC (Quad-Level Cell)
    • +
  • ✅ High endurance rating - 600+ TBW recommended
    • +
  • ✅ NVMe interface - SATA SSDs are too slow
    • +
+ +
+

⚠️ Warning

+

+ Using a QLC SSD or SSD without DRAM cache will result in poor performance and potential node failures. + See the tested SSD list for recommendations. +

+
+ +

Software Requirements

+ +

Operating System

+ +

Supported operating systems:

+ +
    +
  • Linux: Ubuntu 20.04+, Debian 11+, or other modern distributions
    • +
  • macOS: macOS 12 (Monterey) or later
    • +
  • Windows: Windows 10/11 with WSL2 (Ubuntu)
    • +
+ +

Linux is highly recommended for production use.

+ +

Required Software

+ +

Go (for building from source)

+ +

Version 1.24 or later required:

+ + + +

Install from: https://go.dev/dl/

+ +

Rust (for Starknet clients)

+ +

Recommended for building Juno and other Starknet clients:

+ + + +

Make

+ +

Required for building certain clients:

+ + + +

Network Requirements

+ +

Bandwidth

+ +
    +
  • Download: 100+ Mbps
    • +
  • Upload: 25+ Mbps
    • +
  • Data Cap: Unlimited (or 2+ TB/month)
    • +
+ +

Ports

+ +

Ensure these ports are accessible:

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PortProtocolPurpose
30303TCP/UDPEthereum execution P2P
9000TCP/UDPLighthouse consensus P2P
13000TCPPrysm consensus P2P
6060TCPJuno RPC (localhost only)
+
+ +

For Validator Nodes

+ +

Additional requirements for running a validator:

+ +
    +
  • Uptime: 99.9%+ availability required
    • +
  • Backup Power: UPS mandatory
    • +
  • Monitoring: 24/7 monitoring and alerting
    • +
  • Backup Internet: Secondary connection recommended
    • +
  • Dedicated Hardware: No shared resources
    • +
+ +

Tested Hardware Configurations

+ +

Budget Build (~$800)

+ +
    +
  • Intel NUC 13 PRO (i5)
    • +
  • 32 GB DDR4 RAM
    • +
  • 2 TB NVMe SSD (Samsung 980 PRO)
    • +
  • Ubuntu 22.04 LTS
    • +
+ +

Recommended Build (~$1500)

+ +
    +
  • Custom build: AMD Ryzen 7 or Intel i7
    • +
  • 64 GB DDR4 RAM
    • +
  • 4 TB NVMe SSD (Samsung 990 PRO)
    • +
  • 1 Gbps fiber connection
    • +
  • UPS with 30min+ runtime
    • +
  • Ubuntu 22.04 LTS
    • +
+ +

Pro Build (~$3000+)

+ +
    +
  • High-end workstation or server
    • +
  • 128 GB ECC RAM
    • +
  • 8 TB NVMe SSD (enterprise grade)
    • +
  • Redundant power supplies
    • +
  • Redundant network connections
    • +
  • Professional monitoring and alerting
    • +
+ +

Cloud Providers

+ +

If running in the cloud, recommended specifications:

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + +
ProviderInstance TypeEst. Cost/Month
AWSm5.2xlarge + 4TB gp3~$500-700
Google Cloudn2-standard-8 + 4TB SSD~$600-800
AzureStandard_D8s_v3 + 4TB Premium SSD~$550-750
+
+ +
+

💡 Cost Consideration

+

+ Running on dedicated hardware is often more cost-effective long-term than cloud hosting, especially for validators. +

+
+
+ ); +} + diff --git a/docs/src/app/validator/page.tsx b/docs/src/app/validator/page.tsx new file mode 100644 index 0000000..156aa27 --- /dev/null +++ b/docs/src/app/validator/page.tsx @@ -0,0 +1,239 @@ +import CodeBlock from '@/components/CodeBlock'; +import Link from 'next/link'; +export default function Validator() { + return ( +
+

Validator Setup

+ +

+ Set up and manage your Starknet validator node using starknode-kit. +

+ +
+

⚠️ Important

+

+ Running a validator requires significant responsibility. Make sure you + understand the requirements and risks before proceeding. +

+
+ +

Prerequisites

+ +

Before setting up a validator, ensure you have:

+ +
    +
  • ✅ A fully synced Juno (Starknet) node
    • +
  • ✅ A Starknet wallet with sufficient funds for staking
    • +
  • ✅ Stable internet connection with 99.9%+ uptime
    • +
  • ✅ Understanding of validator responsibilities
    • +
+ +

Installation

+ +

The validator client is managed through starknode-kit. First, ensure you have starknode-kit installed and configured.

+ +

Validator Commands

+ +

Check Validator Status

+ +

Check the status of your validator:

+ + + +

Get Validator Version

+ +

Check the installed version of the validator client:

+ + + +

Set Juno RPC Endpoint

+ +

Configure the Juno RPC endpoint for your validator:

+ + + +

Or use a remote Juno node:

+ + + +

Configuration

+ +

Validator configuration is stored in your starknode-kit config file. Key settings include:

+ + + +

Setting Up Environment Variables

+ +

Store sensitive validator data in environment variables:

+ + + +

Add these to your ~/.bashrc or ~/.zshrc to make them persistent.

+ +

Starting Your Validator

+ +

Step 1: Ensure Juno is Running

+ +

Your Juno node must be fully synced and running:

+ + + +

Step 2: Verify Configuration

+ +

Check your validator configuration:

+ + + +

Step 3: Start the Validator

+ +

Start your validator client:

+ + + +

Monitoring Your Validator

+ +

Monitor your validator status:

+ + + +

Validator Responsibilities

+ +
    +
  1. Uptime - Maintain high availability (99.9%+)
    2. +
  2. Security - Keep your keys secure and never share them
    3. +
  3. Updates - Keep your validator software up to date
    4. +
  4. Monitoring - Actively monitor your validator performance
    5. +
  5. Backup - Maintain secure backups of your keys
    6. +
+ +

Security Best Practices

+ +
    +
  • ✅ Use hardware wallets when possible
    • +
  • ✅ Store keys in environment variables, not in config files
    • +
  • ✅ Use firewall to restrict access to validator ports
    • +
  • ✅ Enable SSH key-based authentication
    • +
  • ✅ Keep your server updated with security patches
    • +
  • ✅ Monitor for unusual activity
    • +
  • ✅ Have a disaster recovery plan
    • +
  • ❌ Never share your private keys
    • +
  • ❌ Don't run validators on shared hosting
    • +
  • ❌ Avoid storing keys in version control
    • +
+ +

Staking and Commission

+ +

Configure your validator's commission rate:

+ + + +

This sets a 10% commission on staking rewards. Validators typically charge 5-15% commission.

+ +

Troubleshooting

+ +

Validator Not Connecting to Juno

+ +

Check that:

+
    +
  • Juno is running: starknode-kit status
    • +
  • RPC endpoint is correct in config
    • +
  • Firewall allows connections to Juno port
    • +
+ +

Keys Not Loading

+ +

Verify environment variables are set:

+ + + +

If empty, add to your shell profile and reload.

+ +

Validator Offline

+ +

If your validator goes offline:

+
    +
  1. ✅ Check system resources
    2. +
  2. ✅ Check network connectivity
    3. +
  3. ✅ Review validator logs
    4. +
  4. ✅ Restart validator if needed
    5. +
+ +

Performance Metrics

+ +

Monitor these key metrics:

+ +
    +
  • Attestation rate - Percentage of successful attestations
    • +
  • Block proposals - Number of blocks proposed
    • +
  • Uptime - Validator availability percentage
    • +
  • Rewards - Staking rewards earned
    • +
+ +

Validator Economics

+ +

Understand the economics:

+ +
    +
  • Minimum Stake - Required amount to become a validator
    • +
  • Rewards - Earned from successful validation
    • +
  • Commission - Your fee for running the validator
    • +
  • Penalties - For downtime or malicious behavior
    • +
+ +
+

💡 Tip

+

+ Start on the testnet (Sepolia) to familiarize yourself with validator operations before running on mainnet. +

+
+ +

Resources

+ + + +
+

📖 Next Steps

+

+ Ready to dive deeper? Check out our comprehensive guides: +

+
+ System Requirements +
+
+
+ ); +} + diff --git a/docs/src/components/CodeBlock.tsx b/docs/src/components/CodeBlock.tsx new file mode 100644 index 0000000..8f6f33e --- /dev/null +++ b/docs/src/components/CodeBlock.tsx @@ -0,0 +1,35 @@ +'use client'; + +import { useState } from 'react'; + +interface CodeBlockProps { + code: string; + language?: string; +} + +export default function CodeBlock({ code, language = 'bash' }: CodeBlockProps) { + const [copied, setCopied] = useState(false); + + const copyToClipboard = async () => { + await navigator.clipboard.writeText(code); + setCopied(true); + setTimeout(() => setCopied(false), 2000); + }; + + return ( +
+
+ +
+ 
+        
{code}

+
+
+ ); +} + diff --git a/docs/src/components/Header.tsx b/docs/src/components/Header.tsx new file mode 100644 index 0000000..7be998d --- /dev/null +++ b/docs/src/components/Header.tsx @@ -0,0 +1,41 @@ +'use client'; + +import Link from 'next/link'; + +export default function Header() { + return ( +
+
+
+ + + + + + + + + + +
+
+
+ ); +} + diff --git a/docs/src/components/Sidebar.tsx b/docs/src/components/Sidebar.tsx new file mode 100644 index 0000000..0c7c350 --- /dev/null +++ b/docs/src/components/Sidebar.tsx @@ -0,0 +1,60 @@ +'use client'; + +import Link from 'next/link'; +import { usePathname } from 'next/navigation'; + +interface NavItem { + title: string; + href: string; +} + +const navigation: NavItem[] = [ + { title: 'Introduction', href: '/' }, + { title: 'Getting Started', href: '/getting-started' }, + { title: 'Installation', href: '/installation' }, + { title: 'Configuration', href: '/configuration' }, + { title: 'Commands', href: '/commands' }, + { title: 'Clients', href: '/clients' }, + { title: 'Validator Setup', href: '/validator' }, + { title: 'Requirements', href: '/requirements' }, + { title: 'Contributing', href: '/contributing' }, +]; + +export default function Sidebar() { + const pathname = usePathname(); + + const isActive = (href: string) => { + if (href === '/') return pathname === href; + return pathname.startsWith(href); + }; + + return ( + + ); +} + diff --git a/docs/styles/website.css b/docs/styles/website.css deleted file mode 100644 index 1288007..0000000 --- a/docs/styles/website.css +++ /dev/null @@ -1,282 +0,0 @@ -/* Custom styles for Starknode Kit documentation */ - -/* Brand colors */ -:root { - --primary-color: #6366f1; - --secondary-color: #8b5cf6; - --accent-color: #06b6d4; - --success-color: #10b981; - --warning-color: #f59e0b; - --error-color: #ef4444; - --text-color: #1f2937; - --bg-color: #ffffff; - --border-color: #e5e7eb; -} - -/* Header styling */ -.book-header { - background: linear-gradient(135deg, var(--primary-color), var(--secondary-color)); - border-bottom: 1px solid var(--border-color); -} - -.book-header h1 { - color: white; - font-weight: 600; -} - -/* Navigation styling */ -.book-summary { - background-color: #f8fafc; - border-right: 1px solid var(--border-color); -} - -.book-summary ul.summary li a { - color: var(--text-color); - font-weight: 500; -} - -.book-summary ul.summary li.active > a { - color: var(--primary-color); - background-color: #e0e7ff; - border-left: 3px solid var(--primary-color); -} - -.book-summary ul.summary li a:hover { - color: var(--primary-color); - background-color: #f1f5f9; -} - -/* Content styling */ -.book-body { - background-color: var(--bg-color); -} - -.markdown-section { - max-width: 900px; - line-height: 1.6; - color: var(--text-color); -} - -.markdown-section h1, -.markdown-section h2, -.markdown-section h3, -.markdown-section h4, -.markdown-section h5, -.markdown-section h6 { - color: var(--text-color); - font-weight: 600; - margin-top: 2rem; - margin-bottom: 1rem; -} - -.markdown-section h1 { - font-size: 2.5rem; - border-bottom: 2px solid var(--primary-color); - padding-bottom: 0.5rem; -} - -.markdown-section h2 { - font-size: 2rem; - color: var(--primary-color); -} - -.markdown-section h3 { - font-size: 1.5rem; - color: var(--secondary-color); -} - -/* Code styling */ -.markdown-section pre { - background-color: #1e293b; - border: 1px solid #334155; - border-radius: 8px; - padding: 1rem; - overflow-x: auto; -} - -.markdown-section code { - background-color: #f1f5f9; - color: var(--primary-color); - padding: 0.2rem 0.4rem; - border-radius: 4px; - font-size: 0.9em; -} - -.markdown-section pre code { - background-color: transparent; - color: #e2e8f0; - padding: 0; -} - -/* Blockquote styling */ -.markdown-section blockquote { - border-left: 4px solid var(--accent-color); - background-color: #f0f9ff; - padding: 1rem; - margin: 1rem 0; - border-radius: 0 8px 8px 0; -} - -.markdown-section blockquote p { - margin: 0; - color: #0c4a6e; -} - -/* Table styling */ -.markdown-section table { - border-collapse: collapse; - width: 100%; - margin: 1rem 0; - border-radius: 8px; - overflow: hidden; - box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1); -} - -.markdown-section table th { - background-color: var(--primary-color); - color: white; - padding: 0.75rem; - text-align: left; - font-weight: 600; -} - -.markdown-section table td { - padding: 0.75rem; - border-bottom: 1px solid var(--border-color); -} - -.markdown-section table tr:nth-child(even) { - background-color: #f8fafc; -} - -.markdown-section table tr:hover { - background-color: #f1f5f9; -} - -/* Alert boxes */ -.alert { - padding: 1rem; - margin: 1rem 0; - border-radius: 8px; - border-left: 4px solid; -} - -.alert-info { - background-color: #f0f9ff; - border-left-color: var(--accent-color); - color: #0c4a6e; -} - -.alert-warning { - background-color: #fffbeb; - border-left-color: var(--warning-color); - color: #92400e; -} - -.alert-success { - background-color: #f0fdf4; - border-left-color: var(--success-color); - color: #166534; -} - -.alert-error { - background-color: #fef2f2; - border-left-color: var(--error-color); - color: #991b1b; -} - -/* Button styling */ -.btn { - display: inline-block; - padding: 0.5rem 1rem; - background-color: var(--primary-color); - color: white; - text-decoration: none; - border-radius: 6px; - font-weight: 500; - transition: background-color 0.2s; -} - -.btn:hover { - background-color: var(--secondary-color); - color: white; - text-decoration: none; -} - -.btn-secondary { - background-color: var(--secondary-color); -} - -.btn-secondary:hover { - background-color: var(--primary-color); -} - -/* Feature highlights */ -.feature-grid { - display: grid; - grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); - gap: 1.5rem; - margin: 2rem 0; -} - -.feature-card { - background: white; - border: 1px solid var(--border-color); - border-radius: 12px; - padding: 1.5rem; - box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1); - transition: transform 0.2s, box-shadow 0.2s; -} - -.feature-card:hover { - transform: translateY(-2px); - box-shadow: 0 4px 8px rgba(0, 0, 0, 0.15); -} - -.feature-card h3 { - color: var(--primary-color); - margin-top: 0; - margin-bottom: 1rem; -} - -.feature-card .icon { - font-size: 2rem; - margin-bottom: 1rem; -} - -/* Responsive design */ -@media (max-width: 768px) { - .markdown-section { - padding: 1rem; - } - - .markdown-section h1 { - font-size: 2rem; - } - - .markdown-section h2 { - font-size: 1.5rem; - } - - .feature-grid { - grid-template-columns: 1fr; - } -} - -/* Print styles */ -@media print { - .book-header, - .book-summary, - .book-body .navigation { - display: none; - } - - .book-body { - margin: 0; - padding: 0; - } - - .markdown-section { - max-width: none; - } -} diff --git a/docs/tailwind.config.ts b/docs/tailwind.config.ts new file mode 100644 index 0000000..f67c807 --- /dev/null +++ b/docs/tailwind.config.ts @@ -0,0 +1,16 @@ +import type { Config } from "tailwindcss"; + +const config: Config = { + content: [ + "./src/pages/**/*.{js,ts,jsx,tsx,mdx}", + "./src/components/**/*.{js,ts,jsx,tsx,mdx}", + "./src/app/**/*.{js,ts,jsx,tsx,mdx}", + ], + theme: { + extend: {}, + }, + plugins: [], +}; + +export default config; + diff --git a/docs/tsconfig.json b/docs/tsconfig.json new file mode 100644 index 0000000..c133409 --- /dev/null +++ b/docs/tsconfig.json @@ -0,0 +1,27 @@ +{ + "compilerOptions": { + "target": "ES2017", + "lib": ["dom", "dom.iterable", "esnext"], + "allowJs": true, + "skipLibCheck": true, + "strict": true, + "noEmit": true, + "esModuleInterop": true, + "module": "esnext", + "moduleResolution": "bundler", + "resolveJsonModule": true, + "isolatedModules": true, + "jsx": "preserve", + "incremental": true, + "plugins": [ + { + "name": "next" + } + ], + "paths": { + "@/*": ["./src/*"] + } + }, + "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"], + "exclude": ["node_modules"] +}