Installation Guide

Updated for nself v0.4.8 v0.4.8

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

System Requirements

Operating System Support

nself 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

v0.4.8: Plugin System Release

The latest release introduces a powerful plugin system for third-party integrations. Install Stripe, GitHub, or Shopify plugins with a single command. Includes database schemas, webhook handlers, and CLI actions for managing synced data.

The fastest way to install nself 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 nself binary
  4. Install to ~/.nself/bin
  5. Add nself 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 nself 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 nself 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 nself releases page and download the appropriate binary for your system:

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

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

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

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

Step 2: Install the Binary

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

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

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

Step 3: Update PATH

Add nself to your PATH by updating your shell profile:

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

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

# For fish
echo 'set -gx PATH $HOME/.nself/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

nself 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, nself is distributed as a standalone binary. We recommend using the automated installer script or manual binary installation described above.

Package Manager Support Coming Soon

We're working on official package manager support for APT, YUM/DNF, and Homebrew. For now, please use the direct installation methods above.

Verification and Testing

After installation, verify nself is working correctly:

Basic Verification

# Check version
nself version

# View help
nself --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

nself stores global configuration in ~/.nself/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 nself 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 nself

Seamless Updates

Simply run nself update to get the latest version. The update system includes automatic rollback, progress indicators, and version verification. v0.4.8 adds the plugin system with full cross-platform compatibility.

Automatic Updates (Recommended)

nself 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 nself and all associated data:

# Stop all running services first
nself down --all

# Remove binary and data
rm -rf ~/.nself

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

Troubleshooting Installation

Common Issues

Permission Denied

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

# Fix: Check PATH is correctly set
echo $PATH | grep -o ~/.nself/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 nself

# 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
nself --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
nself debug system-info

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

Next Steps

Once nself 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 nself 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! nself is ready to help you deploy production-ready backend infrastructure with a single command.