Installation Guide

Updated for ɳSelf v0.4.8 v0.4.8

This comprehensive guide covers all installation methods and platform-specific instructions for ɳSelf, the powerful CLI tool for deploying production-ready backend infrastructure.

System Requirements

Operating System Support

ɳSelf is compatible with:

• Linux (Ubuntu 20.04+, CentOS 8+, Debian 11+, Alpine Linux)
• macOS (10.15+ / macOS Catalina and newer)
• Windows (Windows 10+ with WSL2)

Hardware Requirements

Minimum (Development)

• CPU: 2 cores
• RAM: 4GB
• Storage: 10GB free space
• Network: Internet connection for downloads

Recommended (Production)

• CPU: 4+ cores
• RAM: 8GB+
• Storage: 50GB+ SSD
• Network: Stable internet connection

Quick Installation

The fastest way to install ɳSelf is using our automated installer:

curl -sSL https://install.nself.org | bash

This single command will:

1. Detect your operating system and architecture
2. Check for existing installations (v0.2.2+)
3. Download the appropriate ɳSelf binary
4. Install to ~/.ɳSelf/bin
5. Add ɳSelf to your PATH
6. Verify the installation with visual feedback
7. Install Docker and Docker Compose if needed
8. Create automatic backups of previous versions

What the installer does

The installation script performs these steps:

1. System Detection: Identifies OS, architecture, and package manager
2. Dependency Check: Verifies Docker, Docker Compose, and other requirements
3. Binary Download: Fetches the latest ɳSelf release from GitHub
4. Permission Setup: Makes the binary executable and places it in the correct location
5. PATH Configuration: Updates your shell profile to include ɳSelf in PATH
6. Verification: Runs nself version to confirm successful installation

Manual Installation

If you prefer to install manually or need more control over the process:

Step 1: Download the Binary

Visit the ɳSelf releases page and download the appropriate binary for your system:

# Linux x64
wget https://github.com/nself-org/cli/releases/latest/download/nself-linux-x64

# macOS (Intel)
wget https://github.com/nself-org/cli/releases/latest/download/nself-macos-x64

# macOS (Apple Silicon)
wget https://github.com/nself-org/cli/releases/latest/download/nself-macos-arm64

# Windows (WSL2)
wget https://github.com/nself-org/cli/releases/latest/download/nself-windows-x64.exe

Step 2: Install the Binary

# Create nself directory
mkdir -p ~/.ɳSelf/bin

# Move and rename binary (Linux/macOS)
mv nself-* ~/.ɳSelf/bin/nself

# Make executable
chmod +x ~/.ɳSelf/bin/nself

Step 3: Update PATH

Add ɳSelf to your PATH by updating your shell profile:

# For bash
echo 'export PATH="$HOME/.ɳSelf/bin:$PATH"' >> ~/.bashrc

# For zsh
echo 'export PATH="$HOME/.ɳSelf/bin:$PATH"' >> ~/.zshrc

# For fish
echo 'set -gx PATH $HOME/.ɳSelf/bin $PATH' >> ~/.config/fish/config.fish

Reload your shell or run:

source ~/.bashrc  # or ~/.zshrc

Step 4: Verify Installation

nself version

You should see output similar to:

nself version 0.4.8
Plugin System Release

Installing Dependencies

ɳSelf requires Docker and Docker Compose to orchestrate your backend services.

Docker Installation

Ubuntu/Debian

# Update package index
sudo apt-get update

# Install dependencies
sudo apt-get install ca-certificates curl gnupg lsb-release

# Add Docker's GPG key
sudo mkdir -m 0755 -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Set up repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Add user to docker group
sudo usermod -aG docker $USER

CentOS/RHEL/Fedora

# Install Docker
sudo dnf install docker docker-compose

# Start and enable Docker
sudo systemctl start docker
sudo systemctl enable docker

# Add user to docker group
sudo usermod -aG docker $USER

macOS

# Using Homebrew
brew install docker docker-compose

# Or download Docker Desktop from https://docker.com

Windows (WSL2)

1. Install Docker Desktop for Windows
2. Enable WSL2 integration in Docker Desktop settings
3. Restart WSL2

Verify Docker Installation

# Check Docker version
docker --version

# Check Docker Compose
docker compose version

# Test Docker (should download and run hello-world)
docker run hello-world

Installation Methods

Currently, ɳSelf is distributed as a standalone binary. We recommend using the automated installer script or manual binary installation described above.

Verification and Testing

After installation, verify ɳSelf is working correctly:

Basic Verification

# Check version
nself version

# View help
ɳSelf --help

# Check available commands
nself help

Comprehensive Test

Create a test project to ensure everything works:

# Create test directory
mkdir nself-test && cd nself-test

# Initialize project
nself init

# Build configuration
nself build

# Start services
nself start

# Check status
nself status

# Clean up
nself stop
cd .. && rm -rf nself-test

Configuration

Global Configuration

ɳSelf stores global configuration in ~/.ɳSelf/config.yaml:

# Default settings
auto_update: true
telemetry: false
default_environment: development
docker_socket: unix:///var/run/docker.sock

# Registry settings
registry:
  default: docker.io
  mirrors: []

# Update settings
updates:
  check_interval: 24h
  include_prereleases: false

Environment Variables

Configure ɳSelf behavior with environment variables:

# Disable auto-updates
export NSELF_AUTO_UPDATE=false

# Custom Docker socket
export DOCKER_HOST=unix:///var/run/docker.sock

# Debug mode
export NSELF_DEBUG=true

# Custom config location
export NSELF_CONFIG_DIR=$HOME/.config/nself

Updating ɳSelf

Automatic Updates (Recommended)

ɳSelf can automatically update itself with seamless update system:

# Update to latest version (currently v0.4.8)
nself update

# The update process will:
# 1. Check current version
# 2. Download latest release
# 3. Create backup of current version
# 4. Install new version
# 5. Verify installation
# 6. Rollback if needed

# Check for updates without installing
nself update --check

# Force update even if on latest version
nself update --force

Manual Updates

Binary Update

# Download and replace binary curl -sSL https://install.nself.org | bash

Uninstallation

Complete Removal

Remove ɳSelf and all associated data:

# Stop all running services first
nself down --all

# Remove binary and data
rm -rf ~/.ɳSelf

# Remove from PATH (edit your shell profile)
# Remove the line: export PATH="$HOME/.ɳSelf/bin:$PATH"

Troubleshooting Installation

Common Issues

Permission Denied

# Fix: Ensure binary is executable
chmod +x ~/.ɳSelf/bin/nself

# Fix: Check PATH is correctly set
echo $PATH | grep -o ~/.ɳSelf/bin

Docker Not Running

# Start Docker service
sudo systemctl start docker

# Check Docker status
docker ps

Command Not Found

# Check if nself is in PATH
which ɳSelf

# Reload shell configuration
source ~/.bashrc

Network Issues

# Test connectivity
curl -I https://github.com

# Use proxy if needed
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

Debug Mode

Enable debug logging for troubleshooting:

# Enable debug mode
export NSELF_DEBUG=true

# Run command with verbose output
ɳSelf --debug version

# Check logs
nself logs --debug

Getting Help

If you encounter issues:

1. Check the logs: nself logs --debug
2. Verify system requirements: Ensure all dependencies are installed
3. Search existing issues: GitHub Issues
4. Create a new issue: Include debug logs and system information

System Information for Support

When reporting issues, include:

# Generate system info
ɳSelf debug system-info

# This outputs:
# - nself version
# - Operating system and version
# - Docker version
# - Available resources
# - Network configuration

Next Steps

Once ɳSelf is installed:

1. Quick Start: Follow our Quick Start Guide to create your first project
2. Database Tools: Explore the powerful Database Management features
3. Microservices: Learn about NestJS, Python, and Go services
4. Production: Review the Production Deployment Guide for production setup

Advanced Installation Options

Custom Installation Directory

Install ɳSelf to a custom location:

# Set custom installation directory
export NSELF_INSTALL_DIR=/opt/nself

# Run installer
curl -sSL https://install.nself.org | bash

Offline Installation

For environments without internet access:

1. Download the binary and dependencies on a connected machine
2. Transfer to the target machine
3. Install manually following the manual installation steps

Enterprise Installation

For enterprise environments with specific requirements:

# Use enterprise registry
export NSELF_REGISTRY=registry.company.com

# Custom CA certificates
export NSELF_CA_BUNDLE=/path/to/ca-bundle.crt

# Install with enterprise settings
curl -sSL https://install.nself.org | bash

The installation is now complete! ɳSelf is ready to help you deploy production-ready backend infrastructure with a single command.