Running Harbor Locally
If you're willing to contribute to Harbor and/or need its code up & running on your local dev environment then follow along, this guide will get you started.
Harbor is an open-source registry that secures artifacts with policies and role-based access control, ensures images are scanned and free from vulnerabilities, and signs images as trusted.
Here's a video I recorded for the same.
Device Hardware Specs (Recommended)
Before you begin the heavy lifting, you need some hardware juice. Following are some recommendations
Processor: 4 Core Intel i5/i7 10th gen plus or equivalent
RAM: 8GB workable, more is good
Storage: 40-60GB (Docker Images take up space)
If your device doesn't have at least the above specs, maybe try using a cloud VM or GitHub Codespaces or GitPod. There are some great free trials/referral bonuses on providers👨💻
Following is a list of software with versions you need as of March 2023 for version
2.7.0. Check the official build guide to get the latest version details.
*optional, required if you use your own Golang environment.
Test your Go & Docker installations before proceeding.
Forking & Cloning
Fork the official Harbor repository to your account.
Following is a snippet from the CONTRIBUTING.md file. Read the comments.
#Set golang environment
export GOPATH=$HOME/go # Add this to your .bashrc/equivalent file
mkdir -p $GOPATH/src/github.com/goharbor
git clone --depth=1 email@example.com:goharbor/harbor.git # Add URL of your fork here
# Set the depth, you don't need everything
# The below steps can be performed later, you can skip if you want to
#Track repository under your personal account
git config push.default nothing # Anything to avoid pushing to goharbor/harbor by default
git remote rename origin goharbor
git remote add $USER firstname.lastname@example.org:$USER/harbor.git
git fetch $USER
Note: GOPATH can be any directory, the example above uses $HOME/go. Change $USER above to your own GitHub username.
Prerequisite YAML Config
Navigate to the
$GOPATH/src/github.com/goharbor/harbor directory. To get Harbor running, first, a YAML config needs to be done in the
If you want to take a look at the codebase you can open it in VS Code or your favorite IDE/editor.
A sample YAML config file is provided as the
Make a copy of this file or you can rename it as well, I'd recommend you make a copy.
The file should be named
Open the file in your favorite text editor.
The file looks something like this
Let's understand the config changes needed
hostname: Line 5. Hostname to access admin UI. You can provide any non-conflicting URL here
HTTP(S) ports: Lines 10 & 15. The HTTP ports that harbor will run on
private_key: Lines 17, 18. The SSL certificate & key files
Following is how my config looks followed by an explanation
The hostname is a demo subdomain on my domain, it's not live. (Don't hit it hehe)
My development environment is a server VM so ports 80 & 443 are occupied, so I chose different ports.
The certificate & key paths. Their generation is explained in the following section.
Generating SSL Certificate & Key
To generate, you need OpenSSL installed. You can generate by any other way also, if you're clueless, just follow along.
Navigate to the directory you want the credentials to be generated and execute the following command. Replace
demohub.wilfredalmeida.com with the hostname you specified above.
openssl req -x509 \
-sha256 -days 356 \
-newkey rsa:2048 \
-subj "/CN=demohub.wilfredalmeida.com/C=US/L=San Fransisco" \
-keyout rootCA.key -out rootCA.crt
Two files named
rootCA.crt will be generated, specify their paths accordingly in the config and save and exit.
Building and Running Harbor
The bare minimum config needed to get Harbor up & running is now complete.
To run harbor, execute the following command in the project root.
There are other options as well to run this, check out the compile guide
Note: This command will take time to execute. It takes ~25 - 30 mins for me, it depends on your hardware juice. Be patient.
If you're running on WSL, your build might get stuck at the following stage for which I have no solution
Once this build finishes, you'll see a message similar to the following
Start complete. You can visit harbor now.
If the build is completed successfully after the eternity it takes, you can load harbor UI in your browser by going to the HTTPS port on your localhost.
Here's an example
https://localhost:2400. Note that the URL has HTTPS.
You might get a certificate warning in the browser due to the self-signed certificate, ignore that and proceed.
If Harbor loads in your browser then viola, you did it. Good Job!!🤝
To stop harbor, run the following command. It'll stop all running containers for harbor.
Testing code changes
If you want to make some code changes and check them, then run the following command
make versions_prepare compile_core build -e BUILDTARGET="_build_core" -e PULL_BASE_FROM_DOCKERHUB=false prepare start
This command will compile the harbor-core image, build the necessary components for it and redeploy harbor.
If you're working on some other image like the
harbor-portal, specify/replace it at the place of
compile_core in the command.
It depends on your changes, however, the command takes ~2-3 mins to complete for me.
So in this comparatively little time, you can see your changes live
This command is courtesy of Wang Yan. It saves the hassle of executing
25 mins just to see 2 lines of code changes is not a pleasant experience.
Been there, done that. Not at all a pleasant experience😆
That's all. Hope you're able to get Harbor up & running now.
For any queries, help join the Harbor Slack channels at the official CNCF Slack.
Like my content? Check out my other blogs.
Did you find this article valuable?
Support Wilfred Almeida by becoming a sponsor. Any amount is appreciated!