1 # TensorFlow Dockerfiles 2 3 This directory houses TensorFlow's Dockerfiles and the infrastructure used to 4 create and deploy them to 5 [Docker Hub](https://hub.docker.com/r/tensorflow/tensorflow). 6 7 **DO NOT EDIT THE DOCKERFILES/ DIRECTORY MANUALLY!** The files within are 8 maintained by `assembler.py`, which builds Dockerfiles from the files in 9 `partials/` and the rules in `spec.yml`. See 10 [the Contributing section](#contributing) for more information. 11 12 These Dockerfiles are planned to replace the Dockerfiles used to generate 13 [TensorFlow's official Docker images](https://hub.docker.com/r/tensorflow/tensorflow). 14 15 ## Building 16 17 The Dockerfiles in the `dockerfiles` directory must have their build context set 18 to **the directory with this README.md** to copy in helper files. For example: 19 20 ```bash 21 $ docker build -f ./dockerfiles/cpu.Dockerfile -t tf . 22 ``` 23 24 Each Dockerfile has its own set of available `--build-arg`s which are documented 25 in the Dockerfile itself. 26 27 ## Running Locally Built Images 28 29 After building the image with the tag `tf` (for example), use `docker run` to 30 run the images. 31 32 Note for new Docker users: the `-v` and `-u` flags share directories and 33 permissions between the Docker container and your machine. Without `-v`, your 34 work will be wiped once the container quits, and without `-u`, files created by 35 the container will have the wrong file permissions on your host machine. Check 36 out the 37 [Docker run documentation](https://docs.docker.com/engine/reference/run/) for 38 more info. 39 40 ```bash 41 # Volume mount (-v) is optional but highly recommended, especially for Jupyter. 42 # User permissions (-u) are required if you use (-v). 43 44 # CPU-based images 45 $ docker run -u $(id -u):$(id -g) -v $(pwd):/my-devel -it tf 46 47 # GPU-based images (set up nvidia-docker2 first) 48 $ docker run --runtime=nvidia -u $(id -u):$(id -g) -v $(pwd):/my-devel -it tf 49 50 # Images with Jupyter run on port 8888 and need a volume for your notebooks 51 # You can change $(PWD) to the full path to a directory if your notebooks 52 # live outside the current directory. 53 $ docker run --user $(id -u):$(id -g) -p 8888:8888 -v $(PWD):/tf/notebooks -it tf 54 ``` 55 56 These images do not come with the TensorFlow source code -- but the development 57 images have git included, so you can `git clone` it yourself. 58 59 ## Contributing 60 61 To make changes to TensorFlow's Dockerfiles, you'll update `spec.yml` and the 62 `*.partial.Dockerfile` files in the `partials` directory, then run 63 `assembler.py` to re-generate the full Dockerfiles before creating a pull 64 request. 65 66 You can use the `Dockerfile` in this directory to build an editing environment 67 that has all of the Python dependencies you'll need: 68 69 ```bash 70 # Build the tools-helper image so you can run the assembler 71 $ docker build -t tf-tools -f tools.Dockerfile . 72 73 # Set --user to set correct permissions on generated files 74 $ docker run --user $(id -u):$(id -g) -it -v $(pwd):/tf tf-tools bash 75 76 # Next you can make a handy alias depending on what you're doing. When building 77 # Docker images, you need to run as root with docker.sock mounted so that the 78 # container can run Docker commands. When assembling Dockerfiles, though, you'll 79 # want to run as your user so that new files have the right permissions. 80 81 # If you're BUILDING OR DEPLOYING DOCKER IMAGES, run as root with docker.sock: 82 $ alias asm_images="docker run --rm -v $(pwd):/tf -v /var/run/docker.sock:/var/run/docker.sock tf-tools python3 assembler.py " 83 84 # If you're REBUILDING OR ADDING DOCKERFILES, remove docker.sock and add -u: 85 $ alias asm_dockerfiles="docker run --rm -u $(id -u):$(id -g) -v $(pwd):/tf tf-tools python3 assembler.py " 86 87 # Check assembler flags 88 $ asm_dockerfiles --help 89 90 # Assemble all of the Dockerfiles 91 $ asm_dockerfiles --release dockerfiles --construct_dockerfiles 92 93 # Build all of the "nightly" images on your local machine: 94 $ asm_images --release nightly --build_images 95 96 # Save the list of built images to a file: 97 $ asm_images --release nightly --build_images > tf-built.txt 98 99 # Build version release for version 99.0, except "gpu" tags: 100 $ asm_images --release versioned --arg _TAG_PREFIX=99.0 --build_images --exclude_tags_matching '.*gpu.*' 101 102 # Test your changes to the devel images: 103 $ asm_images --release nightly --build_images --run_tests_path=$(realpath tests) --only_tags_matching="^devel-gpu-py3$" 104 ``` 105
