# 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, manages essential system swap space, 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, 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.

---

## Prerequisites
- A server running Linux (Ubuntu/Debian recommended).
- **Docker** and **Docker Compose** installed.
- **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).

---

## 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, prepare your operating system, and launch GitLab.

1. Make the script executable:
   ```bash
   chmod +x run.sh scripts/*.sh
   ```
2. Execute the script:
   ```bash
   ./run.sh
   ```
3. **What happens next?** 
   - **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**. 

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`.