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:

1. Create a free account at codehooks.io
2. Use the Codehooks CLI to authenticate and deploy your app
3. 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:

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

winget install OpenJS.NodeJS

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

sudo port install nodejs18

# 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

# 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

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.

# Install via Homebrew
brew install colima docker docker-compose

# Start Colima
colima start

docker --version
docker compose version

# 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

# 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

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​

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:

1. Check: docker compose ps (should show "Up")
2. Check: npm run logs for errors
3. 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! 🚀