GitLab Local Development Setup

A complete, ready-to-use GitLab instance with an automatically registered GitLab Runner for local development and CI/CD testing.

Note: This repository is used as part of the CCIE Automation Bootcamp at DevNet Academy.

Features

• One-Command Setup - Get a fully functional GitLab instance running with a single command
• Automatic Runner Registration - GitLab Runner is automatically registered and ready to use
• Docker-Based - All services run in containers for easy management and isolation
• Persistent Data - All GitLab data, repositories, and configurations persist across restarts
• Network Testing Ready - Optimized for testing network devices in Cisco CML environments
• CI/CD Ready - Sample pipeline included to get started with GitLab CI/CD

Quick Start

Simply run:

docker compose up -d

That's it! The setup will automatically:

• Start GitLab CE
• Register the GitLab Runner
• Configure everything to work together

Note:

• GitLab takes 5-10 minutes to fully initialize on the first startup
• The runner will automatically register once GitLab is ready
• You can monitor progress with: docker compose logs -f

Accessing GitLab

Once GitLab is ready (check with docker compose ps), access it at:

• URL: http://localhost:8081
• Username: root
• Password: 1234QWer!

What's Included

Services

1. GitLab CE (web)

   • Full GitLab instance with all features
   • Accessible at http://localhost:8081
   • HTTPS available at https://localhost:8443

2. GitLab Runner (runner)

   • Automatically registered on startup
   • Executes CI/CD pipelines
   • Uses Docker executor

3. Register Runner (register-runner)

   • One-time service that registers the runner
   • Runs automatically and exits after registration

Usage

Check Status

docker compose ps

All services should show as "Up" and GitLab should be "healthy".

View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f web
docker compose logs -f runner

Stop Services

docker compose down

Stop and Remove All Data

docker compose down -v

This will delete all GitLab data, repositories, and configurations. Use with caution!

Restart Services

docker compose restart

Running CI/CD Pipelines

The runner is configured to:

• Run untagged jobs automatically
• Access GitLab via the internal Docker network
• Connect to network devices in the same CML subnet

Basic Example .gitlab-ci.yml

test:
  script:
    - echo "Hello from GitLab CI!"
    - python --version

Troubleshooting

GitLab is Unhealthy

• Normal during first startup: Wait 5-10 minutes for GitLab to initialize
• Check logs: docker compose logs web
• Verify health: docker compose ps should show "healthy" after initialization

Runner Not Registered

• Check registration logs: docker compose logs register-runner
• Ensure GitLab is healthy before registration
• Verify config exists: ls -la config/config.toml
• Re-register manually if needed:

  docker compose up -d register-runner

Pipeline Fails to Clone Repository

• The runner is configured with clone_url = "http://web" to work inside containers
• If you see connection errors, verify the runner config: cat config/config.toml
• Restart the runner: docker compose restart runner

Port Conflicts

If ports 8081 or 8443 are already in use:

1. Edit docker-compose.yml
2. Change the port mappings (e.g., '8082:80' instead of '8081:80')
3. Update external_url in the GITLAB_OMNIBUS_CONFIG section
4. Restart: docker compose down && docker compose up -d

GitLab Not Accessible After Configuration Changes

If you've modified docker-compose.yml:

docker compose exec web gitlab-ctl reconfigure
docker compose restart web

For a completely fresh start:

docker compose down -v
docker compose up -d

Data Persistence

All data is stored in local directories:

• gitlab/ - GitLab configuration, logs, and data (repositories, users, etc.)
• config/ - GitLab Runner configuration
• data/ - Runner cache data

Important: These directories are created automatically and contain all your GitLab data. To start completely fresh, delete these directories and run docker compose up -d again.

Architecture

• Network: All services run on the gitlab-network Docker network
• Runner: Uses Docker executor for CI/CD job execution
• Clone URL: Configured to use http://web (internal service name) for Git operations
• Storage: All data persists in local directories

Security Notes

• Default credentials are set for educational purposes
• For production use, change the root password immediately
• The runner runs with standard Docker access (not privileged)
• All services are on an isolated Docker network

Requirements

• Docker Engine 20.10+
• Docker Compose 2.0+
• At least 4GB RAM (8GB recommended)
• At least 10GB free disk space

Support

For issues or questions:

1. Check the troubleshooting section above
2. Review service logs: docker compose logs
3. Verify all services are running: docker compose ps

Contributing

Contributions are welcome! If you'd like to contribute to this project:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Commit your changes (git commit -m 'Add some amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

Please ensure that:

• Your code follows existing patterns and conventions
• You've tested your changes locally
• You've updated the README if needed
• You haven't committed any sensitive data (secrets, tokens, etc.)

License

This project is provided as-is for educational and development purposes. GitLab CE is licensed under the MIT Expat License.

Important Security Note: This setup includes default credentials for local development. Never use these default credentials in production environments. Always change the root password and registration tokens before deploying to any accessible network.