SERVER MANAGEMENT - nself-org/cli GitHub Wiki
Command: nself deploy server and nself deploy sync
Comprehensive server management, initialization, diagnostics, and environment synchronization for nself deployments.
Complete documentation for the 10 newly implemented deploy server management features.
The nself deploy server and nself deploy sync commands provide comprehensive server management, initialization, diagnostics, and environment synchronization.
Purpose: Initialize a fresh VPS server for nself deployment with complete automation.
Usage:
nself deploy server init <host> [options]
nself deploy server init [email protected] --domain example.comOptions:
-
--host, -h- Server hostname or IP -
--user, -u- SSH user (default: root) -
--port, -p- SSH port (default: 22) -
--key, -k- SSH private key file -
--domain, -d- Domain for SSL setup -
--env, -e- Environment name (default: prod) -
--skip-ssl- Skip SSL certificate setup -
--skip-dns- Skip DNS fallback configuration -
--yes, -y- Skip confirmation prompts
What It Does:
Phase 1: System Setup
- Updates system packages (apt-get or yum)
- Installs Docker and Docker Compose from official repositories
- Enables and starts Docker service
- Verifies installation
Phase 2: Security Configuration
- Installs and configures UFW firewall
- Denies all incoming by default
- Allows SSH, HTTP (80), HTTPS (443)
- Installs and configures fail2ban
- Protects against SSH brute force
- 5 retries, 1-hour ban, 10-minute window
- Hardens SSH configuration
- Disables password authentication
- Enables public key authentication only
- Disables X11 forwarding
Phase 3: nself Environment
- Creates
/var/www/nselfdirectory structure - Creates backup and log directories
- Configures DNS fallback (Cloudflare, Google DNS)
- Sets up SSL if domain provided and resolves
- Creates environment marker file
Example:
# Basic initialization
nself deploy server init [email protected]
# With domain for SSL
nself deploy server init [email protected] --domain example.com
# Non-interactive for automation
nself deploy server init [email protected] --domain example.com --yes
# Custom SSH port and key
nself deploy server init [email protected] --port 2222 --key ~/.ssh/deploy_keyOutput:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ nself deploy server init โ
โ Initialize VPS for nself deployment โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Server Configuration
Host: server.example.com
User: root
Port: 22
Domain: example.com
Env: prod
This will:
1. Update system packages
2. Install Docker and Docker Compose
3. Configure firewall (UFW)
4. Setup fail2ban for SSH protection
5. Configure DNS fallback (optional)
6. Setup Let's Encrypt SSL (optional)
Continue? [y/N]:
Purpose: Verify a server is ready for nself deployment with 8 comprehensive checks.
Usage:
nself deploy server check <host>
nself deploy server check user@host:portChecks Performed:
- SSH Connectivity - Can connect to server
- Docker Installation - Docker is installed and version
- Docker Service - Docker daemon is running
- Docker Compose - Compose plugin is available
- Disk Space - Available disk space and usage percentage
- Memory - Total and available RAM
- Firewall - UFW status (active/inactive)
- Required Ports - Ports 80 and 443 availability
Example:
nself deploy server check [email protected]Output:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ nself deploy server check โ
โ Verify server readiness for deployment โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
[1/8] SSH Connectivity... PASS
[2/8] Docker Installation... PASS (v24.0.7)
[3/8] Docker Service... PASS
[4/8] Docker Compose... PASS (v2.23.0)
[5/8] Disk Space... PASS (45G available, 15% used)
[6/8] Memory... PASS (4.0G total, 3.2G available)
[7/8] Firewall... PASS (active)
[8/8] Required Ports (80, 443)... PASS (available)
Check Summary
Passed: 8/8
โ Server is ready for deployment
Status Codes:
- PASS (green) - Check passed
- WARN (yellow) - Warning, not critical
- FAIL (red) - Check failed
Recommendations:
- 8/8 passed: Ready for deployment
- 6-7 passed: Mostly ready (warnings)
- <6 passed: Not ready, run
server init
Purpose: Quick status check of all configured remote servers.
Usage:
nself deploy server statusWhat It Shows:
- All environments with server configurations
- Connection status (online/offline)
- Server uptime if online
- Summary statistics
Example:
nself deploy server statusOutput:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ nself deploy server status โ
โ Check server connectivity โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
staging โ ONLINE up 2 days, 5 hours
production โ ONLINE up 15 days, 3 hours
backup โ OFFLINE [email protected]:22
Total: 3 server(s), 2 online, 1 offline
Indicators:
-
โ(green) - Server is online and reachable -
โ(red) - Server is offline or unreachable
Purpose: Comprehensive server diagnostics with detailed network and system information.
Usage:
nself deploy server diagnose <environment>Diagnostics Performed:
Network Diagnostics:
- DNS Resolution - Resolves hostname to IP
- ICMP Ping - Network reachability and latency
- Port 22 (SSH) - SSH port accessibility
- Port 80 (HTTP) - HTTP port availability
- Port 443 (HTTPS) - HTTPS port availability
SSH Connection Test:
- Attempts SSH connection
- Retrieves server information if successful
Server Information (if connected):
- Hostname
- Operating system
- Kernel version
- Uptime and load average
- Memory capacity
- Docker version
Example:
nself deploy server diagnose prodOutput:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ nself deploy server diagnose โ
โ Full server diagnostics โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Environment: prod
Host: server.example.com
User: root
Port: 22
Network Diagnostics
[1/5] DNS Resolution... OK โ 192.168.1.100
[2/5] ICMP Ping... OK (15.3 ms)
[3/5] Port 22 (SSH)... OPEN
[4/5] Port 80 (HTTP)... OPEN
[5/5] Port 443 (HTTPS)... OPEN
SSH Connection Test
Attempting SSH connection... SUCCESS
Server Information
hostname: prod-server-01
os: ubuntu
kernel: 5.15.0-91-generic
uptime: up 2 days, 5 hours
load: 0.15, 0.20, 0.18
memory: 4.0G
docker: 24.0.7
โ Diagnostics complete
Recommendations (if connection fails):
- Verify SSH key authorization
- Check SSH is running on correct port
- Ensure firewall allows SSH
- Try manual connection command
Purpose: List all configured servers across environments.
Usage:
nself deploy server listInformation Shown:
- Environment name
- Server hostname
- SSH user
- SSH port
- Connection status (online/offline)
Example:
nself deploy server listOutput:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ nself deploy server โ
โ Server List โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
NAME HOST USER PORT STATUS
--------------- ------------------------- ---------- ---------- ----------
staging staging.example.com deploy 22 online
production prod.example.com root 22 online
backup backup.example.com root 2222 offline
Total: 3 server(s)
Status Indicator:
- Quick connectivity check (2-second timeout)
- Shows online/offline status
- Color-coded: green (online), red (offline)
Purpose: Add or update server configuration for an environment.
Usage:
nself deploy server add <name> --host <host> [options]Options:
-
--host, -h- Server hostname or IP (required) -
--user, -u- SSH user (default: root) -
--port, -p- SSH port (default: 22) -
--key, -k- SSH private key file path -
--path- Deployment path (default: /var/www/nself)
What It Does:
- Creates environment directory if it doesn't exist
- Creates or updates
server.jsonconfiguration - Stores SSH connection details
- Records creation timestamp
Example:
# Basic server addition
nself deploy server add staging --host staging.example.com
# With custom user and port
nself deploy server add prod --host prod.example.com --user deploy --port 2222
# With SSH key
nself deploy server add prod --host prod.example.com --key ~/.ssh/production_key
# With custom deploy path
nself deploy server add staging --host staging.example.com --path /opt/myappOutput:
โ Server added: staging
Server details:
Host: staging.example.com
User: root
Port: 22
Deploy path: /var/www/nself
โน Test connection with: nself deploy server check staging
server.json Format:
{
"name": "staging",
"type": "remote",
"host": "staging.example.com",
"port": 22,
"user": "root",
"key": "",
"deploy_path": "/var/www/nself",
"description": "Remote server configuration",
"created_at": "2026-01-30T12:34:56Z"
}Purpose: Remove server configuration from an environment.
Usage:
nself deploy server remove <name> [--force]Options:
-
--force, -f- Skip confirmation prompt
What It Does:
- Removes
server.jsonconfiguration - Preserves environment directory and .env files
- Requires confirmation unless
--forceused
Safety:
- Does NOT delete remote server data
- Does NOT delete local environment directory
- Only removes server configuration
Example:
# Remove with confirmation
nself deploy server remove old-server
# Remove without confirmation
nself deploy server remove old-server --forceOutput:
This will remove server configuration:
Name: old-server
Host: old.example.com
WARNING: This will NOT delete the environment or remote data
Only the server.json configuration will be removed
Are you sure? [y/N]: y
โ Server configuration removed: old-server
โน The environment directory still exists at: .environments/old-server
โน To completely remove the environment, use: nself env delete old-server
Purpose: Quick SSH connection to a configured server or execute remote commands.
Usage:
# Interactive SSH session
nself deploy server ssh <name>
# Execute remote command
nself deploy server ssh <name> <command>Features:
- Uses stored SSH configuration (host, user, port, key)
- Supports interactive sessions
- Supports command execution
- Automatically applies correct SSH options
Example:
# Connect interactively
nself deploy server ssh staging
# Execute remote command
nself deploy server ssh staging "docker ps"
# Check disk space
nself deploy server ssh prod "df -h"
# View logs
nself deploy server ssh staging "tail -f /var/log/nginx/access.log"Output (interactive):
โน Connecting to staging ([email protected]:22)...
root@staging:~#
Output (command execution):
โน Executing on staging: docker ps
CONTAINER ID IMAGE STATUS PORTS
a1b2c3d4e5f6 nginx:latest Up 2 days 80/tcp, 443/tcp
Purpose: Display comprehensive information about a configured server.
Usage:
nself deploy server info <name>Information Shown:
- Connection Details: Host, user, port, SSH key, deploy path
- Connectivity Test: Real-time SSH connection test
- Remote System Info: Hostname, OS, kernel, CPU, memory, disk, uptime
- Deployment Status: Whether nself is deployed, container counts
- Quick Actions: Common commands for this server
Example:
nself deploy server info prodOutput:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ nself deploy server info โ
โ Server Details: prod โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Connection Details
Name: prod
Host: prod.example.com
User: root
Port: 22
Type: remote
SSH Key: ~/.ssh/production_key
Deploy Path: /var/www/nself
Description: Production server
Connectivity
Testing SSH connection... CONNECTED
Remote System Information
hostname: prod-server-01
os: Ubuntu 22.04.3 LTS
kernel: 5.15.0-91-generic
arch: x86_64
cpu_cores: 4
memory: 8.0G
disk_root: 50G
disk_avail: 38G
uptime: up 15 days, 3 hours
docker: 24.0.7
compose: 2.23.0
Deployment Status
Status: Deployed
Containers: 24/24 running
Quick Actions
Connect: nself deploy server ssh prod
Diagnose: nself deploy server diagnose prod
Deploy: nself deploy prod
Comprehensive environment synchronization between local and remote servers.
Purpose: Pull configuration files from remote environment to local.
Usage:
nself deploy sync pull <environment> [options]Options:
-
--dry-run- Preview without making changes -
--force, -f- Skip confirmation prompt
What It Pulls:
-
.env- Environment configuration -
.env.secrets- Secret credentials -
docker-compose.yml- Docker configuration
Example:
# Pull from staging
nself deploy sync pull staging
# Dry run first
nself deploy sync pull staging --dry-run
# Force without confirmation
nself deploy sync pull prod --forceOutput:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ nself deploy sync pull โ
โ Pull configuration from staging โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Sync Configuration
Source: [email protected]:/var/www/nself
Destination: .environments/staging
โ Connected
Files to Pull
- .env
- .env.secrets
- docker-compose.yml
This will overwrite local files. Continue? [y/N]: y
โน Pulling files...
Pulling .env... OK
Pulling .env.secrets... OK
Pulling docker-compose.yml... OK
โ Sync complete: staging โ local
โน Files synced to: .environments/staging
Purpose: Push configuration files from local to remote environment.
Usage:
nself deploy sync push <environment> [options]Options:
-
--dry-run- Preview without making changes -
--force, -f- Skip confirmation prompt
What It Pushes:
-
.env- Environment configuration -
.env.secrets- Secret credentials (with chmod 600)
Safety:
- Shows warning for production environments
- Requires confirmation unless
--force - Sets proper permissions on secrets
Example:
# Push to staging
nself deploy sync push staging
# Dry run first
nself deploy sync push staging --dry-run
# Force without confirmation
nself deploy sync push staging --forceOutput:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ nself deploy sync push โ
โ Push configuration to staging โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Sync Configuration
Source: .environments/staging
Destination: [email protected]:/var/www/nself
โ Connected
Files to Push
- .env
- .env.secrets
This will overwrite remote files. Continue? [y/N]: y
โน Pushing files...
Pushing .env... OK
Pushing .env.secrets... OK
โ Sync complete: local โ staging
โน Files synced to: [email protected]:/var/www/nself
Purpose: Show synchronization status for all environments.
Usage:
nself deploy sync statusInformation Shown:
- Environment name
- Sync status (synced/not synced)
- Last sync timestamp
- Files status (complete/partial/missing)
Example:
nself deploy sync statusOutput:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ nself deploy sync โ
โ Synchronization Status โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
ENVIRONMENT STATUS LAST SYNC FILES
--------------- ---------- ------------------------- ----------
staging synced 2026-01-30T14:23:15Z complete
production synced 2026-01-28T09:15:43Z complete
backup not synced never partial
Legend:
complete - .env and .env.secrets present
partial - only .env present
missing - configuration files missing
โน Sync files between environments:
Pull: nself deploy sync pull <environment>
Push: nself deploy sync push <environment>
Purpose: Perform complete synchronization including configs, services, and restart.
Usage:
nself deploy sync full <environment> [options]Options:
-
--dry-run- Preview without making changes -
--force, -f- Skip confirmation prompt -
--no-rebuild- Skip service restart
What It Syncs:
- Environment files (.env, .env.secrets)
- Docker Compose configuration
- Nginx configuration directory
- Custom services directory
- Restarts services on remote (optional)
Example:
# Full sync to staging
nself deploy sync full staging
# Dry run first
nself deploy sync full staging --dry-run
# Sync without restart
nself deploy sync full staging --no-rebuild
# Force sync
nself deploy sync full prod --forceOutput:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ nself deploy sync full โ
โ Full synchronization to staging โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Full Sync Plan
1. Sync environment files (.env, .env.secrets)
2. Sync docker-compose.yml and configs
3. Sync nginx configuration
4. Sync custom services
5. Restart services on remote
This will perform a full sync to staging. Continue? [y/N]: y
โ Connected
Step 1: Environment Files
Syncing .env... OK
Syncing .env.secrets... OK
Step 2: Docker Configuration
Syncing docker-compose.yml... OK
Step 3: Nginx Configuration
Syncing nginx directory... OK
Step 4: Custom Services
Syncing services directory... OK
Step 5: Restart Services
Restarting services on remote... OK
โ Full sync complete: 5 file(s) synced
โน Next: nself deploy staging
# 1. Initialize the server
nself deploy server init [email protected] --domain example.com --yes
# 2. Create production environment locally
nself env create prod
# 3. Add server configuration
nself deploy server add prod --host prod.example.com
# 4. Generate production secrets
nself config secrets generate --env prod
# 5. Build for production
nself build --env prod
# 6. Push configuration to server
nself deploy sync push prod
# 7. Deploy to production
nself deploy prod# Quick status of all servers
nself deploy server status
# Detailed check of specific server
nself deploy server check [email protected]
# Full diagnostics for environment
nself deploy server diagnose prod
# Get comprehensive server info
nself deploy server info prod# Check sync status
nself deploy sync status
# Pull staging config to local
nself deploy sync pull staging
# Edit local files
vim .environments/staging/.env
# Push changes back to staging
nself deploy sync push staging
# Full sync including services
nself deploy sync full staging# Interactive SSH
nself deploy server ssh prod
# Execute remote command
nself deploy server ssh prod "docker ps"
# View logs
nself deploy server ssh staging "tail -f /var/log/nginx/error.log"
# Check disk space
nself deploy server ssh prod "df -h"- Disables password authentication (key-only)
- Enables UFW firewall with strict rules
- Configures fail2ban for SSH protection
- Hardens SSH configuration
-
.env.secretsautomatically set to chmod 600 - Never synced to version control
- Encrypted in transit via SSH
- Production warnings on push operations
- Keys stored in server.json configuration
- Keys are gitignored by default
- Use separate keys per environment
- Store keys securely (encrypted volume)
Problem: "Cannot connect to server"
# Check DNS resolution
host server.example.com
# Check network connectivity
ping server.example.com
# Check port accessibility
nc -zv server.example.com 22
# Full diagnostics
nself deploy server diagnose prodProblem: "Permission denied (publickey)"
# Verify SSH key is specified
nself deploy server info prod
# Test SSH manually
ssh -i ~/.ssh/key [email protected]
# Add key to server
ssh-copy-id -i ~/.ssh/key.pub [email protected]Problem: "Files not found on remote"
# Check if deployed
nself deploy server ssh prod "ls -la /var/www/nself"
# Create directory structure
nself deploy server init [email protected]
# Try full sync
nself deploy sync full prodProblem: "Permission denied during sync"
# Check SSH key permissions
chmod 600 ~/.ssh/deploy_key
# Check remote directory permissions
nself deploy server ssh prod "ls -ld /var/www/nself"
# Fix remote permissions
nself deploy server ssh prod "chown -R root:root /var/www/nself"{
"name": "production",
"type": "remote",
"host": "prod.example.com",
"port": 22,
"user": "root",
"key": "~/.ssh/production_key",
"deploy_path": "/var/www/nself",
"description": "Production server",
"created_at": "2026-01-30T12:34:56Z"
}.environments/
โโโ prod/
โ โโโ .env # Environment configuration
โ โโโ .env.secrets # Sensitive credentials (chmod 600)
โ โโโ server.json # SSH connection details
โ โโโ .sync-history # Sync history log (auto-generated)
โโโ staging/
โโโ .env
โโโ .env.secrets
โโโ server.json
โโโ .sync-history
-
Always use
server checkbefore deploymentnself deploy server check prod
-
Use dry-run for sync operations first
nself deploy sync push prod --dry-run
-
Verify with
server infobefore making changesnself deploy server info prod
-
Monitor sync status regularly
nself deploy sync status
-
Use separate SSH keys per environment
- Development:
~/.ssh/dev_key - Staging:
~/.ssh/staging_key - Production:
~/.ssh/production_key
- Development:
-
Always backup before full sync
nself backup create nself deploy sync full prod
-
Use
--forcewith caution- Never use
--forcefor production without review - Always verify with dry-run first
- Never use
-
Regular server diagnostics
# Weekly health check nself deploy server status nself deploy server diagnose prod
# Create environment first
nself env create prod
# Then add server configuration
nself deploy server add prod --host prod.example.com# Generate secrets
nself config secrets generate --env prod
# Validate before sync
nself config validate prod
# Then sync to remote
nself deploy sync push prod# Backup before sync
nself backup create
# Perform sync
nself deploy sync full prod
# Rollback if needed
nself backup rollbackThe nself deploy server command provides comprehensive server management with 10 core subcommands:
| Subcommand | Purpose | Safety Level |
|---|---|---|
init |
Initialize VPS for nself deployment | Destructive (SSH hardening) |
check |
Verify server readiness | Read-only |
status |
Quick status of all servers | Read-only |
diagnose |
Comprehensive server diagnostics | Read-only |
list |
List all configured servers | Read-only |
add |
Add server configuration | Modifies config |
remove |
Remove server configuration | Modifies config |
ssh |
Quick SSH connection or command | Interactive |
info |
Display comprehensive server info | Read-only |
sync |
Synchronize files (use nself deploy sync) |
Modifies files |
# Complete server initialization workflow
# 1. Initialize the VPS
nself deploy server init [email protected] --domain example.com --yes
# 2. Verify server is ready
nself deploy server check [email protected]
# 3. Add to nself configuration
nself deploy server add prod --host prod.example.com
# 4. Test SSH connection
nself deploy server ssh prod "uptime"
# 5. View complete info
nself deploy server info prod# Quick health check
nself deploy server status
# Detailed diagnostics for specific server
nself deploy server diagnose prod
# Execute remote commands
nself deploy server ssh staging "docker ps"
nself deploy server ssh prod "df -h"
# Interactive SSH session
nself deploy server ssh prod# List all servers
nself deploy server list
# Add new server
nself deploy server add staging \
--host staging.example.com \
--user deploy \
--port 2222 \
--key ~/.ssh/staging_key
# Remove old server
nself deploy server remove old-prod --force
# Update existing (re-add)
nself deploy server add prod --host new-prod.example.com# Check all servers
nself deploy server status
# Deep dive on specific server
nself deploy server check prod
nself deploy server diagnose prod
nself deploy server info prod
# Monitor in script
#!/bin/bash
if nself deploy server check prod > /dev/null 2>&1; then
echo "Server healthy"
else
echo "Server issues detected"
nself deploy server diagnose prod
fi- Production Deployment Guide
- Environment Management
- Security Best Practices
- Destroy Command - Safe infrastructure teardown
- Troubleshooting Guide