gNode

gNode Installation Checklist

Complete checklist for installing gNode on a fresh system.

Pre-Installation Checklist

System Requirements

Required Software

User Permissions

Installation Steps

Step 1: Clone Repository

git clone https://github.com/geodineum/gNode.git
cd gNode

Step 2: Run Initialization Script

./setup-gnode.sh

What happens during initialization:

Step 3: Activate gNode Group Membership

CRITICAL: You must activate the gnode group before using gNode!

Option A: Activate for current session only

newgrp gnode

Option B: Activate permanently (recommended)

# Log out and log back in
# Then verify:
groups | grep gnode

Step 4: Verify Installation

# 1. Check ValKey is running
systemctl status valkey-gnode
# 2. Test ValKey authentication
./scripts/valkey-cli-secure.sh PING
# 3. Count loaded functions
./scripts/valkey-cli-secure.sh FUNCTION LIST | grep -c GNODE_
# 4. Check daemon binary
ls -lh daemon/target/release/gnode-daemon
# 5. Verify permissions
ls -la logs/
ls -la run/
# 6. Check group membership
groups | grep gnode

Step 5: Start Daemon

sudo systemctl start gnode-daemon
# Verify daemon is running
ps aux | grep gnode-daemon

Step 6: Test Basic Functionality

# Check daemon status
./scripts/check-gnode-status.sh
# Send test command
./scripts/valkey-cli-secure.sh XADD "default:gnode:unified:production" '*' \
  id "test-1" cmd "ping" params '{}'

Post-Installation Checklist

Security

Files Created

Configuration

Optional: Run Test Suite

# Test all ValKey functions
./scripts/test-all-valkey-functions.sh
# Check gNode status
./scripts/check-gnode-status.sh

Troubleshooting Checklist

If Installation Fails

Permission Issues

Build Failures

ValKey Issues

Function Loading Issues

Common Mistakes

Mistake 1: Not Running with Sudo

Problem: Permission setup script fails Solution: The init script automatically calls sudo when needed

Mistake 2: Not Activating gNode Group

Problem: "Permission denied" when writing logs Solution: Run newgrp gnode or logout/login after installation

Mistake 3: Forgetting Password Location

Problem: Can't connect to ValKey Solution: Password is in /etc/geodineum/credentials/valkey_daemon.password (use REDISCLI_AUTH env var or ./scripts/valkey-cli-secure.sh)

Mistake 4: Running Daemon Before Group Activation

Problem: Logs not written, PID file fails Solution: Always run newgrp gnode first, or logout/login

Success Indicators

If all these are true, your installation is complete:

Next Steps After Installation

  1. Read Documentation

    • [ ] Read CLAUDE.md for architecture details
    • [ ] Check COMMAND_SCHEMA.md for command reference

  2. Integrate with Application

    • [ ] Install gNode-Client: composer require geodineum/gnode-client
    • [ ] Configure application with credentials from /etc/geodineum/credentials/
    • [ ] Test basic commands from application

  3. Production Preparation

    • [ ] Configure monitoring and logging
    • [ ] Set up automated backups of ValKey data (./scripts/backup-valkey.sh)

  4. Performance Tuning

    • [ ] Adjust thread count if needed
    • [ ] Configure batch sizes for workload
    • [ ] Monitor resource usage
    • [ ] Run benchmarks with production data

Quick Reference Commands

# Start daemon
sudo systemctl start gnode-daemon

# Stop daemon
sudo systemctl stop gnode-daemon

# Check status
./scripts/check-gnode-status.sh

# View logs
sudo journalctl -u gnode-daemon -f

# Test connection
./scripts/valkey-cli-secure.sh PING

# Reload functions
./scripts/load-valkey-functions.sh

# Full setup/repair
./setup-gnode.sh

Support Resources

Remember: The most common issue is forgetting to activate the gnode group membership. Always run newgrp gnode after installation or logout/login for permanent effect!