Dev Environment Setup Guide

Overview

This guide covers how to set up and run the Cloudinary documentation site locally for development purposes using Docker. For the alternative local Ruby setup, see Advanced: Local Machine Setup.

Prerequisites

• IDE: Install Cursor (recommended) or VS Code, along with essential extensions - see Essential Tools for setup details
• GitHub: Set up SSH keys for your GitHub account - see GitHub SSH setup
• VPN: Access to Cloudflare WARP VPN (required for installing gem dependencies)
• Docker: Install Docker Desktop - sign in with your Cloudinary email
• Repository: Clone the cld_docs repository to a /dev folder for consistency with other Cloudinary colleagues

Docker Setup

Docker provides a consistent, isolated environment that's easy to maintain and troubleshoot. This is the recommended approach for all team members.

Initial 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

Running the Site

Start the Site:

Access the Site:

http://localhost:3000/documentation

Stop the Site:

Optional: Use Custom Domain with HTTPS

If you prefer a more production-like experience with HTTPS, you can set up the docs-dev.cloudinary.com domain.

1. Add the domain to your hosts file:

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

2. Set up port forwarding (required after every computer restart):

Enter your Mac password when prompted.

3. Access the site at: https://docs-dev.cloudinary.com/documentation

Content Renderer Integration

The content renderer (markdown → HTML rendering and code widgets) is now part of the main codebase in lib/content_renderer/.

What Changed

Before: Content renderer was a separate gem (cld_content_renderer) in its own repository.

After: All code is integrated directly into cld_docs under lib/content_renderer/.

Key Benefits

• Simpler development: Edit files directly in lib/content_renderer/ and restart the server
• No gem publishing: Changes are immediate, no version bumps needed
• Better debugging: All code visible in one repository

Code Structure

Core files:

• lib/content_renderer/markdown_renderer.rb - Markdown to HTML conversion
• lib/content_renderer/helpers/multi_code_widget.rb - Interactive code examples
• lib/content_renderer/helpers/frameworks.rb - SDK definitions and versions
• app/assets/javascripts/content_renderer.js - Client-side code widget logic
• app/assets/stylesheets/content_renderer.scss - Code widget styles

Development Workflow

When modifying content renderer functionality:

1. Edit files in lib/content_renderer/ or app/assets/
2. Restart Docker container
3. Test changes
4. Commit as normal code

Technical Details

• Dependencies: redcarpet, coderay, and rest-client are now direct dependencies (previously bundled with gem)
• Loading: Manually loaded in config/application.rb to avoid Zeitwerk conflicts
• No Engine: Removed Rails Engine architecture, code loads directly
• Assets: Moved to main application's asset pipeline

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

Advanced: 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:

In the root of your cld_docs folder: bash bundle

Running the Local Environment

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

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

Configuring Aliases (Optional)

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

Then run: source ~/.bash_profile

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

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