CLI_INTEGRATION

nself CLI Integration Guide

Overview

nself-admin is designed as an optional web-based administration interface for the nself CLI backend stack. It runs as a Docker container alongside your nself services, providing real-time monitoring, configuration management, and service control through an intuitive web interface.

Installation Methods

1. Using nself CLI (Recommended)

The nself CLI will automatically detect and install the admin interface:

# Install admin interface with default settings
nself admin install

# Install specific version
nself admin install --version 1.0.0-beta.3

# Install with custom port
nself admin install --port 3021

# Update existing installation
nself admin update

2. Manual Docker Installation

# Run standalone
docker run -d \
  --name nself-admin \
  --restart unless-stopped \
  -p 3021:3021 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $(pwd):/project \
  -e ADMIN_PASSWORD=your-secure-password \
  nself/admin:latest

# Using docker-compose
wget https://raw.githubusercontent.com/nself-org/admin/main/docker-compose.nself-admin.yml
docker-compose -f docker-compose.nself-admin.yml up -d

3. Integration with Existing nself Stack

Add to your existing docker-compose.override.yml:

services:
  admin:
    image: nself/admin:latest
    container_name: nself-admin
    restart: unless-stopped
    ports:
      - '3021:3021'
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./:/project:rw
    environment:
      - ADMIN_PASSWORD=${ADMIN_PASSWORD}
      - AUTO_UPDATE=true
    networks:
      - nself-network
    labels:
      - 'traefik.enable=true'
      - 'traefik.http.routers.admin.rule=Host(`admin.${BASE_DOMAIN}`)'

Configuration

Environment Variables

Variable	Description	Default
ADMIN_PASSWORD	Admin interface password	(required)
ADMIN_PORT	Port to expose admin interface	3021
PROJECT_PATH	Path to nself project	/project
AUTO_UPDATE	Enable automatic updates	true
UPDATE_CHECK_INTERVAL	Hours between update checks	6
NODE_ENV	Environment mode	production
TZ	Timezone	UTC

Volume Mounts

Mount Point	Description	Required
/var/run/docker.sock	Docker socket for container management	Yes
/project	Your nself project directory	Yes
/data	Persistent data storage	No

Features

Core Functionality

• Dashboard: Real-time metrics and service status overview
• Service Management: Start, stop, restart, and monitor containers
• Configuration Editor: Edit environment variables across environments
• Database Console: PostgreSQL management and query execution
• Log Viewer: Real-time log streaming from all services
• Health Monitoring: Service health checks and alerts
• Auto-Updates: Automatic version updates with rollback support

Security

• Password-protected access
• Read-only Docker socket access by default
• Isolated container environment
• No external dependencies

API Endpoints

The admin interface exposes several API endpoints for integration:

Health & Status

• GET /api/health - Health check endpoint
• GET /api/version - Version information
• GET /api/project/status - Project status

Service Management

• GET /api/docker/containers - List containers
• POST /api/docker/containers/{id}/start - Start container
• POST /api/docker/containers/{id}/stop - Stop container
• POST /api/docker/containers/{id}/restart - Restart container

Configuration

• GET /api/config/env - Get environment configuration
• POST /api/config/env - Update environment configuration

Updates

• GET /api/version - Check for updates
• POST /api/version - Perform update

CLI Commands

The nself CLI provides commands for managing the admin interface:

# Install admin interface
nself admin install

# Check admin status
nself admin status

# View admin logs
nself admin logs

# Update admin interface
nself admin update

# Remove admin interface
nself admin remove

# Open admin interface in browser
nself admin open

Plugin Commands (v0.4.8+)

nself Admin v0.0.8 wraps the CLI plugin system with a visual UI. These are the CLI commands executed by the Admin API:

nself Admin Action	CLI Command Executed
View plugins page	nself plugin list
Install plugin button	nself plugin install <name>
Remove plugin button	nself plugin remove <name>
Sync button	nself plugin <name> sync
View plugin status	nself plugin status <name>

Full CLI docs: See nself CLI for complete plugin command reference.

Database Commands (v0.4.8+)

nself Admin v0.0.8 wraps database operations. These are the CLI commands executed by the Admin API:

nself Admin Action	CLI Command Executed
Create backup button	nself db backup create
Backup list	nself db backup list
Restore button	nself db restore <file>
Run migrations	nself db migrate up
View migration status	nself db migrate status
Execute SQL query	nself db query "<sql>"
Schema browser	nself db inspect

Full CLI docs: See nself CLI for complete database command reference.

Versioning

The admin interface follows semantic versioning:

• Major: Breaking changes to API or configuration
• Minor: New features, backwards compatible
• Patch: Bug fixes and minor improvements
• Beta/Alpha: Pre-release versions for testing

Current stable version: 1.0.0-beta.3

Docker Image Tags

Tag	Description
latest	Latest stable release
1.0.0-beta.3	Specific version
1.0	Latest 1.0.x version
beta	Latest beta release
dev	Development build (unstable)

Platform Support

Multi-architecture Docker images are available for:

• linux/amd64 - Standard x86_64
• linux/arm64 - ARM 64-bit (Apple Silicon, AWS Graviton)
• linux/arm/v7 - ARM 32-bit (Raspberry Pi)

Troubleshooting

Container won't start

# Check logs
docker logs nself-admin

# Verify Docker socket access
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  alpine sh -c "apk add docker && docker ps"

# Check port availability
lsof -i :3021

Cannot access interface

# Check container status
docker ps | grep nself-admin

# Test health endpoint
curl http://localhost:3021/api/health

# Check firewall rules
sudo iptables -L | grep 3021

Update issues

# Manual update
docker pull nself/admin:latest
docker stop nself-admin
docker rm nself-admin
# Re-run installation command

# Force specific version
docker run -d \
  --name nself-admin \
  -e ADMIN_VERSION=1.0.0-beta.3 \
  nself/admin:1.0.0-beta.3

Development

Building from source

# Clone repository
git clone https://github.com/nself-org/admin.git
cd nself-admin

# Install dependencies
npm install

# Development mode
npm run dev

# Build Docker image
npm run docker:build

# Run tests
npm test

Contributing

1. Fork the repository
2. Create feature branch
3. Make changes and test
4. Submit pull request

Support

• GitHub Issues: https://github.com/nself-org/admin/issues
• Documentation: https://docs.nself.org/admin
• the community chat: https://chat.nself.org

License

nself-admin is part of the nself ecosystem. See LICENSE file for details.