Upstream/harbor
1
0
Fork 0
mirror of https://github.com/goharbor/harbor.git synced 2024-11-25 19:56:09 +01:00
Code Issues Projects Releases Wiki Activity

Merge pull request #39 from hainingzhang/master

Browse Source 
update installation guide
This commit is contained in:
Haining Henry Zhang 2016-03-24 16:49:34 +08:00
commit 82899e9731
1 changed files with 17 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
docs/installation_guide.md
View File

@ -1,16 +1,16 @@
# Installation Guide of Harbor # Installation Guide of Harbor
### Download the installation package ### 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 using 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 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 ### Prerequisites for target machine
Harbor is deployed as several Docker containers. Hence, it can be deployed on any Linux distribution that supports Docker. 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 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. * 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 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 ### Configuration of Harbor
After downloading the package file **```harbor-<version>.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-&lt;version&gt;.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 fully qualified hostname of your target machine, for example 192.168.1.10. Please see the next section for the description of each parameter. 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 $ tar -xzvf harbor-0.1.0.tgz
$ cd harbor $ cd harbor
@ -29,26 +29,26 @@ After that, you can open a browser and access Harbor via the IP you set in harbo
```docker pull 192.168.1.10/library/ubuntu``` ```docker pull 192.168.1.10/library/ubuntu```
#### Parameters in harbor.cfg #### Parameters in harbor.cfg
**hostname**: The endpoint for user to access UI and registry service, for example 192.168.1.10 or exampledomian.com. **hostname**: The endpoint for a user to access the user interface and the 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. **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 user's password, it is not mandatory unless password reset function is needed in Harbor. **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 * email_server = smtp.mydomain.com
* email_server_port = 25 * email_server_port = 25
* email_username = sample_admin@mydomain.com * email_username = sample_admin@mydomain.com
* email_password = abc * email_password = abc
* email_from = admin <sample_admin@mydomain.com> * email_from = admin <sample_admin@mydomain.com>
**harbor_admin_password**: The password for administrator of Harbor, by default it is Harbor12345, the user name is admin. **harbor_admin_password**: The password for the administrator of Harbor, by default the password 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. **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_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*. **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.
### Deploy Harbor to a target machine that does not have Internet access ### 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. 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 #### 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: 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:
``` ```
$ cd harbor $ cd harbor
@ -69,8 +69,8 @@ $ cd ../
$ tar -cvzf harbor_offline-0.1.0.tgz harbor $ 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. The package file **harbor_offline-0.1.0.tgz** contains the images saved by previously steps and the files required to start Harbor.
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. 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.
``` ```
$ tar -xzvf harbor_offline-0.1.tgz $ tar -xzvf harbor_offline-0.1.tgz
$ cd harbor $ cd harbor
@ -98,7 +98,7 @@ $ sudo docker-compose up -d
### Manage Harbor's lifecycle ### 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: 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: Build and start Harbor:
``` ```
$ sudo docker-compose up -d $ sudo docker-compose up -d
Creating harbor_log_1 Creating harbor_log_1
@ -125,7 +125,7 @@ Starting harbor_registry_1
Starting harbor_ui_1 Starting harbor_ui_1
Starting harbor_proxy_1 Starting harbor_proxy_1
```` ````
Remove Harbor's containers (the image data and Harbor database files remains on the file system): Remove Harbor's containers (the image data and Harbor's database files remains on the file system):
``` ```
$ sudo docker-compose rm $ sudo docker-compose rm
Going to remove harbor_proxy_1, harbor_ui_1, harbor_registry_1, harbor_mysql_1, harbor_log_1 Going to remove harbor_proxy_1, harbor_ui_1, harbor_registry_1, harbor_mysql_1, harbor_log_1
@ -135,8 +135,8 @@ Removing harbor_ui_1 ... done
Removing harbor_registry_1 ... done Removing harbor_registry_1 ... done
Removing harbor_mysql_1 ... done Removing harbor_mysql_1 ... done
``` ```
[Compose command-line reference](https://docs.docker.com/compose/reference/) describes the usage information for the docker-compose subcommands. [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 ### 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 Harbor's containers are removed and recreated the data will remain unchanged. 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 directory **/var/log/harbor/** . 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.