From 0bf12de7b7e1baf7e1f0e0a0a26889dd2a034208 Mon Sep 17 00:00:00 2001 From: Adnan Abdulhussein Date: Wed, 17 Jun 2015 15:28:42 -0700 Subject: [PATCH] Add README --- bitnami/ruby/README.md | 287 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 287 insertions(+) create mode 100644 bitnami/ruby/README.md diff --git a/bitnami/ruby/README.md b/bitnami/ruby/README.md new file mode 100644 index 000000000000..d90ed881bb40 --- /dev/null +++ b/bitnami/ruby/README.md @@ -0,0 +1,287 @@ +# What is Ruby? + +> Ruby is a dynamic, open source programming language with a focus on simplicity and productivity. +> It has an elegant syntax that is natural to read and easy to write. + +ruby-lang.org + +# TLDR + +```bash +docker run -it --name ruby bitnami/ruby +``` + +## Docker Compose + +```yaml +ruby: + image: bitnami/ruby + command: ruby script.rb + volumes: + - path/to/ruby/app:/app +``` + +# Get this image + +The recommended way to get the Bitnami Ruby Docker Image is to pull the prebuilt image from the +[Docker Hub Registry](https://hub.docker.com). + +```bash +docker pull bitnami/ruby:2.2.2-3 +``` + +To always get the latest version, pull the `latest` tag. + +```bash +docker pull bitnami/ruby:latest +``` + +If you wish, you can also build the image yourself. + +```bash +git clone https://github.com/bitnami/bitnami-docker-ruby.git +cd docker-ruby +docker build -t bitnami/ruby +``` + +# Entering the REPL + +By default, running this image will drop you into the Ruby REPL (`irb`), where you can interactively +test and try things out in Ruby. + +```bash +docker run -it --name ruby bitnami/ruby +``` + +**Further Reading:** + +- Ruby IRB Documentation + +# Running your Ruby script + +The default work directory for the Ruby image is `/app`. You can mount a folder from your host +here that includes your Ruby script, and run it normally using the `ruby` command. + +```bash +docker run -it --name ruby -v /path/to/ruby/app:/app bitnami/ruby \ + ruby script.rb +``` + +# Running a Ruby app with gems + +If your Ruby app has a `Gemfile` defining your app's dependencies and start script, you can +install the dependencies before running your app. + +```bash +docker run -it --name ruby -v /path/to/ruby/app:/app bitnami/ruby \ + sh -c "bundle install && ruby script.rb" +``` + +or using Docker Compose: + +```yaml +ruby: + image: bitnami/ruby + command: "sh -c 'bundle install && ruby script.rb'" +``` + +**Further Reading:** + +- rubygems.org +- bundler.io + +# Accessing a Ruby app running a web server + +This image exposes port `3000` in the container, so you should ensure that your web server is +binding to port `3000`, as well as accepting remote connections. + +Below is an example of a Sinatra app +listening to remote connections on port `3000`: + +```ruby +require 'sinatra' + +set :bind, '0.0.0.0' +set :port, 3000 + +get '/hi' do + "Hello World!" +end +``` + +To access your web server from your host machine you can ask Docker to map a random port on your +host to port `3000` inside the container. + +```bash +docker run -it --name ruby -P bitnami/ruby +``` + +Run `docker port` to determine the random port Docker assigned. + +```bash +$ docker port ruby +3000/tcp -> 0.0.0.0:32769 +``` + +You can also manually specify the port you want forwarded from your host to the container. + +```bash +docker run -it --name ruby -p 8080:3000 bitnami/ruby +``` + +Access your web server in the browser by navigating to +[http://localhost:8080](http://localhost:8080/). + +# Linking + +If you want to connect to your Ruby web server inside another container, you can use the linking +system provided by Docker. + +## Serving your Ruby app through an nginx frontend + +We may want to make our Ruby web server only accessible via an nginx web server. Doing so will +allow us to setup more complex configuration, serve static assets using nginx, load balance to +different Ruby instances, etc. + +### Step 1: Create a virtual host + +Let's create an nginx virtual host to reverse proxy to our Ruby container. The Bitnami nginx Docker +Image ships with some example virtual hosts for connecting to Bitnami runtime images. We will +make use of the Ruby example: + +```nginx +server { + listen 0.0.0.0:80; + server_name yourapp.com; + access_log /logs/yourapp_access.log; + error_log /logs/yourapp_error.log; + + location / { + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header HOST $http_host; + proxy_set_header X-NginX-Proxy true; + + # proxy_pass http://[your_ruby_container_link_alias]:3000; + proxy_pass http://yourapp:3000; + proxy_redirect off; + } +} +``` + +Notice we've substituted the link alias name `yourapp`, we will use the same name when creating the +link. + +Copy the virtual host above, saving the file somewhere on your host. We will mount it as a volume +in our nginx container. + +### Step 2: Run the Ruby image with a specific name + +Docker's linking system uses container ids or names to reference containers. We can explicitly +specify a name for our Ruby server to make it easier to connect to other containers. + +``` +docker run -it --name ruby -v /path/to/ruby/app:/app bitnami/ruby ruby script.rb +``` + +or using Docker Compose: + +```yaml +ruby: + image: bitnami/ruby + command: ruby script.rb + volumes: + - path/to/ruby/app:/app +``` + +### Step 3: Run the nginx image and link it to the Ruby server + +Now that we have our Ruby server running, we can create another container that links to it by +giving Docker the `--link` option. This option takes the id or name of the container we want to link +it to as well as a hostname to use inside the container, separated by a colon. For example, to have +our Ruby server accessible in another container with `yourapp` as it's hostname we would pass +`--link ruby:yourapp` to the Docker run command. + +```bash +docker run -it -v /path/to/vhost.conf:/bitnami/nginx/conf/vhosts/yourapp.conf \ + --link ruby:yourapp \ + bitnami/nginx +``` + +or using Docker Compose: + +```yaml +nginx: + image: bitnami/nginx + links: + - ruby:yourapp + volumes: + - path/to/vhost.conf:/bintami/nginx/conf/yourapp.conf +``` + +We started the nginx server, mounting the virtual host we created in +[Step 1](#step-1-create-a-virtual-host), and created a link to the Ruby server with the alias +`yourapp`. + +# Maintenance + +## Upgrade this image + +Bitnami provides up-to-date versions of Ruby, including security patches, soon after they are +made upstream. We recommend that you follow these steps to upgrade your container. + +### Step 1: Get the updated image + +```bash +docker pull bitnami/ruby:2.2.2-3 +``` + +or if you're using Docker Compose, update the value of the image property to +`bitnami/ruby:2.2.2-3`. + +### Step 2: Remove the currently running container + +```bash +docker rm -v ruby +``` + +or using Docker Compose: + +```bash +docker-compose rm -v ruby +``` + +### Step 3: Run the new image + +Re-create your container from the new image. + +```bash +docker run --name ruby bitnami/ruby:2.2.2-3 +``` + +or using Docker Compose: + +```bash +docker-compose start ruby +``` + +# Contributing + +We'd love for you to contribute to this Docker image. You can request new features by creating an +[issue](https://github.com/bitnami/bitnami-docker-ruby/issues), or submit a +[pull request](https://github.com/bitnami/bitnami-docker-ruby/pulls) with your contribution. + +# Issues + +If you encountered a problem running this container, you can file an +[issue](https://github.com/bitnami/bitnami-docker-ruby/issues). For us to provide better support, +be sure to include the following information in your issue: + +- Host OS and version +- Docker version (`docker version`) +- Output of `docker info` +- Version of this container (`echo $BITNAMI_APP_VERSION` inside the container) +- The command you used to run the container, and any relevant output you saw (masking any sensitive +information) + +# License