DEV Community: Ursula Okafo

Building an AI News Digest Agent with Mastra and Telex.im

Ursula Okafo — Fri, 07 Nov 2025 22:47:44 +0000

How I built a real-time news aggregation agent, integrated it with Telex.im, and learned about AI agent architecture along the way.

Introduction

For the HNG Stage 3 backend challenge, I set out to build something practical: an AI agent that delivers fresh news headlines on demand. The result? Daily Headline Digest Agent — an intelligent system that fetches trending news, summarizes it with AI, and integrates seamlessly with Telex.im.

This blog post walks through my journey: why I chose Mastra, how I built the agent, the integration challenges I faced, and what I learned about building AI systems at scale.

What I Built

Daily Headline Digest Agent is an AI-powered news assistant that:

Fetches real-time news from the GNews API across multiple categories (tech, business, sports, health, entertainment, science)
Supports country-specific news (Nigeria, USA, UK, Canada, Australia, India, and more)
Uses Google's Gemini 2.0 Flash model for intelligent summarization
Integrates with Telex.im for seamless workplace collaboration
Provides formatted, emoji-enhanced news digests with source attribution

Example interaction:

User: "Give me today's tech news"
Agent: "🗞️ Tech Headlines - Friday, November 7, 2025
1️⃣ OnePlus 15 launching in India on November 13...
2️⃣ iOS 26 Marks a New Divide in the iPhone Lineup..."

Why Mastra?

When I started this project, I had three options:

Build from scratch with raw APIs
Use LangChain/LlamaIndex
Use Mastra

I chose Mastra for several reasons:

1. Built for Telex Integration
Mastra has first-class support for Telex.im through the A2A protocol. This wasn't a hack — it was designed for this use case.

2. Simpler Agent Definition
With Mastra, defining an agent is straightforward:

export const newsDigestAgent = new Agent({
  name: 'newsDigestAgent',
  instructions: '...',
  model: google('gemini-2.0-flash'),
  tools: { fetchNews },
});

No complex prompt engineering needed. Clear, declarative syntax.

3. Type Safety
Being a TypeScript-first framework, Mastra gave me confidence with full type checking. My tools had validated schemas using Zod:

const newsToolSchema = z.object({
  topic: z.string().default('world'),
  maxArticles: z.number().min(3).max(10).default(5),
});

4. Built-in Server/Routing
Mastra handles HTTP routing, JSON-RPC validation, and API structure automatically. I didn't have to write boilerplate.

Architecture

Here's how the system is structured:

src/
├── mastra/
│   ├── agents/
│   │   └── news-agent.ts          # Main AI agent
│   ├── tools/
│   │   └── news-tools.ts          # GNews API integration
│   └── index.ts                   # Mastra instance
├── routes/
│   └── a2a-agent-route.ts         # Telex A2A protocol handler
├── index.ts                       # Express server
└── types/
    └── a2a.types.ts              # Protocol types

Key Components:

newsDigestAgent - The AI agent that understands natural language and decides when to use tools
fetchNews - A tool that fetches news from GNews API with smart topic mapping
a2aAgentRoute - Handles JSON-RPC 2.0 requests from Telex.im
Express Server - Hosts everything on Railway

The Integration Journey

Phase 1: Local Development

I started by building the agent locally:

npm install @mastra/core @ai-sdk/google dotenv
npm run dev

The Mastra dev server gave me a Studio interface to test the agent instantly. This was powerful — I could iterate on instructions and see results in real-time.

Phase 2: Deployment Challenge

This is where I hit my first major hurdle: Node.js version compatibility.

My dependencies required Node 20+, but Railway was deploying Node 18. The error was cryptic at first:

ERR_MODULE_NOT_FOUND: Cannot find module '/app/dist/mastra/agents/news-agent'

Solution: Create a .node-version file to specify Node.js 20:

echo "20" > .node-version

Lesson: Always verify your runtime environment. A simple version mismatch can cause confusing module resolution errors with ES modules.

Phase 3: ES Module Path Issues

Another challenge: ES modules require explicit file extensions in imports.

Before (broken):

import { newsDigestAgent } from './agents/news-agent';

After (working):

import { newsDigestAgent } from './agents/news-agent.js';

This is a Node.js ES module requirement, not specific to Mastra, but it's easy to miss.

Phase 4: Environment Variables

My biggest debugging headache was environment variables not being passed to the deployed container.

Initially, I set them via Railway CLI:

railway variables --set GOOGLE_GENERATIVE_AI_API_KEY=...

But they didn't persist properly. The fix was to redeploy and verify they appeared in the logs.

Lesson: Always check railway logs after setting environment variables.

Phase 5: A2A Protocol Implementation

The real integration work came with implementing the A2A (Agent-to-Agent) protocol for Telex.

Telex expects JSON-RPC 2.0 format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "message": {
      "parts": [{"text": "your message"}]
    }
  }
}

I built a dedicated route handler:

export const a2aAgentRoute = registerApiRoute('/a2a/agent/:agentId', {
  method: 'POST',
  handler: async (c) => {
    // Validate JSON-RPC 2.0
    // Extract message
    // Call agent
    // Return formatted response
  },
});

Key challenge: Handling multiple message formats. Telex might send different structures depending on context. My solution:

let message = 'Hello';
if (params?.message?.parts?.[0]?.text) {
  message = params.message.parts[0].text;
} else if (typeof params?.message === 'string') {
  message = params.message;
} else if (params?.content) {
  message = params.content;
}

What Worked Well

✅ Mastra's Structure - The framework enforces good patterns without feeling restrictive

✅ Tool System - Defining tools with Zod schemas is clean and type-safe

✅ Model Flexibility - Easy to switch between Google, OpenAI, Anthropic models

✅ Railway Deployment - Once environment issues were solved, deployments were smooth

✅ GNews API - Free, reliable news data with good coverage across categories and countries

What Was Tricky

❌ Telex Integration Documentation - Limited docs on custom A2A implementations (Telex seems designed primarily for Mastra Cloud)

❌ Module Resolution - ES modules require explicit extensions and proper tsconfig settings

❌ Environment Variables - Railroad between CLI setup and deployment wasn't intuitive

❌ Debugging A2A Failures - Hard to know exactly what Telex was sending without better error messages

Lessons Learned

1. Start with Local Testing
Always validate your agent works locally before deploying. The Mastra Studio is invaluable.

2. Read the Logs
Railway logs showed exactly what was failing. "No service linked" → "Missing environment variables" → "Module not found". The logs told the story.

3. Type Safety Saves Time
TypeScript + Zod caught errors before runtime. Schema validation prevented bad data from reaching the API.

4. Keep the Agent Instructions Clear
I spent time crafting detailed agent instructions with examples. This actually improved the agent's behavior significantly. Good instructions > complex prompts.

5. Handle Multiple Input Formats
Real-world integrations are messy. Building flexibility into message parsing was essential.

The Code

You can find the complete implementation here:

GitHub: https://github.com/Ursulaonyi/news-digest-agent
Deployed API: https://daily-headline-digest-production.up.railway.app
Health Check: https://daily-headline-digest-production.up.railway.app/health
Test Endpoint: POST /api/chat with {"message": "your query"}

What's Next

Possible improvements:

Add caching to reduce API calls
Implement sentiment analysis on headlines
Add multi-language support
Create a web UI for the agent
Build a scheduled digest for Slack integration

Final Thoughts

Building the Daily Headline Digest Agent taught me that modern AI agent frameworks like Mastra handle a lot of complexity beautifully. The hardest parts weren't about AI — they were about infrastructure, environment setup, and protocol integration.

If you're building AI agents, I'd recommend:

Use Mastra if you want structure and Telex integration
Invest time in good instructions — they matter more than you think
Test locally first — catch issues before deploying
Read the logs — they tell you everything
Build for flexibility — real integrations are messier than documentation suggests

The Daily Headline Digest Agent is live, integrated with Telex.im, and delivering real news to users. Not bad for a stage 3 backend challenge! 🚀

Built with: TypeScript, Mastra, Google Gemini 2.0 Flash, GNews API, Express, Railway

Deployed: November 7, 2025

GitHub: https://github.com/Ursulaonyi/news-digest-agent

Building a Production-Grade Automated Deployment Script

Ursula Okafo — Mon, 20 Oct 2025 18:40:06 +0000

Introduction

Automation is the backbone of modern DevOps. In this comprehensive guide, I'll walk you through building a production-grade Bash script that automates the entire deployment process for a Dockerized application on a remote Linux server. This is my journey through the HNG DevOps Stage 1 task.

What We Built

A single Bash script (deploy.sh) that handles:

Git repository authentication and cloning
Remote server SSH connectivity
Automated Docker, Docker Compose, and Nginx installation
Docker image building and container deployment
Nginx reverse proxy configuration
Comprehensive logging and error handling
Deployment validation

Why Automation Matters

Manual deployments are error-prone, time-consuming, and don't scale. By automating the entire process, we achieve:

Consistency: Same process every time
Speed: Deploy in minutes, not hours
Reliability: Fewer human errors
Repeatability: Deploy multiple times safely
Documentation: The script IS the deployment process

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                    Local Machine                        │
│  ┌──────────────────────────────────────────────────┐  │
│  │  deploy.sh (Deployment Script)                   │  │
│  │  - Collects parameters                           │  │
│  │  - Clones Git repo                               │  │
│  │  - SSH into remote server                        │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                          │
                          │ SSH
                          ▼
┌─────────────────────────────────────────────────────────┐
│              Remote Server (EC2/VPS)                    │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Step 1: Install Docker & Nginx                  │  │
│  │  Step 2: Clone application repo                  │  │
│  │  Step 3: Build Docker image                      │  │
│  │  Step 4: Run container                           │  │
│  │  Step 5: Configure Nginx proxy                   │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

The 8-Step Deployment Process

Step 1: Collect Parameters

The script prompts for all necessary information:

Git repository URL
Personal Access Token (for authentication)
Git branch to deploy
SSH credentials (username, IP, key path)
Application port

This interactive approach makes the script reusable and flexible.

Enter Git Repository URL: https://github.com/yourname/your-app
Enter Personal Access Token (PAT): ••••••••••
Enter Branch name (default: main): main
Enter SSH Username: ubuntu
Enter Server IP Address: 54.123.45.67
Enter SSH Key Path: ~/.ssh/id_rsa
Enter Application Port: 3000

Step 2: Clone the Repository

The script authenticates using the PAT and clones the repository with the specified branch. This ensures we have the exact code version to deploy.

Step 3: Verify Docker Configuration

Before proceeding, the script verifies that either a Dockerfile or docker-compose.yml exists. This validation prevents failed deployments early.

Step 4: Test SSH Connection

A connectivity check ensures the remote server is reachable before we start any remote operations. This saves time if there's a network issue.

Step 5: Prepare Remote Environment

The script SSH's into the server and:

Updates system packages
Installs Docker and Docker Compose
Installs Nginx
Adds the user to the Docker group
Enables and starts all services

All operations are idempotent—if Docker is already installed, the script skips it.

Step 6: Deploy the Application

The script:

Transfers project files to the remote server
Builds a Docker image
Stops any old containers
Launches a new container with the specified port

Step 7: Configure Nginx

A reverse proxy configuration is created that forwards HTTP traffic (port 80) to the Docker container's internal port. This allows external users to access your app.

server {
    listen 80;
    server_name _;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Step 8: Validate Deployment

The script confirms:

Docker service is running
Container is active
Nginx is running
Application is accessible

Key Technical Decisions

Bash Over Other Languages

Why Bash instead of Python or Go?

Portability: Works on any Linux/Unix system
No dependencies: Pre-installed on all servers
Simplicity: Close to shell commands we'd run manually
Production-tested: Used by major organizations

Error Handling

The script uses set -euo pipefail to catch errors immediately and trap functions to handle unexpected failures gracefully.

set -euo pipefail
trap 'handle_error $? $LINENO' ERR

Logging

All operations are logged to timestamped files:

./logs/deploy_20251020_180825.log

This provides an audit trail and helps with debugging failed deployments.

Idempotency

The script can be run multiple times safely:

It stops and removes old containers before creating new ones
Installation commands check if packages exist first
Nginx configuration is overwritten, not appended

Lessons Learned

Repository Structure Matters

Keep your deployment scripts alongside your application code in the same repository. This makes it easier for others to deploy your application without hunting for separate tools. A single repository with all necessary deployment files is more maintainable.

Separate Concerns

While the deployment script lives in the app repository, you might keep a separate deployment folder locally for running deployments. This keeps your working directory organized without affecting the repository structure.

Environment Configuration

Store .env files in your repository for non-sensitive defaults, but add them to .gitignore for production deployments. For sensitive data (API keys, database passwords), use GitHub Secrets or environment variable management tools instead of checking them into version control.

Testing Before Deployment

Always test your endpoints after deployment:

curl http://your-server-ip/
curl http://your-server-ip/health
curl http://your-server-ip/api/info

SSH Key Management

Store SSH keys securely and never commit them to repositories. Use appropriate file permissions (chmod 600).

Real-World Considerations

What We Didn't Include (But Should in Production)

SSL/TLS Certificates: Use Let's Encrypt with Certbot
Health Checks: Kubernetes-style readiness probes
Monitoring: Prometheus, Datadog, or similar
Scaling: Load balancers for multiple instances
Backup Strategy: Database backups before deployments
Rollback Plan: Ability to revert to previous versions

Security Improvements

Use GitHub Secrets instead of manual PAT entry
Implement IP whitelisting for SSH access
Use IAM roles instead of long-lived credentials
Scan Docker images for vulnerabilities
Implement least-privilege Docker containers

CI/CD Integration

This script integrates well with GitHub Actions:

- name: Deploy
  run: |
    chmod +x deploy.sh
    ./deploy.sh

Results

After running the deployment script:

Application successfully deployed to EC2
Accessible at http://3.78.183.186
All endpoints responding correctly
Nginx proxying traffic to container
Logs show successful deployment

The app returns:

{
  "message": "Deploy Wizard - HNG DevOps Stage 1",
  "status": "running",
  "version": "1.0.0",
  "timestamp": "2025-10-20T17:26:58.469Z"
}

Conclusion

Building an automated deployment script teaches you the fundamentals of DevOps:

Infrastructure as code
Automation principles
Server configuration
Container orchestration basics
Monitoring and validation

This script is a foundation you can build upon. In a real-world scenario, you'd integrate it with CI/CD pipelines, add monitoring, implement rollback strategies, and scale to multiple servers.

The journey from manual deployments to automation is what separates junior developers from seasoned DevOps engineers. Start here, and keep building.

The Implementation

The complete deployment script uses several key patterns that make it production-ready:

Error Handling: The script implements bash error handling with set -euo pipefail and trap functions to catch failures and provide meaningful error messages at each stage.

Logging: All operations are logged to timestamped files, creating an audit trail for debugging and compliance.

Idempotency: The script safely handles re-runs by checking if services exist before installation and cleanly stopping containers before redeployment.

SSH Integration: Rather than requiring multiple manual SSH commands, the script orchestrates the entire remote deployment through a single SSH connection, executing setup and deployment steps sequentially.

Parameter Validation: User inputs are validated immediately (checking SSH keys exist, ports are numbers, URLs have correct format) to fail fast.

View the Full Code

The complete deployment script and all supporting files are available in the repository:

View on GitHub

In the repository you'll find:

deploy.sh - The main deployment script
Dockerfile - Container configuration
package.json - Node.js dependencies
index.js - Sample application
README.md - Detailed documentation
.gitignore - Version control configuration

Feel free to fork, modify, and use this script as a foundation for your own deployments.

Resources

Have you built your own deployment script? Share your experience in the comments below.

Building a Production-Ready String Analyzer API with Node.js and EC2

Ursula Okafo — Mon, 20 Oct 2025 11:32:40 +0000

A complete guide to creating, deploying, and scaling a RESTful API service

Introduction

Ever wondered what makes a string special? Is it a palindrome? How many unique characters does it have? What's its cryptographic fingerprint?

I recently built a String Analyzer API that answers all these questions and more. In this post, I'll walk you through the entire journey—from the first line of code to a production deployment on AWS EC2 with Nginx as a reverse proxy.

What Does It Do?

The String Analyzer API is a RESTful service that accepts any string and returns comprehensive analysis including:

Length and word count
Palindrome detection (case-insensitive)
Unique character count
Character frequency mapping
SHA256 hash for unique identification
Advanced filtering with multiple criteria
Natural language queries ("show me single word palindromes")

Here's what happens when you analyze the string "ursula is a devops engineer":

{
  "id": "8f3e825d9f5b2c7a4e1f6d9c3b8a5e2f...",
  "value": "ursula is a devops engineer",
  "properties": {
    "length": 28,
    "is_palindrome": false,
    "unique_characters": 15,
    "word_count": 5,
    "sha256_hash": "8f3e825d9f5b2c7a4e1f6d9c3b8a5e2f...",
    "character_frequency_map": {
      "u": 2,
      "r": 2,
      "s": 3,
      "l": 1,
      "a": 2,
      "i": 2,
      "d": 1,
      "e": 4,
      "v": 1,
      "o": 1,
      "p": 1,
      "n": 2,
      "g": 1
    }
  },
  "created_at": "2025-10-20T12:00:00.000Z"
}

The Tech Stack

I chose a modern, lightweight stack that prioritizes performance and simplicity:

Node.js + Express: Fast, minimal web framework
Crypto module: Built-in SHA256 hashing
In-memory storage: Lightning-fast data access (perfect for MVP)
PM2: Process management for production
Nginx: Reverse proxy for clean URLs
AWS EC2: Free tier Ubuntu instance

No databases, no heavy ORMs—just pure JavaScript efficiency.

Architecture Decisions

1. In-Memory Storage

Instead of reaching for MongoDB or PostgreSQL, I implemented a simple Map-based storage system. Why?

Speed: Microsecond access times
Simplicity: No schema migrations or connection pools
Perfect for MVP: Easy to swap later if needed

const stringStore = new Map();

const store = {
  set(id, data) {
    stringStore.set(id, data);
  },
  get(id) {
    return stringStore.get(id);
  },
  getAll() {
    return Array.from(stringStore.values());
  }
};

2. SHA256 as Primary Key

Each string gets a unique identifier based on its SHA256 hash. This means:

No duplicate strings (hash collision = duplicate detected)
Content-addressable storage
Cryptographically secure IDs
Same string always gets same ID

3. RESTful Design

The API follows REST principles strictly:

POST /strings - Create
GET /strings/:stringValue - Read one
GET /strings - Read all (with filters)
DELETE /strings/:stringValue - Delete
GET /strings/filter-by-natural-language - Natural language queries

4. Natural Language Processing

The coolest feature? You can query in plain English:

GET /strings/filter-by-natural-language?query=single word palindromic strings

The API parses your intent and translates it to filters:

{
  "parsed_filters": {
    "word_count": 1,
    "is_palindrome": true
  }
}

Implementation Highlights

String Analysis Algorithm

The core analysis function is elegantly simple:

function analyzeString(value) {
  // Length
  const length = value.length;

  // Palindrome check (case-insensitive, ignore spaces)
  const cleanString = value.toLowerCase().replace(/\s/g, '');
  const is_palindrome = cleanString === cleanString.split('').reverse().join('');

  // Unique characters
  const unique_characters = new Set(value.toLowerCase()).size;

  // Word count
  const word_count = value.trim().split(/\s+/).filter(w => w.length > 0).length;

  // SHA256 hash
  const sha256_hash = crypto.createHash('sha256').update(value).digest('hex');

  // Character frequency
  const character_frequency_map = {};
  for (const char of value.toLowerCase()) {
    if (char !== ' ') {
      character_frequency_map[char] = (character_frequency_map[char] || 0) + 1;
    }
  }

  return { length, is_palindrome, unique_characters, word_count, sha256_hash, character_frequency_map };
}

Advanced Filtering

Users can combine multiple filters:

GET /strings?is_palindrome=true&min_length=5&word_count=1&contains_character=a

The controller chains filters efficiently:

let results = store.getAll();

if (is_palindrome !== undefined) {
  results = results.filter(s => s.properties.is_palindrome === (is_palindrome === 'true'));
}

if (min_length !== undefined) {
  results = results.filter(s => s.properties.length >= parseInt(min_length));
}

// ... more filters

Error Handling

Proper HTTP status codes make the API predictable:

201 Created - String successfully analyzed
400 Bad Request - Missing or invalid parameters
404 Not Found - String doesn't exist
409 Conflict - String already exists
422 Unprocessable Entity - Wrong data type
500 Internal Server Error - Something went wrong

Deployment Journey

Step 1: Local Development

Started with a clean Node.js setup:

mkdir string-analyzer-api
cd string-analyzer-api
npm init -y
npm install express body-parser cors dotenv crypto
npm install --save-dev nodemon

Organized the code into a clean structure:

src/
├── controllers/    # Request handlers
├── routes/         # API endpoints
├── storage/        # Data persistence
├── utils/          # Business logic
└── server.js       # Entry point

Step 2: AWS EC2 Setup

Launched a t2.micro Ubuntu instance (free tier):

Security Group Configuration:
- Port 22 (SSH) - for admin access
- Port 80 (HTTP) - for public API access
- Port 3000 (optional) - for direct Node.js access
System Preparation:

sudo apt update && sudo apt upgrade -y
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs git nginx

Step 3: Process Management with PM2

PM2 keeps the application running 24/7:

sudo npm install -g pm2
pm2 start src/server.js --name string-analyzer
pm2 startup  # Auto-start on reboot
pm2 save     # Save current process list

Benefits of PM2:

Auto-restart on crashes
Load balancing (can run multiple instances)
Log management
Monitoring dashboard

Step 4: Nginx Reverse Proxy

Instead of exposing port 3000, I configured Nginx to forward traffic:

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
}

This gives us:

Clean URLs (no :3000 suffix)
SSL termination capability (add Let's Encrypt later)
Load balancing (scale horizontally if needed)
Static file serving (future expansion)

Testing It Out

Let's create and query some strings:

Create a string:

curl -X POST http://your-api.com/strings \
  -H "Content-Type: application/json" \
  -d '{"value":"ursula is a devops engineer"}'

Query with filters:

curl "http://your-api.com/strings?word_count=5&min_length=20"

Natural language search:

curl "http://your-api.com/strings/filter-by-natural-language?query=strings longer than 25 characters"

Retrieve specific string:

curl "http://your-api.com/strings/ursula%20is%20a%20devops%20engineer"

Performance Considerations

In-Memory Trade-offs

Pros:

Sub-millisecond response times
No network latency
Simple implementation
Perfect for caching layer

Cons:

Data lost on restart
Limited by RAM
Single-server limitation

Solution for Production:

Add Redis for persistent caching
Use PostgreSQL for long-term storage
Implement write-through cache pattern

Scalability Path

Current setup handles ~1000 requests/second on t2.micro. To scale:

Vertical: Upgrade to larger EC2 instance
Horizontal: Add load balancer + multiple instances
Caching: Add CloudFront CDN for GET requests
Database: Migrate to RDS for persistence

Lessons Learned

1. Start Simple

I could have added a database from day one, but in-memory storage taught me to focus on core features first. Premature optimization is real.

2. REST Principles Matter

Following RESTful conventions made the API intuitive. Developers know exactly what POST /strings does.

3. Error Messages Save Time

Clear, specific error messages saved hours of debugging. "Missing 'value' field" beats "Bad Request" every time.

4. Natural Language is Hard

Building even a simple NLP parser was challenging. Regex patterns only go so far—production systems need better approaches.

5. DevOps is Part of Development

Setting up PM2 and Nginx taught me that deployment is as important as code quality. An app that crashes in production is a failed app.

Future Enhancements

Here's what's on the roadmap:

Persistent Storage: Add PostgreSQL with automatic migration
Authentication: JWT-based API keys
Rate Limiting: Prevent abuse
Webhooks: Notify on new strings
Advanced NLP: Better natural language understanding
Batch Processing: Analyze multiple strings at once
String Comparison: Find similar strings
Export Formats: CSV, JSON, XML downloads
Analytics Dashboard: Visualize string patterns

Try It Yourself

The entire project is open source and deployment-ready:

Live API: Check out the working demo
GitHub Repo: Clone and deploy in minutes
Full Documentation: Complete API reference included

Whether you're learning Node.js, practicing DevOps, or building a production service, this project covers the full stack from code to cloud.

Conclusion

Building this String Analyzer API was a fantastic journey through modern web development. From Express routing to AWS deployment, every step taught valuable lessons about creating production-ready services.

The best part? It took less than a day from first commit to live deployment. That's the power of choosing the right tools and keeping things simple.

What would you analyze with this API? What features would you add? Drop your thoughts in the comments!

Tech Stack: Node.js · Express · AWS EC2 · Nginx · PM2

Deployment Time: ~2 hours

Lines of Code: ~300

Want to build something similar? Check out the full tutorial and source code on GitHub. Stars and contributions welcome!

Building and Deploying a Django REST API on AWS EC2: A Complete Guide

Ursula Okafo — Sun, 19 Oct 2025 08:41:25 +0000

Introduction

In this article, I'll walk you through my journey of building a dynamic REST API with Django and deploying it to AWS EC2. This project is part of the HNG 13 Backend Wizards track, and it's a fantastic way to learn API development, third-party integrations, and cloud deployment.

By the end of this guide, you'll have a live API endpoint serving real data from your Django application on AWS.

What we're building: A /me endpoint that returns your profile information along with random cat facts from an external API.

The Project Overview
Local Development Setup
Understanding the Code
Deploying to AWS EC2
Testing and Verification
Key Learnings
Troubleshooting Tips

Project Overview {#project-overview}

What We're Building

A simple yet powerful REST API endpoint with:

User profile information (email, name, tech stack)
Dynamic timestamps in ISO 8601 format
Integration with an external Cat Facts API
Graceful error handling with fallbacks
Production-ready deployment on AWS

Tech Stack

Framework: Django + Django REST Framework
Server: Gunicorn (WSGI application server)
Reverse Proxy: Nginx
Hosting: AWS EC2 (Ubuntu 22.04 LTS)
Language: Python 3.10+

Why This Stack?

Django: Robust, batteries-included framework with excellent documentation
DRF: Simple and powerful for building REST APIs
Gunicorn: Reliable WSGI server for production
Nginx: High-performance reverse proxy
AWS: Industry-standard cloud platform with free tier

Local Development Setup {#local-development}

Step 1: Create Your Project Structure

mkdir backend-wizards-stage0
cd backend-wizards-stage0

Step 2: Set Up Virtual Environment

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Always use virtual environments! They isolate project dependencies and prevent conflicts.

Step 3: Install Dependencies

pip install django djangorestframework python-dotenv requests
pip freeze > requirements.txt

Why each package?

django - Web framework
djangorestframework - Simplified API building
python-dotenv - Load environment variables from .env file
requests - HTTP library for consuming external APIs

Step 4: Initialize Django Project

django-admin startproject config .
python manage.py startapp api

Naming convention: I use config for the project folder to avoid naming conflicts with the django library.

Step 5: Configure Settings

Update config/settings.py:

from pathlib import Path
import os
from dotenv import load_dotenv

load_dotenv()

# Your environment variables
EMAIL = os.getenv('EMAIL')
NAME = os.getenv('NAME')
BACKEND_STACK = os.getenv('BACKEND_STACK')
CAT_API_TIMEOUT = int(os.getenv('CAT_API_TIMEOUT', 5))

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'rest_framework',  # Add this
    'api',              # Add this
]

Step 6: Create `.env` File

EMAIL=your-email@example.com
NAME=Your Full Name
BACKEND_STACK=Python/Django
CAT_API_TIMEOUT=5
DEBUG=True

Pro tip: Never commit .env to version control. Add it to .gitignore.

Understanding the Code {#code-walkthrough}

The Main API View

Here's the heart of the project (api/views.py):

from rest_framework.response import Response
from rest_framework.decorators import api_view
from rest_framework import status
from datetime import datetime, timezone
import requests
import logging
from django.conf import settings

logger = logging.getLogger(__name__)

@api_view(['GET'])
def profile_endpoint(request):
    """
    Returns user profile with a dynamic cat fact
    """
    try:
        # Fetch cat fact from external API
        cat_fact = fetch_cat_fact()

        # Build response
        response_data = {
            "status": "success",
            "user": {
                "email": settings.EMAIL,
                "name": settings.NAME,
                "stack": settings.BACKEND_STACK,
            },
            "timestamp": datetime.now(timezone.utc).isoformat().replace('+00:00', 'Z'),
            "fact": cat_fact,
        }

        return Response(response_data, status=status.HTTP_200_OK)

    except Exception as e:
        logger.error(f"Error in profile endpoint: {str(e)}")
        return Response(
            {
                "status": "error",
                "message": "Failed to fetch profile data",
            },
            status=status.HTTP_500_INTERNAL_SERVER_ERROR
        )

def fetch_cat_fact():
    """
    Fetches a random cat fact from the Cat Facts API
    Returns a fallback fact if the API fails
    """
    try:
        response = requests.get(
            'https://catfact.ninja/fact',
            timeout=settings.CAT_API_TIMEOUT
        )
        response.raise_for_status()
        return response.json()['fact']

    except requests.exceptions.Timeout:
        logger.warning("Cat Facts API timeout")
        return "Cats have over 20 different vocal sounds!"

    except requests.exceptions.RequestException as e:
        logger.warning(f"Failed to fetch cat fact: {str(e)}")
        return "Cats spend 70% of their lives sleeping!"

    except Exception as e:
        logger.error(f"Unexpected error: {str(e)}")
        return "A cat's purr may promote bone healing."

Key Concepts Here

1. Decorators: @api_view(['GET']) - Restricts the endpoint to GET requests only.

2. Dynamic Timestamps:

datetime.now(timezone.utc).isoformat().replace('+00:00', 'Z')

This ensures the timestamp is always current and in ISO 8601 format.

3. Error Handling: Multiple except blocks handle different failure scenarios gracefully.

4. Timeouts: timeout=settings.CAT_API_TIMEOUT prevents hanging indefinitely if the external API is slow.

URL Configuration

Create api/urls.py:

from django.urls import path
from . import views

urlpatterns = [
    path('me', views.profile_endpoint, name='profile'),
]

Then include it in config/urls.py:

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('api.urls')),
]

Test Locally

python manage.py runserver

Visit: http://127.0.0.1:8000/me

Expected response:

{
  "status": "success",
  "user": {
    "email": "your-email@example.com",
    "name": "Your Full Name",
    "stack": "Python/Django"
  },
  "timestamp": "2025-10-19T14:35:22.123Z",
  "fact": "Cats have a specialized collarbone..."
}

Deploying to AWS EC2 {#aws-deployment}

Why AWS EC2?

Free tier available (t2.micro for 12 months)
Full control over your server
Scalable infrastructure
Industry-standard platform
Perfect learning tool

Step 1: Launch an EC2 Instance

Sign in to AWS Console
Navigate to EC2 Dashboard
Click "Launch Instance"
Select Ubuntu 22.04 LTS
Instance type: t2.micro (free tier)
Storage: 30GB (default)
Security Group:
- SSH (22) - from your IP
- HTTP (80) - from anywhere
- HTTPS (443) - from anywhere
Create a key pair (.pem file) and download it

Step 2: Connect to Your Instance

chmod 400 your-key.pem
ssh -i your-key.pem ubuntu@your-ec2-public-ip

Replace your-ec2-public-ip with your instance's public IP from the AWS console.

Step 3: Install System Dependencies

sudo apt update
sudo apt upgrade -y
sudo apt install -y python3-pip python3-venv git nginx

Step 4: Clone Your Repository

cd /home/ubuntu
git clone https://github.com/YOUR_USERNAME/backend-wizards-stage0.git
cd backend-wizards-stage0

Step 5: Set Up Python Environment

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install gunicorn

Step 6: Configure Environment Variables

nano .env

Add your variables and save (Ctrl+X, Y, Enter).

Step 7: Update Django Settings

Edit config/settings.py:

ALLOWED_HOSTS = ['your-ec2-public-ip', 'localhost']
DEBUG = False

Never leave DEBUG=True in production! It exposes sensitive information.

Step 8: Create Systemd Service

sudo nano /etc/systemd/system/django.service

Paste:

[Unit]
Description=Django Gunicorn application
After=network.target

[Service]
User=ubuntu
WorkingDirectory=/home/ubuntu/backend-wizards-stage0
ExecStart=/home/ubuntu/backend-wizards-stage0/venv/bin/gunicorn config.wsgi:application --bind 0.0.0.0:8000
Restart=always

[Install]
WantedBy=multi-user.target

This ensures Django restarts automatically if it crashes.

Step 9: Enable and Start Django

sudo systemctl daemon-reload
sudo systemctl enable django.service
sudo systemctl start django.service
sudo systemctl status django.service

Step 10: Configure Nginx

sudo nano /etc/nginx/sites-available/default

Replace with:

server {
    listen 80 default_server;
    listen [::]:80 default_server;

    server_name _;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Step 11: Start Nginx

sudo nginx -t
sudo systemctl restart nginx

Step 12: Test Your API

Visit: http://your-ec2-public-ip/me

🎉 Your API is now live!

Testing and Verification {#testing}

Manual Testing

curl http://your-ec2-public-ip/me

Check Response Headers

curl -i http://your-ec2-public-ip/me

Look for:

Content-Type: application/json
HTTP/1.1 200 OK

Verify Dynamic Updates

Call the endpoint multiple times and check:

✅ Timestamp changes each time
✅ Cat fact is different each time
✅ Response is consistent

Test Error Handling

Check logs to ensure errors are logged:

sudo journalctl -u django.service -f

Key Learnings {#learnings}

1. API Design Matters

Consistent response structures make client integration easier. Always version your APIs and document endpoints clearly.

2. Error Handling is Critical

Never let your API fail silently. Provide fallback responses and log everything. Users appreciate transparent error messages.

3. Environment Variables are Essential

Never hardcode credentials or configuration. Use .env files and keep them secure.

4. Testing is Non-Negotiable

Test locally before deploying. Test from different networks. Test error scenarios.

5. Monitoring and Logging

Always log important events. Use:

logger.error("Error message")
logger.warning("Warning message")
logger.info("Info message")

6. Timeouts Prevent Hanging

Always set timeouts on external API calls:

requests.get(url, timeout=5)

7. Reverse Proxies Improve Performance

Nginx sits between users and Gunicorn, handling:

SSL termination
Load balancing
Compression
Static file serving

8. Systemd Services Ensure Availability

Using systemd services with Restart=always ensures your API stays up even after crashes.

Troubleshooting Tips {#troubleshooting}

502 Bad Gateway

Problem: Nginx can't reach Gunicorn

Solution:

sudo systemctl status django.service
sudo journalctl -u django.service -f

Ensure Gunicorn is running on port 8000.

404 Not Found

Problem: Endpoint returns 404

Solution:

Verify URL: http://ip/me (not / or /api/me)
Check urls.py routing
Ensure api is in INSTALLED_APPS

Environment Variables Not Loading

Problem: Settings are None

Solution:

Verify .env file exists in project root
Check .env file syntax
Restart Django: sudo systemctl restart django.service

Cat Facts API Timeout

Problem: API returns fallback facts consistently

Solution:

Check internet connection
Verify firewall isn't blocking outbound requests
Increase timeout in .env: CAT_API_TIMEOUT=10

Conclusion

Building and deploying a Django API on AWS taught me valuable lessons about:

REST API design principles
Error handling and resilience
Production deployment strategies
Linux server management
Monitoring and logging

This project serves as a solid foundation for more complex applications. From here, you can add:

Database models
User authentication
Advanced caching
Horizontal scaling
CI/CD pipelines

Next Steps:

Add a database (PostgreSQL)
Implement authentication (JWT)
Write automated tests
Set up CI/CD with GitHub Actions
Add API documentation (Swagger)

Resources

Let's Connect

If you found this helpful, feel free to reach out! I'm always excited to discuss backend development, cloud deployment, and web technologies.

GitHub: [Your GitHub Profile]

Twitter/X: [@Your Handle]

Email: ursulaokafo32@gmail.com

This article is part of my journey through the HNG 13 Backend Wizards track. Happy coding! 🚀

Setting Up a Simple Web Server on a Fresh Ubuntu Server with NGINX

Ursula Okafo — Wed, 29 Jan 2025 10:09:09 +0000

Introduction

During the DevOps Stage 0 in the HNG Internship, I was tasked with setting up a simple web server using NGINX on an Ubuntu server. This task aimed to test my ability to work with basic web server configurations while ensuring my deployed server was publicly accessible. It sounded straightforward at first, but this task ended up teaching me quite a lot about web servers, Linux, and cloud platforms. Here's a breakdown of my experience, what I learned, and how I did it.

Why I Chose Azure:

For this task, I used an Ubuntu server hosted on Microsoft Azure. The main reason? I’m a new Azure user and received free credits as part of their welcome package. This made Azure a budget-friendly and convenient choice for launching a virtual machine without spending a dime.
Beyond the free credits, Azure provides a clean and beginner-friendly interface, which made it easy to deploy and manage my VM. I was able to get the server up and running quickly, allowing me to focus entirely on learning and configuring NGINX.
Note: You’re not limited to Azure!
This task can be completed using any cloud platform like AWS, Google Cloud Platform (GCP), or even a local virtual machine. The important part is understanding how to work with the server, not where it's hosted.

🔧 What Is NGINX? (Like You’ve Never Heard of It)

If you’re like me before this task, you might be wondering: “What in the world is NGINX?”
Well, NGINX (pronounced "Engine-X") is a powerful and super popular web server. You can think of it like a smart waiter in a restaurant. When someone visits your website, NGINX takes that request, finds the correct page or file, and brings it back to their browser.

But NGINX doesn’t just stop at being a “waiter.” It’s also a:
🖥️ Web server
🔁 Reverse proxy (passes requests to another server)
⚖️ Load balancer (shares traffic across multiple servers)
🔐 SSL handler (helps secure your website)
📦 Cache (speeds things up by storing responses)
It’s lightweight, fast, and used by companies like Netflix, Dropbox, and WordPress. Pretty cool for something I hadn’t heard of before this task!

Getting Started with Azure Virtual Machine(VM)

Setting up a VM on Microsoft Azure was a smooth process. Here’s what I selected during setup:

Chose the Ubuntu 22.04 LTS image from the Azure Marketplace.
Selected the Standard B1s size (which is eligible for Azure Free Tier).
Created a new resource group to organize my resources.
Allowed SSH (port 22) and HTTP (port 80) through the network security group (NSG) settings to enable secure access and web traffic.
Generated a new SSH key pair to securely connect to the VM from my terminal using the .pem file (or convert to .ppk for PuTTY on Windows).
Chose a region closest to me for better latency.
Launched the VM and connected to it via SSH to begin configuration.

🛠️ Setting Up NGINX: Steps I Followed

Here’s a summary of how I installed and configured NGINX:

Update Server Packages:

sudo apt update
sudo apt upgrade

Install NGINX:

sudo apt install nginx

Start and Enable NGINX:

sudo systemctl start nginx
sudo systemctl enable nginx

# Check if Nginx is running
sudo systemctl status nginx

Test the Setup
I accessed my public IP address:

http://<your-public-ip>/

and confirmed that nginx is rightly configured.

Create a Custom HTML Page:

echo "Welcome to DevOps Stage 0 - [Your Name]/[SlackName], we are glad to have you" | sudo tee /var/www/html/index.html

NB: (I replaced [Your Name] and [SlackName] with my actual name and Slack username.)
Access your IP address once more:

http://<your-public-ip>/

And boom — my custom message was live on the web!

Key Takeaways

This task taught me several important lessons:

✅ How to launch an instance and configure it for web hosting.

✅ Setting up a basic web server using NGINX.

✅ Managing cloud security settings to allow public access.

✅ Troubleshooting connectivity issues related to firewall and inbound rules.

😅 Challenges I Faced

Permission issues: When trying to write to /var/www/html/index.html, I got denied until I added sudo.

🎯 What I Learned

This task taught me a lot more than just typing commands:
I now understand what a web server does and how to use one.
I learned how to use Azure’s cloud platform to host my own VM.
I got hands-on with Linux and command-line tools, which are key skills in DevOps.
It was also a fun reminder of how small configurations can power big things on the internet.

References