server-bootstrap/README.md

Server Bootstrap Framework

🚀 Overview

The server-bootstrap project provides a robust, modular, and opinionated framework for setting up new Linux servers quickly and consistently. It automates critical initial configurations, including user management, security hardening, essential package installation, and system-wide package mirror optimization for Iranian cloud providers like Liara, ArvanCloud, and Runflare.

This framework is designed to save time, reduce manual errors, and ensure a secure and performant base environment for your applications. It's built with modularity in mind, allowing easy extension and customization.

✨ Features

• Modular Design: Each core function (User, Security, System Installation, Docker) is encapsulated in a dedicated script.
• Interactive CLI: A single run.sh script provides a user-friendly interface for executing full setups or individual components.
• User Management:
  • Interactive user creation with password setup.
  • Optional addition to sudo group.
  • Flexible addition to custom additional groups.
  • SSH key management (copy existing root keys or paste new ones).
  • Optional, interactive addition to the docker group if Docker is detected.
• Security Hardening:
  • Optional disabling of root SSH login.
  • Enforcement of SSH key-only authentication.
  • Basic UFW firewall setup.
• System Installation & Configuration:
  • OS detection for platform-specific commands.
  • Intelligent DNS configuration, prioritizing systemd-resolved when available, falling back to /etc/resolv.conf.
  • Installation of common development tools and essential packages.
  • Automatic system updates.
• Multi-Provider Repository Mirroring:
  • Automated setup of high-speed package mirrors for Liara, ArvanCloud, and Runflare for various Linux distributions.
  • Supports Debian, Ubuntu, Fedora, RHEL variants (CentOS, Rocky, AlmaLinux), Arch, Manjaro, Alpine, OpenSUSE, and Kali.
• Docker Installation with Registry Mirroring:
  • Multi-distribution Docker installation.
  • Interactive selection and configuration of Docker registry mirrors for Liara, ArvanCloud, and Runflare.
  • Handles daemon.json configuration and Docker service restarts.

📁 Directory Structure

The project is organized into a clear, logical structure for maintainability and extensibility.

server-bootstrap
├── run.sh                  # Main CLI entry point for the entire framework
└── scripts/                # Contains all modular setup scripts
    ├── docker/             # Docker installation and configuration scripts
    │   ├── install.sh      # Main Docker installer (OS detection, calls OS-specific installer, prompts for mirror)
    │   ├── mirrors/        # Scripts for configuring Docker registry mirrors
    │   │   ├── arvancloud.sh # Configures ArvanCloud Docker registry mirror
    │   │   ├── liara.sh    # Configures Liara Docker registry mirror
    │   │   └── runflare.sh # Configures Runflare Docker registry mirror
    │   └── os/             # OS-specific Docker installation logic
    │       ├── alpine.sh   # Docker installation for Alpine Linux
    │       ├── arch.sh     # Docker installation for Arch Linux / Manjaro
    │       ├── debian.sh   # Docker installation for Debian / Kali
    │       ├── opensuse.sh # Docker installation for OpenSUSE
    │       ├── rhel.sh     # Docker installation for RHEL-based systems (CentOS, Fedora, Rocky, AlmaLinux)
    │       └── ubuntu.sh   # Docker installation for Ubuntu
    ├── installer.sh        # Handles system-wide installations (packages, DNS, updates, calls mirror scripts)
    ├── mirrors/            # System package repository mirror configurations
    │   └── os/             # Organized by provider and then OS
    │       ├── arvancloud/ # ArvanCloud package mirror scripts
    │       │   ├── alpine.sh   # ArvanCloud mirror for Alpine
    │       │   ├── archlinux.sh# ArvanCloud mirror for Arch Linux
    │       │   ├── centos.sh   # ArvanCloud mirror for CentOS/RHEL
    │       │   ├── debian.sh   # ArvanCloud mirror for Debian
    │       │   ├── manjaro.sh  # ArvanCloud mirror for Manjaro
    │       │   ├── opensuse.sh # ArvanCloud mirror for OpenSUSE
    │       │   └── ubuntu.sh   # ArvanCloud mirror for Ubuntu
    │       ├── liara/        # Liara package mirror scripts
    │       │   ├── alpine.sh   # Liara mirror for Alpine
    │       │   ├── archlinux.sh# Liara mirror for Arch Linux
    │       │   ├── centos.sh   # Liara mirror for CentOS/RHEL
    │       │   ├── debian.sh   # Liara mirror for Debian
    │       │   ├── fedora.sh   # Liara mirror for Fedora
    │       │   ├── manjaro.sh  # Liara mirror for Manjaro
    │       │   ├── opensuse.sh # Liara mirror for OpenSUSE
    │       │   ├── rocky.sh    # Liara mirror for Rocky Linux
    │       │   └── ubuntu.sh   # Liara mirror for Ubuntu
    │       └── runflare/     # Runflare package mirror scripts
    │           ├── almalinux.sh# Runflare mirror for AlmaLinux
    │           ├── alpine.sh   # Runflare mirror for Alpine
    │           ├── archlinux.sh# Runflare mirror for Arch Linux
    │           ├── debian.sh   # Runflare mirror for Debian
    │           ├── fedora.sh   # Runflare mirror for Fedora
    │           ├── kali.sh     # Runflare mirror for Kali Linux
    │           └── ubuntu.sh   # Runflare mirror for Ubuntu
    ├── security.sh         # Hardens server security (SSH, Firewall)
    └── user.sh             # Manages user creation, groups, and SSH keys

🚀 Usage Guide

This guide is for both new and experienced users.

⚠️ Prerequisites

• Operating System: A fresh installation of a supported Linux distribution (Ubuntu, Debian, Fedora, CentOS/RHEL variants, Arch, Manjaro, Alpine, OpenSUSE, Kali).
• Permissions: You must run the run.sh script as the root user or with sudo.

1. Make Scripts Executable

First, navigate to the server-bootstrap directory and ensure all scripts are executable:

cd server-bootstrap
sudo chmod +x $(find . -type f -name "*.sh")

2. Running the Bootstrap CLI

Execute the main CLI script:

sudo ./run.sh

You will be presented with a menu of options:

=================================
      Server Bootstrap CLI
=================================
1) Run FULL setup
2) User setup
3) Security setup
4) System installer
5) Install Docker
6) Exit
Select an option:

3. Understanding the Options

• 1) Run FULL setup: This option executes all the bootstrap steps sequentially:

  1. User Setup (scripts/user.sh)
  2. Security Setup (scripts/security.sh)
  3. System Installer (scripts/installer.sh)
  4. Install Docker (scripts/docker/install.sh) This is recommended for fresh server deployments.

• 2) User setup: (Runs scripts/user.sh)

  • Guides you through creating a new non-root user.
  • Asks for password, full name, etc.
  • Prompts to add the user to the sudo group.
  • Allows adding the user to additional custom groups (e.g., www-data, nginx).
  • Sets up SSH access for the new user by copying root's authorized_keys or accepting a new public key.
  • Interactively asks if the user should be added to the docker group if Docker is installed on the system.

• 3) Security setup: (Runs scripts/security.sh)

  • Asks to optionally disable root SSH login (highly recommended for security).
  • Configures SSH to allow only key-based authentication.
  • Sets up a basic UFW (Uncomplicated Firewall) profile.

• 4) System installer: (Runs scripts/installer.sh)

  • Detects your operating system.
  • Asks if you want to set custom DNS servers and intelligently configures them (prioritizes systemd-resolved.conf).
  • Installs essential development tools and common packages (e.g., git, curl, wget, build-essential).
  • Asks to enable automatic system updates.
  • Configures system package mirrors: Based on your OS, it will attempt to configure the fastest available mirrors from Liara, ArvanCloud, or Runflare for optimal package download speeds.

• 5) Install Docker: (Runs scripts/docker/install.sh)

  • Detects your operating system and installs Docker using the appropriate package manager (APT, DNF, Pacman, APK, Zypper).
  • After installation, it will interactively prompt you to select a Docker registry mirror (Liara, ArvanCloud, or Runflare) to accelerate Docker image pulls. This involves modifying /etc/docker/daemon.json and restarting the Docker service.

• 6) Exit: Exits the CLI.

🛠️ Customization & Development (For Developers)

The modular design makes it straightforward to extend or modify the framework.

Adding New Package Mirror Providers

1. Create a new directory under scripts/mirrors/os/ for your provider (e.g., scripts/mirrors/os/myprovider/).
2. Inside, create OS-specific shell scripts (e.g., ubuntu.sh, debian.sh, rhel.sh) that contain the logic to configure your provider's mirrors for that specific OS. Refer to existing scripts for examples.
3. Modify scripts/installer.sh to include your new provider in the selection logic and call the appropriate script.

Adding New Docker Mirror Providers

1. Create a new script under scripts/docker/mirrors/ (e.g., myprovider.sh). This script should modify /etc/docker/daemon.json to include your registry mirror and restart Docker.
2. Modify scripts/docker/install.sh to include your new provider in the interactive selection and call your new script.

Adding New OS Support for Docker Installation

1. Create a new script under scripts/docker/os/ for the new OS (e.g., gentoo.sh). This script should contain the commands to install Docker on that specific OS.
2. Modify scripts/docker/install.sh's OS detection logic to call your new script.

Safe Shell Scripting (set -e)

The scripts utilize set -e, which causes the script to exit immediately if any command fails (returns a non-zero exit status). This is a best practice for robust scripting.

• Handling expected failures: If a command might legitimately fail but you want the script to continue, use || true (e.g., command_that_might_fail || true) or wrap it in an if condition:

  if ! command_that_might_fail; then
      echo "Warning: Command failed but we are continuing."
  fi
  

• Quoting variables: Always quote variables, especially when dealing with paths or user input (e.g., "$USERNAME", "/home/$USERNAME/.ssh"), to prevent issues with spaces or special characters.
• Sanitizing input: For user input like group names, consider trimming whitespace or validating input before passing it to commands.

🤝 Contributing

We welcome contributions! If you have suggestions, bug reports, or want to contribute code, please:

1. Fork the repository.
2. Create a new branch (git checkout -b feature/your-feature).
3. Make your changes.
4. Commit your changes (git commit -am 'Add new feature').
5. Push to the branch (git push origin feature/your-feature).
6. Open a Pull Request.

Please ensure your code adheres to existing style and set -e best practices.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.