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:

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

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, optimize your server, and launch GitLab.

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

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.