Deno Microservices with Consul & HAProxy

Build a production-ready Deno microservices architecture with Consul service discovery, HAProxy load balancing, and comprehensive monitoring using Prometheus. This tutorial covers container orchestration, health checks, and automated failover for scalable applications.

Prerequisites

Linux server with sudo access
4GB+ RAM for running multiple services
Basic understanding of microservices architecture
Familiarity with TypeScript/JavaScript

What this solves

Modern applications need to scale horizontally by breaking into smaller services, but managing multiple Deno microservices becomes complex without proper service discovery and load balancing. This tutorial builds a production-ready architecture where Deno services automatically register themselves with Consul, HAProxy distributes traffic based on health checks, and Prometheus monitors the entire stack.

Step-by-step installation

Update system packages

Start by updating your package manager to ensure you get the latest versions of all components.

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl wget unzip software-properties-common

sudo dnf update -y
sudo dnf install -y curl wget unzip

Install Deno runtime

Install Deno using the official installation script, then verify the installation.

curl -fsSL https://deno.land/install.sh | sh
echo 'export DENO_INSTALL="$HOME/.deno"' >> ~/.bashrc
echo 'export PATH="$DENO_INSTALL/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
deno --version

Install Consul for service discovery

Download and install HashiCorp Consul for service registration and health checking.

CONSUL_VERSION="1.17.0"
wget https://releases.hashicorp.com/consul/${CONSUL_VERSION}/consul_${CONSUL_VERSION}_linux_amd64.zip
unzip consul_${CONSUL_VERSION}_linux_amd64.zip
sudo mv consul /usr/local/bin/
sudo chmod +x /usr/local/bin/consul
consul version

Configure Consul server

Create Consul configuration directory and setup the main configuration file.

sudo mkdir -p /etc/consul.d /opt/consul
sudo useradd --system --home /etc/consul.d --shell /bin/false consul
sudo chown -R consul:consul /etc/consul.d /opt/consul

datacenter = "dc1"
data_dir = "/opt/consul"
log_level = "INFO"
server = true
bootstrap_expect = 1
bind_addr = "0.0.0.0"
client_addr = "0.0.0.0"
ui_config {
  enabled = true
}
connect {
  enabled = true
}
ports {
  grpc = 8502
}
acl = {
  enabled = false
  default_policy = "allow"
}

Create Consul systemd service

Setup Consul to run as a systemd service with automatic restarts.

[Unit]
Description=Consul
Requires=network-online.target
After=network-online.target
ConditionFileNotEmpty=/etc/consul.d/consul.hcl

[Service]
Type=notify
User=consul
Group=consul
ExecStart=/usr/local/bin/consul agent -config-dir=/etc/consul.d/
ExecReload=/bin/kill -HUP $MAINPID
KillMode=process
Restart=on-failure
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable consul
sudo systemctl start consul
sudo systemctl status consul

Install HAProxy load balancer

Install HAProxy for distributing traffic across Deno microservices with health checks.

sudo apt install -y haproxy

sudo dnf install -y haproxy

Configure HAProxy with Consul integration

Setup HAProxy configuration with service discovery integration and health checks.

global
    daemon
    maxconn 4096
    log stdout local0
    stats socket /var/run/haproxy.sock mode 660 level admin
    stats timeout 30s

defaults
    mode http
    timeout connect 5s
    timeout client 30s
    timeout server 30s
    option httplog
    option dontlognull
    option redispatch
    retries 3

frontend api_gateway
    bind *:80
    bind *:443 ssl crt /etc/ssl/certs/haproxy.pem
    redirect scheme https if !{ ssl_fc }
    
    # Route based on URL path
    acl is_users_service path_beg /api/users
    acl is_orders_service path_beg /api/orders
    acl is_health path /health
    
    use_backend users_service if is_users_service
    use_backend orders_service if is_orders_service
    use_backend health_check if is_health
    default_backend api_default

backend users_service
    balance roundrobin
    option httpchk GET /health
    http-check expect status 200
    # Dynamic backend discovery via Consul
    server-template users 3 _users._tcp.service.consul:8080 check resolvers consul

backend orders_service
    balance roundrobin
    option httpchk GET /health
    http-check expect status 200
    server-template orders 3 _orders._tcp.service.consul:8081 check resolvers consul

backend api_default
    balance roundrobin
    server default 127.0.0.1:8000 check

backend health_check
    http-request return status 200 content-type text/plain string "HAProxy healthy"

resolvers consul
    nameserver consul 127.0.0.1:8600
    accepted_payload_size 8192
    hold valid 5s

listen stats
    bind *:8404
    stats enable
    stats uri /
    stats refresh 5s
    stats admin if TRUE

Install Prometheus for monitoring

Download and install Prometheus to monitor your microservices architecture.

PROMETHEUS_VERSION="2.48.0"
wget https://github.com/prometheus/prometheus/releases/download/v${PROMETHEUS_VERSION}/prometheus-${PROMETHEUS_VERSION}.linux-amd64.tar.gz
tar xvf prometheus-${PROMETHEUS_VERSION}.linux-amd64.tar.gz
sudo mv prometheus-${PROMETHEUS_VERSION}.linux-amd64/prometheus /usr/local/bin/
sudo mv prometheus-${PROMETHEUS_VERSION}.linux-amd64/promtool /usr/local/bin/
sudo mkdir -p /etc/prometheus /var/lib/prometheus
sudo useradd --system --home /var/lib/prometheus --shell /bin/false prometheus
sudo chown prometheus:prometheus /etc/prometheus /var/lib/prometheus

Configure Prometheus with service discovery

Setup Prometheus to automatically discover services registered in Consul.

global:
  scrape_interval: 15s
  evaluation_interval: 15s

rule_files:
  - "/etc/prometheus/rules/*.yml"

alerting:
  alertmanagers:
    - static_configs:
        - targets:
          - localhost:9093

scrape_configs:
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']

  - job_name: 'consul'
    static_configs:
      - targets: ['localhost:8500']
    metrics_path: /v1/agent/metrics
    params:
      format: ['prometheus']

  - job_name: 'haproxy'
    static_configs:
      - targets: ['localhost:8404']
    metrics_path: /stats/prometheus

  - job_name: 'consul-services'
    consul_sd_configs:
      - server: 'localhost:8500'
        services: ['users', 'orders']
    relabel_configs:
      - source_labels: [__meta_consul_service]
        target_label: job
      - source_labels: [__meta_consul_node]
        target_label: instance
      - source_labels: [__meta_consul_service_address]
        target_label: __address__
      - source_labels: [__meta_consul_service_port]
        target_label: __address__
        regex: '(.*)'
        replacement: '${1}:${__meta_consul_service_port}'

  - job_name: 'deno-services'
    consul_sd_configs:
      - server: 'localhost:8500'
        tags: ['deno', 'microservice']
    relabel_configs:
      - source_labels: [__meta_consul_service]
        target_label: service
      - source_labels: [__address__]
        target_label: __address__
        regex: '([^:]+):(\d+)'
        replacement: '${1}:${2}'
    metrics_path: '/metrics'

Create Prometheus systemd service

Setup Prometheus to run as a systemd service with proper permissions.

[Unit]
Description=Prometheus
Wants=network-online.target
After=network-online.target

[Service]
User=prometheus
Group=prometheus
Type=simple
ExecStart=/usr/local/bin/prometheus \
    --config.file /etc/prometheus/prometheus.yml \
    --storage.tsdb.path /var/lib/prometheus/ \
    --web.console.templates=/etc/prometheus/consoles \
    --web.console.libraries=/etc/prometheus/console_libraries \
    --web.listen-address=0.0.0.0:9090 \
    --web.enable-lifecycle
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable prometheus
sudo systemctl start prometheus

Create Deno microservice template

Create a reusable template for Deno microservices with service registration and metrics.

mkdir -p ~/deno-microservices
cd ~/deno-microservices

import { serve } from "https://deno.land/std@0.208.0/http/server.ts";

export interface ServiceConfig {
  name: string;
  port: number;
  version: string;
  consulUrl?: string;
}

export class MicroService {
  private config: ServiceConfig;
  private routes: Map

Create users microservice

Build the first microservice for user management with Consul registration.

import { MicroService } from "./service-base.ts";

const service = new MicroService({
  name: "users",
  port: 8080,
  version: "1.0.0",
});

// Mock user data
const users = new Map([
  ["1", { id: "1", name: "Alice Johnson", email: "alice@example.com" }],
  ["2", { id: "2", name: "Bob Smith", email: "bob@example.com" }],
  ["3", { id: "3", name: "Carol Wilson", email: "carol@example.com" }],
]);

// GET /api/users
service.addRoute("/api/users", async (req: Request) => {
  if (req.method !== "GET") {
    return new Response("Method Not Allowed", { status: 405 });
  }
  
  return new Response(JSON.stringify(Array.from(users.values())), {
    status: 200,
    headers: { "Content-Type": "application/json" },
  });
});

// GET /api/users/:id
service.addRoute("/api/users/", async (req: Request) => {
  if (req.method !== "GET") {
    return new Response("Method Not Allowed", { status: 405 });
  }
  
  const url = new URL(req.url);
  const id = url.pathname.split("/").pop();
  
  if (!id || !users.has(id)) {
    return new Response("User not found", { status: 404 });
  }
  
  return new Response(JSON.stringify(users.get(id)), {
    status: 200,
    headers: { "Content-Type": "application/json" },
  });
});

if (import.meta.main) {
  service.start();
}

Create orders microservice

Build the second microservice for order management with service discovery.

import { MicroService } from "./service-base.ts";

const service = new MicroService({
  name: "orders",
  port: 8081,
  version: "1.0.0",
});

// Mock order data
const orders = new Map([
  ["1", { id: "1", userId: "1", items: ["laptop", "mouse"], total: 1299.99, status: "shipped" }],
  ["2", { id: "2", userId: "2", items: ["phone"], total: 899.99, status: "processing" }],
  ["3", { id: "3", userId: "1", items: ["keyboard"], total: 129.99, status: "delivered" }],
]);

// GET /api/orders
service.addRoute("/api/orders", async (req: Request) => {
  if (req.method !== "GET") {
    return new Response("Method Not Allowed", { status: 405 });
  }
  
  const url = new URL(req.url);
  const userId = url.searchParams.get("userId");
  
  let result = Array.from(orders.values());
  
  if (userId) {
    result = result.filter(order => order.userId === userId);
  }
  
  return new Response(JSON.stringify(result), {
    status: 200,
    headers: { "Content-Type": "application/json" },
  });
});

// GET /api/orders/:id
service.addRoute("/api/orders/", async (req: Request) => {
  if (req.method !== "GET") {
    return new Response("Method Not Allowed", { status: 405 });
  }
  
  const url = new URL(req.url);
  const id = url.pathname.split("/").pop();
  
  if (!id || !orders.has(id)) {
    return new Response("Order not found", { status: 404 });
  }
  
  return new Response(JSON.stringify(orders.get(id)), {
    status: 200,
    headers: { "Content-Type": "application/json" },
  });
});

if (import.meta.main) {
  service.start();
}

Create systemd services for Deno microservices

Setup systemd services to manage the Deno microservices lifecycle with automatic restarts.

[Unit]
Description=Deno Users Microservice
After=network.target consul.service
Requires=consul.service

[Service]
Type=simple
User=deno
Group=deno
WorkingDirectory=/home/deno/microservices
ExecStart=/home/deno/.deno/bin/deno run --allow-net --allow-env users-service.ts
Restart=always
RestartSec=5
Environment=SERVICE_ADDRESS=localhost
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

[Unit]
Description=Deno Orders Microservice
After=network.target consul.service
Requires=consul.service

[Service]
Type=simple
User=deno
Group=deno
WorkingDirectory=/home/deno/microservices
ExecStart=/home/deno/.deno/bin/deno run --allow-net --allow-env orders-service.ts
Restart=always
RestartSec=5
Environment=SERVICE_ADDRESS=localhost
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Create dedicated user and setup permissions

Create a dedicated user for running Deno services securely with minimal permissions.

sudo useradd --system --home /home/deno --create-home --shell /bin/bash deno
sudo mkdir -p /home/deno/microservices
sudo cp ~/deno-microservices/* /home/deno/microservices/
sudo chown -R deno:deno /home/deno
sudo chmod 755 /home/deno/microservices
sudo chmod 644 /home/deno/microservices/*.ts

Never use chmod 777. It gives every user on the system full access to your files. Instead, fix ownership with chown and use minimal permissions like 755 for directories and 644 for files.

Start all services

Enable and start all the services in the correct order with dependency checking.

# Start Consul first
sudo systemctl status consul

# Start HAProxy
sudo

Automated install script

Run this to automate the entire setup

install.sh

#!/usr/bin/env bash

set -euo pipefail

# Color codes for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color

# Default values
CONSUL_VERSION="1.17.0"
BIND_IP="${1:-0.0.0.0}"

# Usage message
usage() {
    echo "Usage: $0 [bind_ip]"
    echo "  bind_ip: IP address to bind services (default: 0.0.0.0)"
    exit 1
}

# Logging functions
log_info() { echo -e "${BLUE}[INFO]${NC} $1"; }
log_success() { echo -e "${GREEN}[SUCCESS]${NC} $1"; }
log_warning() { echo -e "${YELLOW}[WARNING]${NC} $1"; }
log_error() { echo -e "${RED}[ERROR]${NC} $1"; }

# Cleanup function for rollback
cleanup() {
    log_error "Installation failed. Cleaning up..."
    systemctl stop consul 2>/dev/null || true
    systemctl stop haproxy 2>/dev/null || true
    systemctl disable consul 2>/dev/null || true
    systemctl disable haproxy 2>/dev/null || true
    rm -f /usr/local/bin/consul /usr/local/bin/deno
    rm -rf /etc/consul.d /opt/consul
    userdel consul 2>/dev/null || true
    exit 1
}

trap cleanup ERR

# Check prerequisites
check_prerequisites() {
    if [[ $EUID -ne 0 ]]; then
        log_error "This script must be run as root or with sudo"
        exit 1
    fi
    
    if ! command -v curl >/dev/null 2>&1; then
        log_error "curl is required but not installed"
        exit 1
    fi
}

# Auto-detect distribution
detect_distro() {
    if [ -f /etc/os-release ]; then
        . /etc/os-release
        case "$ID" in
            ubuntu|debian) 
                PKG_MGR="apt"
                PKG_UPDATE="apt update && apt upgrade -y"
                PKG_INSTALL="apt install -y"
                ;;
            almalinux|rocky|centos|rhel|ol|fedora)
                PKG_MGR="dnf"
                PKG_UPDATE="dnf update -y"
                PKG_INSTALL="dnf install -y"
                ;;
            amzn)
                PKG_MGR="yum"
                PKG_UPDATE="yum update -y"
                PKG_INSTALL="yum install -y"
                ;;
            *)
                log_error "Unsupported distribution: $ID"
                exit 1
                ;;
        esac
    else
        log_error "Cannot detect distribution. /etc/os-release not found."
        exit 1
    fi
    log_success "Detected distribution: $ID using $PKG_MGR"
}

# Validate arguments
if [[ $# -gt 1 ]]; then
    usage
fi

check_prerequisites
detect_distro

log_info "[1/6] Updating system packages..."
eval $PKG_UPDATE
if [[ "$PKG_MGR" == "apt" ]]; then
    $PKG_INSTALL curl wget unzip software-properties-common
else
    $PKG_INSTALL curl wget unzip
fi
log_success "System packages updated"

log_info "[2/6] Installing Deno runtime..."
DENO_INSTALL="/usr/local" curl -fsSL https://deno.land/install.sh | sh
mv ~/.deno/bin/deno /usr/local/bin/
chmod 755 /usr/local/bin/deno
if deno --version >/dev/null 2>&1; then
    log_success "Deno installed successfully"
else
    log_error "Deno installation failed"
    exit 1
fi

log_info "[3/6] Installing Consul for service discovery..."
cd /tmp
wget -q https://releases.hashicorp.com/consul/${CONSUL_VERSION}/consul_${CONSUL_VERSION}_linux_amd64.zip
unzip -q consul_${CONSUL_VERSION}_linux_amd64.zip
mv consul /usr/local/bin/
chmod 755 /usr/local/bin/consul
rm -f consul_${CONSUL_VERSION}_linux_amd64.zip
if consul version >/dev/null 2>&1; then
    log_success "Consul installed successfully"
else
    log_error "Consul installation failed"
    exit 1
fi

log_info "[4/6] Configuring Consul server..."
mkdir -p /etc/consul.d /opt/consul
useradd --system --home /etc/consul.d --shell /bin/false consul 2>/dev/null || true
chown -R consul:consul /etc/consul.d /opt/consul

cat > /etc/consul.d/consul.hcl << EOF
datacenter = "dc1"
data_dir = "/opt/consul"
log_level = "INFO"
server = true
bootstrap_expect = 1
bind_addr = "${BIND_IP}"
client_addr = "${BIND_IP}"
ui_config {
  enabled = true
}
connect {
  enabled = true
}
ports {
  grpc = 8502
}
acl = {
  enabled = false
  default_policy = "allow"
}
EOF
chmod 644 /etc/consul.d/consul.hcl
chown consul:consul /etc/consul.d/consul.hcl

cat > /etc/systemd/system/consul.service << EOF
[Unit]
Description=Consul
Requires=network-online.target
After=network-online.target
ConditionFileNotEmpty=/etc/consul.d/consul.hcl

[Service]
Type=notify
User=consul
Group=consul
ExecStart=/usr/local/bin/consul agent -config-dir=/etc/consul.d/
ExecReload=/bin/kill -HUP \$MAINPID
KillMode=process
Restart=on-failure
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable consul
systemctl start consul
log_success "Consul configured and started"

log_info "[5/6] Installing and configuring HAProxy..."
$PKG_INSTALL haproxy

# Backup original config
cp /etc/haproxy/haproxy.cfg /etc/haproxy/haproxy.cfg.backup

cat > /etc/haproxy/haproxy.cfg << EOF
global
    daemon
    maxconn 4096
    log stdout local0
    stats socket /var/run/haproxy.sock mode 660 level admin
    stats timeout 30s

defaults
    mode http
    timeout connect 5s
    timeout client 30s
    timeout server 30s
    option httplog
    option dontlognull
    option redispatch
    retries 3

resolvers consul
    nameserver consul1 127.0.0.1:8600
    accepted_payload_size 8192
    hold valid 5s

frontend api_gateway
    bind *:8080
    
    # Route based on URL path
    acl is_users_service path_beg /api/users
    acl is_orders_service path_beg /api/orders
    acl is_health path /health
    
    use_backend users_service if is_users_service
    use_backend orders_service if is_orders_service
    use_backend health_check if is_health
    default_backend api_default

backend users_service
    balance roundrobin
    option httpchk GET /health
    http-check expect status 200

backend orders_service
    balance roundrobin
    option httpchk GET /health
    http-check expect status 200

backend health_check
    option httpchk GET /health
    http-check expect status 200

backend api_default
    option httpchk GET /health
    http-check expect status 200

listen stats
    bind *:8404
    stats enable
    stats uri /stats
    stats refresh 30s
EOF

chmod 644 /etc/haproxy/haproxy.cfg
systemctl enable haproxy
systemctl start haproxy
log_success "HAProxy configured and started"

log_info "[6/6] Configuring firewall and final verification..."
if command -v ufw >/dev/null 2>&1; then
    ufw allow 8080/tcp
    ufw allow 8500/tcp
    ufw allow 8404/tcp
elif command -v firewall-cmd >/dev/null 2>&1; then
    firewall-cmd --permanent --add-port=8080/tcp
    firewall-cmd --permanent --add-port=8500/tcp
    firewall-cmd --permanent --add-port=8404/tcp
    firewall-cmd --reload
fi

# Verification checks
log_info "Performing verification checks..."
sleep 5

if systemctl is-active --quiet consul; then
    log_success "✓ Consul service is running"
else
    log_error "✗ Consul service failed to start"
fi

if systemctl is-active --quiet haproxy; then
    log_success "✓ HAProxy service is running"
else
    log_error "✗ HAProxy service failed to start"
fi

if curl -s http://localhost:8500/ui/ >/dev/null; then
    log_success "✓ Consul UI accessible at http://localhost:8500"
else
    log_warning "⚠ Consul UI may not be accessible"
fi

if curl -s http://localhost:8404/stats >/dev/null; then
    log_success "✓ HAProxy stats accessible at http://localhost:8404/stats"
else
    log_warning "⚠ HAProxy stats may not be accessible"
fi

log_success "Installation completed successfully!"
log_info "Services available:"
log_info "  - Consul UI: http://localhost:8500"
log_info "  - HAProxy Stats: http://localhost:8404/stats"
log_info "  - Load Balancer: http://localhost:8080"

Review the script before running. Execute with: bash install.sh

#deno #microservices #consul #haproxy #prometheus

Implement Deno microservices architecture with service discovery and load balancing