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   > **NOTE**<br>
37   > You do not need to obtain the source code for the HPM-based Docker environment.
38
393. Obtaining the required permissions.
40
41   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.
42
43## Standalone Docker Environment
44
45A 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.
46
47### Setting Up the Docker Environment for Mini- and Small-System Devices
48
491. Obtain the Docker image.
50
51   For mini-system devices:
52
53   ```
54   docker pull swr.cn-south-1.myhuaweicloud.com/openharmony-docker/docker_oh_small:3.2
55   ```
56   For small-system devices:
57   ```
58   docker pull swr.cn-south-1.myhuaweicloud.com/openharmony-docker/docker_oh_mini:3.2
59   ```
60
612. Access the Docker build environment.
62
63   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.
64
65   - Ubuntu
66
67      ```
68      # For mini-system devices
69      docker run -it -v $(pwd):/home/openharmony swr.cn-south-1.myhuaweicloud.com/openharmony-docker/docker_oh_small:3.2
70
71      # For small-system devices:
72      docker run -it -v $(pwd):/home/openharmony swr.cn-south-1.myhuaweicloud.com/openharmony-docker/docker_oh_mini:3.2
73      ```
74
75   - Windows (example source code directory: `D:\OpenHarmony`)
76
77      ```
78      # For mini-system devices
79      docker run -it -v D:\OpenHarmony:/home/openharmony swr.cn-south-1.myhuaweicloud.com/openharmony-docker/docker_oh_small:3.2
80
81      # For small-system devices:
82      docker run -it -v D:\OpenHarmony:/home/openharmony swr.cn-south-1.myhuaweicloud.com/openharmony-docker/docker_oh_mini:3.2
83      ```
84
85   > **NOTE**<br>
86   > `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.
87
88### Building for Mini- and Small-System Devices
89
901. Run the build script.
91
92   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).
93
94   ```
95   python3 build.py -p {product_name}@{company}
96   ```
97
98   where, `{product_name}` indicates the platform supported by the current version, and `{company}` indicates the company name.
99
100   For example, to start building for `ipcamera_hispark_taurus` of `hisilicon`, use the following command:
101
102   ```
103   python3 build.py -p ipcamera_hispark_taurus@hisilicon
104   ```
105
106   Similarly, to start building for `qemu_small_system_demo` of `ohemu`, use the following command:
107
108   ```
109   python3 build.py -p qemu_small_system_demo@ohemu
110   ```
111
1122. View the build result.
113
114   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/`.
115
116> **NOTE**<br>
117> To exit Docker, run `exit`. This command stops the current Docker container and goes back to your OS.
118
119### Setting Up the Docker Environment for Standard-System Devices
120
1211. Obtain the Docker image.
122
123   Before setting up a Docker environment for standard-system devices, you need to obtain the corresponding Docker image by running the following command:
124
125   ```
126   docker pull swr.cn-south-1.myhuaweicloud.com/openharmony-docker/docker_oh_standard:3.2
127   ```
128
1292. Access the Docker build environment.
130
131   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.
132
133   - Ubuntu
134
135      ```
136      docker run -it -v $(pwd):/home/openharmony swr.cn-south-1.myhuaweicloud.com/openharmony-docker/docker_oh_standard:3.2
137      ```
138
139   - Windows (example source code directory: D:\OpenHarmony)
140
141      ```
142      docker run -it -v D:\OpenHarmony:/home/openharmony swr.cn-south-1.myhuaweicloud.com/openharmony-docker/docker_oh_standard:3.2
143      ```
144
145### Building for Standard-System Devices
146
1471. Run the build script.
148
149   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).
150
151   ```
152   ./build.sh --product-name {product_name} --ccache
153   ```
154
155   `{product_name}` indicates the platform supported by the current distribution. For example, if `{product_name}` is `rk3568`, run the following command to start building:
156
157   ```
158   ./build.sh --product-name rk3568 --ccache
159   ```
160
1612. View the build result.
162   Files generated during the build are stored in `out/{device_name}/`, and the generated image is stored in `out/{device_name}/packages/phone/images/`.
163
164> **NOTE**<br>
165> To exit Docker, run `exit`. This command stops the current Docker container and goes back to your OS.
166
167
168## HPM-based Docker Environment
169
170**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:
171
172
173### Setting Up the Docker Environment
174
1751. Initialize the installation template.
176
177   Run the following command in any of the working directories:
178
179   ```
180   hpm init -t @ohos/docker_dist
181   ```
182
1832. Modify the **publishAs** field.
184
185   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.
186
187
188### Obtaining and Building Source Code
189
190Start building. Docker can be automatically installed only in Ubuntu. If you are using any other operating system, manually install Docker before pulling the image.
191
192- Automatical installation (Ubuntu)<br>
193  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.
194
195  Method 1:
196
197  Add a parameter to specify the solution. For example:
198
199
200  ```
201  hpm run docker solution={product}
202  ```
203
204  **{product}** indicates the solution, for example, **\@ohos/hispark_taurus**, **\@ohos/hispark_aries**, or **\@ohos/hispark_pegasus**.
205
206  Method 2:
207
208  Set an environment variable to specify the solution, and then run the build command.
209
210  1. Select the desired solution.
211
212      ```
213      export solution={product}
214      ```
215
216      **{product}** indicates the solution, for example, **\@ohos/hispark_taurus**, **\@ohos/hispark_aries**, and **\@ohos/hispark_pegasus**.
217  2. Obtain and build the source code.
218
219      ```
220      hpm run docker
221      ```
222
223    This example uses the **\@ohos/hispark_taurus** solution for illustration. If the execution is successful, the output is as follows:
224
225  ```
226  ......
227  ohos ipcamera_hispark_taurus build success!
228  @ohos/hispark_taurus: distribution building completed.
229  ```
230
231- Manual installation (Non-Ubuntu)<br>
232  Perform the following operations to install Docker:
233
234
235  ```
236  # Pull an image.
237  docker pull swr.cn-south-1.myhuaweicloud.com/openharmony-docker/openharmony-docker:0.0.3# Build the Docker image in the Linux environment.
238  hpm run distWithDocker solution={product}
239  # On Windows, make sure to configure the Git Bash.
240  hpm config set shellPath "Git Bash path"
241  hpm run distWithDocker solution={product}
242  ```
243