@@ -172,106 +172,6 @@ If you're having trouble getting your version to build, try wiping out the exist
172
172
Build environment
173
173
-----------------
174
174
175
- Build environments use `Docker `_ to handle container virtualization. To perform
176
- any development on the Docker build system, you will need to set up `Docker `_ on
177
- your host system. Setup of Docker will vary by system, and so is out of the
178
- scope of this documentation.
179
-
180
- Once you have Docker set up, you will need to pull down our build image. These
181
- images are found on our `Docker Hub repository `_, the source comes from our
182
- `container image repo `_.
183
-
184
- .. note :: The size of the Docker images is around 5 to 9 GB.
185
-
186
- To get started using Docker for build environments, you'll need to pull down at
187
- least one build image. For example, to pull down our latest image::
188
-
189
- docker pull readthedocs/build:latest
190
-
191
- The default image used by our build servers is :djangosetting: `DOCKER_IMAGE `.
192
- This would be a good place to start testing as the ``latest `` version could
193
- operate differently. See ``DOCKER_IMAGE `` below for setting this configuration
194
- option.
195
-
196
- After this image is downloaded, you can update your settings to use the new
197
- image -- see `Configuration `_.
198
-
199
- .. _`Docker` : http://docker.com
200
- .. _`Docker Hub repository` : https://hub.docker.com/r/readthedocs/build/
201
- .. _`container image repo` : https://github.com/readthedocs/readthedocs-docker-images
202
-
203
- Configuration
204
- -------------
205
-
206
- There are several settings used to configure usage of virtual machines:
207
-
208
- DOCKER_ENABLE
209
- True/False value used to enable the Docker build environment.
210
-
211
- Default: :djangosetting: `DOCKER_ENABLE `
212
-
213
- DOCKER_LIMITS
214
- A dictionary of limits to virtual machines. These limits include:
215
-
216
- time
217
- An integer representing the total allowed time limit (in
218
- seconds) of build processes. This time limit affects the parent
219
- process to the virtual machine and will force a virtual machine
220
- to die if a build is still running after the allotted time
221
- expires.
222
-
223
- memory
224
- The maximum memory allocated to the virtual machine. If this
225
- limit is hit, build processes will be automatically killed.
226
- Examples: '200m' for 200MB of total memory, or '2g' for 2GB of
227
- total memory.
228
-
229
- Default: :djangosetting: `DOCKER_LIMITS `
230
-
231
- DOCKER_IMAGE
232
- Tag of a Docker image to use as a base image.
233
-
234
- Default: :djangosetting: `DOCKER_IMAGE `
235
-
236
- DOCKER_SOCKET
237
- URI of the socket to connect to the Docker daemon. Examples include:
238
- ``unix:///var/run/docker.sock `` and ``tcp://127.0.0.1:2375 ``.
239
-
240
- Default: :djangosetting: `DOCKER_SOCKET `
241
-
242
- DOCKER_VERSION
243
- Version of the API to use for the Docker API client.
244
-
245
- Default: :djangosetting: `DOCKER_VERSION `
246
-
247
-
248
- Local development
249
- -----------------
250
-
251
- On Linux development environments, it's likely that your UID and GID do not
252
- match the ``docs `` user that is set up as the default user for builds. In this
253
- case, it's necessary to make a new image that overrides the UID and GID for the
254
- normal container user::
255
-
256
- contrib/docker_build.sh latest
257
-
258
- This will create a new image, ``readthedocs/build-dev:latest ``. To build a
259
- different image, you can instead specify a version to build::
260
-
261
- contrib/docker_build.sh 5.0
262
-
263
- This will create a new image, ``readthedocs/build-dev:5.0 ``.
264
-
265
- You can set a ``local_settings.py `` option to automatically patch the image
266
- names to the development image names that are built here:
267
-
268
- DOCKER_USE_DEV_IMAGES
269
- If set to ``True ``, replace the normal Docker image name used in building
270
- ``readthedocs/build `` with the image name output for these commands,
271
- ``readthedocs/build-dev ``.
272
-
273
- The *Sphinx * and *Mkdocs * builders set the following RTD-specific environment variables when building your documentation:
274
-
275
175
.. csv-table ::
276
176
:header-rows: 1
277
177
0 commit comments