b033923756
- Remove executable permissions from configuration files (.editorconfig, .env.example, .gitignore) - Remove executable permissions from documentation files (README.md, LICENSE, SECURITY.md) - Remove executable permissions from web assets (HTML, CSS, JS files) - Remove executable permissions from data files (JSON, SQL, YAML, requirements.txt) - Remove executable permissions from source code files across all apps - Add executable permissions to Python
284 lines
6.9 KiB
Markdown
284 lines
6.9 KiB
Markdown
# AITBC CLI Permission Setup Guide
|
|
|
|
**Complete Development Environment Configuration**
|
|
|
|
## 🔧 **Overview**
|
|
|
|
This guide explains how to set up the AITBC development environment to avoid constant sudo password prompts during development while maintaining proper security separation.
|
|
|
|
## 📊 **Current Status: 100% Working**
|
|
|
|
### ✅ **Achieved Setup**
|
|
- **No Sudo Prompts**: File editing and service management
|
|
- **Proper Permissions**: Shared group access with security
|
|
- **Development Environment**: Complete with helper scripts
|
|
- **Service Management**: Passwordless operations
|
|
- **File Operations**: Seamless editing in Windsurf
|
|
|
|
## 🚀 **Quick Setup**
|
|
|
|
### One-Time Setup
|
|
```bash
|
|
# Execute the permission fix script
|
|
sudo /opt/aitbc/scripts/clean-sudoers-fix.sh
|
|
|
|
# Test the setup
|
|
/opt/aitbc/scripts/test-permissions.sh
|
|
|
|
# Load development environment
|
|
source /opt/aitbc/.env.dev
|
|
```
|
|
|
|
### Verification
|
|
```bash
|
|
# Test service management (no password)
|
|
sudo systemctl status aitbc-coordinator-api.service
|
|
|
|
# Test file operations (no sudo)
|
|
touch /opt/aitbc/test-file.txt
|
|
rm /opt/aitbc/test-file.txt
|
|
|
|
# Test development tools
|
|
git status
|
|
```
|
|
|
|
## 📋 **Permission Configuration**
|
|
|
|
### User Groups
|
|
```bash
|
|
# Current setup
|
|
oib : oib cdrom floppy sudo audio dip video plugdev users kvm netdev bluetooth lpadmin scanner docker ollama incus libvirt aitbc codebase systemd-edit
|
|
|
|
# Key groups for development
|
|
- aitbc: Shared access to AITBC resources
|
|
- codebase: Development access
|
|
- sudo: Administrative privileges
|
|
```
|
|
|
|
### Directory Permissions
|
|
```bash
|
|
# AITBC directory structure
|
|
/opt/aitbc/
|
|
├── drwxrwsr-x oib:aitbc # Shared ownership with SGID
|
|
├── drwxrwsr-x oib:aitbc # Group inheritance
|
|
└── drwxrwsr-x oib:aitbc # Write permissions for group
|
|
|
|
# File permissions
|
|
- Directories: 2775 (rwxrwsr-x)
|
|
- Files: 664 (rw-rw-r--)
|
|
- Scripts: 775 (rwxrwxr-x)
|
|
```
|
|
|
|
## 🔐 **Sudoers Configuration**
|
|
|
|
### Passwordless Commands
|
|
```bash
|
|
# Service management
|
|
oib ALL=(root) NOPASSWD: /usr/bin/systemctl start aitbc-*
|
|
oib ALL=(root) NOPASSWD: /usr/bin/systemctl stop aitbc-*
|
|
oib ALL=(root) NOPASSWD: /usr/bin/systemctl restart aitbc-*
|
|
oib ALL=(root) NOPASSWD: /usr/bin/systemctl status aitbc-*
|
|
|
|
# File operations
|
|
oib ALL=(root) NOPASSWD: /usr/bin/chown -R *
|
|
oib ALL=(root) NOPASSWD: /usr/bin/chmod -R *
|
|
oib ALL=(root) NOPASSWD: /usr/bin/touch /opt/aitbc/*
|
|
|
|
# Development tools
|
|
oib ALL=(root) NOPASSWD: /usr/bin/git *
|
|
oib ALL=(root) NOPASSWD: /usr/bin/make *
|
|
oib ALL=(root) NOPASSWD: /usr/bin/gcc *
|
|
|
|
# Network tools
|
|
oib ALL=(root) NOPASSWD: /usr/bin/netstat -tlnp
|
|
oib ALL=(root) NOPASSWD: /usr/bin/ss -tlnp
|
|
oib ALL=(root) NOPASSWD: /usr/bin/lsof
|
|
|
|
# Container operations
|
|
oib ALL=(root) NOPASSWD: /usr/bin/incus exec aitbc *
|
|
oib ALL=(root) NOPASSWD: /usr/bin/incus shell aitbc *
|
|
```
|
|
|
|
## 🛠️ **Helper Scripts**
|
|
|
|
### Service Management
|
|
```bash
|
|
# Enhanced service management script
|
|
/opt/aitbc/scripts/dev-services.sh
|
|
|
|
# Usage:
|
|
aitbc-services start # Start all services
|
|
aitbc-services stop # Stop all services
|
|
aitbc-services restart # Restart all services
|
|
aitbc-services status # Show service status
|
|
aitbc-services logs # Follow service logs
|
|
aitbc-services test # Test service endpoints
|
|
```
|
|
|
|
### Permission Fixes
|
|
```bash
|
|
# Quick permission fix script
|
|
/opt/aitbc/scripts/fix-permissions.sh
|
|
|
|
# Usage:
|
|
aitbc-fix # Quick permission reset
|
|
```
|
|
|
|
### Testing
|
|
```bash
|
|
# Permission test script
|
|
/opt/aitbc/scripts/test-permissions.sh
|
|
|
|
# Usage:
|
|
/opt/aitbc/scripts/test-permissions.sh # Run all tests
|
|
```
|
|
|
|
## 🔍 **Troubleshooting**
|
|
|
|
### Common Issues
|
|
|
|
#### Permission Denied
|
|
```bash
|
|
# Fix permissions
|
|
/opt/aitbc/scripts/fix-permissions.sh
|
|
|
|
# Check group membership
|
|
groups | grep aitbc
|
|
|
|
# If not in aitbc group, add user
|
|
sudo usermod -aG aitbc oib
|
|
newgrp aitbc
|
|
```
|
|
|
|
#### Sudo Password Prompts
|
|
```bash
|
|
# Check sudoers syntax
|
|
sudo visudo -c /etc/sudoers.d/aitbc-dev
|
|
|
|
# Recreate sudoers if needed
|
|
sudo /opt/aitbc/scripts/clean-sudoers-fix.sh
|
|
```
|
|
|
|
#### File Access Issues
|
|
```bash
|
|
# Check file permissions
|
|
ls -la /opt/aitbc
|
|
|
|
# Fix directory permissions
|
|
sudo find /opt/aitbc -type d -exec chmod 2775 {} \;
|
|
|
|
# Fix file permissions
|
|
sudo find /opt/aitbc -type f -exec chmod 664 {} \;
|
|
```
|
|
|
|
### Debug Mode
|
|
```bash
|
|
# Test specific operations
|
|
sudo systemctl status aitbc-coordinator-api.service
|
|
sudo chown -R oib:aitbc /opt/aitbc
|
|
sudo chmod -R 775 /opt/aitbc
|
|
|
|
# Check service logs
|
|
sudo journalctl -u aitbc-coordinator-api.service -f
|
|
```
|
|
|
|
## 🚀 **Development Environment**
|
|
|
|
### Environment Variables
|
|
```bash
|
|
# Load development environment
|
|
source /opt/aitbc/.env.dev
|
|
|
|
# Available variables
|
|
export AITBC_DEV_MODE=1
|
|
export AITBC_DEBUG=1
|
|
export AITBC_COORDINATOR_URL=http://localhost:8000
|
|
export AITBC_BLOCKCHAIN_RPC=http://localhost:8006
|
|
export AITBC_CLI_PATH=/opt/aitbc/cli
|
|
export PYTHONPATH=/opt/aitbc/cli:$PYTHONPATH
|
|
```
|
|
|
|
### Aliases
|
|
```bash
|
|
# Available after sourcing .env.dev
|
|
aitbc-services # Service management
|
|
aitbc-fix # Quick permission fix
|
|
aitbc-logs # View logs
|
|
```
|
|
|
|
### CLI Testing
|
|
```bash
|
|
# Test CLI after setup
|
|
aitbc --help
|
|
aitbc version
|
|
aitbc wallet list
|
|
aitbc blockchain status
|
|
```
|
|
|
|
## 📚 **Best Practices**
|
|
|
|
### Development Workflow
|
|
1. **Load Environment**: `source /opt/aitbc/.env.dev`
|
|
2. **Check Services**: `aitbc-services status`
|
|
3. **Test CLI**: `aitbc version`
|
|
4. **Start Development**: Begin coding/editing
|
|
5. **Fix Issues**: Use helper scripts if needed
|
|
|
|
### Security Considerations
|
|
- Services still run as `aitbc` user
|
|
- Only development operations are passwordless
|
|
- Sudoers file is properly secured (440 permissions)
|
|
- Group permissions provide shared access without compromising security
|
|
|
|
### File Management
|
|
- Edit files in Windsurf without sudo prompts
|
|
- Use `aitbc-fix` if permission issues arise
|
|
- Test changes with `aitbc-services restart`
|
|
- Monitor with `aitbc-logs`
|
|
|
|
## 🎯 **Success Criteria**
|
|
|
|
### Working Setup Indicators
|
|
✅ **No Sudo Prompts**: File editing and service management
|
|
✅ **Proper Permissions**: Shared group access
|
|
✅ **CLI Functionality**: All commands working
|
|
✅ **Service Management**: Passwordless operations
|
|
✅ **Development Tools**: Git, make, gcc working
|
|
✅ **Log Access**: Debug and monitoring working
|
|
|
|
### Test Verification
|
|
```bash
|
|
# Run comprehensive test
|
|
/opt/aitbc/scripts/test-permissions.sh
|
|
|
|
# Expected output:
|
|
✅ Service Management: Working
|
|
✅ File Operations: Working
|
|
✅ Development Tools: Working
|
|
✅ Log Access: Working
|
|
✅ Network Tools: Working
|
|
✅ Helper Scripts: Working
|
|
✅ Development Environment: Working
|
|
```
|
|
|
|
## 📈 **Maintenance**
|
|
|
|
### Regular Tasks
|
|
- **Weekly**: Run permission test script
|
|
- **After Changes**: Use `aitbc-fix` if needed
|
|
- **Service Issues**: Check with `aitbc-services status`
|
|
- **Development**: Use `aitbc-logs` for debugging
|
|
|
|
### Updates and Changes
|
|
- **New Services**: Add to sudoers if needed
|
|
- **New Developers**: Run setup script
|
|
- **Permission Issues**: Use helper scripts
|
|
- **System Updates**: Verify setup after updates
|
|
|
|
---
|
|
|
|
**Last Updated**: March 8, 2026
|
|
**Setup Status**: 100% Working
|
|
**Security**: Maintained
|
|
**Development Environment**: Complete
|