From 0532735d2162a6e61702229ad669e6751ba8b8ee Mon Sep 17 00:00:00 2001 From: Tan Jiang Date: Tue, 5 Apr 2016 19:48:13 +0800 Subject: [PATCH 01/12] handle the case when docker request token for multiple scopes --- service/token.go | 7 ++++--- service/utils/authutils.go | 31 ++++++++++++++++++------------- service/utils/registryutils.go | 7 ++++--- 3 files changed, 26 insertions(+), 19 deletions(-) diff --git a/service/token.go b/service/token.go index b274be3f8..cd2386833 100644 --- a/service/token.go +++ b/service/token.go @@ -42,13 +42,14 @@ func (a *TokenHandler) Get() { username, password, _ := request.BasicAuth() authenticated := authenticate(username, password) service := a.GetString("service") - scope := a.GetString("scope") + scopes := a.GetStrings("scope") + log.Debugf("scopes: %+v", scopes) - if len(scope) == 0 && !authenticated { + if len(scopes) == 0 && !authenticated { log.Info("login request with invalid credentials") a.CustomAbort(http.StatusUnauthorized, "") } - access := svc_utils.GetResourceActions(scope) + access := svc_utils.GetResourceActions(scopes) for _, a := range access { svc_utils.FilterAccess(username, authenticated, a) } diff --git a/service/utils/authutils.go b/service/utils/authutils.go index 4c00dd579..c8a33710d 100644 --- a/service/utils/authutils.go +++ b/service/utils/authutils.go @@ -38,17 +38,19 @@ const ( ) // GetResourceActions ... -func GetResourceActions(scope string) []*token.ResourceActions { +func GetResourceActions(scopes []string) []*token.ResourceActions { var res []*token.ResourceActions - if scope == "" { - return res + for _, s := range scopes { + if s == "" { + continue + } + items := strings.Split(s, ":") + res = append(res, &token.ResourceActions{ + Type: items[0], + Name: items[1], + Actions: strings.Split(items[2], ","), + }) } - items := strings.Split(scope, ":") - res = append(res, &token.ResourceActions{ - Type: items[0], - Name: items[1], - Actions: strings.Split(items[2], ","), - }) return res } @@ -66,9 +68,12 @@ func FilterAccess(username string, authenticated bool, a *token.ResourceActions) if strings.Contains(a.Name, "/") { //Only check the permission when the requested image has a namespace, i.e. project projectName := a.Name[0:strings.LastIndex(a.Name, "/")] var permission string - var err error if authenticated { - if username == "admin" { + isAdmin, err := dao.IsAdminRole(username) + if err != nil { + log.Errorf("Error occurred in IsAdminRole: %v") + } + if isAdmin { exist, err := dao.ProjectExists(projectName) if err != nil { log.Errorf("Error occurred in CheckExistProject: %v", err) @@ -100,8 +105,8 @@ func FilterAccess(username string, authenticated bool, a *token.ResourceActions) } // GenTokenForUI is for the UI process to call, so it won't establish a https connection from UI to proxy. -func GenTokenForUI(username, service, scope string) (string, error) { - access := GetResourceActions(scope) +func GenTokenForUI(username string, service string, scopes []string) (string, error) { + access := GetResourceActions(scopes) for _, a := range access { FilterAccess(username, true, a) } diff --git a/service/utils/registryutils.go b/service/utils/registryutils.go index 66c39cd1f..37ada5426 100644 --- a/service/utils/registryutils.go +++ b/service/utils/registryutils.go @@ -63,14 +63,15 @@ func RegistryAPIGet(url, username string) ([]byte, error) { authenticate := response.Header.Get("WWW-Authenticate") log.Debugf("authenticate header: %s", authenticate) var service string - var scope string + var scopes []string + //Disregard the case for hanlding multiple scopes for http call initiated from UI, as there's refactor planned. re := regexp.MustCompile(`service=\"(.*?)\".*scope=\"(.*?)\"`) res := re.FindStringSubmatch(authenticate) if len(res) > 2 { service = res[1] - scope = res[2] + scopes = append(scopes, res[2]) } - token, err := GenTokenForUI(username, service, scope) + token, err := GenTokenForUI(username, service, scopes) if err != nil { return nil, err } From 3a3262d1e17d4558476ccab629505d6c0e7e4dd8 Mon Sep 17 00:00:00 2001 From: Tan Jiang Date: Tue, 5 Apr 2016 20:04:29 +0800 Subject: [PATCH 02/12] fix error in go vet --- service/utils/authutils.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/service/utils/authutils.go b/service/utils/authutils.go index c8a33710d..c8bdd6d59 100644 --- a/service/utils/authutils.go +++ b/service/utils/authutils.go @@ -71,7 +71,7 @@ func FilterAccess(username string, authenticated bool, a *token.ResourceActions) if authenticated { isAdmin, err := dao.IsAdminRole(username) if err != nil { - log.Errorf("Error occurred in IsAdminRole: %v") + log.Errorf("Error occurred in IsAdminRole: %v", err) } if isAdmin { exist, err := dao.ProjectExists(projectName) From 8dd59b77e8c141953321bc5c532b96f95ae08351 Mon Sep 17 00:00:00 2001 From: Tan Jiang Date: Thu, 7 Apr 2016 16:49:11 +0800 Subject: [PATCH 03/12] add schema version to db --- Deploy/db/registry.sql | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/Deploy/db/registry.sql b/Deploy/db/registry.sql index b560aeeb8..9e4a342b3 100644 --- a/Deploy/db/registry.sql +++ b/Deploy/db/registry.sql @@ -101,3 +101,12 @@ create table access_log ( FOREIGN KEY (user_id) REFERENCES user(user_id), FOREIGN KEY (project_id) REFERENCES project (project_id) ); + +create table properties ( + k varchar(64) NOT NULL, + v varchar(128) NOT NULL, + primary key (k) + ); + +insert into properties (k, v) values +('schema_version', '0.1.1'); From 42c398fac8f45d986bd5c9ad91e9a16dc06bbf07 Mon Sep 17 00:00:00 2001 From: Tan Jiang Date: Thu, 7 Apr 2016 18:34:12 +0800 Subject: [PATCH 04/12] refactor --- Deploy/docker-compose.yml | 4 +++- Dockerfile => Dockerfile.ui | 10 ++++------ main.go => ui/main.go | 2 +- {routers => ui}/router.go | 10 +++++----- 4 files changed, 13 insertions(+), 13 deletions(-) rename Dockerfile => Dockerfile.ui (78%) rename main.go => ui/main.go (98%) rename {routers => ui}/router.go (92%) diff --git a/Deploy/docker-compose.yml b/Deploy/docker-compose.yml index 2a223cd95..0bead2e5d 100644 --- a/Deploy/docker-compose.yml +++ b/Deploy/docker-compose.yml @@ -36,7 +36,9 @@ services: syslog-address: "tcp://127.0.0.1:1514" syslog-tag: "mysql" ui: - build: ../ + build: + context: ../ + dockerfile: Dockerfile.ui env_file: - ./config/ui/env volumes: diff --git a/Dockerfile b/Dockerfile.ui similarity index 78% rename from Dockerfile rename to Dockerfile.ui index 535881d3b..459158279 100644 --- a/Dockerfile +++ b/Dockerfile.ui @@ -9,30 +9,28 @@ RUN apt-get update \ COPY . /go/src/github.com/vmware/harbor #golang.org is blocked in China COPY ./vendor/golang.org /go/src/golang.org -WORKDIR /go/src/github.com/vmware/harbor +WORKDIR /go/src/github.com/vmware/harbor/ui ENV GO15VENDOREXPERIMENT 1 RUN go get -d github.com/docker/distribution \ && go get -d github.com/docker/libtrust \ && go get -d github.com/go-sql-driver/mysql \ - && go install -v -a + && go build -v -a -o /go/bin/harbor_ui ENV MYSQL_USR root \ MYSQL_PWD root \ - MYSQL_PORT_3306_TCP_ADDR localhost \ - MYSQL_PORT_3306_TCP_PORT 3306 \ REGISTRY_URL localhost:5000 COPY views /go/bin/views COPY static /go/bin/static COPY favicon.ico /go/bin/favicon.ico -RUN chmod u+x /go/bin/harbor \ +RUN chmod u+x /go/bin/harbor_ui \ && sed -i 's/TLS_CACERT/#TLS_CAERT/g' /etc/ldap/ldap.conf \ && sed -i '$a\TLS_REQCERT allow' /etc/ldap/ldap.conf WORKDIR /go/bin/ -ENTRYPOINT ["/go/bin/harbor"] +ENTRYPOINT ["/go/bin/harbor_ui"] EXPOSE 80 diff --git a/main.go b/ui/main.go similarity index 98% rename from main.go rename to ui/main.go index 60d36bfd1..fdfd3f139 100644 --- a/main.go +++ b/ui/main.go @@ -24,7 +24,6 @@ import ( _ "github.com/vmware/harbor/auth/ldap" "github.com/vmware/harbor/dao" "github.com/vmware/harbor/models" - _ "github.com/vmware/harbor/routers" "os" @@ -71,5 +70,6 @@ func main() { if err := updateInitPassword(adminUserID, os.Getenv("HARBOR_ADMIN_PASSWORD")); err != nil { log.Error(err) } + initRouters() beego.Run() } diff --git a/routers/router.go b/ui/router.go similarity index 92% rename from routers/router.go rename to ui/router.go index 6cce814bc..1853192f0 100644 --- a/routers/router.go +++ b/ui/router.go @@ -13,7 +13,7 @@ limitations under the License. */ -package routers +package main import ( "github.com/vmware/harbor/api" @@ -23,11 +23,11 @@ import ( "github.com/astaxie/beego" ) -func init() { +func initRouters() { - beego.SetStaticPath("registry/static/i18n", "static/i18n") - beego.SetStaticPath("registry/static/resources", "static/resources") - beego.SetStaticPath("registry/static/vendors", "static/vendors") + beego.SetStaticPath("registry/static/i18n", "/static/i18n") + beego.SetStaticPath("registry/static/resources", "/static/resources") + beego.SetStaticPath("registry/static/vendors", "/static/vendors") beego.Router("/login", &controllers.CommonController{}, "post:Login") beego.Router("/logout", &controllers.CommonController{}, "get:Logout") From d725947517e971a215fc35bbadce40b95d7f4b08 Mon Sep 17 00:00:00 2001 From: Tan Jiang Date: Thu, 7 Apr 2016 18:44:29 +0800 Subject: [PATCH 05/12] fix path typo --- ui/router.go | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ui/router.go b/ui/router.go index 1853192f0..4eb04108b 100644 --- a/ui/router.go +++ b/ui/router.go @@ -25,9 +25,9 @@ import ( func initRouters() { - beego.SetStaticPath("registry/static/i18n", "/static/i18n") - beego.SetStaticPath("registry/static/resources", "/static/resources") - beego.SetStaticPath("registry/static/vendors", "/static/vendors") + beego.SetStaticPath("registry/static/i18n", "static/i18n") + beego.SetStaticPath("registry/static/resources", "static/resources") + beego.SetStaticPath("registry/static/vendors", "static/vendors") beego.Router("/login", &controllers.CommonController{}, "post:Login") beego.Router("/logout", &controllers.CommonController{}, "get:Logout") From 306065f54d646c03599be6d5edc727496de4082d Mon Sep 17 00:00:00 2001 From: Alexander Zeitler Date: Thu, 7 Apr 2016 22:43:52 +0200 Subject: [PATCH 06/12] Add documentation to run Harbor using Docker Machine. --- docs/installation_guide.md | 57 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/docs/installation_guide.md b/docs/installation_guide.md index 1a7ddf3fa..ebe953297 100644 --- a/docs/installation_guide.md +++ b/docs/installation_guide.md @@ -140,3 +140,60 @@ Removing harbor_mysql_1 ... done ### Persistent data and log files By default, the data of database and image files in the registry are persisted in the directory **/data/** of the target machine. When Harbor's containers are removed and recreated, the data remain unchanged. Harbor leverages rsyslog to collect the logs of each container, by default the log files are stored in the directory **/var/log/harbor/** on Harbor's host. + +### Deploying Harbor using Docker Machine +Docker Machine allows you to deploy your containers to several cloud providers or on premises using a unified interface. +To deploy Harbor using Docker Machine, first create a virtual machine using Docker Machine. + +This example will use DigitalOcean, but you can use VMware vCloud Air, AWS or Azure as well. Please see the list of supported drivers in the [Docker Machine driver documentation](https://docs.docker.com/machine/drivers/). + +``` +$ docker-machine create --driver digitalocean --digitalocean-access-token harbor.mydomain.com +``` + +After the machine has been created successfully, you need to create a DNS entry at your provider for e.g. harbor.mydomain.com using the IP address for the machine we just created. +You can get this IP address using: + +``` +$ docker-machine ip harbor.mydomain.com +``` + +Make sure to change the `hostname` in `Deploy/harbor.cfg` to `harbor.mydomain.com` and run `prepare`. + +Now, activate the created Docker Machine instance: + +`$ eval $(docker-machine env harbor.mydomain.com)` + +From within the `Deploy` directory, next copy the contents of the `config` directory to the machine. +First, get your local path to the `Deploy` directory: + +``` +$ echo $PWD +``` + +This will give you something like this: + +``` +/home//src/harbor/Deploy +``` + +Then create this directory structure on the remote machine and copy the local files to the remote folders: + +``` +$ docker-machine ssh harbor.mydomain.com 'mkdir -p /home//src/harbor/Deploy/config +$ docker-machine scp -r ./config harbor.mydomain.com:$PWD +``` + +Next, build your Harbor images: + +``` +$ docker-compose build +``` + +And finally, spin up your Harbor containers: + +``` +$ docker-compose up -d +``` + +Now you should be able to browse `http://harbor.mydomain.com`. \ No newline at end of file From c8781cf66f60cc4454b75c92f1973cd78378ebec Mon Sep 17 00:00:00 2001 From: Tan Jiang Date: Fri, 8 Apr 2016 12:06:56 +0800 Subject: [PATCH 07/12] create contrib directory --- contrib/README.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 contrib/README.md diff --git a/contrib/README.md b/contrib/README.md new file mode 100644 index 000000000..b11059165 --- /dev/null +++ b/contrib/README.md @@ -0,0 +1 @@ +The `contrib` directory contains documents, scripts, and other helpful things which are contributed by community. From b10387c6a92552b3762f7585be2809aa3ac2ac15 Mon Sep 17 00:00:00 2001 From: Alexander Zeitler Date: Fri, 8 Apr 2016 10:06:43 +0200 Subject: [PATCH 08/12] Move Docker Machine installation guide to contrib folder. --- contrib/deploying_using_docker_machine.md | 56 +++++++++++++++++++++ docs/installation_guide.md | 59 +---------------------- 2 files changed, 57 insertions(+), 58 deletions(-) create mode 100644 contrib/deploying_using_docker_machine.md diff --git a/contrib/deploying_using_docker_machine.md b/contrib/deploying_using_docker_machine.md new file mode 100644 index 000000000..e010dbdb0 --- /dev/null +++ b/contrib/deploying_using_docker_machine.md @@ -0,0 +1,56 @@ +### Deploying Harbor using Docker Machine +Docker Machine allows you to deploy your containers to several cloud providers or on premises using a unified interface. +To deploy Harbor using Docker Machine, first create a virtual machine using Docker Machine. + +This example will use DigitalOcean, but you can use VMware vCloud Air, AWS or Azure as well. Please see the list of supported drivers in the [Docker Machine driver documentation](https://docs.docker.com/machine/drivers/). + +``` +$ docker-machine create --driver digitalocean --digitalocean-access-token harbor.mydomain.com +``` + +After the machine has been created successfully, you need to create a DNS entry at your provider for e.g. harbor.mydomain.com using the IP address for the machine we just created. +You can get this IP address using: + +``` +$ docker-machine ip harbor.mydomain.com +``` + +Make sure to change the `hostname` in `Deploy/harbor.cfg` to `harbor.mydomain.com`, configure everything else according to the [Harbor Installation Guide](../docs/insallation_guide.md) and run `prepare`. + +Now, activate the created Docker Machine instance: + +`$ eval $(docker-machine env harbor.mydomain.com)` + +From within the `Deploy` directory, next copy the contents of the `config` directory to the machine. +First, get your local path to the `Deploy` directory: + +``` +$ echo $PWD +``` + +This will give you something like this: + +``` +/home//src/harbor/Deploy +``` + +Then create this directory structure on the remote machine and copy the local files to the remote folders: + +``` +$ docker-machine ssh harbor.mydomain.com 'mkdir -p /home//src/harbor/Deploy/config +$ docker-machine scp -r ./config harbor.mydomain.com:$PWD +``` + +Next, build your Harbor images: + +``` +$ docker-compose build +``` + +And finally, spin up your Harbor containers: + +``` +$ docker-compose up -d +``` + +Now you should be able to browse `http://harbor.mydomain.com`. \ No newline at end of file diff --git a/docs/installation_guide.md b/docs/installation_guide.md index ebe953297..7c5471a4b 100644 --- a/docs/installation_guide.md +++ b/docs/installation_guide.md @@ -139,61 +139,4 @@ Removing harbor_mysql_1 ... done ### Persistent data and log files By default, the data of database and image files in the registry are persisted in the directory **/data/** of the target machine. When Harbor's containers are removed and recreated, the data remain unchanged. -Harbor leverages rsyslog to collect the logs of each container, by default the log files are stored in the directory **/var/log/harbor/** on Harbor's host. - -### Deploying Harbor using Docker Machine -Docker Machine allows you to deploy your containers to several cloud providers or on premises using a unified interface. -To deploy Harbor using Docker Machine, first create a virtual machine using Docker Machine. - -This example will use DigitalOcean, but you can use VMware vCloud Air, AWS or Azure as well. Please see the list of supported drivers in the [Docker Machine driver documentation](https://docs.docker.com/machine/drivers/). - -``` -$ docker-machine create --driver digitalocean --digitalocean-access-token harbor.mydomain.com -``` - -After the machine has been created successfully, you need to create a DNS entry at your provider for e.g. harbor.mydomain.com using the IP address for the machine we just created. -You can get this IP address using: - -``` -$ docker-machine ip harbor.mydomain.com -``` - -Make sure to change the `hostname` in `Deploy/harbor.cfg` to `harbor.mydomain.com` and run `prepare`. - -Now, activate the created Docker Machine instance: - -`$ eval $(docker-machine env harbor.mydomain.com)` - -From within the `Deploy` directory, next copy the contents of the `config` directory to the machine. -First, get your local path to the `Deploy` directory: - -``` -$ echo $PWD -``` - -This will give you something like this: - -``` -/home//src/harbor/Deploy -``` - -Then create this directory structure on the remote machine and copy the local files to the remote folders: - -``` -$ docker-machine ssh harbor.mydomain.com 'mkdir -p /home//src/harbor/Deploy/config -$ docker-machine scp -r ./config harbor.mydomain.com:$PWD -``` - -Next, build your Harbor images: - -``` -$ docker-compose build -``` - -And finally, spin up your Harbor containers: - -``` -$ docker-compose up -d -``` - -Now you should be able to browse `http://harbor.mydomain.com`. \ No newline at end of file +Harbor leverages rsyslog to collect the logs of each container, by default the log files are stored in the directory **/var/log/harbor/** on Harbor's host. \ No newline at end of file From 65e20339d980396a7be4842362b5c676b49435a6 Mon Sep 17 00:00:00 2001 From: Alexander Zeitler Date: Fri, 8 Apr 2016 10:17:53 +0200 Subject: [PATCH 09/12] Fix broken link to Installation Guide. --- contrib/deploying_using_docker_machine.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contrib/deploying_using_docker_machine.md b/contrib/deploying_using_docker_machine.md index e010dbdb0..d14e8f872 100644 --- a/contrib/deploying_using_docker_machine.md +++ b/contrib/deploying_using_docker_machine.md @@ -15,7 +15,7 @@ You can get this IP address using: $ docker-machine ip harbor.mydomain.com ``` -Make sure to change the `hostname` in `Deploy/harbor.cfg` to `harbor.mydomain.com`, configure everything else according to the [Harbor Installation Guide](../docs/insallation_guide.md) and run `prepare`. +Make sure to change the `hostname` in `Deploy/harbor.cfg` to `harbor.mydomain.com`, configure everything else according to the [Harbor Installation Guide](../docs/installation_guide.md) and run `prepare`. Now, activate the created Docker Machine instance: @@ -53,4 +53,4 @@ And finally, spin up your Harbor containers: $ docker-compose up -d ``` -Now you should be able to browse `http://harbor.mydomain.com`. \ No newline at end of file +Now you should be able to browse `http://harbor.mydomain.com`. From 2cfbbda2a342dcb821f73ac234d525e1b0e661ad Mon Sep 17 00:00:00 2001 From: Henry Zhang Date: Fri, 8 Apr 2016 17:04:47 +0800 Subject: [PATCH 10/12] document update --- Deploy/harbor.cfg | 3 +- README.md | 17 ++--- docs/installation_guide.md | 129 +++++++++++++++++++++++++++---------- 3 files changed, 105 insertions(+), 44 deletions(-) diff --git a/Deploy/harbor.cfg b/Deploy/harbor.cfg index b89a5d03c..90dc66540 100644 --- a/Deploy/harbor.cfg +++ b/Deploy/harbor.cfg @@ -30,6 +30,7 @@ ldap_basedn = uid=%s,ou=people,dc=mydomain,dc=com #The password for the root user of mysql db, change this before any production use. db_password = root123 -#Switch for self-registration feature + +#Turn on or off the self-registration feature self_registration = on ##### diff --git a/README.md b/README.md index cbf84220b..44a872e17 100644 --- a/README.md +++ b/README.md @@ -16,11 +16,11 @@ Project Harbor is an enterprise-class registry server. It extends the open sourc * **Internationalization**: Localized for English and Chinese languages. More languages can be added. * **RESTful API**: RESTful APIs are provided for most administrative operations of Harbor. The integration with other management softwares becomes easy. -### Try it -Harbor is self-contained and can be easily deployed via docker-compose. +### Getting Started +Harbor is self-contained and can be easily deployed via docker-compose. The below is a quick-start guide. Refer to the [Installation and Configuration Guide](docs/installation_guide.md) for detail information. **System requirements:** -Harbor only works with docker 1.8+ and docker-compose 1.6.0+ . +Harbor only works with docker 1.10+ and docker-compose 1.6.0+ . The host must be connected to the Internet. 1. Get the source code: @@ -43,16 +43,17 @@ The host must be connected to the Internet. $ docker-compose up ``` -If everything works fine, you can open a browser to visit the admin portal at http://your_registry_host . The default administrator username and password are admin/Harbor12345 . -After creating a project in the admin portal, you can login and use docker commands to push images. The default port of Harbor registry server is 80: +If everything works fine, you can open a browser to visit the admin portal at http://reg.yourdomain.com . The default administrator username and password are admin/Harbor12345 . + +Create a new project, e.g. myproject, in the admin portal. You can then use docker commands to login and push images. The default port of Harbor registry server is 80: ```sh -$ docker login your_registry_host -$ docker push your_registry_host/myrepo/myapp +$ docker login reg.yourdomain.com +$ docker push reg.yourdomain.com/myproject/myrepo ``` **NOTE:** -To simplify the installation process, a pre-built installation package of Harbor is provided so that you don't need to clone the source code. By using this package, you can even install Harbor onto a host that is not connected to the Internet. For details on how to download and use this installation package, please refer to [Installation Guide](docs/installation_guide.md) . +To simplify the installation process, a pre-built installation package of Harbor is provided so that you don't need to clone the source code. By using this package, you can even install Harbor onto a host that is not connected to the Internet. For details on how to download and use this installation package, please refer to [Installation and Configuration Guide](docs/installation_guide.md) . For information on how to use Harbor, please see [User Guide](docs/user_guide.md) . diff --git a/docs/installation_guide.md b/docs/installation_guide.md index 7c5471a4b..03395eb7a 100644 --- a/docs/installation_guide.md +++ b/docs/installation_guide.md @@ -1,35 +1,31 @@ -# Installation Guide of Harbor -### Download the installation package -Harbor can be installed from the source code by using "docker-compose up" command, which goes through a full build process. Besides, a pre-built installation package of each release can be downloaded from the [release page](https://github.com/vmware/harbor/releases). This guide describes the installation of Harbor by using the pre-built package. -### Prerequisites for target machine +# Installation and Configuration Guide of Harbor +Harbor can be installed by two approaches: + +1. Install from the source code, which goes through a full build process. Internet connection is required. +2. Install via a pre-built installation package, which saves time for building the code. Further, it provides a way to install Harbor to a host that is isolated from the Internet (offline installation). + +This guide describes both approaches and their usage. + +## Prerequisites of the target host Harbor is deployed as several Docker containers. Hence, it can be deployed on any Linux distribution that supports Docker. -Before deploying Harbor, the target machine requires Python, Docker, Docker Compose to be installed. +Before deploying Harbor, the target host requires Python, Docker, Docker Compose to be installed. * Python should be version 2.7 or higher. Some Linux distributions (Gentoo, Arch) may not have a Python interpreter installed by default. On those systems, you need to install Python manually. * The Docker engine should be version 1.10 or higher. For the details to install Docker engine, please refer to: https://docs.docker.com/engine/installation/ * The Docker Compose needs to be version 1.6.0 or higher. For the details to install Docker compose, please refer to: https://docs.docker.com/compose/install/ -### Configuration of Harbor -After downloading the package file **harbor-<version>.tgz** from the release page, you need to extract files from the package. Before installing Harbor, you should configure the parameters in the file **harbor.cfg**. You then execute the **prepare** script to generate configuration files for Harbor's containers. Finally, you use Docker Compose to start Harbor. -At minimum, you only need to change the **hostname** attribute in **harbor.cfg** by updating the IP address or the fully qualified domain name (FQDN) of your target machine, for example 192.168.1.10. Please see the next section for the description of each parameter. -``` -$ tar -xzvf harbor-0.1.0.tgz -$ cd harbor -$ vi ./harbor.cfg -...... -$ ./prepare -Generated configuration file: ./config/ui/env -Generated configuration file: ./config/ui/app.conf -Generated configuration file: ./config/registry/config.yml -Generated configuration file: ./config/db/env -The configuration files are ready, please use docker-compose to start the service. -$ sudo docker-compose up -d -...... -``` -After that, you can open a browser and access Harbor via the IP you set in harbor.cfg, such as http://192.168.1.10 . The same IP address is used as the Registry address in your Docker client, for example: -```docker pull 192.168.1.10/library/ubuntu``` +## Install Harbor from the source code -#### Parameters in harbor.cfg -**hostname**: The endpoint for a user to access the user interface and the registry service, for example 192.168.1.10 or exampledomian.com. +To install from the source, the target host must be connected to the Internet. +#### Get the source code: + ```sh + $ git clone https://github.com/vmware/harbor + ``` +#### Configure Harbor +Before installing Harbor, you should configure the parameters in the file **harbor.cfg**. You then execute the **prepare** script to generate configuration files for Harbor's containers. Finally, you use Docker Compose to start Harbor. + +At minimum, you need to change the **hostname** attribute in **harbor.cfg**. The description of each attribute is as follows: + +**hostname**: The hostname for a user to access the user interface and the registry service. It should be the IP address or the fully qualified domain name (FQDN) of your target machine, for example 192.168.1.10 or reg.yourdomain.com . Do NOT use localhost or 127.0.0.1 for the hostname because the registry service needs to be accessed by external clients. **ui_url_protocol**: The protocol for accessing the user interface and the token/notification service, by default it is http. **Email settings**: the following 5 attributes are used to send an email to reset a user's password, they are not mandatory unless the password reset function is needed in Harbor. * email_server = smtp.mydomain.com @@ -42,13 +38,67 @@ After that, you can open a browser and access Harbor via the IP you set in harbo **auth_mode**: The authentication mode of Harbor. By default it is *db_auth*, i.e. the credentials are stored in a database. Please set it to *ldap_auth* if you want to verify user's credentials against an LDAP server. **ldap_url**: The URL for LDAP endpoint, for example ldaps://ldap.mydomain.com. It is only used when **auth_mode** is set to *ldap_auth*. **ldap_basedn**: The basedn template for verifying the user's credentials against LDAP, for example uid=%s,ou=people,dc=mydomain,dc=com. It is only used when **auth_mode** is set to *ldap_auth*. -**db_password**: The password of root user of mySQL database. +**db_password**: The password of root user of mySQL database. +**self_registration**: The flag to turn on or off the user self-registration function. If this flag is turned off, only an admin user can create new users in Harbor. The default value is on. + +#### Build and start Harbor +After configuring harbor.cfg, build and start Harbor by the following commands. Because it requires downloading necesary files from the Internet, it may take a while for the docker-compose process to finish. + + ```sh + $ cd Deploy + + $ ./prepare + Generated configuration file: ./config/ui/env + Generated configuration file: ./config/ui/app.conf + Generated configuration file: ./config/registry/config.yml + Generated configuration file: ./config/db/env + The configuration files are ready, please use docker-compose to start the service. + + $ sudo docker-compose up -d + ``` + +If everything works fine, you can open a browser to visit the admin portal at http://reg.yourdomain.com . The default administrator username and password are admin/Harbor12345 . + +Create a new project, e.g. myproject, in the admin portal. You can then use docker commands to login and push images. The default port of Harbor registry server is 80: +```sh +$ docker login reg.yourdomain.com +$ docker push reg.yourdomain.com/myproject/myrepo +``` +**NOTE:** The default installation of Harbor uses HTTP protocol, you should add the option "--insecure-registry" to your client's Docker daemon and restart Docker service. + +For information on how to use Harbor, please refer to [User Guide of Harbor](user_guide.md) . + +#### Configure Harbor with HTTPS Access +Because Harbor does not ship with any certificates, it uses HTTP by default to serve registry requests. This makes it relatively simple to configure, especially for a development or testing environment. However, it is highly recommended that security be enabled for any production environment. Refer to [Configure Harbor with HTTPS Access](configure_https.md) if you want to enable HTTPS access to Harbor. + +## Install Harbor via a pre-built installation package + +A pre-built installation package of each release can be downloaded from the [release page](https://github.com/vmware/harbor/releases). After downloading the package file **harbor-<version>.tgz** , extract files in the package. +``` +$ tar -xzvf harbor-0.1.1.tgz +$ cd harbor +``` + +Then configure Harbor by following instructions in Section [Configure Harbor](#markdown-header-configure-harbor). Next, run **prepare** script to generate config files and use docker compose to build Harbor's container images and eventually spin it up. + + +``` +$ ./prepare +Generated configuration file: ./config/ui/env +Generated configuration file: ./config/ui/app.conf +Generated configuration file: ./config/registry/config.yml +Generated configuration file: ./config/db/env +The configuration files are ready, please use docker-compose to start the service. + +$ sudo docker-compose up -d +...... +``` ### Deploy Harbor to a target machine that does not have Internet access When you run *docker-compose up* to start Harbor, it will pull base images from Docker Hub and build new images for the containers. This process requires accessing the Internet. If you want to deploy Harbor to a host that is not connected to the Internet, you need to prepare Harbor on a machine that has access to the Internet. After that, you export the images as tgz files and transfer them to the target machine, then load the tgz file into Docker's local image repo. #### Build and save images for offline installation -On a machine that is connected to the Internet, extract files from the installation package. Then run command "docker-compose build" to build the images and use the script *save_image.sh* to export them as tar files. The tar files will be stored in **images** directory. Next, package everything in the directory **harbor** into a tgz file and transfer it to the target machine. This can be done by executing the following commands: +On a machine that is connected to the Internet, extract files from the pre-built installation package. Then run command "docker-compose build" to build the images and use the script *save_image.sh* to export them as tar files. The tar files will be stored in **images** directory. Next, package everything in the directory **harbor** into a tgz file and transfer it to the target machine. This can be done by executing the following commands: ``` $ cd harbor @@ -66,14 +116,15 @@ finished saving the image of nginx saving the image of registry finished saving the image of registry $ cd ../ -$ tar -cvzf harbor_offline-0.1.0.tgz harbor +$ tar -cvzf harbor_offline-0.1.1.tgz harbor ``` -The package file **harbor_offline-0.1.0.tgz** contains the images saved by previously steps and the files required to start Harbor. -You can use tools such as scp to transfer the file **harbor_offline-0.1.0.tgz** to the target machine that does not have Internet connection. On the target machine, you can execute the following commands to start Harbor. Again, before running the **prepare** script, be sure to update **harbor.cfg** to reflect the right configuration of the target machine. +The file **harbor_offline-0.1.0.tgz** contains the images saved by previously steps and the files required to start Harbor. +You can use tools such as scp to transfer the file **harbor_offline-0.1.0.tgz** to the target machine that does not have Internet connection. On the target machine, you can execute the following commands to start Harbor. Again, before running the **prepare** script, be sure to update **harbor.cfg** to reflect the right configuration of the target machine. (Refer to Section [Configure Harbor](#markdown-header-configure-harbor) .) ``` -$ tar -xzvf harbor_offline-0.1.tgz +$ tar -xzvf harbor_offline-0.1.1.tgz $ cd harbor + # load images save by excute ./save_image.sh $ ./load_image.sh loading the image of harbor_ui @@ -84,12 +135,14 @@ loading the image of nginx finished loading the image of nginx loading the image of registry finished loading the image of registry + # Make update to the parameters in ./harbor.cfg $ ./prepare Generated configuration file: ./config/ui/env Generated configuration file: ./config/ui/app.conf Generated configuration file: ./config/registry/config.yml Generated configuration file: ./config/db/env + The configuration files are ready, please use docker-compose to start the service. # Build the images and then start the services $ sudo docker-compose up -d @@ -125,7 +178,7 @@ Starting harbor_registry_1 Starting harbor_ui_1 Starting harbor_proxy_1 ```` -Remove Harbor's containers (the image data and Harbor's database files remains on the file system): +Remove Harbor's containers while keeping the image data and Harbor's database files on the file system: ``` $ sudo docker-compose rm Going to remove harbor_proxy_1, harbor_ui_1, harbor_registry_1, harbor_mysql_1, harbor_log_1 @@ -135,8 +188,14 @@ Removing harbor_ui_1 ... done Removing harbor_registry_1 ... done Removing harbor_mysql_1 ... done ``` + +Remove Harbor's database and image data (for a clean reinstallation): +```sh +$ rm -r /data/database +$ rm -r /data/registry +``` + [Docker Compose command-line reference](https://docs.docker.com/compose/reference/) describes the usage information for the docker-compose subcommands. ### Persistent data and log files -By default, the data of database and image files in the registry are persisted in the directory **/data/** of the target machine. When Harbor's containers are removed and recreated, the data remain unchanged. -Harbor leverages rsyslog to collect the logs of each container, by default the log files are stored in the directory **/var/log/harbor/** on Harbor's host. \ No newline at end of file +By default, the data of database and image files in the registry are persisted in the directory **/data/** of the target machine. When Harbor's containers are removed and recreated, the data remain unchanged. Harbor leverages rsyslog to collect the logs of each container, by default the log files are stored in the directory **/var/log/harbor/** on Harbor's host. From 659e8a9e108baab30a33fcefd2add5d15a22cb1d Mon Sep 17 00:00:00 2001 From: Henry Zhang Date: Fri, 8 Apr 2016 17:26:53 +0800 Subject: [PATCH 11/12] update readme & installation guide --- README.md | 4 +-- docs/installation_guide.md | 52 ++++++++++++++++++++------------------ 2 files changed, 29 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 44a872e17..88b93ad34 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ Project Harbor is an enterprise-class registry server. It extends the open sourc * **RESTful API**: RESTful APIs are provided for most administrative operations of Harbor. The integration with other management softwares becomes easy. ### Getting Started -Harbor is self-contained and can be easily deployed via docker-compose. The below is a quick-start guide. Refer to the [Installation and Configuration Guide](docs/installation_guide.md) for detail information. +Harbor is self-contained and can be easily deployed via docker-compose. The below are quick-start steps. Refer to the [Installation and Configuration Guide](docs/installation_guide.md) for detail information. **System requirements:** Harbor only works with docker 1.10+ and docker-compose 1.6.0+ . @@ -28,7 +28,7 @@ The host must be connected to the Internet. ```sh $ git clone https://github.com/vmware/harbor ``` -2. Edit the file **Deploy/harbor.cfg**, make necessary configuration changes such as hostname, admin password and mail server. Refer to [Installation Guide](docs/installation_guide.md) for more info. +2. Edit the file **Deploy/harbor.cfg**, make necessary configuration changes such as hostname, admin password and mail server. Refer to [Installation and Configuration Guide](docs/installation_guide.md) for more info. 3. Install Harbor by the following commands. It may take a while for the docker-compose process to finish. diff --git a/docs/installation_guide.md b/docs/installation_guide.md index 03395eb7a..c6f26be4c 100644 --- a/docs/installation_guide.md +++ b/docs/installation_guide.md @@ -1,8 +1,8 @@ # Installation and Configuration Guide of Harbor Harbor can be installed by two approaches: -1. Install from the source code, which goes through a full build process. Internet connection is required. -2. Install via a pre-built installation package, which saves time for building the code. Further, it provides a way to install Harbor to a host that is isolated from the Internet (offline installation). +1. Installing from the source code, which goes through a full build process. Internet connection is required. +2. Installing via a pre-built installation package, which saves time for building the code. Further, it provides a way to install Harbor to a host that is isolated from the Internet (offline installation). This guide describes both approaches and their usage. @@ -13,19 +13,21 @@ Before deploying Harbor, the target host requires Python, Docker, Docker Compose * The Docker engine should be version 1.10 or higher. For the details to install Docker engine, please refer to: https://docs.docker.com/engine/installation/ * The Docker Compose needs to be version 1.6.0 or higher. For the details to install Docker compose, please refer to: https://docs.docker.com/compose/install/ -## Install Harbor from the source code +## Installing Harbor from the source code To install from the source, the target host must be connected to the Internet. -#### Get the source code: - ```sh - $ git clone https://github.com/vmware/harbor - ``` -#### Configure Harbor +#### Getting the source code: + +```sh +$ git clone https://github.com/vmware/harbor +``` + +#### Configuring Harbor Before installing Harbor, you should configure the parameters in the file **harbor.cfg**. You then execute the **prepare** script to generate configuration files for Harbor's containers. Finally, you use Docker Compose to start Harbor. At minimum, you need to change the **hostname** attribute in **harbor.cfg**. The description of each attribute is as follows: -**hostname**: The hostname for a user to access the user interface and the registry service. It should be the IP address or the fully qualified domain name (FQDN) of your target machine, for example 192.168.1.10 or reg.yourdomain.com . Do NOT use localhost or 127.0.0.1 for the hostname because the registry service needs to be accessed by external clients. +**hostname**: The hostname for a user to access the user interface and the registry service. It should be the IP address or the fully qualified domain name (FQDN) of your target machine, for example 192.168.1.10 or reg.yourdomain.com . Do NOT use localhost or 127.0.0.1 for the hostname because the registry service needs to be accessed by external clients. **ui_url_protocol**: The protocol for accessing the user interface and the token/notification service, by default it is http. **Email settings**: the following 5 attributes are used to send an email to reset a user's password, they are not mandatory unless the password reset function is needed in Harbor. * email_server = smtp.mydomain.com @@ -41,10 +43,10 @@ At minimum, you need to change the **hostname** attribute in **harbor.cfg**. The **db_password**: The password of root user of mySQL database. **self_registration**: The flag to turn on or off the user self-registration function. If this flag is turned off, only an admin user can create new users in Harbor. The default value is on. -#### Build and start Harbor -After configuring harbor.cfg, build and start Harbor by the following commands. Because it requires downloading necesary files from the Internet, it may take a while for the docker-compose process to finish. +#### Building and starting Harbor +After configuring harbor.cfg, build and start Harbor by the following commands. Because it requires downloading necessary files from the Internet, it may take a while for the docker-compose process to finish. - ```sh +```sh $ cd Deploy $ ./prepare @@ -55,7 +57,7 @@ After configuring harbor.cfg, build and start Harbor by the following commands. The configuration files are ready, please use docker-compose to start the service. $ sudo docker-compose up -d - ``` +``` If everything works fine, you can open a browser to visit the admin portal at http://reg.yourdomain.com . The default administrator username and password are admin/Harbor12345 . @@ -68,10 +70,10 @@ $ docker push reg.yourdomain.com/myproject/myrepo For information on how to use Harbor, please refer to [User Guide of Harbor](user_guide.md) . -#### Configure Harbor with HTTPS Access +#### Configuring Harbor with HTTPS Access Because Harbor does not ship with any certificates, it uses HTTP by default to serve registry requests. This makes it relatively simple to configure, especially for a development or testing environment. However, it is highly recommended that security be enabled for any production environment. Refer to [Configure Harbor with HTTPS Access](configure_https.md) if you want to enable HTTPS access to Harbor. -## Install Harbor via a pre-built installation package +## Installing Harbor via a pre-built installation package A pre-built installation package of each release can be downloaded from the [release page](https://github.com/vmware/harbor/releases). After downloading the package file **harbor-<version>.tgz** , extract files in the package. ``` @@ -79,7 +81,7 @@ $ tar -xzvf harbor-0.1.1.tgz $ cd harbor ``` -Then configure Harbor by following instructions in Section [Configure Harbor](#markdown-header-configure-harbor). Next, run **prepare** script to generate config files and use docker compose to build Harbor's container images and eventually spin it up. +Then configure Harbor by following instructions in Section [Configure Harbor](#configuring-harbor). Next, run **prepare** script to generate config files and use docker compose to build Harbor's container images and eventually spin it up. ``` @@ -94,11 +96,11 @@ $ sudo docker-compose up -d ...... ``` -### Deploy Harbor to a target machine that does not have Internet access -When you run *docker-compose up* to start Harbor, it will pull base images from Docker Hub and build new images for the containers. This process requires accessing the Internet. If you want to deploy Harbor to a host that is not connected to the Internet, you need to prepare Harbor on a machine that has access to the Internet. After that, you export the images as tgz files and transfer them to the target machine, then load the tgz file into Docker's local image repo. +### Deploying Harbor to a target machine that does not have Internet access +When you run *docker-compose up* to start Harbor, it will pull base images from Docker Hub and build new images for the containers. This process requires accessing the Internet. If you want to deploy Harbor to a host that is not connected to the Internet, you need to prepare Harbor on a machine that has access to the Internet. After that, you export the images as tgz files and transfer them to the target machine. Then load the tgz file into Docker's local image repo. -#### Build and save images for offline installation -On a machine that is connected to the Internet, extract files from the pre-built installation package. Then run command "docker-compose build" to build the images and use the script *save_image.sh* to export them as tar files. The tar files will be stored in **images** directory. Next, package everything in the directory **harbor** into a tgz file and transfer it to the target machine. This can be done by executing the following commands: +#### Building and saving images for offline installation +On a machine that is connected to the Internet, extract files from the pre-built installation package. Then run command "docker-compose build" to build the images and use the script *save_image.sh* to export them as tar files. The tar files will be stored in *images/* directory. Next, package everything in the directory *harbor/* into a tgz file and transfer it to the target machine. This can be done by executing the following commands: ``` $ cd harbor @@ -119,8 +121,8 @@ $ cd ../ $ tar -cvzf harbor_offline-0.1.1.tgz harbor ``` -The file **harbor_offline-0.1.0.tgz** contains the images saved by previously steps and the files required to start Harbor. -You can use tools such as scp to transfer the file **harbor_offline-0.1.0.tgz** to the target machine that does not have Internet connection. On the target machine, you can execute the following commands to start Harbor. Again, before running the **prepare** script, be sure to update **harbor.cfg** to reflect the right configuration of the target machine. (Refer to Section [Configure Harbor](#markdown-header-configure-harbor) .) +The file **harbor_offline-0.1.1.tgz** contains the images saved by previously steps and the files required to start Harbor. +You can use tools such as scp to transfer the file **harbor_offline-0.1.1.tgz** to the target machine that does not have Internet connection. On the target machine, you can execute the following commands to start Harbor. Again, before running the **prepare** script, be sure to update **harbor.cfg** to reflect the right configuration of the target machine. (Refer to Section [Configure Harbor](#configuring-harbor) .) ``` $ tar -xzvf harbor_offline-0.1.1.tgz $ cd harbor @@ -142,13 +144,13 @@ Generated configuration file: ./config/ui/env Generated configuration file: ./config/ui/app.conf Generated configuration file: ./config/registry/config.yml Generated configuration file: ./config/db/env - The configuration files are ready, please use docker-compose to start the service. + # Build the images and then start the services $ sudo docker-compose up -d ``` -### Manage Harbor's lifecycle +### Managing Harbor's lifecycle Harbor is composed of a few containers which are deployed via docker-compose, you can use docker-compose to manage the lifecycle of the containers. Below are a few useful commands: Build and start Harbor: @@ -189,7 +191,7 @@ Removing harbor_registry_1 ... done Removing harbor_mysql_1 ... done ``` -Remove Harbor's database and image data (for a clean reinstallation): +Remove Harbor's database and image data (for a clean re-installation): ```sh $ rm -r /data/database $ rm -r /data/registry From 82b3f0657af718714c604f72ed134873fceda409 Mon Sep 17 00:00:00 2001 From: Henry Zhang Date: Fri, 8 Apr 2016 17:31:26 +0800 Subject: [PATCH 12/12] update installation guide --- docs/installation_guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/installation_guide.md b/docs/installation_guide.md index c6f26be4c..1c4aa4bd4 100644 --- a/docs/installation_guide.md +++ b/docs/installation_guide.md @@ -71,7 +71,7 @@ $ docker push reg.yourdomain.com/myproject/myrepo For information on how to use Harbor, please refer to [User Guide of Harbor](user_guide.md) . #### Configuring Harbor with HTTPS Access -Because Harbor does not ship with any certificates, it uses HTTP by default to serve registry requests. This makes it relatively simple to configure, especially for a development or testing environment. However, it is highly recommended that security be enabled for any production environment. Refer to [Configure Harbor with HTTPS Access](configure_https.md) if you want to enable HTTPS access to Harbor. +Because Harbor does not ship with any certificates, it uses HTTP by default to serve registry requests. This makes it relatively simple to configure, especially for a development or testing environment. However, it is highly recommended that security be enabled for any production environment. Refer to [Configuring Harbor with HTTPS Access](configure_https.md) if you want to enable HTTPS access to Harbor. ## Installing Harbor via a pre-built installation package @@ -81,7 +81,7 @@ $ tar -xzvf harbor-0.1.1.tgz $ cd harbor ``` -Then configure Harbor by following instructions in Section [Configure Harbor](#configuring-harbor). Next, run **prepare** script to generate config files and use docker compose to build Harbor's container images and eventually spin it up. +Then configure Harbor by following instructions in Section [Configuring Harbor](#configuring-harbor). Next, run **prepare** script to generate config files and use docker compose to build Harbor's container images and eventually spin it up. ```