Use specific subfolder for additionalBuildFiles (#119)

* additionalBuildFiles should use a specific subfolder of the build context to prevent overrunning other files copied by the tool

* additional text to describe sections for COPY

Author: ddsharpe

imagetool/src/main/java/com/oracle/weblogic/imagetool/cli/menu/CommonOptions.java

@@ -73,11 +73,13 @@ private void handleAdditionalBuildCommands() throws IOException {
         }
 
         if (additionalBuildFiles != null) {
+            final String FILES_DIR = "files";
+            Files.createDirectory(Paths.get(getTempDirectory(), FILES_DIR));
             for (Path additionalFile : additionalBuildFiles) {
                 if (!Files.isRegularFile(additionalFile)) {
                     throw new FileNotFoundException(Utils.getMessage("IMG-0030", additionalFile));
                 }
-                Path targetFile = Paths.get(getTempDirectory(), additionalFile.getFileName().toString());
+                Path targetFile = Paths.get(getTempDirectory(), FILES_DIR, additionalFile.getFileName().toString());
                 logger.info("IMG-0043", additionalFile);
                 Utils.copyLocalFile(additionalFile.toString(), targetFile.toString(), false);
             }

site/create-image.md

@@ -53,11 +53,29 @@ Each section can contain one or more valid Dockerfile commands and would look li
 ```dockerfile
 [after-fmw-install]
 RUN rm /some/dir/unnecessary-file
+COPY --chown=oracle:oracle files/my_additional_file.txt /u01
 
 [final-build-commands]
 LABEL owner="middleware team"
 ```
 
+#### `--additionalBuildFiles`
+
+This option provides a way to supply additional files to the image build command.
+All provided files are copied directly under the `files` subfolder of the build context.  
+To get those files into the image, additional build commands must be provided using the `additionalBuildCommands` options.
+Access to these files using a build command, such as `COPY` or `ADD`, should use the original filename 
+with the folder prefix, `files/`.  For example, if the 
+original file was provided as `--additionalBuildFiles /scratch/test1/convenience.sh`, the Docker build command `COPY`
+provided in `--additionalBuildCommands` should look like 
+`COPY --chown=oracle:oracle files/convenience.sh /my/internal/image/location`.  
+Because Image Tool uses multi-stage 
+builds, it is important to place the build command (like `COPY`) in the appropriate section of the `Dockerfile` based
+on when the build needs access to the file.  For example, if the file is needed in the final image and not for 
+installation or domain creation steps, use the `final-build-commands` section so that the `COPY` command occurs in the 
+final stage of the image build.  Or, if the file needs to change the Oracle Home prior to domain creation, use 
+the `after-fmw-install` or `before-wdt-command` sections.
+
 #### Use an argument file
 
 You can save all arguments passed for the Image Tool in a file, then use the file as a parameter.

site/rebase-image.md

@@ -47,11 +47,29 @@ Each section can contain one or more valid Dockerfile commands and would look li
 ```dockerfile
 [after-fmw-install]
 RUN rm /some/dir/unnecessary-file
+COPY --chown=oracle:oracle files/my_additional_file.txt /u01
 
 [final-build-commands]
 LABEL owner="middleware team"
 ```
 
+#### `--additionalBuildFiles`
+
+This option provides a way to supply additional files to the image build command.
+All provided files are copied directly under the `files` subfolder of the build context.  
+To get those files into the image, additional build commands must be provided using the `additionalBuildCommands` options.
+Access to these files using a build command, such as `COPY` or `ADD`, should use the original filename 
+with the folder prefix, `files/`.  For example, if the 
+original file was provided as `--additionalBuildFiles /scratch/test1/convenience.sh`, the Docker build command `COPY`
+provided in `--additionalBuildCommands` should look like 
+`COPY --chown=oracle:oracle files/convenience.sh /my/internal/image/location`.  
+Because Image Tool uses multi-stage 
+builds, it is important to place the build command (like `COPY`) in the appropriate section of the `Dockerfile` based
+on when the build needs access to the file.  For example, if the file is needed in the final image and not for 
+installation or domain creation steps, use the `final-build-commands` section so that the `COPY` command occurs in the 
+final stage of the image build.  Or, if the file needs to change the Oracle Home prior to domain creation, use 
+the `after-fmw-install` or `before-wdt-command` sections.
+
 #### Use an argument file
 
 You can save all arguments passed for the Image Tool in a file, then use the file as a parameter.

site/update-image.md

@@ -72,11 +72,29 @@ increase the size of the image significantly, and is not recommended.
 ```dockerfile
 [after-fmw-install]
 RUN rm /some/dir/unnecessary-file
+COPY --chown=oracle:oracle files/my_additional_file.txt /u01
 
 [final-build-commands]
 LABEL owner="middleware team"
 ```
 
+#### `--additionalBuildFiles`
+
+This option provides a way to supply additional files to the image build command.
+All provided files are copied directly under the `files` subfolder of the build context.  
+To get those files into the image, additional build commands must be provided using the `additionalBuildCommands` options.
+Access to these files using a build command, such as `COPY` or `ADD`, should use the original filename 
+with the folder prefix, `files/`.  For example, if the 
+original file was provided as `--additionalBuildFiles /scratch/test1/convenience.sh`, the Docker build command `COPY`
+provided in `--additionalBuildCommands` should look like 
+`COPY --chown=oracle:oracle files/convenience.sh /my/internal/image/location`.  
+Because Image Tool uses multi-stage 
+builds, it is important to place the build command (like `COPY`) in the appropriate section of the `Dockerfile` based
+on when the build needs access to the file.  For example, if the file is needed in the final image and not for 
+installation or domain creation steps, use the `final-build-commands` section so that the `COPY` command occurs in the 
+final stage of the image build.  Or, if the file needs to change the Oracle Home prior to domain creation, use 
+the `after-fmw-install` or `before-wdt-command` sections.
+
 #### Use an argument file
 
 You can save all arguments passed for the Image Tool in a file, then use the file as a parameter.