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:

GitLab Server: The main web application, database, and background workers.
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.

Make a copy of the sample environment file:
```
cp .env.sample .env
```
Open .env in your favorite text editor (e.g., nano .env).
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).
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.

Make the script executable:
```
chmod +x run.sh scripts/*.sh
```
Execute the script:
```
./run.sh
```
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.

Go to your GitLab Web UI.
Navigate to Admin Area -> CI/CD -> Runners.
Click New instance runner and copy the Authentication Token.
Go back to your server terminal and run:
```
bash ./scripts/setup-runner.sh
```
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.