# 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](https://goharbor.io/) 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](https://youtu.be/1U9v2QmERaA) I recorded for the same. ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1680597208246/8392e747-c944-4a5b-baff-7f88d35c0acb.jpeg align="center") ### 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👨‍💻 > > Use these links to get started > [Hetzner](https://hetzner.cloud/?ref=pCRmvzCoA0hO) (Recommended, I use it. Cheap & Powerful) > [DigitalOcean](https://m.do.co/c/c3c6f5ac727e) ### Software Requirements Following is a list of software with versions you need as of March 2023 for version `2.7.0`. Check the official [build guide](https://goharbor.io/docs/2.7.0/build-customize-contribute/compile-guide/) to get the latest version details. | **Software** | **Required Version** | | --- | --- | | docker | 17.05 + | | docker-compose | 1.18.0 + | | python | 2.7 + | | git | 1.9.1 + | | make | 3.81 + | | golang\* | 1.15.6 + | \*optional, required if you use your own Golang environment. Speaking of OS, you need a Linux-based OS. I tried WSL, but it didn't work, builds get stuck. You can use virtualization with [VMware](https://www.vmware.com/) or [Virtual Box](https://www.virtualbox.org/) if you're on Windows. Even Mac-OS works. Test your Go & Docker installations before proceeding. --- ## Forking & Cloning Fork the official [Harbor](https://github.com/goharbor/harbor/) repository to your account. Following is a snippet from the [CONTRIBUTING.md](https://github.com/goharbor/harbor/blob/main/CONTRIBUTING.md) file. Read the comments. ```bash #Set golang environment export GOPATH=$HOME/go # Add this to your .bashrc/equivalent file mkdir -p $GOPATH/src/github.com/goharbor #Get code git clone --depth=1 git@github.com:goharbor/harbor.git # Add URL of your fork here # Set the depth, you don't need everything cd $GOPATH/src/github.com/goharbor/harbor # 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 git@github.com:$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 `make` directory. 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/harbor.yml.tmpl` 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 `harbor.yml` Open the file in your favorite text editor. The file looks something like this ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1680110671708/187b5c21-347d-4196-9ba3-193b59e92d94.png align="center") 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 * `certificate` & `private_key`: Lines 17, 18. The SSL certificate & key files Following is how my config looks followed by an explanation ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1680111020482/b726fe58-a9a5-400d-9d8a-24c07284f56a.jpeg align="center") 1. The hostname is a demo subdomain on my domain, it's not live. *(Don't hit it hehe)* 2. My development environment is a server VM so ports 80 & 443 are occupied, so I chose different ports. 3. The certificate & key paths. Their generation is explained in the following section. ### Generating SSL Certificate & Key To generate, you need [OpenSSL](https://www.openssl.org/) 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. ```bash openssl req -x509 \ -sha256 -days 356 \ -nodes \ -newkey rsa:2048 \ -subj "/CN=demohub.wilfredalmeida.com/C=US/L=San Fransisco" \ -keyout rootCA.key -out rootCA.crt ``` Two files named `rootCA.key` and `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. ```bash make install ``` There are other options as well to run this, check out the [compile guide](https://goharbor.io/docs/2.7.0/build-customize-contribute/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 ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1680113191716/cc3c0a40-18df-47f6-b28e-01e7837ec6fc.png align="center") Once this build finishes, you'll see a message similar to the following ```sh ... Start complete. You can visit harbor now. ``` ### Verifying Installation 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!!🤝 ### Stopping Harbor To stop harbor, run the following command. It'll stop all running containers for harbor. ```bash make down ``` --- ## Testing code changes If you want to make some code changes and check them, then run the following command ```bash 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-db` or `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](https://twitter.com/wy65701436). It saves the hassle of executing `make install` 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](http://cloud-native.slack.com). Reach out to me on [Twitter](https://twitter.com/WilfredAlmeida_) or elsewhere from my [portfolio](https://wilfredalmeida.com/). Like my content? Check out my other [blogs](https://blog.wilfredalmeida.com/).