Initial commit
This commit is contained in:
Honza Horak
parent
f131432cc2
commit
791e2c695d
19 changed files with 910 additions and 0 deletions
268
root/help.1
Normal file
268
root/help.1
Normal file
|
|
@ -0,0 +1,268 @@
|
|||
.TH "RUBY-23-RHEL7" "1" " Container Image Pages" "Red Hat" "April 07, 2017" ""
|
||||
|
||||
|
||||
.SH Ruby 2.4 platform for building and running applications
|
||||
.PP
|
||||
This repository contains the source for building various versions of
|
||||
the Ruby application as a reproducible Docker image using
|
||||
|
||||
\[la]https://github.com/openshift/source-to-image\[ra].
|
||||
Users can choose between RHEL and CentOS based builder images.
|
||||
The resulting image can be run using
|
||||
\[la]http://docker.io\[ra].
|
||||
|
||||
.SH Usage
|
||||
.PP
|
||||
To build a simple
|
||||
\[la]https://github.com/openshift/sti-ruby/tree/master/2.3/test/puma-test-app\[ra] application
|
||||
using standalone
|
||||
\[la]https://github.com/openshift/source-to-image\[ra] and then run the
|
||||
resulting image with
|
||||
\[la]http://docker.io\[ra] execute:
|
||||
.IP \n+[step]
|
||||
|
||||
\item
|
||||
.PP
|
||||
\fBFor RHEL based image\fP
|
||||
\fB\fC
|
||||
$ s2i build https://github.com/openshift/sti\-ruby.git \-\-context\-dir=2.3/test/puma\-test\-app/ rhscl/ruby\-23\-rhel7 ruby\-sample\-app
|
||||
$ docker run \-p 8080:8080 ruby\-sample\-app
|
||||
\fR
|
||||
\item
|
||||
.PP
|
||||
\fBFor CentOS based image\fP
|
||||
\fB\fC
|
||||
$ s2i build https://github.com/openshift/sti\-ruby.git \-\-context\-dir=2.3/test/puma\-test\-app/ centos/ruby\-23\-centos7 ruby\-sample\-app
|
||||
$ docker run \-p 8080:8080 ruby\-sample\-app
|
||||
\fR
|
||||
.PP
|
||||
\fBAccessing the application:\fP
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
$ curl 127.0.0.1:8080
|
||||
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.SH Repository organization.IP \n+[step]
|
||||
|
||||
\item
|
||||
.PP
|
||||
\fB\fB\fC<ruby\-version>\fR\fP.IP \n+[step]
|
||||
|
||||
\item
|
||||
.PP
|
||||
\fBDockerfile\fP
|
||||
.PP
|
||||
CentOS based Dockerfile.
|
||||
\item
|
||||
.PP
|
||||
\fBDockerfile.rhel7\fP
|
||||
.PP
|
||||
RHEL based Dockerfile. In order to perform build or test actions on this
|
||||
Dockerfile you need to run the action on a properly subscribed RHEL machine.
|
||||
\item
|
||||
.PP
|
||||
\fB\fB\fCs2i/bin/\fR\fP
|
||||
.PP
|
||||
This folder contains scripts that are run by
|
||||
\[la]https://github.com/openshift/source-to-image\[ra]:
|
||||
.IP \n+[step]
|
||||
|
||||
\item
|
||||
.PP
|
||||
\fBassemble\fP
|
||||
.PP
|
||||
Used to install the sources into the location where the application
|
||||
will be run and prepare the application for deployment (eg. installing
|
||||
modules using bundler, etc.)
|
||||
\item
|
||||
.PP
|
||||
\fBrun\fP
|
||||
.PP
|
||||
This script is responsible for running the application by using the
|
||||
application web server.
|
||||
\item
|
||||
.PP
|
||||
\fBusage\fP*
|
||||
.PP
|
||||
This script prints the usage of this image.
|
||||
\item
|
||||
.PP
|
||||
\fB\fB\fCcontrib/\fR\fP
|
||||
.PP
|
||||
This folder contains a file with commonly used modules.
|
||||
\item
|
||||
.PP
|
||||
\fB\fB\fCtest/\fR\fP
|
||||
.PP
|
||||
This folder contains a
|
||||
\[la]https://github.com/openshift/source-to-image\[ra]
|
||||
test framework with a simple Rack server.
|
||||
.IP \n+[step]
|
||||
|
||||
\item
|
||||
.PP
|
||||
\fB\fB\fCpuma\-test\-app/\fR\fP
|
||||
.PP
|
||||
Simple Puma web server used for testing purposes by the
|
||||
\[la]https://github.com/openshift/source-to-image\[ra] test framework.
|
||||
\item
|
||||
.PP
|
||||
\fB\fB\fCrack\-test\-app/\fR\fP
|
||||
.PP
|
||||
Simple Rack web server used for testing purposes by the
|
||||
\[la]https://github.com/openshift/source-to-image\[ra] test framework.
|
||||
\item
|
||||
.PP
|
||||
\fBrun\fP
|
||||
.PP
|
||||
Script that runs the
|
||||
\[la]https://github.com/openshift/source-to-image\[ra] test framework.
|
||||
.SH Environment variables
|
||||
.PP
|
||||
To set these environment variables, you can place them as a key value pair into a \fB\fC.sti/environment\fR
|
||||
file inside your source code repository.
|
||||
.IP \n+[step]
|
||||
|
||||
\item
|
||||
.PP
|
||||
\fBRACK\_ENV\fP
|
||||
.PP
|
||||
This variable specifies the environment where the Ruby application will be deployed (unless overwritten) \- \fB\fCproduction\fR, \fB\fCdevelopment\fR, \fB\fCtest\fR.
|
||||
Each level has different behaviors in terms of logging verbosity, error pages, ruby gem installation, etc.
|
||||
|
||||
.PP
|
||||
\fBNote\fP: Application assets will be compiled only if the \fB\fCRACK\_ENV\fR is set to \fB\fCproduction\fR
|
||||
\item
|
||||
.PP
|
||||
\fBDISABLE\_ASSET\_COMPILATION\fP
|
||||
.PP
|
||||
This variable set to \fB\fCtrue\fR indicates that the asset compilation process will be skipped. Since this only takes place
|
||||
when the application is run in the \fB\fCproduction\fR environment, it should only be used when assets are already compiled.
|
||||
\item
|
||||
.PP
|
||||
\fBPUMA\_MIN\_THREADS\fP, \fBPUMA\_MAX\_THREADS\fP
|
||||
.PP
|
||||
These variables indicate the minimum and maximum threads that will be available in
|
||||
\[la]https://github.com/puma/puma\[ra]'s thread pool.
|
||||
\item
|
||||
.PP
|
||||
\fBPUMA\_WORKERS\fP
|
||||
.PP
|
||||
This variable indicate the number of worker processes that will be launched. See documentation on Puma's
|
||||
\[la]https://github.com/puma/puma#clustered-mode\[ra].
|
||||
.SH Hot deploy
|
||||
.PP
|
||||
In order to dynamically pick up changes made in your application source code, you need to make following steps:
|
||||
.IP \n+[step]
|
||||
|
||||
\item
|
||||
.PP
|
||||
\fBFor Ruby on Rails applications\fP
|
||||
.PP
|
||||
Run the built Rails image with the \fB\fCRAILS\_ENV=development\fR environment variable passed to the
|
||||
\[la]http://docker.io\[ra] \fB\fC\-e\fR run flag:
|
||||
\fB\fC
|
||||
$ docker run \-e RAILS\_ENV=development \-p 8080:8080 rails\-app
|
||||
\fR
|
||||
\item
|
||||
.PP
|
||||
\fBFor other types of Ruby applications (Sinatra, Padrino, etc.)\fP
|
||||
.PP
|
||||
Your application needs to be built with one of gems that reloads the server every time changes in source code are done inside the running container. Those gems are:
|
||||
.IP \n+[step]
|
||||
|
||||
\item
|
||||
\[la]https://github.com/rtomayko/shotgun\[ra]
|
||||
\item
|
||||
\[la]https://github.com/alexch/rerun\[ra]
|
||||
\item
|
||||
\[la]https://github.com/johnbintz/rack-livereload\[ra]
|
||||
.PP
|
||||
Please note that in order to be able to run your application in development mode, you need to modify the
|
||||
\[la]https://github.com/openshift/source-to-image#anatomy-of-a-builder-image\[ra], so the web server is launched by the chosen gem, which checks for changes in the source code.
|
||||
|
||||
.PP
|
||||
After you built your application image with your version of
|
||||
\[la]https://github.com/openshift/source-to-image#anatomy-of-a-builder-image\[ra], run the image with the RACK\_ENV=development environment variable passed to the
|
||||
\[la]http://docker.io\[ra] \-e run flag:
|
||||
\fB\fC
|
||||
$ docker run \-e RACK\_ENV=development \-p 8080:8080 sinatra\-app
|
||||
\fR
|
||||
.PP
|
||||
To change your source code in running container, use Docker's
|
||||
\[la]http://docker.io\[ra] command:
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
docker exec \-it <CONTAINER\_ID> /bin/bash
|
||||
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.PP
|
||||
After you
|
||||
\[la]http://docker.io\[ra] into the running container, your current
|
||||
directory is set to \fB\fC/opt/app\-root/src\fR, where the source code is located.
|
||||
|
||||
.SH Performance tuning
|
||||
.PP
|
||||
You can tune the number of threads per worker using the
|
||||
\fB\fCPUMA\_MIN\_THREADS\fR and \fB\fCPUMA\_MAX\_THREADS\fR environment variables.
|
||||
Additionally, the number of worker processes is determined by the number of CPU
|
||||
cores that the container has available, as recommended by
|
||||
|
||||
\[la]https://github.com/puma/puma\[ra]'s documentation. This is determined using
|
||||
the cgroup
|
||||
\[la]https://www.kernel.org/doc/Documentation/cgroup-v1/cpusets.txt\[ra]
|
||||
subsystem. You can specify the cores that the container is allowed to use by passing
|
||||
the \fB\fC\-\-cpuset\-cpus\fR parameter to the
|
||||
\[la]http://docker.io\[ra] run command:
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
$ docker run \-e PUMA\_MAX\_THREADS=32 \-\-cpuset\-cpus='0\-2,3,5' \-p 8080:8080 sinatra\-app
|
||||
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.PP
|
||||
The number of workers is also limited by the memory limit that is enforced using
|
||||
cgroups. The builder image assumes that you will need 50 MiB as a base and
|
||||
another 15 MiB for every worker process plus 128 KiB for each thread. Note that
|
||||
each worker has its own threads, so the total memory required for the whole
|
||||
container is computed using the following formula:
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
50 + 15 * WORKERS + 0.125 * WORKERS * PUMA\_MAX\_THREADS
|
||||
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.PP
|
||||
You can specify a memory limit using the \fB\fC\-\-memory\fR flag:
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
$ docker run \-e PUMA\_MAX\_THREADS=32 \-\-memory=300m \-p 8080:8080 sinatra\-app
|
||||
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.PP
|
||||
If memory is more limiting then the number of available cores, the number of
|
||||
workers is scaled down accordingly to fit the above formula. The number of
|
||||
workers can also be set explicitly by setting \fB\fCPUMA\_WORKERS\fR.
|
||||
Loading…
Add table
Add a link
Reference in a new issue