From 6395421861d1628ca9d3d62dd97ae9b7696edf60 Mon Sep 17 00:00:00 2001 From: Amirhossein Khalili Date: Wed, 18 Mar 2026 04:09:15 +0800 Subject: [PATCH] docs(README): add README.md file --- README.md | 214 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 214 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..b88f3ce --- /dev/null +++ b/README.md @@ -0,0 +1,214 @@ +# 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: + +```bash +cd server-bootstrap +sudo chmod +x $(find . -type f -name "*.sh") +``` + +### 2. Running the Bootstrap CLI + +Execute the main CLI script: + +```bash +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: + ```bash + 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.