{"id":45157380,"url":"https://github.com/couchbase-examples/ruby-on-rails-quickstart","last_synced_at":"2026-02-20T05:02:31.077Z","repository":{"id":228574574,"uuid":"772042699","full_name":"couchbase-examples/ruby-on-rails-quickstart","owner":"couchbase-examples","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-18T05:29:38.000Z","size":821,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-12-21T14:42:43.971Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/couchbase-examples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-03-14T12:31:49.000Z","updated_at":"2025-12-18T05:29:36.000Z","dependencies_parsed_at":"2024-04-15T11:09:26.011Z","dependency_job_id":"68f20583-29c0-4352-98ca-462a1b32b43f","html_url":"https://github.com/couchbase-examples/ruby-on-rails-quickstart","commit_stats":null,"previous_names":["couchbase-examples/ruby-on-rails-quickstart"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/couchbase-examples/ruby-on-rails-quickstart","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fruby-on-rails-quickstart","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fruby-on-rails-quickstart/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fruby-on-rails-quickstart/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fruby-on-rails-quickstart/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/couchbase-examples","download_url":"https://codeload.github.com/couchbase-examples/ruby-on-rails-quickstart/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fruby-on-rails-quickstart/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29641929,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-20T03:21:14.183Z","status":"ssl_error","status_checked_at":"2026-02-20T03:18:24.455Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-20T05:02:30.376Z","updated_at":"2026-02-20T05:02:31.067Z","avatar_url":"https://github.com/couchbase-examples.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Quickstart in Couchbase with Ruby on Rails\n\n## Build a REST API with Ruby on Rails and Couchbase\n\nOften, the first step developers take after creating their database is to create a REST API capable of performing Create, Read, Update, and Delete (CRUD) operations for that database. This repository is designed to teach you and provide you with a starter project (in Ruby on Rails) to generate such a REST API. Once you have installed the travel-sample bucket in your database, you can run this application, which is a REST API with Swagger documentation, to learn:\n\n- How to create, read, update, and delete documents using Key-value operations (KV operations). Key-value operations are unique to Couchbase and provide super-fast (think microseconds) queries.\n- How to write simple parameterized SQL++ queries using the built-in travel-sample bucket.\n\nYou can find the full documentation for the tutorial on the [Couchbase Developer Portal](https://www.couchbase.com/developers)\n\n## Prerequisites\n\nTo run this prebuilt project, you will need:\n\n- [Couchbase Capella cluster](https://www.couchbase.com/products/capella/) with [travel-sample bucket](https://docs.couchbase.com/ruby-sdk/current/ref/travel-app-data-model.html) loaded.\n- To run this tutorial using a [self-managed Couchbase cluster](https://docs.couchbase.com/capella/current/getting-started/self-managed-cluster.html), please refer to the appendix.\n- [Ruby 3.4.1](https://www.ruby-lang.org/en/documentation/installation/) is installed on the local machine.\n- [rbenv](https://github.com/rbenv/rbenv) is recommended for managing Ruby versions (see Ruby-on-Rails-install.md for installation guide).\n- Basic knowledge of [Ruby](https://www.ruby-lang.org/en/documentation/), [Ruby on Rails](https://rubyonrails.org/), and [RSpec](https://rspec.info/).\n\n### Ruby Version Management\n\nThis project uses Ruby 3.4.1. We recommend using rbenv for managing Ruby versions. The `.ruby-version` file in the repository root will automatically configure rbenv to use the correct Ruby version.\n\nIf you don't have rbenv installed, see `Ruby-on-Rails-install.md` for detailed installation instructions.\n\n## Loading Travel Sample Bucket\n\nIf travel-sample is not loaded in your Capella cluster, you can load it by following the instructions for your Capella Cluster:\n\n- Load travel-sample bucket in Couchbase Capella\n\n## App Setup\n\nWe will walk through the different steps required to get the application running.\n\n### Cloning Repo\n\n```sh\ngit clone https://github.com/couchbase-examples/ruby-on-rails-quickstart.git\n```\n\n### Install Dependencies\n\nAny dependencies will be installed by running the bundle install command, which installs any dependencies required for the project.\n\n```sh\nbundle install\n```\n\n### Setup Database Configuration\n\nTo learn more about connecting to your Capella cluster, please follow the instructions.\n\nSpecifically, you need to do the following:\n\nCreate the database credentials to access the travel-sample bucket (Read and Write) used in the application.\nAllow access to the Cluster from the IP on which the application is running.\nAll configuration for communication with the database is read from the environment variables. We have provided a convenience feature in this quickstart to read the environment variables from a local file, dev.env.example.\n\nCreate a copy of dev.env.example file, rename it to dev.env and add the values for the Couchbase connection.\n\n```sh\nDB_CONN_STR=\u003cconnection_string\u003e\nDB_USERNAME=\u003cuser_with_read_write_permission_to_travel-sample_bucket\u003e\nDB_PASSWORD=\u003cpassword_for_user\u003e\n```\n\nNote: The connection string expects the couchbases:// or couchbase:// part.\n\n## Running The Application\n\n### Directly on machine\n\nAt this point, we have installed the dependencies, loaded the travel-sample data and configured the application with the credentials. The application is now ready and you can run it.\n\nThe application will run on a port specified by Rails. You can find the port in the terminal after running the application. You will find the Swagger documentation at [http://localhost:3000/api-docs](http://localhost:3000/api-docs) of the API if you go to the URL in your browser.\n\n```sh\nrails server\n```\n\n### Using Docker\n\n- Build the Docker image\n\n```sh\ndocker build -t couchbase-rails-quickstart .\n```\n\n- Run the Docker image\n\n```sh\ndocker run -p 3000:3000 couchbase-rails-quickstart -e DB_CONN_STR=\u003cconnection_string\u003e -e DB_USERNAME=\u003cuser_with_read_write_permission_to_travel-sample_bucket\u003e -e DB_PASSWORD=\u003cpassword_for_user\u003e\n```\n\n\u003e Note: The dev.env.example file in the root folder has the connection information to connect to your Capella cluster. Create a copy of dev.env.example file and rename it to dev.env and add the values for the Couchbase connection.\n\n## Verifying the Application\n\nOnce the application starts, you can see the details of the application on the terminal.\n\n![Application Start](./assets/images/app_startup.png)\n\nThe application will run on the port specified by Rails on your local machine (eg: http://localhost:3000). You will find the interactive Swagger documentation of the API if you go to the URL in your browser. Swagger documentation is used in this demo to showcase the different API endpoints and how they can be invoked. More details on the Swagger documentation can be found in the appendix.\n\n![Swagger Documentation](./assets/images/swagger_documentation.png)\n\n## Running The Tests\n\nCreate a copy of dev.env.example file and rename it to dev.env and add the values for the Couchbase connection.\n\n```sh\nDB_CONN_STR=\u003cconnection_string\u003e\nDB_USERNAME=\u003cuser_with_read_write_permission_to_travel-sample_bucket\u003e\nDB_PASSWORD=\u003cpassword_for_user\u003e\n```\n\n### Run the integration tests\n\n```sh\nbundle exec rspec spec/requests\n```\n\n## Troubleshooting\n\n### Integration Tests Failing with \"undefined method 'get' for nil\"\n\nThis error means Couchbase is not properly initialized. Follow these steps:\n\n#### 1. Verify Environment Variables\n\nFor local development, ensure `dev.env` file exists in project root:\n\n```bash\ncat dev.env\n```\n\nShould contain:\n```\nDB_CONN_STR=\"couchbases://cb.hlcup4o4jmjr55yf.cloud.couchbase.com\"\nDB_USERNAME=\"your-username\"\nDB_PASSWORD=\"your-password\"\n```\n\n#### 2. Verify Couchbase Connection\n\nTest the connection:\n```bash\nbundle exec rails runner 'puts COUCHBASE_CLUSTER ? \"✓ Connected\" : \"✗ Not connected\"'\n```\n\n#### 3. Verify travel-sample Bucket\n\nThe application requires the `travel-sample` bucket with:\n- **Scope:** `inventory`\n- **Collections:** `airline`, `airport`, `route`, `hotel`\n\nFor Couchbase Capella:\n1. Log into Capella console\n2. Navigate to your cluster\n3. Check Buckets \u003e travel-sample exists\n4. Verify inventory scope and collections exist\n\n#### 4. Check Permissions\n\nThe database user needs:\n- Read/Write access to `travel-sample` bucket\n- Query permissions for N1QL queries\n- Search permissions for FTS operations\n\n#### 5. Verify Network Access (Capella Only)\n\nFor Couchbase Capella:\n1. Go to Settings \u003e Allowed IP Addresses\n2. Add your IP address or `0.0.0.0/0` for testing\n3. Ensure cluster is not paused\n\n### CI Tests Failing\n\nCheck GitHub repository configuration:\n\n1. **Secrets** (Settings \u003e Secrets and variables \u003e Actions \u003e Secrets):\n   - `DB_PASSWORD` - Your Couchbase password\n\n2. **Variables** (Settings \u003e Secrets and variables \u003e Actions \u003e Variables):\n   - `DB_CONN_STR` - Your Couchbase connection string\n   - `DB_USERNAME` - Your Couchbase username\n\n3. **Capella IP Allowlist**:\n   - GitHub Actions runners use dynamic IPs\n   - Temporarily allow `0.0.0.0/0` or use Capella's \"Allow All IPs\" option\n\n### Common Errors\n\n**Error:** `Couchbase::Error::AuthenticationFailure`\n- **Solution:** Check username/password in `dev.env` or GitHub Secrets\n\n**Error:** `Couchbase::Error::BucketNotFound`\n- **Solution:** Ensure `travel-sample` bucket is created and loaded\n\n**Error:** `Couchbase::Error::Timeout`\n- **Solution:** Check network connectivity, verify connection string uses correct protocol (`couchbase://` for local, `couchbases://` for Capella)\n\n**Error:** `Couchbase::Error::ScopeNotFound` or `CollectionNotFound`\n- **Solution:** The initializer auto-creates scope/collections, but user needs create permissions\n\n### Health Check Endpoint\n\nCheck application health:\n```bash\ncurl http://localhost:3000/api/v1/health\n```\n\nResponse shows Couchbase status:\n```json\n{\n  \"status\": \"healthy\",\n  \"timestamp\": \"2025-12-02T10:30:00Z\",\n  \"services\": {\n    \"couchbase\": {\n      \"status\": \"up\",\n      \"message\": \"Connected to travel-sample bucket\"\n    }\n  }\n}\n```\n\n### Getting Help\n\nIf issues persist:\n1. Check application logs for detailed error messages\n2. Verify Ruby version matches `.ruby-version` (3.4.1)\n3. Run `bundle install` to ensure all gems are current\n4. Check Couchbase SDK compatibility\n\n# Appendix\n\n## Data Model\n\nFor this quickstart, we use three collections, airport, airline and routes that contain sample airports, airlines and airline routes respectively. The routes collection connects the airports and airlines as seen in the figure below. We use these connections in the quickstart to generate airports that are directly connected and airlines connecting to a destination airport. Note that these are just examples to highlight how you can use SQL++ queries to join the collections.\n\n![Data Model](./assets/images/travel_sample_data_model.png)\n\n## Extending API by Adding New Entity\n\nIf you would like to add another entity to the APIs, these are the steps to follow:\n\n1. Create a new model: Create a new model for the entity in the `app/models` folder. This model should contain the schema for the entity.\n2. Create the new route: In Rails, you can create a new route by adding a new resource in the `config/routes.rb` file. This file should contain the logic for the new entity's CRUD operations.\n3. Create the new controller: Create a new controller for the entity in the `app/controllers` folder. This controller should contain the logic for the new entity's CRUD operations.\n4. Add the integration tests: Add integration tests for the new entity in the `test/integration` folder. This ensures that the new entity's CRUD operations are tested. The test file should be named `\u003centity\u003e_spec.rb`.\n\nFollowing these steps ensures a systematic and organized approach to expanding the API functionality with a new entity.\n\n## Running Self-Managed Couchbase Cluster\n\nIf you are running this quickstart with a self-managed Couchbase cluster, you need to load the travel-sample data bucket in your cluster and generate the credentials for the bucket by creating a user.\n\nYou need to update the connection string and the credentials in the `dev.env` file in the root folder.\n\nNote: Couchbase Server must be installed and running prior to running this app.\n\n## Swagger Documentation\n\nSwagger documentation provides a clear view of the API including endpoints, HTTP methods, request parameters, and response objects.\n\nClick on an individual endpoint to expand it and see detailed information. This includes the endpoint's description, possible response status codes, and the request parameters it accepts.\n\n### Trying Out the API\n\nYou can try out an API by clicking on the \"Try it out\" button next to the endpoints.\n\nParameters: If an endpoint requires parameters, Swagger UI provides input boxes for you to fill in. This could include path parameters, query strings, headers, or the body of a POST/PUT request.\n\nExecution: Once you've inputted all the necessary parameters, you can click the \"Execute\" button to make a live API call. Swagger UI will send the request to the API and display the response directly in the documentation. This includes the response code, response headers, and response body.\n\n### Models\n\nSwagger documents the structure of request and response bodies using models. These models define the expected data structure using JSON schema and are extremely helpful in understanding what data to send and expect.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcouchbase-examples%2Fruby-on-rails-quickstart","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcouchbase-examples%2Fruby-on-rails-quickstart","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcouchbase-examples%2Fruby-on-rails-quickstart/lists"}