gopkg.in/openshift/source-to-image.v1@v1.2.0/examples/nginx-centos7/README.md (about)

     1  
     2  # Creating a basic S2I builder image  
     3  
     4  ## Getting started  
     5  
     6  ### Files and Directories  
     7  | File                   | Required? | Description                                                  |
     8  |------------------------|-----------|--------------------------------------------------------------|
     9  | Dockerfile             | Yes       | Defines the base builder image                               |
    10  | s2i/bin/assemble       | Yes       | Script that builds the application                           |
    11  | s2i/bin/usage          | No        | Script that prints the usage of the builder                  |
    12  | s2i/bin/run            | Yes       | Script that runs the application                             |
    13  | s2i/bin/save-artifacts | No        | Script for incremental builds that saves the built artifacts |
    14  | test/run               | No        | Test script for the builder image                            |
    15  | test/test-app          | Yes       | Test application source code                                 |
    16  
    17  #### Dockerfile
    18  Create a *Dockerfile* that installs all of the necessary tools and libraries that are needed to build and run our application.  This file will also handle copying the s2i scripts into the created image.
    19  
    20  #### S2I scripts
    21  
    22  ##### assemble
    23  Create an *assemble* script that will build our application, e.g.:
    24  - build python modules
    25  - bundle install ruby gems
    26  - setup application specific configuration
    27  
    28  The script can also specify a way to restore any saved artifacts from the previous image.   
    29  
    30  ##### run
    31  Create a *run* script that will start the application. 
    32  
    33  ##### save-artifacts (optional)
    34  Create a *save-artifacts* script which allows a new build to reuse content from a previous version of the application image.
    35  
    36  ##### usage (optional) 
    37  Create a *usage* script that will print out instructions on how to use the image.
    38  
    39  ##### Make the scripts executable 
    40  Make sure that all of the scripts are executable by running *chmod +x s2i/bin/**
    41  
    42  #### Create the builder image
    43  The following command will create a builder image named nginx-centos7 based on the Dockerfile that was created previously.
    44  ```
    45  docker build -t nginx-centos7 .
    46  ```
    47  The builder image can also be created by using the *make* command since a *Makefile* is included.
    48  
    49  Once image has finished building, the command *s2i usage nginx-centos7* will print out the help info that was defined in the *usage* script.
    50  
    51  #### Testing the builder image
    52  The builder image can be tested using the following commands:
    53  ```
    54  docker build -t nginx-centos7-candidate .
    55  IMAGE_NAME=nginx-centos7-candidate test/run
    56  ```
    57  The builder image can also be tested by using the *make test* command since a *Makefile* is included.
    58  
    59  #### Creating the application image
    60  The application image combines the builder image with your applications source code, which is served using whatever application is installed via the *Dockerfile*, compiled using the *assemble* script, and run using the *run* script.
    61  The following command will create the application image:
    62  ```
    63  s2i build test/test-app nginx-centos7 nginx-centos7-app
    64  ---> Building and installing application from source...
    65  ```
    66  Using the logic defined in the *assemble* script, s2i will now create an application image using the builder image as a base and including the source code from the test/test-app directory. 
    67  
    68  #### Running the application image
    69  Running the application image is as simple as invoking the docker run command:
    70  ```
    71  docker run -d -p 8080:8080 nginx-centos7-app
    72  ```
    73  The application, which consists of a simple static web page, should now be accessible at  [http://localhost:8080](http://localhost:8080).
    74  
    75  #### Using the saved artifacts script
    76  Rebuilding the application using the saved artifacts can be accomplished using the following command:
    77  ```
    78  s2i build --incremental=true test/test-app nginx-centos7 nginx-app
    79  ---> Restoring build artifacts...
    80  ---> Building and installing application from source...
    81  ```
    82  This will run the *save-artifacts* script which includes the custom code to backup the currently running application source, rebuild the application image, and then re-deploy the previously saved source using the *assemble* script.
    83  
    84  #### Configuring nginx
    85  It is possible to configure nginx server itself via this s2i builder image. To do so, simply provide an `nginx.conf` file in the root directory of your application. The `s2i/bin/assemble` will find this configuration file and make nginx use it. See the example configuration file in [test/test-app-redirect/](test/test-app-redirect/) directory. You can build and run it by using these commands:
    86  
    87  ```
    88  s2i build test/test-app-redirect nginx-centos7 nginx-centos7-redirect
    89  docker run -d -p 8080:8080 nginx-centos7-redirect
    90  ```
    91  
    92  Going to [http://localhost:8080](http://localhost:8080) should now redirect you to [https://openshift.com](https://openshift.com).
    93  
    94  More generally, it is possible to configure any kind of service using s2i, assuming that the provided `assemble` and/or `run` scripts support this and can recognize and use provided configuration files. It's also possible, assuming the s2i image supports it, to provide scripts that get executed by the s2i `run` script to further customize the functionality. Some more advanced examples of this can be found at https://github.com/sclorg/mongodb-container and https://github.com/sclorg/mariadb-container/.