initial commit

README.md

@@ -0,0 +1,90 @@
+# 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.
+
+*Last Updated: 1404/12/24 (2026/03/15)*
+
+## Architecture Overview
+
+This project uses Docker Compose to spin up two main services:
+1. **GitLab Server**: The main web application, database, and background workers.
+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.
+- `.env.sample`: A template for your configuration variables.
+- `docker-compose.yml`: The blueprint that tells Docker how to build the services.
+- `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.
+
+---
+
+## 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).
+
+---
+
+## Step-by-Step Installation Guide
+
+### Step 1: Prepare the Configuration
+Before starting, GitLab needs to know your domain name, passwords, and email settings.
+
+1. Make a copy of the sample environment file:
+   ```bash
+   cp .env.sample .env
+   ```
+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).
+
+### Step 2: Run the Orchestrator
+We have provided a unified script to validate your configuration, optimize your server, and launch GitLab.
+
+1. Make the script executable:
+   ```bash
+   chmod +x run.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.
+
+### Step 3: Wait for GitLab to Boot
+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.
+
+### Step 4: Log In
+Once the web interface loads:
+- **Username:** `root`
+- **Password:** The password you set in `GITLAB_ROOT_PASSWORD` inside your `.env` file.
+
+### Step 5: Setup the CI/CD Runner
+To run automated tasks (like building Docker images or running tests), you need to register your GitLab Runner.
+
+1. Go to your GitLab Web UI.
+2. Navigate to **Admin Area** -> **CI/CD** -> **Runners**.
+3. Click **New instance runner** and copy the **Authentication Token**.
+4. Go back to your server terminal and run:
+   ```bash
+   bash ./scripts/setup-runner.sh
+   ```
+5. Follow the prompts! The script will ask for your GitLab URL and the token you just copied. It will automatically register the runner and configure it to match your server's CPU cores.
+
+---
+
+## Maintenance & Troubleshooting
+
+- **How do I stop GitLab?**
+  Run `docker compose down` in this directory.
+- **How do I view the logs?**
+  Run `docker compose logs -f gitlab` to see real-time background processes.
+- **Permission Denied on Runner Setup?**
+  If the `setup-runner.sh` script throws a permission error, it means Docker created files as the `root` user. Simply run the script with sudo: `sudo bash ./scripts/setup-runner.sh`.