1# Docker Environment 2 3 4## Introduction 5 6OpenHarmony provides the following two types of docker environments for you to quickly get the development environment ready: 7 8- Standalone Docker environment: applicable when using Ubuntu or Windows to build a distribution 9 10- HPM-based Docker environment: applicable when using the HarmonyOS Package Manager (HPM) to build a distribution 11 12**Table 1** Docker environments 13 14| System Type| Operating Platform| Docker Image Repository| Tag| 15| -------- | -------- | -------- | -------- | 16| Standard system (standalone Docker environment)| Ubuntu/Windows | swr.cn-south-1.myhuaweicloud.com/openharmony-docker/docker_oh_standard | 3.2 | 17| Small system (standalone Docker environment)| Ubuntu/Windows | swr.cn-south-1.myhuaweicloud.com/openharmony-docker/docker_oh_small | 3.2 | 18| Mini system (standalone Docker environment)| Ubuntu/Windows | swr.cn-south-1.myhuaweicloud.com/openharmony-docker/docker_oh_mini | 3.2 | 19| Mini and small systems (HPM Docker environment)| Ubuntu/Windows | swr.cn-south-1.myhuaweicloud.com/openharmony-docker/openharmony-docker | 0.0.3 | 20 21 22## Setting Up Environment 23 24Before using the Docker environment, you need to make necessary preparations. The following uses Ubuntu as an example to describe the specific preparations. 25 261. Installing Docker 27 - Install Docker. 28 ``` 29 sudo apt install docker.io 30 ``` 31 - For details about how to install Docker on other types of OS, see [Docker Guide] (https://docs.docker.com/engine/install/). 32 332. Obtain the OpenHarmony source code. 34 35 For details, see [Source Code Acquisition](sourcecode-acquire.md). 36 37 > **NOTE**<br> 38 > You do not need to obtain the source code for the HPM-based Docker environment. 39 403. Obtaining the required permissions. 41 42 Perform subsequent operations as a user who has the root permission or has been granted the permission to use Docker. On Ubuntu, you can add **sudo** before a command to obtain the **root** permission. On Windows, you may need to run **cmd** or **PowerShell** in administrator mode. 43 44## Standalone Docker Environment 45 46A Docker image is a lightweight executable software package that contains applications and runtimes. Docker images of OpenHarmony are hosted on HuaweiCloud SWR. Using the Docker image will help simplify environment configurations needed for the building. The following describes the detailed procedure. 47 48### Setting Up the Docker Environment for Mini- and Small-System Devices 49 501. Obtain the Docker image. 51 52 For mini-system devices: 53 54 ``` 55 docker pull swr.cn-south-1.myhuaweicloud.com/openharmony-docker/docker_oh_small:3.2 56 ``` 57 For small-system devices: 58 ``` 59 docker pull swr.cn-south-1.myhuaweicloud.com/openharmony-docker/docker_oh_mini:3.2 60 ``` 61 622. Access the Docker build environment. 63 64 After obtaining the Docker image, you need to create a Docker container and access the container. Go to the root directory of OpenHarmony source code and run the respective command to access the Docker build environment. 65 66 - Ubuntu 67 68 ``` 69 # For mini-system devices 70 docker run -it -v $(pwd):/home/openharmony swr.cn-south-1.myhuaweicloud.com/openharmony-docker/docker_oh_small:3.2 71 72 # For small-system devices: 73 docker run -it -v $(pwd):/home/openharmony swr.cn-south-1.myhuaweicloud.com/openharmony-docker/docker_oh_mini:3.2 74 ``` 75 76 - Windows (example source code directory: `D:\OpenHarmony`) 77 78 ``` 79 # For mini-system devices 80 docker run -it -v D:\OpenHarmony:/home/openharmony swr.cn-south-1.myhuaweicloud.com/openharmony-docker/docker_oh_small:3.2 81 82 # For small-system devices: 83 docker run -it -v D:\OpenHarmony:/home/openharmony swr.cn-south-1.myhuaweicloud.com/openharmony-docker/docker_oh_mini:3.2 84 ``` 85 86 > **NOTE**<br> 87 > `docker run -it -v $(pwd):/home/openharmony swr.cn-south-1.myhuaweicloud.com/openharmony-docker/docker_oh_small:3.2`: used to create an OpenHarmony Docker container that runs in interactive mode and maps the current directory to the `/home/openharmony` directory of the container. 88 89### Building for Mini- and Small-System Devices 90 911. Run the build script. 92 93 Run `docker run` to access the Docker container in `/home/openharmony`. Then, run the build script to start building for mini-system devices (reference memory ≥ 128 KiB) and small-system devices (reference memory ≥ 1 MiB). 94 95 ``` 96 python3 build.py -p {product_name}@{company} 97 ``` 98 99 where, `{product_name}` indicates the platform supported by the current version, and `{company}` indicates the company name. 100 101 For example, to start building for `ipcamera_hispark_taurus` of `hisilicon`, use the following command: 102 103 ``` 104 python3 build.py -p ipcamera_hispark_taurus@hisilicon 105 ``` 106 107 Similarly, to start building for `qemu_small_system_demo` of `ohemu`, use the following command: 108 109 ``` 110 python3 build.py -p qemu_small_system_demo@ohemu 111 ``` 112 1132. View the build result. 114 115 The files generated during the build are stored in `out/{device_name}/`, and the resulting images are stored in `out/{device_name}/packages/phone/images/`. 116 117> **NOTE**<br> 118> To exit Docker, run `exit`. This command stops the current Docker container and goes back to your OS. 119 120### Setting Up the Docker Environment for Standard-System Devices 121 1221. Obtain the Docker image. 123 124 Before setting up a Docker environment for standard-system devices, you need to obtain the corresponding Docker image by running the following command: 125 126 ``` 127 docker pull swr.cn-south-1.myhuaweicloud.com/openharmony-docker/docker_oh_standard:3.2 128 ``` 129 1302. Access the Docker build environment. 131 132 Same as the previous procedure, you need to create a new Docker container and access the container. Go to the root directory of OpenHarmony source code and run the respective command to access the Docker build environment. 133 134 - Ubuntu 135 136 ``` 137 docker run -it -v $(pwd):/home/openharmony swr.cn-south-1.myhuaweicloud.com/openharmony-docker/docker_oh_standard:3.2 138 ``` 139 140 - Windows (example source code directory: D:\OpenHarmony) 141 142 ``` 143 docker run -it -v D:\OpenHarmony:/home/openharmony swr.cn-south-1.myhuaweicloud.com/openharmony-docker/docker_oh_standard:3.2 144 ``` 145 146### Building for Standard-System Devices 147 1481. Run the build script. 149 150 Run `docker run` to access the Docker container in `/home/openharmony`. Then, run the build script to start building for standard-system devices (reference memory ≥ 128 MiB). 151 152 ``` 153 ./build.sh --product-name {product_name} --ccache 154 ``` 155 156 `{product_name}` indicates the platform supported by the current distribution. For example, if `{product_name}` is `rk3568`, run the following command to start building: 157 158 ``` 159 ./build.sh --product-name rk3568 --ccache 160 ``` 161 1622. View the build result. 163 Files generated during the build are stored in `out/{device_name}/`, and the generated image is stored in `out/{device_name}/packages/phone/images/`. 164 165> **NOTE**<br> 166> To exit Docker, run `exit`. This command stops the current Docker container and goes back to your OS. 167 168 169## HPM-based Docker Environment 170 171**docker_dist** is a template component in the [HPM](https://hpm.harmonyos.com/) system. It helps to quickly initialize an HPM project and use the Docker image to quickly build a distribution of , greatly simplifying environment configurations needed for building. After configuring the Ubuntu and [hpm-cli](https://device.harmonyos.com/cn/docs/documentation/guide/hpm-part-development-install-0000001178291102) development environments, perform the following steps to access the Docker environment: 172 173 174### Setting Up the Docker Environment 175 1761. Initialize the installation template. 177 178 Run the following command in any of the working directories: 179 180 ``` 181 hpm init -t @ohos/docker_dist 182 ``` 183 1842. Modify the **publishAs** field. 185 186 The obtained bundle is of the template type. Open the **bundle.json** file in the current directory and change the value of **publishAs** from **template** to **distribution** as needed. 187 188 189### Obtaining and Building Source Code 190 191Start building. Docker can be automatically installed only in Ubuntu. If you are using any other operating system, manually install Docker before pulling the image. 192 193- Automatical installation (Ubuntu)<br> 194 Running the following command will automatically install Docker, pull the Docker image, and start the pulling and building of the corresponding solution in the container. 195 196 Method 1: 197 198 Add a parameter to specify the solution. For example: 199 200 201 ``` 202 hpm run docker solution={product} 203 ``` 204 205 **{product}** indicates the solution, for example, **\@ohos/hispark_taurus**, **\@ohos/hispark_aries**, or **\@ohos/hispark_pegasus**. 206 207 Method 2: 208 209 Set an environment variable to specify the solution, and then run the build command. 210 211 1. Select the desired solution. 212 213 ``` 214 export solution={product} 215 ``` 216 217 **{product}** indicates the solution, for example, **\@ohos/hispark_taurus**, **\@ohos/hispark_aries**, or **\@ohos/hispark_pegasus**. 218 2. Obtain and build the source code. 219 220 ``` 221 hpm run docker 222 ``` 223 224 This example uses the **\@ohos/hispark_taurus** solution for illustration. If the execution is successful, the output is as follows: 225 226 ``` 227 ...... 228 ohos ipcamera_hispark_taurus build success! 229 @ohos/hispark_taurus: distribution building completed. 230 ``` 231 232- Manual installation (Non-Ubuntu)<br> 233 Perform the following operations to install Docker: 234 235 236 ``` 237 # Pull an image. 238 docker pull swr.cn-south-1.myhuaweicloud.com/openharmony-docker/openharmony-docker:0.0.3# Build the Docker image in the Linux environment. 239 hpm run distWithDocker solution={product} 240 # On Windows, make sure to configure the Git Bash. 241 hpm config set shellPath "Git Bash path" 242 hpm run distWithDocker solution={product} 243 ``` 244