Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/circleci-public/cimg-ruby
The CircleCI Ruby Docker Convenience Image.
https://github.com/circleci-public/cimg-ruby
cimg circleci circleci-cimg convenience-image docker ruby
Last synced: about 10 hours ago
JSON representation
The CircleCI Ruby Docker Convenience Image.
- Host: GitHub
- URL: https://github.com/circleci-public/cimg-ruby
- Owner: CircleCI-Public
- License: mit
- Created: 2019-03-29T20:19:57.000Z (almost 6 years ago)
- Default Branch: main
- Last Pushed: 2025-02-04T15:32:35.000Z (10 days ago)
- Last Synced: 2025-02-06T22:10:03.176Z (8 days ago)
- Topics: cimg, circleci, circleci-cimg, convenience-image, docker, ruby
- Language: Dockerfile
- Homepage: https://circleci.com/developer/images/image/cimg/ruby
- Size: 199 KB
- Stars: 35
- Watchers: 16
- Forks: 40
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
CircleCI Convenience Images => Ruby
A Continuous Integration focused Ruby Docker image built to run on CircleCI
[](https://circleci.com/gh/CircleCI-Public/cimg-ruby) [](https://raw.githubusercontent.com/CircleCI-Public/cimg-ruby/main/LICENSE) [](https://hub.docker.com/r/cimg/ruby) [](https://discuss.circleci.com/c/ecosystem/circleci-images) [](https://github.com/CircleCI-Public/cimg-ruby)
**_This image is designed to supercede the legacy CircleCI Ruby image, `circleci/ruby`._**
`cimg/ruby` is a Docker image created by CircleCI with continuous integration builds in mind.
Each tag contains a complete Ruby version, the `gem` command, Bundler, and any binaries and tools that are required for builds to complete successfully in a CircleCI environment.
## Support Policy
The CircleCI Docker Convenience Image support policy can be found on the [CircleCI docs](https://circleci.com/docs/convenience-images-support-policy) site. This policy outlines the release, update, and deprecation policy for CircleCI Docker Convenience Images.
## Table of Contents
- [Getting Started](#getting-started)
- [How This Image Works](#how-this-image-works)
- [Development](#development)
- [Contributing](#contributing)
- [Additional Resources](#additional-resources)
- [License](#license)
## Getting Started
This image can be used with the CircleCI `docker` executor.
For example:
```yaml
jobs:
build:
docker:
- image: cimg/ruby:3.2.2
steps:
- checkout
- run: ruby --version
```
In the above example, the CircleCI Ruby Docker image is used for the primary container.
More specifically, the tag `3.2.2` is used meaning the version of Ruby will be Ruby v3.2.2.
You can now use Ruby within the steps for this job.
## How This Image Works
This image contains the Ruby programming language.
This includes the `gem` command as well as Bundler pre-installed.
### Variants
Variant images typically contain the same base software, but with a few additional modifications.
#### Node.js
The Node.js variant is the same Ruby image but with Node.js also installed.
The Node.js variant can be used by appending `-node` to the end of an existing `cimg/ruby` tag.
```yaml
jobs:
build:
docker:
- image: cimg/ruby:3.2-node
steps:
- checkout
- run: ruby --version
- run: node --version
```
#### Browsers
The browsers variant is the same Ruby image but with Node.js, Java, Selenium, and browser dependencies pre-installed via apt.
The browsers variant can be used by appending `-browser` to the end of an existing `cimg/ruby` tag.
The browsers variant is designed to work in conjunction with the [CircleCI Browser Tools orb](https://circleci.com/developer/orbs/orb/circleci/browser-tools).
You can use the orb to install a version of Google Chrome and/or Firefox into your build. The image contains all of the supporting tools needed to use both the browser and its driver.
```yaml
orbs:
browser-tools: circleci/[email protected]
jobs:
build:
docker:
- image: cimg/ruby:3.2-browsers
steps:
- browser-tools/install-browser-tools
- checkout
- run: |
ruby --version
node --version
java --version
google-chrome --version
```
### Tagging Scheme
This image has the following tagging scheme:
```
cimg/ruby:[-variant]
```
`` - The version of Ruby to use.
This can be a full SemVer point release (such as `3.2.0`) or just the minor release (such as `3.2`).
If you use the minor release tag, it will automatically point to future patch updates as they are released.
For example, the tag `3.2` points to Ruby v3.2.0 now, but when the next release comes out, it will point to Ruby v3.2.1.
`[-variant]` - Variant tags, if available, can optionally be used.
For example, the Node.js variant can be used like this: `cimg/ruby:3.2.0-node`.
## Development
Images can be built and run locally with this repository.
This has the following requirements:
- local machine of Linux (Ubuntu tested) or macOS
- modern version of Bash (v4+)
- modern version of Docker Engine (v19.03+)
### Cloning For Community Users (no write access to this repository)
Fork this repository on GitHub.
When you get your clone URL, you'll want to add `--recurse-submodules` to the clone command in order to populate the Git submodule contained in this repo.
It would look something like this:
```bash
git clone --recurse-submodules
```
If you missed this step and already cloned, you can just run `git submodule update --init --recursive` to populate the submodule.
Then you can optionally add this repo as an upstream to your own:
```bash
git remote add upstream https://github.com/CircleCI-Public/cimg-ruby.git
```
### Cloning For Maintainers ( you have write access to this repository)
Clone the project with the following command so that you populate the submodule:
```bash
git clone --recurse-submodules [email protected]:CircleCI-Public/cimg-ruby.git
```
### Generating Dockerfiles
Dockerfiles can be generated for a specific Ruby version using the `gen-dockerfiles.sh` script.
For example, to generate the Dockerfile for Ruby v3.2.0, you would run the following from the root of the repo:
```bash
./shared/gen-dockerfiles.sh 3.2.0
```
The generated Dockerfile will be located at `./3.2/Dockefile`.
To build this image locally and try it out, you can run the following:
```bash
cd 3.2/
docker build -t test/ruby:3.2.0 .
docker run -it test/ruby:3.2.0 bash
```
### Building the Dockerfiles
To build the Docker images locally as this repository does, you'll want to run the `build-images.sh` script:
```bash
./build-images.sh
```
This would need to be run after generating the Dockerfiles first.
When releasing proper images for CircleCI, this script is run from a CircleCI pipeline and not locally.
### Publishing Official Images (for Maintainers only)
The individual scripts (above) can be used to create the correct files for an image, and then added to a new git branch, committed, etc.
A release script is included to make this process easier.
To make a proper release for this image, let's use the fake Ruby version of v9.99, you would run the following from the repo root:
```bash
./shared/release.sh 9.99
```
This will automatically create a new Git branch, generate the Dockerfile(s), stage the changes, commit them, and push them to GitHub.
The commit message will end with the string `[release]`.
This string is used by CircleCI to know when to push images to Docker Hub.
All that would need to be done after that is:
- wait for build to pass on CircleCI
- review the PR
- merge the PR
The main branch build will then publish a release.
### Incorporating Changes
How changes are incorporated into this image depends on where they come from.
**build scripts** - Changes within the `./shared` submodule happen in its [own repository](https://github.com/CircleCI-Public/cimg-shared).
For those changes to affect this image, the submodule needs to be updated.
Typically like this:
```bash
cd shared
git pull
cd ..
git add shared
git commit -m "Updating submodule for foo."
```
**parent image** - By design, when changes happen to a parent image, they don't appear in existing Ruby images.
This is to aid in "determinism" and prevent breaking customer builds.
New Ruby images/versions though will automatically pick up the changes.
If you _really_ want to publish changes from a parent image into the Ruby image, you have to build a specific image version as if it was a new image.
This will create a new Dockerfile and once published, a new image.
**Ruby specific changes** - Editing the `Dockerfile.template` file in this repo is how to modify the Ruby image specifically.
Don't forget that to see any of these changes locally, the `gen-dockerfiles.sh` script will need to be run again (see above).
## Contributing
We encourage [issues](https://github.com/CircleCI-Public/cimg-ruby/issues) and [pull requests](https://github.com/CircleCI-Public/cimg-ruby/pulls) against this repository.
Please check out our [contributing guide](.github/CONTRIBUTING.md) which outlines best practices for contributions and what you can expect from the images team at CircleCI.
## Additional Resources
[CircleCI Docs](https://circleci.com/docs/) - The official CircleCI Documentation website.
[CircleCI Configuration Reference](https://circleci.com/docs/2.0/configuration-reference/#section=configuration) - From CircleCI Docs, the configuration reference page is one of the most useful pages we have.
It will list all of the keys and values supported in `.circleci/config.yml`.
[Docker Docs](https://docs.docker.com/) - For simple projects this won't be needed but if you want to dive deeper into learning Docker, this is a great resource.
## License
This repository is licensed under the MIT license.
The license can be found [here](./LICENSE).