How to Use Vultr's Gitlab MarketPlace Application

GitLab is an open-source platform for managing Git repositories. It provides a web-based interface for version control, CI/CD pipelines, issue tracking, and collaboration. It offers features like project management, code review, and integrations for streamlined software development. The Vultr Marketplace provides a pre-configured GitLab instance, enabling quick deployment and setup on a Vultr server.

This guide explains deploying and using Vultr's GitLab Marketplace Application. You will set up a GitLab instance, explore the dashboard, create a project, set up a CI/CD pipeline, and manage users and integrations.

Deploy Vultr's GitLab Marketplace Application

1. Login to your Vultr Customer Portal and click the Deploy Server button.

2. Select your preferred server type.

3. Choose a server location.

4. Select a server plan with at least 2GB RAM and 2 CPU cores.

5. Click the Configure Software button to proceed.

6. Under Marketplace Apps, search for Gitlab and select it as the Marketplace Application.

7. Select Limited Login option from the Additional Features section to create a limited user with sudo access.

8. Review your configurations and click the Deploy button to start deployment.

   Note

   It may take up to 10 minutes for your server to finish installing GitLab.

9. After the instance shows the status of Running, access your GitLab application by visiting http://SERVER-IP/ in a web browser, and set up your administrator account.

   

10. After the account setup, the page redirects to the Sign In page. Enter your credentials and proceed.

    

Initial Setup and Configuration

1. Create a DNS A record pointing to your server's IP address, such as gitlab.example.com.
2. Connect to your Vultr server instance using SSH using the connection details from the Server Information page.

Secure GitLab with TLS

To secure your GitLab instance with HTTPS and enable automatic TLS certificate management via Let's Encrypt, you need to update the GitLab configuration file. This ensures your domain is registered, and GitLab can request and apply a valid TLS certificate for encrypted access.

1. Edit the GitLab configuration file.

   console Copy

   $ sudo nano /etc/gitlab/gitlab.rb
   

   Explain Code

2. Update the external URL to use your domain.

   ini Copy

   external_url "https://gitlab.example.com"
   

   Explain Code

3. Enable Let's Encrypt and set your contact email.

   ini Copy

   letsencrypt['enable'] = true  
   letsencrypt['contact_emails'] = ['admin@example.com']
   

   Explain Code

4. Update the TLS/SSL certificate paths.

   ini Copy

   nginx['ssl_certificate'] = "/etc/gitlab/ssl/gitlab.example.com.crt"  
   nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/gitlab.example.com.key"
   

   Explain Code

   Save and close the file.

5. Reconfigure GitLab to apply changes and generate the certificate.

   console Copy

   $ sudo gitlab-ctl reconfigure
   

   Explain Code

   This process contacts Let's Encrypt, validates your domain, and installs the certificate. It may take a few minutes.

6. Verify the configuration.

   console Copy

   $ sudo gitlab-ctl status
   

   Explain Code

   All services should show run.

7. Access GitLab at https://gitlab.example.com in a web browser.

Explore GitLab Dashboard

The GitLab dashboard provides a centralized interface for managing your projects and workflows. The sidebar navigation offers quick access to essential tools for collaboration, code management, and administration, tailored to your role and permissions.

The GitLab dashboard provides access to key features in the side pane:

• Projects: Create and manage repositories for your code.
• Groups: Organize projects and manage team access.
• Issues: Track tasks, bugs, and feature requests.
• Merge Requests: Review and manage code contributions from team members.
• To-Do List: View pending tasks and action items assigned to you.
• Milestones: Set and track project milestones for releases or deadlines.
• Snippets: Share and manage small pieces of code or text.
• Activity: Monitor recent activities across projects and groups.
• Admin Area: Manage users, settings, and integrations (accessible to root users via the wrench icon).

Disable Auto DevOps

This section disables Auto DevOps to prevent automatic pipelines on commits. Auto DevOps is enabled by default and may trigger extra pipelines.

1. Log in to GitLab as root.

2. Click the wrench icon to access the Admin Area.

3. Go to Settings > CI/CD.

4. Expand the Continuous Integration and Deployment toggle and uncheck the Default to Auto DevOps pipeline for all projects option.

   

5. Click Save changes.

Create and Manage Projects

1. From the GitLab dashboard, click Create a project.

2. Choose Create blank project.

3. Fill in the project details.

   • Project name: Enter a name for your project, such as my-first-project.

   • Pick a group or namespace: Select root from the dropdown. This determines where the project is created and who owns it.

   • Project slug: GitLab auto-generates a URL-friendly version of the name, such as gitlab-project-example. You can customize this if needed.

   • Visibility Level: Choose Private, Internal, or Public.

   • Click Create project to proceed.

     

Create Example Source Code Files

This section adds sample files to the project using the GitLab web interface.

1. In the project, click the + icon next to the branch name and select New file.

2. Name the file index.js and add the following content.

   javascript Copy

   console.log("Hello, GitLab!");
   

   Explain Code

3. Enter a commit message and click Commit changes.

4. Repeat to create package.json with the following content.

   json Copy

   {
     "name": "gitlab-project-example",
     "version": "1.0.0",
     "description": "A sample Node.js project for GitLab CI/CD",
     "main": "index.js",
     "scripts": {
       "test": "echo 'Running tests...' && exit 0"
     },
     "dependencies": {}
   }
   

   Explain Code

   Commit the changes.

5. Create .gitlab-ci.yml with the following content.

   yaml Copy

   stages:
     - test
   
   test_job:
     stage: test
     image: node:16
     tags:
       - vultr-gitlab
     script:
       - npm install
       - npm test
   

   Explain Code

   Commit the changes. In the above yaml:

   • stages: Defines the pipeline stages. For example, test.
   • test_job: A job that runs in the test stage.
   • image: node:16: Uses a Node.js 16 Docker image to run the job.
   • tags: vultr-gitlab: Only runners with the vultr-gitlab tag will pick up and execute the test_job. This allows you to control which runners are used based on their capabilities or environment.
   • script: Executes commands to install dependencies (npm install) and run the test script (npm test) defined in package.json.

6. Check the Repository section to confirm that index.js, package.json, and .gitlab-ci.yml are listed.

   

Configure CI/CD Pipelines

GitLab's CI/CD pipelines automate building, testing, and deploying your code, streamlining the development process. The .gitlab-ci.yml file created earlier defines a pipeline for a Node.js project, including a test_job that runs a test script. This section explains verifying, running the pipeline, and exploring additional CI/CD features.

Verify Pipeline Status

1. From the Project, go to Build > Pipelines in the left sidebar to see the pipeline in a pending state.

   

2. The Pipeline is in pending state, indicating that no GitLab Runner is available to execute the pipeline.

   Note

   GitLab Runners are agents that run jobs defined in your .gitlab-ci.yml file.

Create a CI/CD Runner

1. In Settings > CI/CD, expand Runners and click Create project runner.

   

2. Enter tags, such as vultr-gitlab.

3. Enter a description, such as test_job_runner.

4. Click Create runner.

5. Copy the runner authentication token as shown below.

   

Install and Register GitLab Runner

1. Access your GitLab server's terminal.

2. Add the GitLab Runner repository.

   console Copy

   $ curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
   

   Explain Code

3. Install GitLab Runner with the following command.

   console Copy

   $ sudo apt install -y gitlab-runner
   

   Explain Code

4. Register the runner.

   console Copy

   $ sudo gitlab-runner register
   

   Explain Code

   It prompts you with:

   • Enter the GitLab instance URL (for example, https://gitlab.com/):: Use the base URL of your GitLab server. For example, https://gitlab.example.com.
   • Enter the registration token:: Enter the runner authentication token which you copied in the last section.
   • Enter a name for the runner. This is stored only in the local config.toml file:: Enter a name, such as gitlab_runner.
   • Enter an executor: Enter docker.
   • Enter the default Docker image (for example, ruby:3.3):: node:16.

Install and Configure Docker for GitLab Runner

To ensure the Docker executor works as expected, follow these steps:

1. Install Docker.

   console Copy

   $ sudo apt install -y docker.io
   

   Explain Code

2. Start Docker.

   console Copy

   $ sudo systemctl start docker
   

   Explain Code

3. Enable Docker.

   console Copy

   $ sudo systemctl enable docker
   

   Explain Code

4. Check Docker Status.

   console Copy

   $ sudo systemctl status docker
   

   Explain Code

5. Add gitlab-runner to Docker Group.

   console Copy

   $ sudo usermod -aG docker gitlab-runner
   

   Explain Code

   This allows the runner to communicate with the Docker daemon.

6. Restart GitLab Runner.

   console Copy

   $ sudo systemctl restart gitlab-runner
   

   Explain Code

Verify the Pipeline

This section checks the pipeline execution.

1. In the project, go to Build > Pipelines.

   

   The Pipeline status should be Passed.

2. If the pipeline is pending, click the Retry icon.

3. The pipeline should now run and pass.

4. Click the pipeline to view job logs.

Manage Users and Integrations

GitLab provides tools for managing users and integrating with external services to enhance collaboration and streamline workflows. This section explains how to add users, assign roles, and set up integrations.

Manage Users

GitLab allows administrators to invite team members, assign roles, and control access to projects and groups. Follow these steps to manage users:

1. Click the wrench icon in the left sidebar to enter the Admin Area and navigate to Users in the sidebar.

2. Create a new user by clicking New user in the Users section and filling in the required details:

   • Name: Enter the user's full name.
   • Username: Choose a unique username.
   • Email: Enter a valid email address.
   • Under the Access Section, assign a role:
     • Regular: Standard user with access to projects and groups they are invited to.
     • Administrator: Full administrative access to the GitLab instance.

3. Click Create User.

   

4. Navigate back to the Users tab.

   

5. In the Users section of the Admin Area, you can activate, deactivate, or delete users.

Set Up Integrations

GitLab supports integrations with external tools for notifications, CI/CD, and project management. Below are the steps to configure a standard integration, such as Slack notifications, to enhance team collaboration.

1. Navigate to your project’s dashboard and select Settings > Integrations from the left sidebar.

2. Choose the desired integration, such as Slack, Jira, Jenkins, Microsoft Teams Notifications, Prometheus, or Phorge.

   

3. Follow the tool-specific setup instructions.

4. Click Save changes to activate the integration.

Conclusion

In this guide, you deployed Vultr's GitLab Marketplace Application. You configured the instance, explored the GitLab dashboard, created a project, set up a CI/CD pipeline, and managed users and integrations. With GitLab’s robust version control, automation, and collaboration features, teams can streamline their development workflows.