How to Fix the “docker: command not found” Error When Deploying Ruby on Rails Apps to a Fresh DigitalOcean Droplet Using Kamal

You’ve configured your Rails app, set up your deploy.yml file, and you’re ready to deploy to your shiny new DigitalOcean droplet using Kamal. You run kamal deploy with anticipation, only to be met with a frustrating error: “docker: command not found.” Sound familiar? Whether you’re deploying your first MVP or scaling an established application, getting your deployment infrastructure right from the start saves countless hours down the line.

This common deployment roadblock stops countless developers in their tracks during their first Kamal deployment. The good news? You’re not alone, and the solution is straightforward once you understand what’s happening behind the scenes. In this comprehensive guide, I’ll walk you through exactly why this error occurs and show you multiple proven solutions to get your Rails application deployed successfully.

Understanding the Root Cause: Why Docker Is Missing

Before we dive into solutions, let’s understand what’s actually happening when you encounter this error. When you run kamal deploy on a fresh DigitalOcean droplet, Kamal attempts to execute Docker commands on your remote server. However, a brand new droplet typically doesn’t have Docker pre-installed—it’s just a vanilla Ubuntu (or other Linux distribution) server waiting for configuration.

Kamal connects to servers via SSH and attempts to install Docker on any server missing it using get.docker.com, but this only happens when running kamal setup, not during kamal deploy. This is where most developers trip up. They skip the crucial kamal setup command and jump straight to deploying, assuming Kamal will handle everything automatically.

The error message you’re seeing—”bash: line 1: docker: command not found”—is your server literally telling you it can’t find the Docker executable in its system PATH. The error typically appears with exit status 127, which specifically indicates a command not found error in Unix systems.

The Critical First Step: Run kamal setup Before kamal deploy

The most elegant and recommended solution is to use Kamal’s built-in server provisioning command. This is exactly what Kamal was designed to handle for you.

What kamal setup Actually Does

The kamal setup command sets up dependencies on your application server, installs Docker if missing, builds your container image locally, pushes it to your registry, pulls the image onto your application server, and generates SSL certificates via Let’s Encrypt. It’s essentially your server’s initialization process.

Here’s what happens step-by-step when you run this command:

1. Kamal establishes an SSH connection to each server listed in your deploy.yml
2. It checks whether Docker is installed on the remote machine
3. If Docker is missing, it automatically installs it using the official installation script
4. It configures Docker to start automatically on system boot
5. It sets up Kamal proxy (the HTTP router) to handle incoming traffic
6. It prepares the environment for your first deployment

How to Run kamal setup Correctly

Before running kamal setup, make absolutely sure you’ve committed all your changes to git. Kamal uses the latest commit hash for image names, and if you don’t commit first, your deployment may ship an old image.

# Commit all your changes first
git add .
git commit -m "Configure Kamal deployment"

# Now run setup
kamal setup

This command will take several minutes to complete—significantly longer than a regular kamal deploy. Don’t worry, this is normal. You’re essentially provisioning an entire server from scratch.

During the process, you’ll see output indicating:

• Docker installation progress
• Image building and pushing to your registry
• Kamal proxy configuration
• Your application container starting up

Once kamal setup completes successfully, your application should be live and accessible at your configured domain or server IP address.

Solution 2: Manually Installing Docker on Your Droplet

If you prefer more control or need to install Docker separately from Kamal’s automated process, you can manually install Docker on your DigitalOcean droplet before attempting deployment. This approach gives you visibility into exactly what’s being installed and how.

Step-by-Step Manual Docker Installation

Connect to your droplet via SSH:

ssh root@your_droplet_ip

First update your package index and install prerequisites like apt-transport-https, ca-certificates, curl, gnupg, and lsb-release, then add Docker’s official GPG key and set up the stable repository.

# Update package database
sudo apt update

# Install prerequisite packages
sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release

# Add Docker's official GPG key
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Set up the stable repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Update package database again
sudo apt update

# Install Docker Engine
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Verify Your Docker Installation

After installation completes, verify that Docker is running properly:

# Check Docker version
docker --version

# Verify Docker is running
sudo systemctl status docker

# Test with hello-world container
docker run hello-world

If you see the “Hello from Docker!” message, your installation is successful and you can proceed with kamal deploy.

Configure Non-Root User Access (Recommended)

For security best practices, you should create a dedicated deployment user rather than using root:

# Create a deployment user
sudo useradd --create-home -s /bin/bash deploy
sudo adduser deploy sudo
sudo passwd deploy

# Add the user to the docker group
sudo usermod -aG docker deploy

Update your config/deploy.yml to use this user:

ssh:
  user: deploy

Solution 3: Using DigitalOcean’s Docker 1-Click Droplet

DigitalOcean offers a streamlined alternative—creating a droplet with Docker pre-installed. This eliminates the installation step entirely.

Creating a Docker-Ready Droplet

When creating your droplet in the DigitalOcean control panel:

1. Click “Create” → “Droplets”
2. Under “Choose an image,” select the “Marketplace” tab
3. Search for “Docker” in the search box
4. Select “Docker on Ubuntu”
5. Choose your droplet size (minimum 1GB RAM recommended)
6. Select your datacenter region
7. Add your SSH keys for authentication
8. Click “Create Droplet”

The Docker 1-Click installation includes Docker CE version 20.10.7 or later and Docker Compose, making it ideal for developers and small-to-medium businesses.

Once your Docker-enabled droplet is created, you can skip directly to kamal deploy without needing kamal setup, since Docker is already installed and running.

Troubleshooting: When Docker Installation Fails

Even with the correct approach, you might encounter issues. Here are solutions to common problems:

Issue: Permission Denied Error

If you see “permission denied while trying to connect to the Docker daemon socket,” your user lacks Docker permissions.

Solution:

# Add your current user to the docker group
sudo usermod -aG docker $USER

# Log out and back in, or run:
newgrp docker

# Verify access
docker ps

Issue: Docker Service Not Starting

If Docker installs but won’t start:

# Check Docker service status
sudo systemctl status docker

# Start Docker service
sudo systemctl start docker

# Enable Docker to start on boot
sudo systemctl enable docker

# View recent logs
sudo journalctl -u docker.service -n 50

Issue: Kamal Can’t Find Docker After Installation

Sometimes the PATH variable doesn’t update immediately.

Solution:

# Find Docker location
which docker

# If it returns a path, add it to your PATH
export PATH="/usr/local/bin:$PATH"

# Make it permanent by adding to ~/.bashrc
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Issue: SSH Connection Failures During Setup

Kamal requires SSH access to servers using root by default, authenticated by your SSH key, and root access via SSH is needed for Docker installation.

Solution: Verify your SSH configuration in config/deploy.yml:

servers:
  web:
    - your_droplet_ip

ssh:
  user: root  # or your custom user

Test SSH connectivity manually:

ssh root@your_droplet_ip

Best Practices for Kamal Deployments on DigitalOcean

1. Always Use kamal setup for Fresh Servers

Make it a habit: fresh server equals kamal setup first, deploy second. This single practice will save you countless headaches.

2. Commit Before Deploying

Kamal versioning relies on git commit hashes. Always commit your changes before running any Kamal commands.

3. Start with Adequate Resources

Ensure you have enough RAM on your server; insufficient memory can cause the system to go into swap during deployment, making it too slow and causing deployment timeouts. Start with at least a 1GB droplet for small applications. Once your deployment infrastructure is running smoothly, learn how Ruby on Rails services power scalable SaaS applications for long-term growth and sustainability.

4. Configure Your Deploy.yml Properly

Here’s a minimal but complete configuration:

service: your-app-name
image: yourusername/your-app-name

servers:
  web:
    - your_droplet_ip

registry:
  username: your_docker_hub_username
  password:
    - KAMAL_REGISTRY_PASSWORD

env:
  secret:
    - RAILS_MASTER_KEY

5. Secure Your Server Immediately

Kamal only installs Docker and doesn’t harden your instance; you need to set up a firewall to block all ports except those necessary for your app, and fail2ban to prevent brute force attacks.

Basic firewall setup:

# Allow SSH, HTTP, and HTTPS
sudo ufw allow 22
sudo ufw allow 80
sudo ufw allow 443

# Enable firewall
sudo ufw enable

Understanding the Kamal Deployment Workflow

To prevent future issues, let’s clarify the complete deployment workflow:

For First-Time Deployment:

1. Configure config/deploy.yml with your server details
2. Set up your .kamal/secrets file with credentials
3. Commit all changes to git
4. Run kamal setup (installs Docker, sets up everything)
5. Your app is now live

For Subsequent Deployments:

1. Make your code changes
2. Commit changes to git
3. Run kamal deploy (Docker already installed)
4. Changes go live with zero downtime

f you’re new to Rails command line tools, mastering Rails CLI commands will help you navigate deployment workflows more efficiently.

Comparison: Different Approaches to Docker Installation

When to Use Each Approach

Use kamal setup when:

• You’re deploying to a fresh server for the first time
• You want Kamal to handle everything automatically
• You’re following standard Kamal workflows
• You trust Kamal’s installation process

Use manual installation when:

• You need specific Docker versions or configurations
• You’re managing multiple servers with infrastructure-as-code tools
• Your organization has specific security requirements
• You want to understand each installation step

Use Docker 1-Click droplets when:

• You’re deploying multiple applications to different servers
• You want to minimize initial setup time
• You’re comfortable with DigitalOcean’s pre-configured Docker version
• You plan to manage Docker independently of Kamal

Wrapping Up: Your Path to Successful Kamal Deployments

The “docker: command not found” error is a rite of passage for Kamal users—frustrating when you first encounter it, but trivial once you understand the solution. The key takeaway is simple: fresh servers need kamal setup, not kamal deploy.

By following this guide, you now have three proven approaches to resolve this error, plus the knowledge to troubleshoot common deployment issues. Whether you choose Kamal’s automated setup, manual Docker installation, or Docker-ready droplets, you’re equipped to deploy your Rails applications confidently.

Remember, Kamal is designed to simplify containerized deployments without vendor lock-in. Once you get past this initial setup hurdle, you’ll experience the joy of zero-downtime deploys, easy rollbacks, and the freedom to run your applications anywhere. For teams managing complex Rails applications or facing unique deployment challenges beyond standard Kamal setups, professional Ruby on Rails consulting can provide customized solutions tailored to your infrastructure needs.

Ready to deploy? Commit your changes, run kamal setup, and watch your Rails application come to life on your DigitalOcean droplet.