Codehooks.io Local Development with Docker

This guide explains how to set up and develop Codehooks.io applications locally using Docker for a seamless development experience. Local development enables instant hot reloading and rapid iteration without deployment delays, dramatically speeding up your development workflow.

Account Requirements

Good news! You can create and develop Codehooks applications locally without registering any account at Codehooks.io. The local development environment allows you to:

Build and test your APIs locally
Use all Codehooks features and libraries
Develop and debug your application completely offline
Access your API endpoints at http://localhost:8080/dev/*

However, to deploy your application to the Codehooks.io cloud platform, you will need to:

Create a free account at codehooks.io
Use the Codehooks CLI to authenticate and deploy your app
Configure your production environment variables and settings

This means you can start building and experimenting with Codehooks right away, and only create an account when you're ready to share your application with the world!

🚀 Quick Start

Get up and running in 2 minutes:

1. Install Requirements

Install the necessary packages in your app directory:

npm install -g codehooks
npm install codehooks-js
npm install -D nodemon

2. Create a Simple App File

Create index.js with your text editor and add:

import { app } from "codehooks-js";
app.get("/", (req, res) => res.send("Hello World!"));
export default app.init();

3. Setup Package.json for Hot Reloading

Add these scripts to your package.json:

{
  "scripts": {
    "build": "codehooks compile --tofile index.cjs",
    "dev": "nodemon --watch . --ext js,html,css,json --exec \"npm run build\"",
    "start": "docker compose up -d",
    "stop": "docker compose down",
    "logs": "docker compose logs -f coderunner-service"
  }
}

4. Get Docker Setup

Download the Docker compose configuration:

curl -o docker-compose.yml https://codehooks.io/download/docker-compose.yml

5. Initial Compile

Build your application for the first time:

npm run build

6. Start Local Server

Start the local Codehooks server:

npm run start

7. Start Hot Reloading

In a new terminal, start the development watcher:

npm run dev

8. Test It Works

Verify your API is running:

curl http://localhost:8080/dev

9. Make Changes and Watch Auto-Reload

Edit index.js, save, and see your changes instantly reflected in the browser!

10. Stop Everything When Done

Stop all services:

npm run stop

That's it! Your API is running at http://localhost:8080/dev

Prerequisites

This section will guide you through installing everything you need for local Codehooks development. We'll explain what each tool does and provide installation instructions for Windows, macOS, and Linux.

Step 1: Install Node.js

What it does: Node.js is the JavaScript runtime that powers Codehooks applications.

Installation:

🪟 Windows

Option A: Download installer (recommended for beginners)

Go to nodejs.org
Download the LTS version for Windows
Run the installer and follow the prompts
Open Command Prompt or PowerShell and verify: node --version

Option B: Using Chocolatey

# Install Chocolatey first: https://chocolatey.org/install
choco install nodejs

Option C: Using winget

winget install OpenJS.NodeJS

🍎 macOS

Option A: Download installer

Go to nodejs.org
Download the LTS version for macOS
Run the installer

Option B: Using Homebrew (recommended)

# Install Homebrew first: https://brew.sh/
brew install node

Option C: Using MacPorts

sudo port install nodejs18

🐧 Linux

Ubuntu/Debian:

# Using NodeSource repository (recommended)
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# Or using snap
sudo snap install node --classic

CentOS/RHEL/Fedora:

# Using NodeSource repository
curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo dnf install nodejs

# Or using package manager
sudo dnf install nodejs npm

Arch Linux:

sudo pacman -S nodejs npm

Verify Node.js installation:

node --version    # Should show v18.x.x or higher
npm --version     # Should show 9.x.x or higher

Step 2: Install Codehooks CLI

What it does: The Codehooks CLI compiles your code and manages deployments.

npm install -g codehooks

Verify installation:

codehooks --version

Step 3: Install Docker

What it does: Docker runs the local Codehooks server environment, mimicking the cloud platform.

🪟 Windows

Requirements: Windows 10/11 with WSL 2 enabled

Enable WSL 2 (if not already enabled):

# Run as Administrator
wsl --install
# Restart computer if prompted

Install Docker Desktop:
- Download from docker.com/products/docker-desktop
- Run installer and follow setup wizard
- Ensure "Use WSL 2 instead of Hyper-V" is checked
- Start Docker Desktop from Start Menu
Verify installation:
```
docker --version
docker compose version
```

🍎 macOS

Option A: Docker Desktop (easiest)

Download from docker.com/products/docker-desktop
Drag to Applications folder
Launch Docker Desktop and complete setup

Option B: Colima (lightweight alternative)

# Install via Homebrew
brew install colima docker docker-compose

# Start Colima
colima start

Verify installation:

docker --version
docker compose version

🐧 Linux

Ubuntu/Debian:

# Remove old versions
sudo apt-get remove docker docker-engine docker.io containerd runc

# Install dependencies
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg lsb-release

# Add Docker's official GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

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

# Install Docker
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Add user to docker group (optional, avoids using sudo)
sudo usermod -aG docker $USER
# Log out and back in for this to take effect

CentOS/RHEL/Fedora:

# Install Docker
sudo dnf install docker docker-compose-plugin

# Start and enable Docker
sudo systemctl start docker
sudo systemctl enable docker

# Add user to docker group (optional)
sudo usermod -aG docker $USER

Verify installation:

docker --version
docker compose version

# Test Docker works
docker run hello-world

Step 4: Create Your Project Directory

Follow the Quick Start guide above to create and set up your project directory. It will walk you through creating a new Codehooks application from scratch.

✅ You're now ready to start developing! All the prerequisites are installed and configured.

Development Workflow

Daily Routine

# Start the server (if not running)
npm run start

# Start hot reloading (in a separate terminal)
npm run dev

# Your app is now available at:
# http://localhost:8080/dev

During development:

Edit your index.js file
Save → hot reload rebuilds automatically
Check logs: npm run logs
Stop everything: npm run stop

Local URLs

URL	Purpose
`http://localhost:8080/dev`	Main endpoint
`http://localhost:8080/dev/api/*`	API routes

Common Tasks

Environment variables:

# .env file
MY_API_KEY=your-secret-key

# In your code
res.json({ apiKey: process.env.MY_API_KEY });

Database example:

import { app, Datastore } from "codehooks-js";

app.post("/api/users", async (req, res) => {
  const db = await Datastore.open();
  const user = await db.insertOne("users", req.body);
  res.json(user);
});

export default app.init();

Environment Variables

Create a .env file in your project root:

# Example variables
PORT=8080
DBSECRET=password1234
EXTERNAL_API_KEY=your-api-key

Access in your code:

const apiKey = process.env.EXTERNAL_API_KEY;

Notes:

Add .env to .gitignore
Restart containers after changes: docker compose restart

Useful Commands

# Development
npm run start        # Start server
npm run stop         # Stop server  
npm run dev          # Hot reloading
npm run build        # Manual build
npm run logs         # View logs

# Docker
docker compose ps        # Check status
docker compose restart  # Restart services
docker compose down --volumes  # Reset everything

# Debugging
codehooks --version     # Check CLI version
docker --version        # Check Docker version

Troubleshooting

Quick Diagnostics

# Check services status
docker compose ps
npm run logs

# Check versions
node --version
docker --version
codehooks --version

Common Issues

Port already in use:

# Change port in .env file
PORT=3000

# Or find and kill process using port 8080
# macOS/Linux: lsof -i :8080
# Windows: netstat -ano | findstr :8080

Docker not running:

Windows: Start Docker Desktop from Start Menu
macOS: Launch Docker Desktop or colima start
Linux: sudo systemctl start docker

Hot reloading not working:

# Check if nodemon is running
npm run dev

# Manual rebuild
npm run build

App not loading:

Check: docker compose ps (should show "Up")
Check: npm run logs for errors
Use correct URL: http://localhost:8080/dev

Reset everything:

npm run stop
docker compose down --volumes
npm run start

Next Steps

You're now ready to:

Build your API endpoints
Test with curl or Postman
Deploy to production

Happy coding! 🚀

Account Requirements​

🚀 Quick Start​

1. Install Requirements​

2. Create a Simple App File​

3. Setup Package.json for Hot Reloading​

4. Get Docker Setup​

5. Initial Compile​

6. Start Local Server​

7. Start Hot Reloading​

8. Test It Works​

9. Make Changes and Watch Auto-Reload​

10. Stop Everything When Done​

Prerequisites​

Step 1: Install Node.js​

Step 2: Install Codehooks CLI​

Step 3: Install Docker​

Step 4: Create Your Project Directory​

Development Workflow​

Daily Routine​

Local URLs​

Common Tasks​

Environment Variables​

Useful Commands​

Troubleshooting​

Quick Diagnostics​

Common Issues​

Next Steps​

Account Requirements

🚀 Quick Start

1. Install Requirements

2. Create a Simple App File

3. Setup Package.json for Hot Reloading

4. Get Docker Setup

5. Initial Compile

6. Start Local Server

7. Start Hot Reloading

8. Test It Works

9. Make Changes and Watch Auto-Reload

10. Stop Everything When Done

Prerequisites

Step 1: Install Node.js

Step 2: Install Codehooks CLI

Step 3: Install Docker

Step 4: Create Your Project Directory

Development Workflow

Daily Routine

Local URLs

Common Tasks

Environment Variables

Useful Commands

Troubleshooting

Quick Diagnostics

Common Issues

Next Steps