Internal Documentation
Menu

Dev Environment Setup Guide

Last updated: Sep-15-2025

Overview

This guide covers how to set up and run the Cloudinary documentation site locally for development purposes. There are two main approaches: using Docker (recommended) or setting up a local Ruby environment.

Note

Before you begin: Installing the various Cloudinary gem dependencies requires connecting to the Cloudflare Warp VPN.

On this page:

Prerequisites

  • Clone this cld_docs repository to a /dev folder for consistency with other Cloudinary colleagues
  • Setup SSH keys for your GitHub account - see GitHub SSH setup
  • Access to Cloudflare Warp VPN
  • Docker Desktop (for Docker approach) or local Ruby environment setup

Setup Options

Option 1: Docker Setup (Recommended)

Docker provides a consistent, isolated environment that's easier to maintain and troubleshoot.

Initial Docker Setup

1. Install Docker Desktop

Download Docker Desktop and install if you don't already have Docker.

2. Start Docker and Login

Start Docker Desktop and login/register using your Cloudinary email.

3. Build the Containers

4. Install gem dependencies

5. Optional: Add Local Domain

Add docs-dev.cloudinary.com to /etc/hosts for a more production-like experience:

If you need help editing the hosts file, see these instructions.

Running with Docker

Start the Site: bash docker-compose up

Access the Site:

  • Standard: http://localhost:3000/documentation
  • With custom domain: https://docs-dev.cloudinary.com/documentation

Stop the Site: bash docker-compose down

Option 2: Local Machine Setup

For developers who prefer running Ruby directly on their machine or need more control over the environment.

Initial One-Time Setup

1. Add Local Domain

Add docs-dev.cloudinary.com to /etc/hosts:

2. Install Prerequisites

A) Install Homebrew bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

B) Install Node.js (if not already installed)

Check if you have Node: node -v

If not installed: bash brew install node

3. Prepare Rails Environment

A) Install Redis Cache: bash brew install redis

B) Add Redis to Mac Startup: bash brew services start redis

C) Install Exiftool: bash brew install exiftool

D) Install RVM (if you don't have it):

Check if you have it: source $HOME/.rvm/scripts/rvm

If not installed: bash \curl -sSL https://get.rvm.io | bash

E) Install Ruby Version

For Intel Macs: bash rvm install 3.3.5

For Apple Silicon Macs or if having installation problems: bash rvm install 3.3.5 --with-openssl-dir=`brew --prefix openssl@1.1`

F) Install Ruby Bundler: bash gem install bundler

G) Bundle the Gems:

Important

Connect to WARP Zero Trust VPN before running bundle.

In the root of your cld_docs folder: bash bundle

Notes
  • You may need to install Xcode and/or Xcode Command Line Tools if you see errors
  • If you have errors with redis-client, try: export CPPFLAGS="-I/usr/local/opt/openssl@3/include" and run bundle again
  • If you encounter GemWrappers warnings, resolve them with: rvm repair wrappers

Running the Local Environment

1. Set Port Forwarding (after every computer restart):

Note

Enter your Mac password to enable this action.

2. Start Rails Server (after every restart or when gems are updated):

Use either: bash rails s

Or for less verbose output: bash puma -b 'ssl://127.0.0.1:8443?key=certs/docs-dev.cloudinary.com.key&cert=certs/docs-dev.cloudinary.com.crt' -t 0:32

3. Access the Site:

Navigate to: https://docs-dev.cloudinary.com/documentation

Note

Allow Chrome to use the non-authorized certificates when prompted.

Maintenance Tasks

Upgrading Ruby Version

When a Ruby upgrade happens:

  1. Stop your dev server and close any open terminals
  2. Checkout the upgrade branch
  3. Install the new Ruby version: bash rvm install 3.3.5 --with-openssl-dir=`brew --prefix openssl@1.1`
  4. Uninstall gem-wrappers if you have it (no longer needed): bash gem uninstall gem-wrappers Follow the specific command it recommends
  5. Run bundle install to install updated dependencies
  6. Start your dev server to verify it's working
  7. If needed, revert to previous version by stopping server, closing terminals, and switching branches

Updating Content Renderer

The content renderer gem handles markdown → HTML rendering and code widgets.

  1. Edit Gemfile and update the version number: ruby gem 'cld_content_renderer', '1.0.4', source: "http://s3-proxy.cloudinary.com/cld-gem-repo/", require: false

  2. For Docker: Stop the containers. Run docker-compose run app bundle install then restart containers For local: run bundle then restart the Rails server

  3. Commit and push the updated Gemfile and Gemfile.lock files

When a content_renderer version is updated, you will need to perform step 2 above to ensure the latest version is installed.

Configuring Aliases (Optional)

To simplify frequently used commands, add these aliases to your ~/.bash_profile:

Then run: source ~/.bash_profile

Advanced: Static Content Generation

For testing full site generation (usually done on staging):

Output files are in public/static/documentation.

Viewing Static Files Locally

Install basic HTTP server (one-time): bash npm install http-server -g

View static files: bash cd public/static http-server

Access at:

  • http://localhost:8080/documentation
  • http://localhost:8080/documentation/sitemap.xml

Troubleshooting

Common Issues

  • Gem installation errors: Ensure you're connected to WARP VPN
  • Redis connection issues: Check that Redis is running with brew services list
  • SSL certificate warnings: Allow the browser to proceed with self-signed certificates
  • Port conflicts: Make sure no other services are using ports 3000, 8443, or 443

Getting Help

  • Check with the documentation team for environment-specific issues
  • Review recent JIRA tickets for known setup problems
  • Consult the main README.md for the most up-to-date setup instructions

✔️ Feedback sent!

Rate this page: