Getting Started: System Administrators

Getting Started: System Administrators

This guide covers ADEPT deployment, user management, and operational maintenance.

---

Prerequisites

• Linux host (Rocky Linux 9 / Ubuntu 22.04+)
• Docker Engine 24+ with Compose v2
• 32GB RAM minimum (64GB for full ML stack)
• Ansible 2.14+ (for automated deployment)
• SSL certificates (self-signed or CA-issued)

---

Deployment Options

Target	Tooling	Time to Deploy
Single VM (Docker Compose)	make start	~5 minutes
AWS EC2	CDK provisioning + Ansible OS prep	~30 minutes
AWS EKS	Helm chart	~20 minutes
Azure AKS	Pulumi + Helm chart	~20 minutes
Bare metal cluster	Ansible playbooks	~45 minutes

---

Quick Deployment (Single VM)

# Clone and configure
git clone https://github.com/pnnl/adept-agentic.git
cd adept-agentic
cp .env.example .env

# Edit .env:
# - Set LLM API keys (AZURE_API_KEY, AWS_ACCESS_KEY_ID, etc.)
# - Set KEYCLOAK_ADMIN_PASSWORD
# - Set POSTGRES_PASSWORD

# Start (25 services)
make start

# Verify all services healthy
make validate-service-health
make validate-comprehensive-health

---

User Management (Keycloak)

Default Users

Username	Role	Purpose
admin	admin group	Platform administration
notebook-user	notebook-users group	JupyterLab access
streamlit-user	notebook-users group	Streamlit chat access

Create New Users

Users are managed via Keycloak Admin Console at https://<host>/auth/.

Alternatively, use the bootstrap script:

make fix-credentials  # Regenerates all service accounts and creates default users

Groups and RBAC

Group	Permissions
admin	Full platform access, tool management, user administration
notebook-users	Chat, file operations, scientific tools
gateway-service	Service-to-service communication (internal)

Tool access is controlled by ACL rules mapped to Keycloak groups.

---

Credential Management

# Generate/regenerate all service credentials
make fix-credentials

# Sync credentials to test runners
make sync-credentials

# Validate credentials are working
make validate-credentials

Credentials are stored in deployment/local/docker-compose/.env-keycloak-credentials-dir/.

---

Service Management

# Lifecycle
make start       # Start all services
make stop        # Stop services
make restart     # Restart services
make rebuild     # Full rebuild (no cache)
make teardown    # Remove containers + volumes

# Individual service rebuilds
make rebuild-gateway
make rebuild-orchestrator
make rebuild-registry

# Health monitoring
make validate-service-health
make validate-comprehensive-health

# Logs
docker logs orchestration_service --tail 50 --since 5m
docker logs agent_gateway --tail 50 --since 5m

---

SSL/TLS Configuration

ADEPT uses nginx as a TLS termination proxy. Self-signed certificates are generated during first startup.

For production, replace certificates in:

infra/nginx/certs/
  api.agentic.local.crt
  api.agentic.local.key

Then restart nginx:

docker compose restart nginx_proxy

---

Backup and Recovery

PostgreSQL (State)

# Backup
docker exec postgres pg_dump -U admin -d agentic_framework > backup_$(date +%Y%m%d).sql

# Restore
docker exec -i postgres psql -U admin -d agentic_framework < backup_20260529.sql

Redis (Cache)

Redis data is ephemeral (tool configs, session metadata). It rebuilds on restart via service initialization.

Volumes

Critical volumes to back up:

• postgres_data -- All conversation state, checkpoints, assistants
• shared_uploads -- User-uploaded files
• chromadb_data -- RAG vector indexes

---

Monitoring

Langfuse (Observability)

Access at https://<host>/langfuse/ for:

• LLM token usage and cost tracking
• Trace visualization
• Session instrumentation

Health Checks

All services expose health endpoints checked by Docker's built-in healthcheck mechanism:

docker ps --format "table {{.Names}}\t{{.Status}}" | grep -v healthy

---

Security Operations

ASOPB Scanning

Run the security scanner against the deployment:

make stage
make docker-scan-staged

Sandbox Security

The sandbox runs code in isolated containers with:

• Import validation (blacklist/whitelist)
• Network isolation (configurable)
• No Docker socket access (default)
• Configurable privileged mode

---

Troubleshooting

Issue	Resolution
Services not starting	Check .env configuration, run make validate-service-health
Authentication failures	Run make fix-credentials then make sync-credentials
Port conflicts	Check port mappings (8083=gateway, 8084=orchestration, 8086=registry)
Out of disk space	Check Docker volumes: docker system df
Credential drift	Run make fix-credentials after Keycloak restarts

---

Further Reading

• Local Development (Docker Compose)
• Security Model
• Kubernetes and Helm