Admin: New server guide

2026-04-14T20:01:04Z

New server guide

New page

# Container Registry Setup: Private Docker Registry with Harbor or GitLab

Setting up a private container registry is crucial for managing your Docker images securely and efficiently. This guide will walk you through the process of establishing your own private Docker registry using either Harbor or the GitLab Container Registry. Both solutions offer robust features for storing, scanning, and distributing your container images.

A **Docker image** is a lightweight, standalone, executable package of software that includes everything needed to run it: code, runtime, system tools, system libraries, and settings. A **container registry** is a centralized repository for storing and managing these Docker images.

## Prerequisites

Before you begin, ensure you have the following:

* A Linux server with root or sudo privileges. This server will host your registry.
* Docker installed on your server. You can find installation instructions on the [official Docker documentation](https://docs.docker.com/engine/install/ubuntu/).
* Basic understanding of Linux command-line operations.
* (Optional) A domain name pointing to your server's IP address for easier access.
* (Optional) If you plan to use Harbor, you will need Docker Compose installed. Instructions can be found on the [Docker Compose documentation](https://docs.docker.com/compose/install/).

## Option 1: Setting Up Harbor

Harbor is an open-source **container image registry** that stores, signs, and scans container images. It provides a web UI and Role-Based Access Control (RBAC) for managing access to your images.

### 1. Install Docker Compose

If you haven't already, install Docker Compose on your server.

```bash
sudo apt-get update
sudo apt-get install docker-compose-plugin -y
```

### 2. Download Harbor

Download the latest release of Harbor. You can find the latest release on the [Harbor GitHub releases page](https://github.com/goharbor/harbor/releases). Replace `v2.10.1` with the desired version.

```bash
wget https://github.com/goharbor/harbor/releases/download/v2.10.1/harbor-offline-installer-v2.10.1.tar.gz
tar xzvf harbor-offline-installer-v2.10.1.tar.gz
cd harbor
```

### 3. Configure Harbor

Edit the `harbor.yml` file to configure your Harbor instance.

```bash
sudo nano harbor.yml
```

Key configurations to consider:

* `hostname`: Set this to your server's IP address or domain name (e.g., `registry.yourdomain.com`).
* `http`: Configure ports for HTTP access.
* `https`: Configure ports and certificates for HTTPS access (recommended for security).
* `harbor_admin_password`: Set a strong password for the Harbor administrator.

### 4. Install Harbor

Run the Harbor installer script.

```bash
sudo ./install.sh
```

This process can take several minutes. Once complete, you should be able to access Harbor through your web browser at `http://your_harbor_hostname` or `https://your_harbor_hostname`.

### 5. Log in and Create Projects

Log in to the Harbor web UI using the administrator credentials you set. You can then create projects to organize your images and manage user access.

## Option 2: Setting Up GitLab Container Registry

If you are already using GitLab for your code repositories, integrating its built-in container registry is a straightforward option.

### 1. Enable Container Registry for Your Project

Navigate to your GitLab project. In the left sidebar, go to **Package & Registry** > **Container Registry**. Click **Enable Container Registry**.

### 2. Log in to the GitLab Container Registry

You'll need to log in to the registry using your GitLab username and a Personal Access Token.

First, create a Personal Access Token in GitLab:
1. Go to your user **Settings** > **Access Tokens**.
2. Give your token a name (e.g., `registry_access`) and select the `read_registry` and `write_registry` scopes.
3. Click **Create personal access token**. **Copy the token immediately**, as you won't be able to see it again.

Now, log in from your server's terminal:

```bash
docker login your.gitlab.server.com
# Enter your GitLab username and the Personal Access Token as the password
```

Replace `your.gitlab.server.com` with your GitLab instance's domain.

### 3. Tag and Push Your Docker Image

Tag your Docker image with the GitLab registry path.

```bash
docker tag your_image_name your.gitlab.server.com/your_group/your_project/your_image_name:tag
```

Then, push the image to the registry:

```bash
docker push your.gitlab.server.com/your_group/your_project/your_image_name:tag
```

Your image is now stored in your GitLab project's container registry.

## Using Your Private Registry

Once your registry is set up, you can pull and push images to it from any machine that has Docker installed and appropriate access credentials.

### Pulling an Image

To pull an image from your private registry:

```bash
docker pull your_registry_hostname/your_image_name:tag
```

### Pushing an Image

To push an image to your private registry:

```bash
docker tag local_image_name your_registry_hostname/your_image_name:tag
docker push your_registry_hostname/your_image_name:tag
```

Remember to log in to your registry before pushing if you haven't already.

## GPU Servers for Containerized Workloads

For demanding containerized workloads, especially those involving machine learning inference or training, consider leveraging specialized **GPU servers**. These servers offer significantly accelerated processing capabilities compared to standard CPU servers. Immers Cloud provides GPU servers starting from $0.23/hr for inference to $4.74/hr for H200 GPUs, offering a scalable and cost-effective solution for compute-intensive tasks. You can explore their offerings at [Immers Cloud](https://en.immers.cloud/signup/r/20241007-8310688-334/).

## Troubleshooting

* **Cannot connect to registry:**
* Ensure your firewall is configured to allow traffic on the registry's ports (e.g., 80, 443 for Harbor).
* Verify that the registry service is running. For Harbor, check `docker ps`. For GitLab, ensure your GitLab instance is accessible.
* **Docker login failed:**
* Double-check your username and password (or Personal Access Token for GitLab).
* Ensure you are using the correct registry hostname.
* **Harbor UI not loading:**
* Check the Harbor logs for errors: `sudo docker logs harbor-core`, `sudo docker logs harbor-jobservice`, `sudo docker logs harbor-portal`.
* Verify that Docker Compose is installed correctly and that Harbor's configuration in `harbor.yml` is valid.

## Related Articles

* [[Docker Basics]]
* [[Securing Docker]]
* [[Introduction to Kubernetes]]
* [[Continuous Integration and Continuous Deployment (CI/CD)]]

[[Category:Containerization]]
[[Category:DevOps]]
[[Category:Server Administration]]

Container Registry Setup - Revision history

Admin: New server guide