From 2fe95f2e9040b6d6d695d5a1456bd191ad0da434 Mon Sep 17 00:00:00 2001 From: Henry Zhang Date: Wed, 23 Mar 2016 10:08:03 +0800 Subject: [PATCH 1/4] udpate installation guide --- docs/installation_guide.md | 63 ++++++++++++++++++++------------------ 1 file changed, 33 insertions(+), 30 deletions(-) diff --git a/docs/installation_guide.md b/docs/installation_guide.md index 2ff87d256..961c637b8 100644 --- a/docs/installation_guide.md +++ b/docs/installation_guide.md @@ -1,16 +1,16 @@ -# Harbor Installation +# Installation Guide of Harbor ### Download the installation package -The installation package file for each release can be downloaded from the [release tab](https://github.com/vmware/harbor/releases). +The installation package file for each release can be downloaded from the [release page](https://github.com/vmware/harbor/releases). ### Prerequisites for target machine -Harbor is deployed as several docker containers. Hence, it can be deployed on any Linux distribution. -Before deploying harbor, the target machine requires python, docker-engine, docker compose installede. -* Python needs to be verion 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 one. -* The docker engine needs to be version 1.8 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/ +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-engine, docker compose 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.8 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/ -### Configure Harbor Parameters -Taking version 0.1.0 as an example, after downloading the package file **harbor-0.1.0.tgz** from release tab, you need to extract the package, make update to the parameters in the file **harbor.cfg**, execute the **prepare** script to generate configuration files for docker containers, and use docker-compose to start the service. -For simplest case, you only need to update the **hostname** attribute in **harbor.cfg** by updating the value to the IP or fully qualified hostname of your target machine, for example 192.168.1.10. Please see the next section for the details of each attriubte. +### Configuration of Harbor +After downloading the package file **```harbor-.tgz```** from release page, you need to extract the package. Before installing Harbor, configure the parameters in the file **harbor.cfg**. Then execute the **prepare** script to generate configuration files for Harbor's containers. Finally, use docker-compose to start the service. +At minimum, you only need to change the **hostname** attribute in **harbor.cfg** by updating the IP address or fully qualified hostname 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 @@ -25,28 +25,30 @@ The configuration files are ready, please use docker-compose to start the servic $ sudo docker-compose up -d ...... ``` -After that, you can open your browser and access harbor via the IP you set in harbor.cfg, such as 192.168.1.10 +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``` + #### Parameters in harbor.cfg **hostname**: The endpoint for user to access UI and registry service, for example 192.168.1.10 or exampledomian.com. **ui_url_protocol**: The protocol for accessing the UI and token/notification service, by default it is http. -**Email settings**: the following 5 attributes are used to send password resetting email, by default it is not necessary. +**Email settings**: the following 5 attributes are used to send an email to reset user's password, it is not mandatory unless password reset function is needed in Harbor. * email_server = smtp.mydomain.com * email_server_port = 25 * email_username = sample_admin@mydomain.com * email_password = abc * email_from = admin -**harbor_admin_password**: The password for administrator of harbor, by default it is Harbor12345. -**auth_mode**: The authentication mode of harbor. By default the it is *db_auth*, i.e. the credentials are stored in a databse. 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 as *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** set as *ldap_auth*. +**harbor_admin_password**: The password for administrator of Harbor, by default it is Harbor12345, the user name is admin. +**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. -### Deploy harbor to a target machine that does not have internet access -When you run *docker-compose up* to start harbor service. Docker will pull base images from docker hub and build new images for the containers. This process requires accessing internet. If you want to deploy harbor to a target machine in intranet which does not have access to the internet, essentially you need to first export the images as tgz files and transfer them to the target machine, then load the tgz file as docker images. +### Deploy Harbor to a target machine that does not have Internet access +When you run *docker-compose up* to start Harbor service. 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 service images -After extracting the installation package. Use command "docker-compose build" to build the images and run the script *save_image.sh* to export them as tar files and they will be stored in **images** directory, after that, user can package everything in directory **harbor** into a tgz file and transfer the tgz file to target machine. This can be done by executing the following commands: +#### Build and save images for offline installation +On a machine that is connect to Internet, extract 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, user can package everything in directory **harbor** into a tgz file and transfer the tgz file to the target machine. This can be done by executing the following commands: ``` $ cd harbor @@ -67,8 +69,8 @@ $ cd ../ $ tar -cvzf harbor_offline-0.1.0.tgz harbor ``` -The package file **harbor_offline-0.1.0.tgz** contains the images saved by previously steps and the files needed to start harbor services. -Then 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 access. Then on the target machine, you can execute the following commands to start harbor service. +The package file **harbor_offline-0.1.0.tgz** contains the images saved by previously steps and the files needed to start Harbor services. +Then 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 access. On the target machine, you can execute the following commands to start Harbor service. Again, before running the **prepare** script, be sure to update **harbor.cfg** to reflect the right configuration of the target machine. ``` $ tar -xzvf harbor_offline-0.1.tgz $ cd harbor @@ -93,9 +95,10 @@ The configuration files are ready, please use docker-compose to start the servic $ sudo docker-compose up -d ``` -### Manage Harbor Lifecycle -Harbor are deployed via docker-compose, you can use docker-compose to manage the lifecycle of the containers as a group. Below are a few useful commands: -create and start containers according to docker-compose.yml +### Manage 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: + +Create and start Harbor: ``` $ sudo docker-compose up -d Creating harbor_log_1 @@ -104,7 +107,7 @@ Creating harbor_registry_1 Creating harbor_ui_1 Creating harbor_proxy_1 ``` -stop docker container according to docker-compose.yml +Stop Harbor: ``` $ sudo docker-compose stop Stopping harbor_proxy_1 ... done @@ -113,7 +116,7 @@ Stopping harbor_registry_1 ... done Stopping harbor_mysql_1 ... done Stopping harbor_log_1 ... done ``` -start stopped services according to docker-compose.yml +Restart Harbor after stopping ``` $ sudo docker-compose start Starting harbor_log_1 @@ -122,7 +125,7 @@ Starting harbor_registry_1 Starting harbor_ui_1 Starting harbor_proxy_1 ```` -remove stopped containers +Remove Harbor's containers (the image data and Harbor database files remains 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,5 +138,5 @@ Removing harbor_mysql_1 ... done [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, data of database, and image files in registry are persisted in directory **/data/** of the target machine. When the containers are removed and recreated the data will remain unchanged. -Harbor leverage rsyslog to collect the logs of each container, by default the log files are stored in directory **/var/log/harbor/** \ No newline at end of file +By default, data of database and image files in registry are persisted in directory **/data/** of the target machine. When Harbor's containers are removed and recreated the data will remain unchanged. +Harbor leverages rsyslog to collect the logs of each container, by default the log files are stored in directory **/var/log/harbor/** . \ No newline at end of file From fe41f08355b4d43156d62e928d2b0b896addd926 Mon Sep 17 00:00:00 2001 From: Henry Zhang Date: Wed, 23 Mar 2016 10:26:40 +0800 Subject: [PATCH 2/4] update installation guide --- docs/installation_guide.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/installation_guide.md b/docs/installation_guide.md index 961c637b8..5fa85cb1d 100644 --- a/docs/installation_guide.md +++ b/docs/installation_guide.md @@ -1,15 +1,15 @@ # Installation Guide of Harbor ### Download the installation package -The installation package file for each release can be downloaded from the [release page](https://github.com/vmware/harbor/releases). +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 for each release can be downloaded from the [release page](https://github.com/vmware/harbor/releases). ### Prerequisites for target machine 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-engine, docker compose installed. +Before deploying Harbor, the target machine 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.8 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/ +* 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-.tgz```** from release page, you need to extract the package. Before installing Harbor, configure the parameters in the file **harbor.cfg**. Then execute the **prepare** script to generate configuration files for Harbor's containers. Finally, use docker-compose to start the service. +After downloading the package file **```harbor-.tgz```** from release page, you need to extract the package. Before installing Harbor, configure the parameters in the file **harbor.cfg**. Then execute the **prepare** script to generate configuration files for Harbor's containers. Finally, use Docker Compose to start the service. At minimum, you only need to change the **hostname** attribute in **harbor.cfg** by updating the IP address or fully qualified hostname 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 From e88b730bba2a555deca5fddb4017dae171e891fc Mon Sep 17 00:00:00 2001 From: Henry Zhang Date: Wed, 23 Mar 2016 10:29:42 +0800 Subject: [PATCH 3/4] update installation guide --- docs/installation_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/installation_guide.md b/docs/installation_guide.md index 5fa85cb1d..c084f6708 100644 --- a/docs/installation_guide.md +++ b/docs/installation_guide.md @@ -1,6 +1,6 @@ # 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 for each release can be downloaded from the [release page](https://github.com/vmware/harbor/releases). +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 for each release can be downloaded from the [release page](https://github.com/vmware/harbor/releases). This guide describes the installation of Harbor by the pre-built package. ### Prerequisites for target machine 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. From a6188ec7066ff03e98d5f86796fa86d3cb439243 Mon Sep 17 00:00:00 2001 From: Henry Zhang Date: Wed, 23 Mar 2016 10:32:16 +0800 Subject: [PATCH 4/4] installation and README update --- README.md | 2 +- docs/installation_guide.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d5e3b9c3b..5d25539d6 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Project Harbor is an enterprise-class registry server. It extends the open sourc * **AD/LDAP support**: Harbor integrates with existing AD/LDAP of the enterprise for user authentication and management. * **Auditing**: All the operations to the repositories are tracked and can be used for auditing purpose. * **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 another management software becomes easy. +* **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. diff --git a/docs/installation_guide.md b/docs/installation_guide.md index c084f6708..8ad143f9c 100644 --- a/docs/installation_guide.md +++ b/docs/installation_guide.md @@ -1,6 +1,6 @@ # 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 for each release can be downloaded from the [release page](https://github.com/vmware/harbor/releases). This guide describes the installation of Harbor by the pre-built 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 for each release can be downloaded from the [release page](https://github.com/vmware/harbor/releases). This guide describes the installation of Harbor by the using pre-built package. ### Prerequisites for target machine 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.