My Nethesis

Documentation

CI and Tests

CI Pipeline:

Backend:

Collect:

Sync:

Frontend:

Proxy:

Release

Production and QA

Web application providing centralized authentication and management using Logto as an Identity Provider with simple Role-Based Access Control.

🏗️ Components

• frontend/ - Vue.js application for UI
• backend/ - Go REST API with Logto JWT authentication and RBAC
• collect/ - Go REST API with Redis queues to handle inventories
• sync/ - CLI tool for RBAC configuration synchronization
• proxy/ - nginx configuration as load balancer

🚀 Quick Start

Requirements

• Development: Go 1.21+ (backend requires 1.23+), Node.js, Make
• Containers: Docker OR Podman (optional, for full infrastructure)
• External: Logto instance with M2M app and Management API permissions
• Deploy: Render account with GitHub integration

Development Setup

Choose your preferred development approach:

Option 1: Full Infrastructure (Recommended)

Complete replica of the production environment with all services containerized:

# Start all services (PostgreSQL, Redis, Backend, Collect, Frontend, Proxy)
docker-compose up -d
# OR
podman-compose up -d

# Access the application at: http://localhost:9090

All URLs and management commands are documented in the docker-compose.yml header.

Option 2: Individual Components

Start services individually for targeted development:

# Start shared databases (PostgreSQL + Redis)
cd backend && make dev-up

# Start individual services in separate terminals:
cd backend && make run          # Backend API on :8080
cd collect && make run          # Collect service on :8081
cd frontend && npm run dev      # Frontend on :5173

# Use sync tool as needed:
cd sync && make run-example

Getting Started

1. RBAC Setup: sync/README.md - Use sync init for complete Logto configuration
2. Frontend Development: frontend/README.md - Vue.js setup and environment configuration
3. Backend Development: backend/README.md - Backend setup and environment configuration
4. Collect Development: collect/README.md - Collect setup and environment configuration
5. Production Deploy: Use ./deploy.sh for automated deployment

🌐 Deployment Environments

QA (qa.my.nethesis.it)

• Trigger: Every commit to main branch
• Auto-deploy: Immediate deployment via Render
• PR Previews: Temporary environments for pull requests

Production (my.nethesis.it)

• Trigger: Manual deployment via ./deploy.sh script
• Auto-Deploy: Render automatically deploys when render.yaml is updated
• Manual Control: Deploy only when explicitly triggered
• Security: Private services (Backend, Collect, Frontend) only accessible through Proxy

📝 Configuration

Local Development

See individual component documentation for setup:

• Fronted: frontend/README.md - Environment variables and setup for frontend
• Backend: backend/README.md - Environment variables and setup for backend
• Collect: collect/README.md - Environment variables and setup for collect
• sync CLI: sync/README.md - Use sync init to generate all required variables
• proxy: proxy/README.md - nginx configuration and setup for load balancer

Production Deployment

• Environment Variables: Configured in Render dashboard
• Service Configuration: Defined in render.yaml
• Deployment: Use ./deploy.sh script for automated deployment

📚 Documentation

👥 User Documentation

Live User Guide: https://nethserver.github.io/my/

Complete guides for end users and administrators:

• Getting Started - Authentication, login, and profile management
• Organizations - Create and manage business hierarchy
• Users - User creation, roles, and permissions
• User Impersonation - Consent-based impersonation for troubleshooting
• Systems - System creation and monitoring
• Registration - System registration workflow
• Inventory & Heartbeat - Data collection and monitoring

💻 Developer Documentation

Component-specific technical documentation:

• frontend - UI setup, environment variables, and pages
• backend - Server setup, environment variables, authorization architecture, and consent-based impersonation
• backend OpenAPI - Complete API specification with authentication
• collect - Server setup, environment variables and inventory structure
• sync CLI - RBAC configuration and sync init setup
• deploy script - Production deployment script for Render
• proxy - Production load balancer configuration with nginx
• DESIGN.md - Architecture decisions and design patterns

📖 API Documentation

Live API Docs: https://bump.sh/nethesis/doc/my - auto-updated on every commit.

🚀 Building Documentation Locally

To preview the user documentation locally:

# Install MkDocs and dependencies
pip install mkdocs-material mkdocs-minify-plugin

# Serve locally (with hot reload)
mkdocs serve

# Build static site
mkdocs build

# Deploy to GitHub Pages
mkdocs gh-deploy

The documentation is automatically deployed to GitHub Pages on every push to the main branch.

🤝 Development Workflow

Standard Development

git commit -m "feat: new feature"
git push origin main                    # → qa.my.nethesis.it updates

Feature Testing

git checkout -b feature/new-feature
git push origin feature/new-feature     # → Create PR
# → my-proxy-qa-pr-123.onrender.com created

Production Release

# Automated release with quality checks
./release.sh patch                       # → 0.0.5 → 0.0.6 (bug fixes)
./release.sh minor                       # → 0.0.5 → 0.1.0 (new features)
./release.sh major                       # → 0.0.5 → 1.0.0 (breaking changes)
# → Runs tests, formatting, linting → Creates tag → Pushes to GitHub

The release script will:

1. Run all quality checks (formatting, linting, tests)
2. Bump version in all files
3. Create git commit and tag
4. Push to GitHub
5. Trigger GitHub Actions to build and publish Docker images

Production Deployment

# Standard deployment with image verification
./deploy.sh

# Fast deployment without image verification (less safe but faster)
./deploy.sh --skip-verify

# Show help
./deploy.sh --help

The deployment script will:

1. Get the latest git tag automatically
2. Show the tag and ask for confirmation
3. Verify Docker images exist on ghcr.io (unless --skip-verify)
4. Update render.yaml with new image tags
5. Commit changes with your git user info
6. Push to main branch
7. Render automatically deploys the updated services

Example output:

ℹ️  Latest git tag: v0.1.5
Do you want to deploy v0.1.5 to production? [y/N] y
✅ All Docker images verified successfully
✅ render.yaml updated successfully
✅ Changes committed and pushed to main branch
✅ Deployment initiated successfully!

🤝 Contributing

1. Follow existing code patterns and conventions
2. Pre-commit: Run make pre-commit in both directories
3. Test RBAC changes with --dry-run before applying
4. Ensure CI tests pass before submitting PRs

📄 License

See LICENSE file for details.