Prerequisites¶
This guide covers all the tools and dependencies required to work with the RCIIS DevOps infrastructure.
System Requirements¶
Operating System Support¶
- macOS 10.15 (Catalina) or later
- Homebrew package manager recommended
- Docker Desktop for Mac
- Ubuntu 20.04+ / RHEL 8+ / CentOS 8+ or equivalent
- Docker Engine or Docker Desktop
- 4GB+ RAM, 20GB+ free disk space
- Windows 10/11 with WSL2
- Docker Desktop for Windows
- Git Bash or PowerShell Core
Hardware Requirements¶
- Minimum: 8GB RAM, 4 CPU cores, 50GB free disk space
- Recommended: 16GB RAM, 8 CPU cores, 100GB free disk space
- For production: 32GB+ RAM, 16+ CPU cores, SSD storage
Core Tools Installation¶
1. Python and Poetry¶
Python Installation¶
Poetry Installation¶
2. Container and Kubernetes Tools¶
Docker¶
kubectl¶
Kind (Kubernetes in Docker)¶
3. Package Management Tools¶
Helm¶
curl https://baltocdn.com/helm/signing.asc | gpg --dearmor | sudo tee /usr/share/keyrings/helm.gpg > /dev/null
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/helm.gpg] https://baltocdn.com/helm/stable/debian/ all main" | sudo tee /etc/apt/sources.list.d/helm-stable-debian.list
sudo apt-get update
sudo apt-get install helm
Kustomize¶
4. Secret Management Tools¶
SOPS (Secrets OPerationS)¶
Age (Encryption Tool)¶
KSOPS (Kustomize SOPS Plugin)¶
# Install via script (all platforms)
curl -s https://raw.githubusercontent.com/viaduct-ai/kustomize-sops/master/scripts/install-ksops-archive.sh | bash
# Or install from source (requires Go)
git clone https://github.com/viaduct-ai/kustomize-sops.git
cd kustomize-sops
make install
5. Additional Development Tools¶
Git¶
jq (JSON processor)¶
yq (YAML processor)¶
Development Environment Setup¶
1. Clone the Repository¶
2. Set up Documentation Environment with Poetry¶
# Navigate to docs directory
cd docs
# Install Poetry dependencies
poetry install
# Install with development dependencies
poetry install --with dev,lint
# Activate virtual environment
poetry shell
# Or run commands directly
poetry run mkdocs --version
3. Verify Tool Installation¶
Create a verification script to check all tools:
#!/bin/bash
# verify-tools.sh
echo "🔍 Verifying tool installations..."
tools=(
"python --version"
"poetry --version"
"docker --version"
"kubectl version --client"
"kind version"
"helm version"
"kustomize version"
"sops --version"
"age --version"
"ksops --help"
"git --version"
"jq --version"
"yq --version"
)
for tool in "${tools[@]}"; do
echo -n "Checking $tool: "
if command -v ${tool%% *} >/dev/null 2>&1; then
echo "✅ Installed"
$tool 2>/dev/null | head -1 || echo " Version check failed"
else
echo "❌ Not found"
fi
echo
done
echo "🎉 Tool verification complete!"
# Test Poetry environment
echo "🔍 Testing Poetry documentation environment..."
if cd docs && poetry run mkdocs --version >/dev/null 2>&1; then
echo "✅ Poetry documentation environment working"
cd ..
else
echo "❌ Poetry documentation environment failed"
echo "Run: cd docs && poetry install"
fi
Save this as scripts/verify-tools.sh and run:
4. Configure Git (if not already done)¶
5. Set up GPG/Age Keys for SOPS¶
# Generate Age key for secret encryption
age-keygen -o ~/.config/sops/age/keys.txt
# Display public key for sharing with team
age-keygen -y ~/.config/sops/age/keys.txt
Documentation Development Setup¶
Poetry Commands for Documentation¶
# Navigate to docs directory first
cd docs
# Install dependencies
poetry install
# Serve documentation locally
poetry run mkdocs serve
# Build documentation
poetry run mkdocs build
# Run with specific Python version
poetry env use python3.11
# Add new documentation dependency
poetry add mkdocs-new-plugin
# Add development dependency
poetry add --group dev pytest
# Update dependencies
poetry update
# Show dependency tree
poetry show --tree
# Export requirements.txt (if needed for CI)
poetry export -f requirements.txt --output requirements.txt
Poetry Configuration¶
# Configure Poetry (optional)
poetry config virtualenvs.in-project true # Create .venv in project dir
poetry config virtualenvs.prefer-active-python true
# View configuration
poetry config --list
# Show virtual environment info
poetry env info
IDE and Editor Setup¶
Visual Studio Code Extensions¶
{
"recommendations": [
"ms-kubernetes-tools.vscode-kubernetes-tools",
"redhat.vscode-yaml",
"ms-vscode.vscode-json",
"signageos.signageos-vscode-sops",
"tim-koehler.helm-intellisense",
"ms-azuretools.vscode-docker",
"ms-python.python",
"ms-python.poetry"
]
}
JetBrains IDEs Plugins¶
- Kubernetes
- Helm
- Docker
- YAML/Ansible Support
- Poetry
Troubleshooting Common Issues¶
Poetry Issues¶
# Clear Poetry cache
poetry cache clear --all pypi
# Reinstall dependencies
poetry install --no-cache
# Fix virtual environment issues
poetry env remove python
poetry install
# Update Poetry itself
poetry self update
Docker Permission Issues (Linux)¶
# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker
# Or run with sudo (not recommended for development)
sudo docker --version
kubectl Context Issues¶
# List available contexts
kubectl config get-contexts
# Set default context
kubectl config use-context kind-local-cluster
KSOPS Installation Issues¶
# Verify KSOPS is in PATH
which ksops
# Manually copy to PATH if needed
sudo cp ksops /usr/local/bin/
sudo chmod +x /usr/local/bin/ksops
Age Key Permission Issues¶
Documentation Development Workflow¶
Quick Start with Poetry¶
# Navigate to docs directory
cd docs
# Set up documentation environment
poetry install
# Start development server
poetry run mkdocs serve
# Open browser to http://127.0.0.1:8000
# Make changes to documentation files
# Changes will auto-reload in browser
# Build for production
poetry run mkdocs build
Adding New Dependencies¶
# Add new MkDocs plugin
poetry add mkdocs-new-plugin
# Add development tool
poetry add --group dev black
# Add linting tool
poetry add --group lint flake8
Next Steps¶
Once you have all prerequisites installed:
- Local Development Setup - Create your first local cluster
- Quick Start Guide - Deploy your first application
- Architecture Overview - Understand the system design
Poetry Benefits
Poetry provides dependency resolution, lock files, and virtual environment management out of the box. It ensures reproducible builds across different environments.
Security Note
Never commit Age private keys or other secrets to version control. Use SOPS encryption for all sensitive data.