feat(deployment): add automated swap space configuration

- Create `scripts/setup-swap.sh` to dynamically detect and allocate
  a 4GB swap file to prevent OOM errors on low-RAM servers.
- Integrate the swap check gracefully into the `run.sh` orchestrator flow.
- Update `README.md` to document new sudo/disk space prerequisites
  and the updated deployment steps.

README.md

@@ -1,6 +1,6 @@
 # Self-Hosted GitLab Docker Deployment
 
-Welcome to the automated, self-hosted GitLab deployment project! This setup is designed to be as "one-click" as possible while remaining highly configurable. It automatically tunes itself to your server's hardware and simplifies the setup of CI/CD runners.
+Welcome to the automated, self-hosted GitLab deployment project! This setup is designed to be as "one-click" as possible while remaining highly configurable. It automatically tunes itself to your server's hardware, manages essential system swap space, and simplifies the setup of CI/CD runners.
 
 *Last Updated: 1404/12/24 (2026/03/15)*
 
@@ -11,9 +11,10 @@ This project uses Docker Compose to spin up two main services:
 2. **GitLab Runner**: A background service that runs your CI/CD pipeline jobs (like testing and deploying code).
 
 **Directory Structure:**
-- `run.sh`: The main launcher script. It checks your config and starts the server.
+- `run.sh`: The main launcher script. It checks your config, sets up system swap, tunes resources, and starts the server.
 - `.env.sample`: A template for your configuration variables.
 - `docker-compose.yml`: The blueprint that tells Docker how to build the services.
+- `scripts/setup-swap.sh`: Safely checks and creates a $4$ GB swap file to prevent out-of-memory crashes on smaller servers.
 - `scripts/auto-tune.sh`: A smart script that calculates the perfect math variables (like $RAM \times 0.25$ for database buffers) to prevent your server from crashing.
 - `scripts/setup-runner.sh`: Automates the tedious process of linking the GitLab Runner to your GitLab Server.
 - `runner-config/`: An empty folder where Docker will safely store your runner's configuration.
@@ -23,7 +24,9 @@ This project uses Docker Compose to spin up two main services:
 ## Prerequisites
 - A server running Linux (Ubuntu/Debian recommended).
 - **Docker** and **Docker Compose** installed.
-- Minimum hardware: 4GB RAM and 2 CPU cores (8GB RAM + 4 Cores highly recommended).
+- **Sudo privileges** for your user.
+- **Hardware:** Minimum $4$ GB RAM and $2$ CPU cores ($8$ GB RAM + $4$ Cores highly recommended).
+- **Disk Space:** At least $15$ GB to $20$ GB of free disk space (a $4$ GB chunk will be safely reserved for swap memory if your server lacks it).
 
 ---
 
@@ -38,26 +41,27 @@ Before starting, GitLab needs to know your domain name, passwords, and email set
    ```
 2. Open `.env` in your favorite text editor (e.g., `nano .env`).
 3. **CRITICAL:** Change `GITLAB_EXTERNAL_URL` to your server's IP address (e.g., `http://192.168.1.50`) or domain name (e.g., `https://git.yourdomain.com`).
-4. Update `GITLAB_ROOT_PASSWORD` (must be at least 8 characters).
+4. Update `GITLAB_ROOT_PASSWORD` (must be at least $8$ characters).
 
 ### Step 2: Run the Orchestrator
-We have provided a unified script to validate your configuration, optimize your server, and launch GitLab.
+We have provided a unified script to validate your configuration, prepare your operating system, and launch GitLab.
 
 1. Make the script executable:
    ```bash
-   chmod +x run.sh
+   chmod +x run.sh scripts/*.sh
    ```
 2. Execute the script:
    ```bash
    ./run.sh
    ```
 3. **What happens next?** 
-   - The script will verify that you filled out the `.env` file correctly.
-   - It will ask if you want to run the **Auto-Tuner**. Press `y`! The auto-tuner will detect your CPU and RAM and dynamically adjust GitLab's internal memory settings in your `.env` file so it doesn't consume all your server's resources.
-   - Finally, it triggers Docker to download and start GitLab.
+   - **Validation:** The script verifies you filled out `.env` correctly.
+   - **Swap Check:** It checks your OS for Swap Memory. If you don't have any, it will ask permission to create a $4$ GB swap file (this requires your `sudo` password) to ensure GitLab doesn't crash during boot.
+   - **Auto-Tuner:** It will ask if you want to run the Auto-Tuner. Press `y`! It detects your CPU/RAM and dynamically adjusts GitLab's internal memory settings in your `.env` file.
+   - **Launch:** Finally, it triggers Docker to download and start GitLab.
 
 ### Step 3: Wait for GitLab to Boot
-GitLab is an enterprise-grade application. Once the script finishes, **you must wait 3 to 5 minutes**. 
+GitLab is an enterprise-grade application. Once the script finishes, **you must wait $3$ to $5$ minutes**. 
 
 If you navigate to your URL too early, you will see a **502 Bad Gateway** error. This simply means the internal web server is up, but the database and backend application are still loading. Grab a coffee and refresh the page in a few minutes.
 

run.sh

@@ -44,6 +44,15 @@ fi
 
 echo -e "${GREEN}[OK] Critical variables are valid.${NC}\n"
 
+echo -e "${GREEN}[OK] Critical variables are valid.${NC}\n"
+
+if [ -f "./scripts/setup-swap.sh" ]; then
+    bash ./scripts/setup-swap.sh
+else
+    echo -e "${YELLOW}[WARNING] ./scripts/setup-swap.sh not found. Skipping swap check.${NC}"
+fi
+echo ""
+
 read -p "Do you want to run the auto-tune script to optimize GitLab for this server's RAM/CPU? (y/n): " -n 1 -r
 echo
 if [[ $REPLY =~ ^[Yy]$ ]]; then

scripts/setup-swap.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+NC='\033[0m' # No Color
+
+echo -e "${CYAN}--- System Swap Space Check ---${NC}"
+
+SWAP_SIZE=$(free -m | awk '/^Swap:/ {print $2}')
+
+if [ "$SWAP_SIZE" -gt "0" ]; then
+    echo -e "${GREEN}[OK] Swap space is already configured ($SWAP_SIZE MB). Skipping creation.${NC}"
+    exit 0
+fi
+
+RAM_SIZE=$(free -m | awk '/^Mem:/ {print $2}')
+
+echo -e "${YELLOW}[WARNING] No swap space detected on this server!${NC}"
+echo -e "GitLab requires at least 4GB of RAM. If your server runs out of memory, GitLab will crash."
+
+if [ "$RAM_SIZE" -le "4500" ]; then
+    echo -e "${RED}[CRITICAL] Your server has ~4GB RAM ($RAM_SIZE MB). A 4GB swap file is HIGHLY recommended.${NC}"
+else
+    echo -e "${CYAN}Your server has plenty of RAM ($RAM_SIZE MB), but adding a swap file is still a safe fallback.${NC}"
+fi
+
+echo ""
+read -p "Do you want to automatically create a 4GB swap file now? (Requires sudo password) (y/n): " -n 1 -r
+echo ""
+
+if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+    echo -e "${YELLOW}Skipping swap creation. If GitLab crashes, please create swap manually.${NC}"
+    exit 0
+fi
+
+echo -e "${CYAN}Allocating 4GB swap file... This may take a moment.${NC}"
+sudo fallocate -l 4G /swapfile
+
+if [ $? -ne 0 ]; then
+    echo -e "${RED}[ERROR] Failed to allocate space. Your disk might be full.${NC}"
+    exit 1
+fi
+
+echo -e "${CYAN}Securing file permissions...${NC}"
+sudo chmod 600 /swapfile
+
+echo -e "${CYAN}Formatting as swap...${NC}"
+sudo mkswap /swapfile
+
+echo -e "${CYAN}Enabling swap...${NC}"
+sudo swapon /swapfile
+
+if grep -q "/swapfile" /etc/fstab; then
+    echo -e "${YELLOW}[INFO] /swapfile entry already exists in /etc/fstab.${NC}"
+else
+    echo -e "${CYAN}Adding swap to /etc/fstab to survive reboots...${NC}"
+    echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab > /dev/null
+fi
+
+NEW_SWAP=$(free -m | awk '/^Swap:/ {print $2}')
+if [ "$NEW_SWAP" -gt "0" ]; then
+    echo -e "${GREEN}[SUCCESS] 4GB Swap space successfully created and enabled!${NC}"
+else
+    echo -e "${RED}[ERROR] Something went wrong. Swap is still reporting 0 MB.${NC}"
+fi