Forem: Felix Jumason

Building a Secure Home Lab on a Raspberry Pi with Tailscale, Pi-hole, and Nextcloud

Felix Jumason — Fri, 27 Mar 2026 19:50:40 +0000

This article is written for anyone giving a talk—or quietly building a lab—about owning your data, reducing noise on the network, and reaching your services safely without turning your router into a public punching bag. We will use a Raspberry Pi, Docker Compose, Tailscale on the host, Pi-hole for DNS filtering, and Nextcloud for files and lightweight collaboration.

The goal is not to replicate a data center. The goal is a small, understandable system you can reason about, patch, and back up.

Who this is for and what you get

You might be a developer who wants sync and calendars without a cloud bill, or a curious tinkerer who wants to learn networking and containers on real hardware. Either way, you get:

Pi-hole: DNS-based ad blocking and telemetry reduction for your home (and optionally for devices on your tailnet).
Nextcloud: Self-hosted files, sync, and optional apps (calendar, contacts, and more).
Tailscale: A mesh VPN so you reach the Pi without exposing SSH or web UIs to the whole internet.

Keep Pi-hole and Nextcloud in separate folders on the Pi (each with its own docker-compose.yml and .env). Tailscale is installed on the Raspberry Pi OS host, not inside those Compose files: the Pi joins your tailnet; Docker runs the services on top.

A light threat model (what you are actually protecting)

Tailscale encrypts traffic between your devices and authenticates them to your tailnet. It does not replace:

Strong passwords for Pi-hole admin, Nextcloud admin, and database users.
Timely updates to the OS, Docker images, and Nextcloud apps.
Backups of volumes (you will lose data if the SD card dies with no backup).

Pi-hole blocks many ads and trackers at DNS resolution. It does not replace a full security stack on clients; malware and phishing still exist.

Nextcloud is a rich PHP application with a large surface area. Treat it like any internet-facing app: least privilege, updates, and backups.

In short: Tailscale shrinks who can reach your Pi; Pi-hole and Nextcloud still need good hygiene once someone is on the tailnet.

Hardware and OS choices

Raspberry Pi 4 or 5 with 64-bit Raspberry Pi OS is a solid baseline. Nextcloud benefits from RAM (4 GB or more helps) and fast storage: an external SSD over USB 3 is dramatically better than a slow SD card for database I/O and file sync.

If you use an SD card, expect more maintenance: monitor wear, keep backups, and avoid large Nextcloud sync jobs that thrash the card all day.

Architecture: how the pieces fit together

Tailscale runs on the Pi host. Docker runs Pi-hole and Nextcloud as separate Compose projects (or on separate Pis if you prefer). Traffic flows from your laptop or phone, through the encrypted mesh, to the Pi, then into the right container.

Why Tailscale on the host? Your Pi’s Tailscale IP and MagicDNS name apply to services bound to the host’s interfaces. You can publish ports from Docker to the host; Tailscale clients then reach 100.x.y.z:port or pi-name.tailnet-name.ts.net:port without extra container networking gymnastics. For advanced setups (e.g. container-only routing), Tailscale documents Docker sidecars; for most home labs, host Tailscale + Docker bridge networking is enough.

Install Docker Engine and Compose on the Pi

Use the official Docker documentation for Debian (Raspberry Pi OS is Debian-based). Install the Docker Engine and the Compose plugin so you can run:

docker compose up -d

Keep your working directory layout predictable, for example:

~/homelab/
  pihole/
  nextcloud/

Each stack has its own docker-compose.yml and a .env file (start from the templates in this article). Keep .env private—do not share or publish it.

Step-by-step: from a fresh Pi to both stacks

Follow these in order. The full Docker files for copy-paste are in the next two sections.

Flash and boot 64-bit Raspberry Pi OS; create a user; run sudo apt update && sudo apt full-upgrade -y.
Install Docker Engine and the Compose plugin using Docker’s Debian instructions (Raspberry Pi OS is Debian-based). Add your user to the docker group, then sign out and back in so docker works without sudo.
Install Tailscale on the host (not inside Compose): follow Tailscale’s Linux install, run sudo tailscale up, and complete browser login. Note your Tailscale IPv4 with tailscale ip -4 and your MagicDNS hostname if you use it.
Resolve port 53 before Pi-hole: Pi-hole needs TCP/UDP 53 on the host. If systemd-resolved holds the port, reconfigure or disable the stub listener (see DNS, port 53, and systemd-resolved below). Verify nothing else is bound with ss -lunp | grep ':53' or similar.
Deploy Pi-hole: create a folder (e.g. mkdir -p ~/homelab/pihole && cd ~/homelab/pihole), add the Pi-hole docker-compose.yml and .env contents from Pi-hole: full Docker files (save the env template as .env and replace placeholders).
Start Pi-hole: docker compose up -d, then check logs with docker compose logs -f briefly. Open the admin UI at http://<pi-tailscale-ip>:8080/admin.
Deploy Nextcloud: create a folder (e.g. mkdir -p ~/homelab/nextcloud && cd ~/homelab/nextcloud), add the Nextcloud docker-compose.yml and .env contents from Nextcloud: full Docker files (save the env template as .env and replace placeholders).
Start Nextcloud: docker compose up -d. Wait until MariaDB and Redis report healthy, then open http://<pi-tailscale-ip>:8081 and sign in with the admin user from .env (first boot performs an unattended install when those variables are set).
Fix “untrusted domain” if needed: add every hostname or IP you use in the browser to NEXTCLOUD_TRUSTED_DOMAINS (space-separated), then docker compose restart app or adjust via occ as documented by Nextcloud.
Restrict Tailscale: in the Tailscale admin console, tune ACLs so only your user or devices can reach SSH, Pi-hole (53, 8080), and Nextcloud (8081).
Set Pi-hole upstream DNS in the web UI (Settings → DNS) to resolvers you trust; optional DoH/DoT upstreams depend on your Pi-hole version and docs.
Back up Docker volumes (or export data) before you rely on the lab; test a restore once.

Screenshots: Pi-hole and Nextcloud over Tailscale

Below is what a working setup looks like in the browser when you use your Pi’s Tailscale IP (addresses in the 100.64.0.0/10 range, shown as 100.x.x.x). Plain HTTP is fine on a private tailnet for testing; the browser may still label the connection “Not secure” until you add HTTPS (for example Tailscale Serve or a reverse proxy with a certificate).

Pi-hole admin dashboard

![Pi-hole admin dashboard: DNS totals, blocked queries, 24-hour charts, and sidebar status — accessed at http://100.x.x.x:8080/admin over Tailscale]

The Pi-hole UI shows aggregate queries, blocks, percentage blocked, and per-client activity. The sidebar lists Status, Performance, and Hostname (Docker often shows a container ID there instead of the Pi’s host name). Your URL will look like http://<your-pi-tailscale-ip>:8080/admin.

Nextcloud Files

![Nextcloud Files app: All files, folders, and apps bar — accessed at http://100.x.x.x:8081 over Tailscale]

Nextcloud is mapped to host port 8081 in this guide (NEXTCLOUD_HTTP_PORT). The Files app lists default folders (Documents, Photos, and so on) and the top bar links to other apps (Photos, Talk, Contacts, Calendar). Storage usage appears in the left sidebar.

Pi-hole: full Docker files

Save these as docker-compose.yml and .env in the same directory (e.g. ~/homelab/pihole). Copy the env template to .env and replace placeholder values.

`docker-compose.yml`

# Pi-hole on Raspberry Pi (ARM64). Install Tailscale on the host, not in this file.
# Port 53: stop or reconfigure systemd-resolved on the Pi before binding (see README in blog).
# Copy .env.example to .env and set WEBPASSWORD + TZ.

services:
  pihole:
    image: pihole/pihole:latest
    container_name: pihole
    hostname: pihole
    platform: linux/arm64
    ports:
      # DNS — requires nothing else listening on 53 on the host (see blog: systemd-resolved)
      - '53:53/tcp'
      - '53:53/udp'
      # Web UI — 8080 avoids clashing with other HTTP services on the Pi
      - '8080:80/tcp'
      # Optional: HTTPS to admin UI (Pi-hole generates cert for its UI when enabled)
      - '8443:443/tcp'
    env_file:
      - .env
    volumes:
      - pihole_etc:/etc/pihole
      - pihole_dnsmasq:/etc/dnsmasq.d
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
    networks:
      - pihole_net

volumes:
  pihole_etc:
  pihole_dnsmasq:

networks:
  pihole_net:
    driver: bridge

`.env` (template; copy from this example)

# Copy to .env and adjust. Do not commit .env.

# Strong password for the Pi-hole web UI
WEBPASSWORD=change-me-to-a-long-random-string

# IANA timezone, e.g. America/New_York, Europe/London
TZ=UTC

Commands

cd ~/homelab/pihole   # or your path
docker compose up -d

Pi-hole: DNS filtering without exposing the whole LAN

What Pi-hole does

Pi-hole answers DNS queries from your network. Blocklists cause ad and tracker domains to resolve to nowhere (or a sinkhole), which cuts noise for every device that uses Pi-hole as its DNS server.

DNS, port 53, and systemd-resolved

Pi-hole needs TCP and UDP port 53 on the host. On many Debian-based systems, systemd-resolved already listens on 127.0.0.53:53. You must either:

Stop or reconfigure the stub resolver so port 53 is free for Docker to bind, or
Use a different deployment (for example host networking) with full understanding of the tradeoffs.

This is the most common “it works on my laptop but not on the Pi” issue. Plan for ten minutes of reading your OS docs and verifying with ss -ulnp | grep ':53' or similar.

Open http://<pi-tailscale-ip>:8080/admin from a device on your tailnet (after you restrict access with ACLs, described below).

Upstream DNS and privacy

Pi-hole forwards queries it does not block to upstream resolvers. You can choose:

Your ISP’s DNS (simple, less privacy from the ISP).
DNS over HTTPS (DoH) or DNS over TLS (DoT) to a provider you trust (better against casual snooping on the path; you still trust the provider).

There is no single “correct” answer; document what you chose and why when you present this to others.

Nextcloud: full Docker files

Save these as docker-compose.yml and .env in the same directory (e.g. ~/homelab/nextcloud). The app listens on host port 8081 by default so it does not clash with Pi-hole on 8080.

`docker-compose.yml`

# Nextcloud + MariaDB + Redis for Raspberry Pi (ARM64). Tailscale runs on the host.
# Web UI on host port 8081 (change if it clashes with Pi-hole or other services).
# Copy .env.example to .env before `docker compose up -d`.

services:
  db:
    image: mariadb:11
    container_name: nextcloud-db
    platform: linux/arm64
    command: >-
      --transaction-isolation=READ-COMMITTED
      --log-bin=binlog
      --binlog-format=ROW
    volumes:
      - nextcloud_db_data:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
      MYSQL_DATABASE: ${MYSQL_DATABASE}
      MYSQL_USER: ${MYSQL_USER}
    restart: unless-stopped
    healthcheck:
      test: ['CMD', 'healthcheck.sh', '--connect', '--innodb_initialized']
      start_period: 20s
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    container_name: nextcloud-redis
    platform: linux/arm64
    restart: unless-stopped
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 10s
      timeout: 5s
      retries: 5

  app:
    image: nextcloud:latest
    container_name: nextcloud
    platform: linux/arm64
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    ports:
      - '${NEXTCLOUD_HTTP_PORT:-8081}:80'
    volumes:
      - nextcloud_app_data:/var/www/html
    environment:
      MYSQL_HOST: db
      MYSQL_DATABASE: ${MYSQL_DATABASE}
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
      NEXTCLOUD_ADMIN_USER: ${NEXTCLOUD_ADMIN_USER}
      NEXTCLOUD_ADMIN_PASSWORD: ${NEXTCLOUD_ADMIN_PASSWORD}
      REDIS_HOST: redis
      # Space-separated list (see Nextcloud docker entrypoint)
      NEXTCLOUD_TRUSTED_DOMAINS: ${NEXTCLOUD_TRUSTED_DOMAINS}
    restart: unless-stopped

volumes:
  nextcloud_db_data:
  nextcloud_app_data:

`.env` (template; copy from this example)

# Copy to .env and set strong passwords. Do not commit .env.

# MariaDB
MYSQL_ROOT_PASSWORD=change-me-root
MYSQL_DATABASE=nextcloud
MYSQL_USER=nextcloud
MYSQL_PASSWORD=change-me-db-user

# First admin user (required for unattended install on first boot)
NEXTCLOUD_ADMIN_USER=admin
NEXTCLOUD_ADMIN_PASSWORD=change-me-admin

# Space-separated hostnames or IPs allowed in trusted_domains (not commas)
# Add your Pi Tailscale MagicDNS name (e.g. pi.tail1234.ts.net) and 100.x.x.x as needed
NEXTCLOUD_TRUSTED_DOMAINS="localhost 127.0.0.1"

# Host port mapped to container :80 (default 8081 to avoid clashing with Pi-hole on 8080)
NEXTCLOUD_HTTP_PORT=8081

Commands

cd ~/homelab/nextcloud   # or your path
docker compose up -d

Nextcloud: your files on hardware you control

Stack overview

This stack includes:

MariaDB for the application database (with a healthcheck so the app starts after the DB is ready).
Redis for PHP session storage (recommended for a smoother experience under load).
Nextcloud itself, with data in a named volume.

The web UI is published on host port 8081 by default (NEXTCLOUD_HTTP_PORT in .env) so it does not collide with Pi-hole’s 8080.

First-time install and trusted domains

The official Nextcloud image can perform an unattended install if you set, before the first start:

MYSQL_* variables pointing at the db service.
NEXTCLOUD_ADMIN_USER and NEXTCLOUD_ADMIN_PASSWORD.
NEXTCLOUD_TRUSTED_DOMAINS as a space-separated list (not comma-separated). The image’s entrypoint loops over each token and runs occ config:system:set trusted_domains.

Add your Pi’s Tailscale MagicDNS name and 100.x address once you know them, for example:

NEXTCLOUD_TRUSTED_DOMAINS="localhost 127.0.0.1 mypi.tailabc123.ts.net 100.101.102.103"

HTTPS without opening the router

You have several good patterns:

Tailscale Serve can terminate HTTPS for a local service and make it available on your tailnet with a proper certificate story for Tailscale’s model. This avoids port-forwarding on your home router.
A reverse proxy on the host (Caddy, Traefik, nginx) with Let’s Encrypt is classic when you have a public hostname and ports 80/443 forwarded.

For a talk aimed at “secure home lab,” leading with Tailscale + Serve keeps the story tight: no inbound ports on the ISP side if you do not want them.

Tailscale: tailnet, MagicDNS, and ACLs

Join the Pi to your tailnet

Install Tailscale on Raspberry Pi OS using Tailscale’s documented steps, authenticate once, and enable MagicDNS if you like human-readable names such as pi.tailnet.ts.net.

Access control lists (ACLs)

By default, Tailscale’s admin console lets you write ACLs that describe which users and devices can reach which ports on which hosts. For a lab Pi, you might:

Allow only your user to SSH to the Pi.
Allow only your user to hit Pi-hole’s web UI and DNS.
Allow only your user to use Nextcloud.

Example shape (illustrative only; adapt tags and users to your tailnet):

{
  "acls": [
    {
      "action": "accept",
      "src": ["group:homelab-admins"],
      "dst": ["tag:pi-hole:53", "tag:pi-hole:8080", "tag:nextcloud:8081"]
    }
  ]
}

In practice you will use auto tags, device names, or IP addresses as your org defines. The important idea for your audience: Tailscale is not “everything can reach everything.” You still design least privilege.

Operational security: updates, backups, and firewall

Updates

Host: apt upgrades for the OS; reboot when the kernel requires it.
Docker: docker compose pull and docker compose up -d per stack; read Nextcloud release notes before major jumps.
Nextcloud apps: update from the Nextcloud UI on a schedule you can sustain.

Backups

Back up named volumes or the host paths behind them. A simple pattern is stopping the stack (brief downtime) and archiving volumes, or using a file-level backup tool that understands Docker. Test restores on a spare SD card or another Pi before you rely on backups.

Host firewall

If you only ever access services over Tailscale, you can use ufw or nftables on the Pi to drop inbound traffic on LAN and WAN interfaces while allowing Tailscale’s interface. If you also serve LAN clients without Tailscale, your rules differ. Document the two modes so you do not lock yourself out.

Common pitfalls (talk fodder)

Symptom	Likely cause
Pi-hole fails to bind port 53	`systemd-resolved` or another DNS listener still on 53
Nextcloud “untrusted domain”	Missing entry in `NEXTCLOUD_TRUSTED_DOMAINS` for the hostname you type in the browser
Nextcloud install loops or fails	DB not ready; the Compose file uses `depends_on` with healthchecks to mitigate
Slow Nextcloud on Pi	SD card bottleneck; move data and DB to SSD; add RAM
Locked out after enabling firewall	SSH allowed only on wrong interface; keep a physical console or time-limited rule

Before you go live: checklist

[ ] .env files created from .env.example with long random passwords.
[ ] Tailscale ACLs reviewed: only you (or your admin group) reach admin UIs and sensitive ports.
[ ] NEXTCLOUD_TRUSTED_DOMAINS includes every hostname and Tailscale IP you will use.
[ ] Backup plan exists and a restore has been tested once.
[ ] Pi-hole upstream DNS choice documented (privacy and reliability tradeoffs understood).
[ ] Router port-forwarding intentionally on or off; if off, Tailscale-only access is the primary path.

Closing

A Raspberry Pi home lab with Tailscale, Pi-hole, and Nextcloud is a practical way to learn real networking, container operations, and defense in depth without a rack full of gear. Keep the architecture boring: Tailscale on the host, Compose for services, strong secrets in .env, ACLs on the tailnet, and backups you have actually restored. That combination is easy to explain on stage and solid enough to live with at home.

References (official docs)

Building an AI-Powered Community Assistant with Google Cloud Platform,Vercel AI SDK, and Calendar API

Felix Jumason — Sun, 09 Nov 2025 11:42:07 +0000

How I integrated Google Gemini AI SDK and Google Calendar API to create CommunitySync—a conversational community management assistant

The Problem That Started It All

As someone deeply involved in community management, I've experienced firsthand the overwhelming burden of juggling multiple tools, spreadsheets, and platforms just to keep a community running smoothly. The constant context-switching between Google Calendar, Slack, spreadsheets, and various management tools wasn't just inefficient—it was exhausting.

The reality:

Community managers spend 10+ hours per week on repetitive administrative tasks
Critical events get missed because they're buried in spreadsheets
Team coordination becomes a nightmare when information is scattered across platforms
The focus shifts from building relationships to managing tools

I knew there had to be a better way—and Google Cloud Platform provided the perfect solution.

Introducing CommunitySync: Powered by GCP

CommunitySync is an AI-powered community management assistant built on Google Cloud Platform, leveraging the Google Gemini AI SDK and Google Calendar API to create a seamless, conversational experience.

Through natural conversation powered by Google's Gemini 2.5 Pro model, it helps community managers:

Manage Events Seamlessly: Schedule, modify, and track community events using natural language—powered by Google Calendar API
Calendar Integration: Full Google Calendar sync—view, create, and manage events directly from chat with real-time synchronization
Proactive AI Assistance: Google Gemini AI anticipates needs and takes action, like automatically checking your calendar when you mention scheduling
Context-Aware Conversations: Remembers your community's needs and preferences across conversations

Simply chat naturally: "Show me my upcoming events" or "Schedule a community meetup next Friday at 6 PM" and CommunitySync handles the rest—all powered by Google Cloud Platform.

The Architecture: GCP at the Core

CommunitySync is built on a modern architecture with Google Cloud Platform services at its heart:

┌─────────────────────────────────────────┐
│         Next.js 15 App Router          │
│  (React Server Components + Actions)   │
└─────────────────────────────────────────┘
                    │
        ┌───────────┴───────────┐
        │                       │
┌───────▼────────┐    ┌────────▼────────┐
│  Google Gemini │    │  Google Calendar│
│  AI SDK 2.5    │    │  API (GCP)      │
└───────┬────────┘    └────────┬────────┘
        │                       │
        │   Google Cloud OAuth  │
        │   Token Management    │
        └───────────┬───────────┘
                    │
        ┌───────────▼───────────┐
        │   PostgreSQL (Neon)  │
        │   + Drizzle ORM       │
        └───────────────────────┘

Google Cloud Platform Services Used

Google Gemini AI SDK: Powers the conversational AI assistant with advanced tool-calling capabilities
Google Calendar API: Enables full calendar management through OAuth 2.0 integration
Google Cloud Console: Manages OAuth credentials, API keys, and service configuration
Google OAuth 2.0: Secure authentication and authorization flow

Tech Stack Highlights

AI: Google Gemini 2.5 Pro via Vercel AI SDK (Google AI SDK integration)
Calendar: Google Calendar API v3 with OAuth 2.0
Framework: Next.js 15 with App Router and Turbo mode
Database: Vercel Postgres (Neon) with Drizzle ORM
UI: React 19, shadcn/ui, and Tailwind CSS
Authentication: NextAuth.js with Google OAuth

Integrating Google Calendar API: The Deep Dive

The most complex and powerful part of CommunitySync is the Google Calendar API integration. Here's how it works:

Setting Up Google Cloud Platform

Before writing any code, you need to configure your GCP project:

Create a Google Cloud Project
- Navigate to Google Cloud Console
- Create a new project or select an existing one
Enable Google Calendar API
- Go to APIs & Services → Library
- Search for "Google Calendar API"
- Click "Enable"
Configure OAuth 2.0 Credentials
- Navigate to APIs & Services → Credentials
- Create OAuth client ID (Web application)
- Add authorized redirect URIs:
  - http://localhost:3000/api/auth/callback/google (development)
  - https://yourdomain.com/api/auth/callback/google (production)
Set Up OAuth Consent Screen
- Configure scopes: openid email profile https://www.googleapis.com/auth/calendar
- Add test users (for development)
Get Google Generative AI API Key
- Go to Google AI Studio
- Create an API key for Gemini

OAuth 2.0 Flow Implementation

The integration uses Google's OAuth 2.0 flow to securely access user calendars:

// OAuth 2.0 Client Setup
const oauth2Client = new google.auth.OAuth2(
  process.env.GOOGLE_CLIENT_ID,
  process.env.GOOGLE_CLIENT_SECRET,
  process.env.GOOGLE_REDIRECT_URI
);

// Set credentials with refresh token
oauth2Client.setCredentials({ 
  refresh_token: userRefreshToken 
});

// Create Calendar API client
const calendar = google.calendar({ 
  version: "v3", 
  auth: oauth2Client 
});

Google Calendar API Tools

The AI assistant has access to five powerful calendar tools powered by the Google Calendar API:

1. List Events (`listEvents`)

Fetches calendar events with filtering and pagination:

async function listEvents({
  calendarId = "primary",
  timeMin,
  timeMax,
  maxResults = 10,
}: {
  calendarId?: string;
  timeMin?: string;
  timeMax?: string;
  maxResults?: number;
}) {
  const calendar = await getCalendarClient();

  const response = await calendar.events.list({
    calendarId,
    timeMin: timeMin ? new Date(timeMin).toISOString() : undefined,
    timeMax: timeMax ? new Date(timeMax).toISOString() : undefined,
    maxResults,
    singleEvents: true,
    orderBy: "startTime",
  });

  return {
    events: response.data.items || [],
    count: response.data.items?.length || 0,
  };
}

2. Create Event (`createEvent`)

Creates new calendar events with full details:

async function createEvent({
  calendarId = "primary",
  summary,
  description,
  start,
  end,
  location,
  attendees,
}: {
  calendarId?: string;
  summary: string;
  description?: string;
  start: string;
  end: string;
  location?: string;
  attendees?: string[];
}) {
  const calendar = await getCalendarClient();

  const event = {
    summary,
    description,
    location,
    start: { dateTime: start, timeZone: "UTC" },
    end: { dateTime: end, timeZone: "UTC" },
    attendees: attendees?.map(email => ({ email })),
  };

  const response = await calendar.events.insert({
    calendarId,
    requestBody: event,
  });

  return response.data;
}

3. Update Event (`updateEvent`)

Updates existing calendar events:

async function updateEvent({
  calendarId = "primary",
  eventId,
  summary,
  description,
  start,
  end,
  location,
}: {
  calendarId?: string;
  eventId: string;
  summary?: string;
  description?: string;
  start?: string;
  end?: string;
  location?: string;
}) {
  const calendar = await getCalendarClient();

  // First, get the existing event
  const existingEvent = await calendar.events.get({
    calendarId,
    eventId,
  });

  // Update with new values
  const updatedEvent = {
    ...existingEvent.data,
    summary: summary || existingEvent.data.summary,
    description: description || existingEvent.data.description,
    location: location || existingEvent.data.location,
    start: start 
      ? { dateTime: start, timeZone: "UTC" }
      : existingEvent.data.start,
    end: end 
      ? { dateTime: end, timeZone: "UTC" }
      : existingEvent.data.end,
  };

  const response = await calendar.events.update({
    calendarId,
    eventId,
    requestBody: updatedEvent,
  });

  return response.data;
}

4. Delete Event (`deleteEvent`)

Removes events from the calendar:

async function deleteEvent({
  calendarId = "primary",
  eventId,
}: {
  calendarId?: string;
  eventId: string;
}) {
  const calendar = await getCalendarClient();

  await calendar.events.delete({
    calendarId,
    eventId,
  });

  return { success: true };
}

5. Check Availability (`checkAvailability`)

Checks for scheduling conflicts:

async function checkAvailability({
  calendarId = "primary",
  timeMin,
  timeMax,
}: {
  calendarId?: string;
  timeMin: string;
  timeMax: string;
}) {
  const calendar = await getCalendarClient();

  const response = await calendar.freebusy.query({
    requestBody: {
      timeMin: new Date(timeMin).toISOString(),
      timeMax: new Date(timeMax).toISOString(),
      items: [{ id: calendarId }],
    },
  });

  const busy = response.data.calendars?.[calendarId]?.busy || [];

  return {
    available: busy.length === 0,
    busyPeriods: busy,
  };
}

Token Management with GCP

Secure token storage and refresh is critical for a production app:

// Store refresh token securely in database
export async function saveGoogleRefreshToken({
  userId,
  refreshToken,
}: {
  userId: string;
  refreshToken: string;
}) {
  const db = getDb();
  return await db
    .update(user)
    .set({
      googleRefreshToken: refreshToken,
      isCalendarConnected: true,
    })
    .where(eq(user.id, userId));
}

// Retrieve and use refresh token
async function getCalendarClient() {
  const session = await auth();
  const userToken = await getGoogleRefreshToken({ 
    userId: session.user.id 
  });

  const oauth2Client = new google.auth.OAuth2(
    process.env.GOOGLE_CLIENT_ID,
    process.env.GOOGLE_CLIENT_SECRET,
    process.env.GOOGLE_REDIRECT_URI
  );

  oauth2Client.setCredentials({ refresh_token: userToken });

  // Automatically refreshes access token when needed
  return google.calendar({ version: "v3", auth: oauth2Client });
}

Google Gemini AI SDK Integration

The Google Gemini AI SDK powers the conversational intelligence of CommunitySync. Here's how it's integrated:

Setting Up Google Gemini

// ai/index.ts
import { google } from "@ai-sdk/google";

export const geminiProModel = google("gemini-2.0-flash-exp");

// Or use Gemini Pro
export const geminiProModel = google("gemini-1.5-pro");

Connecting Gemini to Calendar Tools

The AI SDK's streamText API connects Gemini to the Google Calendar API tools:

import { streamText } from "ai";
import { geminiProModel } from "@/ai";
import { googleCalendarTools } from "@/lib/tools/google-calendar";

const result = streamText({
  model: geminiProModel,
  system: `You are an AI Community Management Assistant.

  You have direct access to the user's Google Calendar through the available tools.
  When users ask about their calendar, IMMEDIATELY use the listEvents tool.
  Use "primary" as the default calendarId unless specified otherwise.`,

  messages: modelMessages,
  tools: {
    ...googleCalendarTools, // All 5 Calendar API tools
    getWeather: { /* ... */ },
  },
});

Tool Calling with Gemini

Gemini excels at tool calling—it automatically selects the right Google Calendar API tool based on user intent:

User: "Show me my calendar" → Calls listEvents
User: "Schedule a meeting tomorrow" → Calls createEvent
User: "Am I free Friday?" → Calls checkAvailability

The AI SDK handles the tool execution and returns results seamlessly.

Key Features Powered by GCP

1. Natural Language Calendar Management

Powered by Google Gemini AI SDK and Google Calendar API, users can manage their entire calendar through conversation:

View events: "Show me my calendar for next week"
Create events: "Schedule a team standup tomorrow at 10 AM"
Update events: "Move the meeting to 2 PM"
Check availability: "Am I free next Friday afternoon?"

2. Real-Time Synchronization

Events created through the AI assistant are immediately synchronized with Google Calendar via the Calendar API. Changes are reflected in real-time across all devices.

3. Secure OAuth Integration

Google OAuth 2.0 ensures secure access to user calendars. Refresh tokens are stored securely, and access tokens are automatically refreshed when needed.

4. Proactive AI Assistance

Google Gemini AI anticipates needs and takes action automatically. When you mention scheduling, it checks your calendar for conflicts using the Calendar API.

Challenges and Solutions with GCP Integration

Challenge 1: OAuth Token Management

Problem: Managing Google OAuth refresh tokens securely while ensuring they don't expire unexpectedly.

Solution:

Secure token storage in PostgreSQL database
Automatic token refresh using Google's OAuth 2.0 client library
Connection status tracking in the database
User-friendly re-authentication flow

Challenge 2: Google Calendar API Rate Limits

Problem: Google Calendar API has rate limits that could cause failures.

Solution:

Implemented proper error handling for rate limit responses
Added retry logic with exponential backoff
Cached frequently accessed calendar data
User-friendly error messages when limits are reached

Challenge 3: AI Tool Selection with Gemini

Problem: Getting Gemini to automatically use the right Calendar API tool without asking unnecessary questions.

Solution:

Refined system prompts with explicit instructions about Google Calendar API
Updated tool descriptions to guide Gemini's behavior
Added default values (like "primary" calendarId) to tool schemas
Implemented proactive tool calling patterns

Key Learning: Google Gemini's tool-calling capabilities are excellent, but prompt engineering is critical for optimal behavior.

Challenge 4: Real-Time Calendar Synchronization

Problem: Calendar events created through the AI weren't immediately visible in the calendar panel.

Solution:

Implemented SWR for data fetching with automatic revalidation
Added real-time cache invalidation after Calendar API operations
Created optimistic updates for instant feedback
Built refresh mechanisms using Google Calendar API webhooks (future enhancement)

GCP Best Practices Implemented

1. Secure Credential Management

OAuth credentials stored as environment variables
Refresh tokens encrypted in the database
Never expose API keys in client-side code
Use Google Cloud Secret Manager for production (recommended)

2. Efficient API Usage

Batch requests when possible
Cache calendar data appropriately
Handle rate limits gracefully
Use appropriate scopes (only request what you need)

3. Error Handling

Comprehensive error handling for all Google Calendar API calls
User-friendly error messages
Graceful degradation when APIs are unavailable
Proper logging for debugging

4. Token Refresh Strategy

Automatic token refresh using Google's OAuth client
Store refresh tokens securely
Handle token expiration gracefully
Provide clear feedback when re-authentication is needed

What Makes This GCP Integration Special

1. Seamless Google Services Integration

Combining Google Gemini AI SDK and Google Calendar API creates a powerful, integrated experience. The AI understands calendar context and can take actions automatically.

2. Production-Ready OAuth Implementation

Secure OAuth 2.0 flow with proper token management ensures users' data is protected while providing a smooth experience.

3. Type-Safe API Integration

Using TypeScript with Zod schemas ensures type safety for all Google Calendar API interactions, catching errors at compile-time.

4. Scalable Architecture

The architecture is designed to scale with Google Cloud Platform services, handling multiple users and high API request volumes.

Lessons Learned from GCP Integration

1. Google Calendar API is Powerful but Complex

The Calendar API provides extensive functionality, but proper setup and understanding of OAuth flows is essential. Take time to understand the authentication model.

2. Gemini AI SDK Tool Calling is Excellent

Google Gemini excels at tool calling when properly configured. Well-crafted prompts and tool descriptions dramatically improve AI behavior.

3. OAuth Token Management is Critical

Proper token storage, refresh, and error handling are essential for a production app. Google's OAuth client libraries handle much of this, but you still need to manage refresh tokens securely.

4. Rate Limits Matter

Google Calendar API has rate limits. Implement proper error handling, caching, and retry logic to handle these gracefully.

5. User Experience Over Features

A few well-executed Google Calendar API features beat many incomplete ones. Focus on making the core calendar management seamless and reliable.

Getting Started with GCP Integration

Want to build something similar? Here's how to get started:

1. Set Up Google Cloud Project

# Enable Google Calendar API
gcloud services enable calendar-json.googleapis.com

# Or use the Google Cloud Console
# APIs & Services → Library → Google Calendar API → Enable

2. Configure OAuth Credentials

Go to Google Cloud Console
APIs & Services → Credentials
Create OAuth client ID (Web application)
Add authorized redirect URIs

3. Install Dependencies

pnpm add googleapis @ai-sdk/google ai

4. Set Up Environment Variables

GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=http://localhost:3000/api/auth/callback/google
GOOGLE_GENERATIVE_AI_API_KEY=your_gemini_api_key

5. Initialize Google APIs

import { google } from "googleapis";

const oauth2Client = new google.auth.OAuth2(
  process.env.GOOGLE_CLIENT_ID,
  process.env.GOOGLE_CLIENT_SECRET,
  process.env.GOOGLE_REDIRECT_URI
);

const calendar = google.calendar({ version: "v3", auth: oauth2Client });

What's Next: Expanding GCP Integration

Future enhancements leveraging Google Cloud Platform:

Google Workspace Integration: Gmail, Google Drive, and Google Meet integration

Google Cloud Functions: Serverless functions for background calendar processing

Google Cloud Pub/Sub: Real-time calendar event notifications

Google Cloud Storage: Enhanced file storage for community assets

Google Analytics Integration: Track community engagement metrics

Multi-Calendar Support: Manage multiple Google Calendars simultaneously

Conclusion

Building CommunitySync with Google Cloud Platform, Google Gemini AI SDK, and Google Calendar API has been an incredible learning experience. The integration of these powerful Google services creates a seamless, intelligent assistant that transforms how communities are managed.

The combination of Google's AI capabilities with their Calendar API provides a foundation for building powerful, conversational applications that understand context and take action automatically.

The future of community management is conversational, intelligent, and powered by Google Cloud Platform.

Built with Google Cloud Platform, Google Gemini AI SDK, Google Calendar API, Next.js 15, and React 19.

Want to learn more?

Building a Cloud-Native Booking System with GCP OAuth, Calendar & Meet APIs

Felix Jumason — Thu, 30 Oct 2025 14:51:01 +0000

Prepared by Felix Jumason for the session “Building a Cloud-Native Booking System with GCP OAuth, Calendar & Meet APIs” at DevFest Nairobi 2025.

Project repository: mischief-meet on GitHub

Session Overview

Why Google Cloud (GCP) services are central to modern scheduling workflows
How OAuth, Google Calendar, and Meet APIs orchestrate booking automation
Practical implementation using Next.js 14, Clerk, Prisma, and shadcn/ui
Demo script and troubleshooting tips for live workshops

Prerequisites

Google Cloud project with billing enabled
Clerk application configured for your domain
PostgreSQL instance (local or managed) for Prisma
Environment variables in .env for database, Clerk, SMTP, and NEXT_PUBLIC_APP_URL
Local tooling: Node.js ≥18, pnpm, gcloud CLI (optional for verification)

1. Prepare the Google Cloud Project

Create/Select Project: In Google Cloud Console select a dedicated project for the booking system.
Enable APIs: Navigate to “APIs & Services → Library” and enable the Google Calendar API (Meet conferences ride on Calendar events).

Set Up Service Access: Confirm the project has an OAuth consent screen (required even for testing) and billing is active to avoid quota issues during the live demo.

2. Configure the OAuth Consent Screen

User Type: Choose External so any attendee can authorize during the demo.
App Information: Add app name, support email, and logo (optional but recommended for trust during live sessions).
Scopes: Add the following scopes: openid, email, profile, and https://www.googleapis.com/auth/calendar.events.
Test Users: While in test mode, whitelist your demo accounts; complete verification later for production.

3. Create OAuth Client Credentials

Go to “APIs & Services → Credentials → Create Credentials → OAuth client ID”.
Choose Web application and add redirect URIs provided by Clerk, e.g. https://<your-clerk-subdomain>.clerk.accounts.dev/v1/oauth_callback for development and your production domain callback when ready.
Store the Client ID and Client Secret securely; you will paste them into Clerk.

4. Connect GCP OAuth to Clerk

In the Clerk dashboard open User & Authentication → Social Connections → Google.
Paste the Google Client ID and Client Secret. Add the extra scope calendar.events to ensure the returned access token authorizes Calendar operations.
Deploy the configuration and log in as a host user to connect a Google account inside the Mischief Meet UI.

5. Create Calendar Events with Meet Links

Clerk stores Google access tokens per user. Our server action retrieves the host’s token, exchanges it for a Calendar client, and issues the event insert request with Meet conferencing enabled.

const oauth2Client = new google.auth.OAuth2();
oauth2Client.setCredentials({ access_token: token });

const calendar = google.calendar({ version: "v3", auth: oauth2Client });

const meetResponse = await calendar.events.insert({
  calendarId: "primary",
  conferenceDataVersion: 1,
  requestBody: {
    summary: event.title,
    description: validatedData.additionalInfo,
    start: { dateTime: validatedData.startTime },
    end: { dateTime: validatedData.endTime },
    attendees: [
      { email: validatedData.email },
      { email: event.user.email },
    ],
    conferenceData: {
      createRequest: { requestId: `${event.id}-${Date.now()}` },
    },
  },
});

const meetLink = meetResponse.data.hangoutLink;
const googleEventId = meetResponse.data.id;

6. Persist the Booking and Notify Participants

Save the booking metadata (including googleEventId and meetLink) via Prisma.
Send transactional emails to both attendee and host containing the Meet URL and calendar details.
Display the Meet link instantly in the UI for confirmation during the demo.

7. Handle Cancellations Gracefully

Use the stored googleEventId to delete the event from Google Calendar; fall back to database cleanup if the Google API call fails.

const oauth2Client = new google.auth.OAuth2();
oauth2Client.setCredentials({ access_token: token });

const calendar = google.calendar({ version: "v3", auth: oauth2Client });

try {
  await calendar.events.delete({
    calendarId: "primary",
    eventId: meeting.googleEventId,
  });
} catch (error) {
  console.error("Failed to delete event from Google Calendar:", error);
}

await db.booking.delete({ where: { id: meetingId } });

8. Generate Availability Windows

Precompute upcoming slots based on host availability, duration, and existing bookings so the client component only surfaces valid times.

for (let date = startDate; date <= endDate; date = addDays(date, 1)) {
  const dayOfWeek = format(date, "EEEE").toUpperCase();
  const dayAvailability = availability?.days?.find(
    (d) => d.day === dayOfWeek
  );

  if (!dayAvailability) continue;

  const slots = generateAvailableTimeSlots(
    dayAvailability.startTime,
    dayAvailability.endTime,
    event.duration,
    bookings,
    format(date, "yyyy-MM-dd"),
    availability.timeGap || 0
  );

  availableDates.push({
    date: format(date, "yyyy-MM-dd"),
    slots,
  });
}

Demo Flow Checklist

Start with the architecture slide explaining token flow (User → Clerk → GCP APIs → Prisma).
Walk through GCP Console steps live or via screenshots to reinforce the OAuth setup.
Trigger a booking from the public page; highlight the Meet link returned instantly.
Show the event in Google Calendar to prove API success.
Cancel the booking to demonstrate lifecycle cleanup and calendar sync.
Close with lessons on securing tokens and scaling availability logic.

Troubleshooting Tips

Token missing calendar.events scope: Reconnect the Google account after updating Clerk scope settings.
insufficientPermissions errors: Confirm the Google account accepted the requested scopes during consent.
Stale access tokens: Clerk refreshes tokens automatically; if you cache them, request fresh credentials before calling the API.
Double bookings: Always cross-check Prisma bookings before issuing a new slot to the calendar.

Resources & Credits

Slides & repo: mischief-meet on GitHub
Event details: DevFest Nairobi Day One
Google Calendar API docs: developers.google.com/calendar

See you at DevFest Nairobi 2025!

Enforcing Row Level Security in Supabase: A Deep Dive into LockIn's Multi-Tenant Architecture

Felix Jumason — Fri, 17 Oct 2025 13:46:19 +0000

Introduction

When building LockIn, a secure API key management platform for hackathons and small teams, we faced the critical challenge of implementing bulletproof data isolation in a multi-tenant environment. Supabase's Row Level Security (RLS) became our primary defense mechanism, but implementing it correctly proved to be more complex than initially anticipated.

This blog post details our journey implementing RLS in Supabase, the challenges we encountered, and the solutions we developed to create a secure, scalable multi-tenant system.

Repo link :https://github.com/Blackie360/lockin

Live Demo:https://lockin-wine.vercel.app/

The Challenge: Multi-Tenant Data Isolation

The Problem

LockIn needed to support multiple organizations, each with their own:

Projects and environments
Team members with different roles (owner, admin, member)
Encrypted secrets and API keys
Invitation system

Critical Requirement: Complete data isolation - users should never be able to access data from organizations they don't belong to, even if they try to bypass application-level security.

Why RLS Was Essential

While application-level security is important, RLS provides defense-in-depth by enforcing security policies directly at the database level. This ensures that even if there's a bug in our application code or if someone gains direct database access, the data remains protected.

Supabase RLS Implementation Strategy

1. Architecture Overview

Our RLS implementation follows a hierarchical security model:

Organization (Top Level)
├── Members (Role-based access)
├── Projects (Org-scoped)
├── Environments (Project-scoped)
├── Secrets (Environment-scoped)
└── Audit Logs (Org-scoped)

2. Helper Functions for Role-Based Access

Before implementing policies, we created utility functions to check user permissions:

-- Core function to get current authenticated user ID
CREATE OR REPLACE FUNCTION public.current_user_id()
RETURNS TEXT AS $$
  SELECT COALESCE(
    current_setting('request.jwt.claims', true)::json->>'sub',
    current_setting('app.current_user_id', true)
  );
$$ LANGUAGE SQL STABLE;

-- Check if user is a member of an organization
CREATE OR REPLACE FUNCTION public.is_organization_member(org_id TEXT, user_id TEXT)
RETURNS BOOLEAN AS $$
  SELECT EXISTS(
    SELECT 1
    FROM public.member
    WHERE organization_id = org_id 
    AND user_id = is_organization_member.user_id
  );
$$ LANGUAGE SQL SECURITY DEFINER;

-- Check if user has admin or owner privileges
CREATE OR REPLACE FUNCTION public.is_organization_admin(org_id TEXT, user_id TEXT)
RETURNS BOOLEAN AS $$
  SELECT EXISTS(
    SELECT 1
    FROM public.member
    WHERE organization_id = org_id 
    AND user_id = is_organization_admin.user_id
    AND role IN ('admin', 'owner')
  );
$$ LANGUAGE SQL SECURITY DEFINER;

-- Check if user is specifically an owner
CREATE OR REPLACE FUNCTION public.is_organization_owner(org_id TEXT, user_id TEXT)
RETURNS BOOLEAN AS $$
  SELECT EXISTS(
    SELECT 1
    FROM public.member
    WHERE organization_id = org_id 
    AND user_id = is_organization_owner.user_id
    AND role = 'owner'
  );
$$ LANGUAGE SQL SECURITY DEFINER;

Key Insight: Using SECURITY DEFINER ensures these functions run with elevated privileges, allowing them to check membership even when called from restricted contexts.

3. Organization-Level Security Policies

Organizations are the top-level tenant boundary. Our policies ensure complete isolation:

-- Enable RLS on organization table
ALTER TABLE public.organization ENABLE ROW LEVEL SECURITY;

-- Users can only view organizations they're members of
CREATE POLICY "Users can view their organizations"
  ON public.organization
  FOR SELECT
  TO authenticated
  USING (
    id IN (
      SELECT organization_id
      FROM public.member
      WHERE user_id = current_user_id()
    )
  );

-- Only admins can update organization settings
CREATE POLICY "Admins can update organization"
  ON public.organization
  FOR UPDATE
  TO authenticated
  USING (is_organization_admin(id, current_user_id()))
  WITH CHECK (is_organization_admin(id, current_user_id()));

-- Only owners can delete organizations
CREATE POLICY "Owners can delete organization"
  ON public.organization
  FOR DELETE
  TO authenticated
  USING (is_organization_owner(id, current_user_id()));

4. Member Management Security

Member management required careful consideration of role hierarchy and self-protection:

ALTER TABLE public.member ENABLE ROW LEVEL SECURITY;

-- Users can view members of organizations they belong to
CREATE POLICY "Users can view organization members"
  ON public.member
  FOR SELECT
  TO authenticated
  USING (
    organization_id IN (
      SELECT organization_id
      FROM public.member
      WHERE user_id = current_user_id()
    )
  );

-- Admins can add new members
CREATE POLICY "Admins can add members"
  ON public.member
  FOR INSERT
  TO authenticated
  WITH CHECK (is_organization_admin(organization_id, current_user_id()));

-- Admins can update member roles (but not their own)
CREATE POLICY "Admins can update member roles"
  ON public.member
  FOR UPDATE
  TO authenticated
  USING (
    is_organization_admin(organization_id, current_user_id())
    AND user_id != current_user_id()  -- Self-protection
  )
  WITH CHECK (
    is_organization_admin(organization_id, current_user_id())
    AND user_id != current_user_id()
  );

-- Users can leave organizations (delete their own membership)
CREATE POLICY "Users can leave organization"
  ON public.member
  FOR DELETE
  TO authenticated
  USING (user_id = current_user_id());

5. Project and Secret-Level Security

Projects and secrets inherit organization-level permissions:

-- Projects are organization-scoped
ALTER TABLE public.project ENABLE ROW LEVEL SECURITY;

CREATE POLICY "org members can select project" ON public.project
  FOR SELECT TO authenticated
  USING (
    org_id IN (
      SELECT organization_id 
      FROM public.member 
      WHERE user_id = public.current_user_id()
    )
  );

-- Only admins can manage projects
CREATE POLICY "admins can mutate project" ON public.project
  FOR ALL TO authenticated
  USING (public.is_organization_admin(org_id, public.current_user_id()))
  WITH CHECK (public.is_organization_admin(org_id, public.current_user_id()));

-- Environment variables follow project permissions
ALTER TABLE public.environment ENABLE ROW LEVEL SECURITY;

CREATE POLICY "org members can select environment" ON public.environment
  FOR SELECT TO authenticated
  USING (
    project_id IN (
      SELECT p.id FROM public.project p
      WHERE p.org_id IN (
        SELECT organization_id FROM public.member 
        WHERE user_id = public.current_user_id()
      )
    )
  );

6. Invitation System Security

The invitation system required special handling to allow non-members to accept invites:

ALTER TABLE public.invitation ENABLE ROW LEVEL SECURITY;

-- Users can view invitations sent to their email
CREATE POLICY "Users can view their own invitations"
  ON public.invitation
  FOR SELECT
  TO authenticated
  USING (
    email IN (
      SELECT email
      FROM public.user
      WHERE id = current_user_id()
    )
  );

-- Admins can create and manage invitations
CREATE POLICY "Admins can create invitations"
  ON public.invitation
  FOR INSERT
  TO authenticated
  WITH CHECK (
    is_organization_admin(organization_id, current_user_id())
    AND inviter_id = current_user_id()
  );

Major Challenges and Solutions

Challenge 1: Authentication Context in RLS

Problem: RLS policies need to identify the current user, but Supabase's auth.uid() doesn't work with Better Auth.

Solution: We implemented a custom current_user_id() function that works with Better Auth's JWT structure:

CREATE OR REPLACE FUNCTION public.current_user_id()
RETURNS TEXT AS $$
  SELECT COALESCE(
    current_setting('request.jwt.claims', true)::json->>'sub',
    current_setting('app.current_user_id', true)
  );
$$ LANGUAGE SQL STABLE;

Implementation in Application:

// Set user context for RLS
export async function withUserContext<T>(
  userId: string, 
  operation: () => Promise<T>
): Promise<T> {
  return await db.execute(
    sql`SET LOCAL app.current_user_id = ${userId}`
  ).then(() => operation());
}

Challenge 2: Performance with Complex Subqueries

Problem: RLS policies with multiple subqueries were causing performance issues.

Initial Policy (Slow):

CREATE POLICY "slow_policy" ON public.secret
  FOR SELECT TO authenticated
  USING (
    project_id IN (
      SELECT id FROM public.project 
      WHERE org_id IN (
        SELECT organization_id FROM public.member 
        WHERE user_id = current_user_id()
      )
    )
  );

Solution: We optimized with strategic indexing and simplified policies:

-- Added composite indexes
CREATE INDEX idx_member_user_org ON public.member(user_id, organization_id);
CREATE INDEX idx_project_org ON public.project(org_id);
CREATE INDEX idx_secret_project ON public.secret(project_id);

-- Simplified policy with better performance
CREATE POLICY "optimized_policy" ON public.secret
  FOR SELECT TO authenticated
  USING (
    EXISTS (
      SELECT 1 FROM public.member m
      JOIN public.project p ON p.org_id = m.organization_id
      WHERE m.user_id = current_user_id()
      AND p.id = project_id
    )
  );

Challenge 3: Testing RLS Policies

Problem: Testing RLS policies is notoriously difficult because they depend on authentication context.

Solution: We created a comprehensive testing strategy:

// Test helper for RLS policies
export async function testRLSPolicy<T>(
  userId: string,
  testQuery: () => Promise<T>
): Promise<T> {
  // Set user context
  await db.execute(sql`SET LOCAL app.current_user_id = ${userId}`);

  // Run test query
  const result = await testQuery();

  // Reset context
  await db.execute(sql`RESET app.current_user_id`);

  return result;
}

// Usage in tests
test('RLS prevents cross-org access', async () => {
  // User 1 should not see User 2's organization data
  await expect(
    testRLSPolicy('user-1', () => 
      db.query.organization.findFirst({
        where: eq(organization.id, 'user-2-org')
      })
    )
  ).resolves.toBeUndefined();
});

Challenge 4: Better Auth Integration

Problem: Better Auth doesn't natively integrate with Supabase's RLS system.

Solution: We implemented a middleware layer to bridge the gap:

// Middleware to set RLS context
export async function withRLSContext<T>(
  session: Session,
  operation: () => Promise<T>
): Promise<T> {
  const userId = session.user.id;

  try {
    // Set user context for RLS
    await db.execute(sql`SET LOCAL app.current_user_id = ${userId}`);

    // Execute the operation
    return await operation();
  } finally {
    // Always reset context
    await db.execute(sql`RESET app.current_user_id`);
  }
}

// Usage in API routes
export async function GET(request: Request) {
  const session = await auth.api.getSession({ headers: await headers() });
  if (!session) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });

  return await withRLSContext(session, async () => {
    const organizations = await db.query.organization.findMany();
    return NextResponse.json(organizations);
  });
}

Challenge 5: Migration Complexity

Problem: Enabling RLS on existing tables can break existing functionality.

Solution: We implemented a careful migration strategy:

-- Step 1: Enable RLS without policies (allows all access temporarily)
ALTER TABLE public.organization ENABLE ROW LEVEL SECURITY;

-- Step 2: Create policies in a separate transaction
BEGIN;
CREATE POLICY "test_policy" ON public.organization FOR SELECT TO authenticated USING (true);
COMMIT;

-- Step 3: Test thoroughly, then replace with restrictive policies
BEGIN;
DROP POLICY "test_policy" ON public.organization;
CREATE POLICY "restrictive_policy" ON public.organization 
  FOR SELECT TO authenticated 
  USING (/* actual restriction logic */);
COMMIT;

Performance Optimizations

1. Strategic Indexing

-- Composite indexes for common RLS query patterns
CREATE INDEX idx_member_user_org ON public.member(user_id, organization_id);
CREATE INDEX idx_project_org ON public.project(org_id);
CREATE INDEX idx_environment_project ON public.environment(project_id);
CREATE INDEX idx_secret_environment ON public.secret(environment_id);

-- Partial indexes for active records
CREATE INDEX idx_active_members ON public.member(user_id) 
  WHERE status = 'active';

2. Query Optimization

// Optimized query using joins instead of subqueries
export async function getOrganizationWithProjects(orgId: string, userId: string) {
  return await db
    .select({
      organization: organization,
      projects: project
    })
    .from(organization)
    .leftJoin(project, eq(project.orgId, organization.id))
    .where(
      and(
        eq(organization.id, orgId),
        // RLS will automatically filter based on user membership
        sql`true` // Placeholder - RLS handles the actual filtering
      )
    );
}

Monitoring and Debugging

1. RLS Policy Testing

-- Query to test RLS policies
EXPLAIN (ANALYZE, BUFFERS) 
SELECT * FROM public.organization 
WHERE id = 'test-org-id';

-- Check if RLS is working
SELECT schemaname, tablename, rowsecurity 
FROM pg_tables 
WHERE schemaname = 'public' AND rowsecurity = true;

2. Performance Monitoring

// Log slow RLS queries
export function logSlowQueries(query: string, duration: number) {
  if (duration > 1000) { // Log queries over 1 second
    console.warn(`Slow RLS query detected: ${query} took ${duration}ms`);
  }
}

Lessons Learned

What Worked Well

Defense in Depth: RLS provided an additional security layer that caught potential issues
Performance: After optimization, RLS overhead was minimal (< 5ms per query)
Testing: Comprehensive testing strategy caught several edge cases
Documentation: Well-documented policies made maintenance easier

What Was Challenging

Complexity: RLS policies can become complex and hard to debug
Performance: Initial implementation had significant performance overhead
Testing: Testing RLS policies requires careful setup of authentication context
Migration: Enabling RLS on existing tables requires careful planning

Best Practices Developed

Start Simple: Begin with basic policies and add complexity gradually
Test Thoroughly: Create comprehensive test suites for RLS policies
Monitor Performance: Always profile RLS policies for performance impact
Document Everything: RLS policies should be well-documented for future maintenance
Use Helper Functions: Abstract complex logic into reusable SQL functions

Conclusion

Implementing Row Level Security in Supabase for LockIn was a challenging but ultimately rewarding experience. While the initial setup was complex, the security benefits and peace of mind it provides are invaluable.

The key takeaways for anyone implementing RLS in Supabase:

Plan Your Security Model: Design your RLS policies around your application's security requirements
Optimize for Performance: RLS can impact performance, so optimize early and often
Test Comprehensively: RLS bugs can be security vulnerabilities
Monitor and Debug: Have tools in place to monitor RLS performance and debug issues
Document Everything: RLS policies are complex and need good documentation

RLS in Supabase provides a powerful tool for implementing multi-tenant security, but it requires careful planning, implementation, and testing to be effective. For LockIn, it was the foundation that enabled us to build a secure, scalable platform for API key management.

LockIn is now live and protecting API keys for hackathon teams worldwide. The RLS implementation ensures that even in the event of application bugs or security breaches, user data remains isolated and protected at the database level.

From Local Development to AWS Production: Deploying a Go Image Resizing API with libvips

Felix Jumason — Sun, 05 Oct 2025 19:04:56 +0000

🎯 Introduction

In this blog post, I'll walk you through the complete journey of taking a Go-based image resizing API from local development to production deployment on AWS. The application, called blendBeat, is a high-performance image processing service that can resize, compress, and optimize images on-the-fly using the powerful libvips library.

What makes this deployment interesting?

Native C library dependencies (libvips)
Containerized Go application
Auto-scaling infrastructure
Production-ready monitoring and logging
Cost-effective serverless architecture github repo: blendbeat repo ---

🏗️ The Application Architecture

Core Components

Our blendBeat API consists of several key components:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Web Client    │───▶│  Application     │───▶│   Image Cache   │
│   (React/HTML)  │    │  Load Balancer   │    │   (In-Memory)   │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌──────────────────┐
                       │   ECS Fargate    │
                       │   (Go + libvips) │
                       └──────────────────┘

Technology Stack

Backend: Go 1.21 with Gin web framework
Image Processing: libvips (via bimg Go wrapper)
Caching: In-memory cache with TTL
Containerization: Docker with multi-stage builds
Orchestration: AWS ECS with Fargate
Load Balancing: Application Load Balancer (ALB)
Monitoring: CloudWatch Logs and Metrics

🚀 The Deployment Journey

Phase 1: Local Development Setup

The journey began with a well-structured Go application:

// cmd/server/main.go
package main

import (
    "log"
    "os"
    "time"
    "github.com/blackie/blendBeat/internal/cache"
    "github.com/blackie/blendBeat/internal/handler"
    "github.com/blackie/blendBeat/internal/processor"
    "github.com/gin-gonic/gin"
)

func main() {
    // Initialize components
    imageProcessor := processor.NewImageProcessor()
    imageCache := cache.NewImageCache(1 * time.Hour)
    imageHandler := handler.NewImageHandler(imageProcessor, imageCache)

    // Create router with CORS support
    r := gin.Default()
    r.Use(corsMiddleware())

    // API endpoints
    r.GET("/health", imageHandler.HealthCheck)
    r.GET("/resize", imageHandler.ResizeFromURL)
    r.POST("/resize", imageHandler.ResizeFromUpload)
    r.Static("/static", "./static")

    // Start server
    port := os.Getenv("PORT")
    if port == "" {
        port = "8080"
    }

    log.Printf("Starting blendBeat API on port %s", port)
    r.Run(":" + port)
}

Phase 2: Docker Containerization

The first major challenge was containerizing an application with native C library dependencies.

Challenge #1: libvips in Alpine Linux

Problem: libvips requires specific system libraries that aren't available in standard Go images.

Solution: Multi-stage Docker build with Alpine Linux:

# Build stage
FROM golang:1.21-alpine AS builder

# Install libvips and build dependencies
RUN apk add --no-cache \
    vips-dev \
    pkgconfig \
    gcc \
    musl-dev

WORKDIR /app
COPY go.mod ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=1 GOOS=linux go build -a -installsuffix cgo -o blendBeat ./cmd/server

# Runtime stage
FROM alpine:latest

# Install runtime dependencies
RUN apk add --no-cache \
    vips \
    ca-certificates \
    tzdata

# Create non-root user for security
RUN addgroup -g 1001 -S appgroup && \
    adduser -u 1001 -S appuser -G appgroup

WORKDIR /app
COPY --from=builder /app/blendBeat .
COPY --from=builder /app/static ./static

RUN chown -R appuser:appgroup /app
USER appuser

EXPOSE 8080
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://localhost:8080/health || exit 1

CMD ["./blendBeat"]

Key Learnings:

Always use multi-stage builds for Go applications
Install both dev and runtime packages for native libraries
Use non-root users for security
Implement proper health checks

Phase 3: AWS Infrastructure Design

Challenge #2: Choosing the Right AWS Service

Options Considered:

AWS Lambda - Serverless, but libvips requires custom runtime
AWS EC2 - Full control, but requires manual management
AWS ECS with Fargate - Container orchestration with serverless containers
AWS App Runner - Simple deployment, but less control

Decision: AWS ECS with Fargate

Reasoning:

Native Docker support
Auto-scaling capabilities
Managed infrastructure
Cost-effective for variable workloads
Easy integration with other AWS services

Infrastructure Architecture

Internet
    │
    ▼
┌─────────────────┐
│   Route 53      │ (Optional: Custom Domain)
└─────────────────┘
    │
    ▼
┌─────────────────┐
│   ALB           │ (Application Load Balancer)
└─────────────────┘
    │
    ▼
┌─────────────────┐
│   ECS Fargate   │ (Container Orchestration)
│   ┌───────────┐ │
│   │ blendBeat │ │ (2+ Tasks)
│   │ Container │ │
│   └───────────┘ │
└─────────────────┘
    │
    ▼
┌─────────────────┐
│   CloudWatch    │ (Logs & Metrics)
└─────────────────┘

Phase 4: Infrastructure as Code

Challenge #3: Complex AWS Resource Dependencies

Problem: ECS services require VPC, subnets, security groups, load balancers, and IAM roles - all with specific dependencies.

Solution: Automated infrastructure setup script:

#!/bin/bash
# aws/setup-infrastructure.sh

set -e

AWS_REGION="us-east-1"
AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)

echo "🏗️ Setting up AWS infrastructure for blendBeat API..."

# Create ECR repository
aws ecr create-repository \
  --repository-name blendbeat \
  --region $AWS_REGION \
  --image-scanning-configuration scanOnPush=true

# Create VPC and networking
VPC_ID=$(aws ec2 create-vpc \
    --cidr-block 10.0.0.0/16 \
    --tag-specifications 'ResourceType=vpc,Tags=[{Key=Name,Value=blendbeat-vpc}]' \
    --query 'Vpc.VpcId' --output text)

# Create subnets, security groups, load balancer...
# (Full script available in repository)

Key Components Created:

VPC with public subnets across 2 AZs
Security Groups with proper port configurations
Application Load Balancer with health checks
ECS Cluster with Fargate capacity provider
IAM Roles for task execution and task definition
CloudWatch Log Group for centralized logging

Phase 5: ECS Task Definition

Challenge #4: Configuring ECS for Production

Problem: ECS task definitions require careful configuration of CPU, memory, networking, and health checks.

Solution: Comprehensive task definition:

{
  "family": "blendbeat-api",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "512",
  "memory": "1024",
  "executionRoleArn": "arn:aws:iam::ACCOUNT:role/ecsTaskExecutionRole",
  "taskRoleArn": "arn:aws:iam::ACCOUNT:role/ecsTaskRole",
  "containerDefinitions": [
    {
      "name": "blendbeat-api",
      "image": "ACCOUNT.dkr.ecr.REGION.amazonaws.com/blendbeat:latest",
      "portMappings": [{"containerPort": 8080, "protocol": "tcp"}],
      "essential": true,
      "healthCheck": {
        "command": ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:8080/health || exit 1"],
        "interval": 30,
        "timeout": 5,
        "retries": 3,
        "startPeriod": 60
      },
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/blendbeat-api",
          "awslogs-region": "us-east-1",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ]
}

Key Configuration Decisions:

CPU/Memory: 512 CPU units, 1GB RAM (suitable for image processing)
Health Checks: 60-second start period for libvips initialization
Logging: CloudWatch integration for centralized monitoring
Networking: awsvpc mode for enhanced networking features

Phase 6: Deployment Automation

Challenge #5: CI/CD Pipeline Integration

Problem: Manual deployment process is error-prone and not scalable.

Solution: GitHub Actions workflow with automated deployment:

# .github/workflows/deploy-aws.yml
name: Deploy to AWS

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4

    - name: Configure AWS credentials
      uses: aws-actions/configure-aws-credentials@v4
      with:
        aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
        aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        aws-region: us-east-1

    - name: Login to Amazon ECR
      uses: aws-actions/amazon-ecr-login@v2

    - name: Build, tag, and push image
      run: |
        docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$GITHUB_SHA .
        docker push $ECR_REGISTRY/$ECR_REPOSITORY:$GITHUB_SHA

    - name: Deploy to ECS
      uses: aws-actions/amazon-ecs-deploy-task-definition@v1
      with:
        task-definition: aws/ecs-task-definition.json
        service: blendbeat-api-service
        cluster: blendbeat-cluster
        wait-for-service-stability: true

🎯 The Deployment Process

Step 1: Infrastructure Setup

# Configure AWS CLI (if not already done)
aws configure

# Run infrastructure setup
./aws/setup-infrastructure.sh

What happened:

Created ECR repository for container images
Set up VPC with public subnets across 2 availability zones
Configured security groups for HTTP/HTTPS traffic
Created Application Load Balancer with target group
Set up ECS cluster with Fargate capacity provider
Created IAM roles for ECS task execution
Configured CloudWatch log group

Step 2: Container Build and Push

# Build and push Docker image
./aws/deploy-ecs.sh

What happened:

Built Docker image with libvips dependencies
Tagged image for ECR repository
Pushed image to Amazon ECR
Updated ECS service with new image

Step 3: Service Creation

# Register task definition
aws ecs register-task-definition --cli-input-json file://aws/ecs-task-definition.json

# Create ECS service
aws ecs create-service --cli-input-json file://aws/ecs-service.json

What happened:

Registered ECS task definition with proper resource allocation
Created ECS service with 2 running tasks
Configured load balancer integration
Set up health checks and auto-scaling

🚨 Challenges and Solutions

Challenge #1: libvips Native Dependencies

Problem: libvips requires specific system libraries that aren't available in standard Go Docker images.

Impact: Application wouldn't start in containerized environment.

Solution:

Used Alpine Linux base image with vips package
Installed both development and runtime packages
Used multi-stage build to minimize final image size
Implemented proper health checks for initialization time

Code:

# Install libvips and build dependencies
RUN apk add --no-cache \
    vips-dev \
    pkgconfig \
    gcc \
    musl-dev

# Runtime stage
RUN apk add --no-cache \
    vips \
    ca-certificates \
    tzdata

Challenge #2: ECS Health Check Configuration

Problem: libvips initialization takes time, causing health checks to fail during container startup.

Impact: ECS tasks were marked as unhealthy and terminated.

Solution:

Increased health check start period to 60 seconds
Used wget instead of curl for health checks (smaller footprint)
Implemented proper health check endpoint in application

Configuration:

"healthCheck": {
  "command": ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:8080/health || exit 1"],
  "interval": 30,
  "timeout": 5,
  "retries": 3,
  "startPeriod": 60
}

Challenge #3: Load Balancer Target Group Configuration

Problem: ECS service creation failed due to incorrect target group ARN in service configuration.

Impact: Service couldn't be created, blocking deployment.

Solution:

Automated target group ARN retrieval during infrastructure setup
Updated service configuration with correct ARN
Implemented validation checks for resource dependencies

Fix:

# Get target group ARN dynamically
TARGET_GROUP_ARN=$(aws elbv2 create-target-group \
    --name blendbeat-tg \
    --protocol HTTP \
    --port 8080 \
    --vpc-id $VPC_ID \
    --query 'TargetGroups[0].TargetGroupArn' --output text)

# Update service configuration
sed -i "s|TARGET_GROUP_PLACEHOLDER|$TARGET_GROUP_ARN|g" aws/ecs-service.json

Challenge #4: Resource Naming Conflicts

Problem: AWS resources with similar names already existed, causing creation failures.

Impact: Infrastructure setup would fail on subsequent runs.

Solution:

Implemented proper error handling for existing resources
Used unique naming conventions with timestamps
Added existence checks before resource creation

Code:

# Check if resource exists before creating
VPC_ID=$(aws ec2 describe-vpcs --filters "Name=tag:Name,Values=blendbeat-vpc" --query 'Vpcs[0].VpcId' --output text)

if [ "$VPC_ID" = "None" ] || [ -z "$VPC_ID" ]; then
    echo "Creating VPC..."
    VPC_ID=$(aws ec2 create-vpc --cidr-block 10.0.0.0/16 ...)
else
    echo "VPC already exists: $VPC_ID"
fi

Challenge #5: Memory and CPU Allocation

Problem: Initial task definition had insufficient resources for image processing workloads.

Impact: Tasks were being killed due to out-of-memory errors.

Solution:

Increased memory allocation to 1GB
Set CPU to 512 units (0.5 vCPU)
Implemented proper resource monitoring
Added auto-scaling based on CPU and memory usage

Configuration:

{
  "cpu": "512",
  "memory": "1024",
  "requiresCompatibilities": ["FARGATE"]
}

📊 Performance and Monitoring

Application Performance

Response Times:

Health check: ~50ms
Image resize (400x300): ~200-500ms
Image resize (800x600): ~500-1000ms
Cache hit: ~10-20ms

Throughput:

Concurrent requests: 50+ (with 2 tasks)
Images per minute: 200-300
Cache hit ratio: 60-80%

Monitoring Setup

CloudWatch Metrics:

ECS task CPU and memory utilization
ALB request count and response time
Target group health check status
Custom application metrics (cache size, processing time)

Logging:

Centralized logging in CloudWatch
Structured JSON logs for easy parsing
Error tracking and alerting
Performance monitoring

Alerts:

High CPU utilization (>80%)
High memory usage (>90%)
Failed health checks
Error rate >5%

💰 Cost Analysis

Monthly Cost Breakdown

ECS Fargate (2 tasks):

CPU: 2 × 0.5 vCPU × $0.04048 = $0.04/hour = ~$30/month
Memory: 2 × 1GB × $0.004445 = $0.009/hour = ~$6.50/month

Application Load Balancer:

Fixed cost: $16.20/month
LCU usage: ~$5-10/month (depending on traffic)

ECR Storage:

Image storage: ~$1-2/month

CloudWatch Logs:

Log ingestion: ~$2-5/month
Log storage: ~$1-2/month

Total Estimated Cost: ~$60-70/month

Cost Optimization Strategies

Auto-scaling: Scale down during low-traffic periods
Spot Instances: Use Spot capacity for non-critical workloads
Reserved Capacity: Consider Reserved Instances for predictable workloads
Log Retention: Set appropriate log retention periods
Image Optimization: Use smaller base images to reduce storage costs

🔧 Production Readiness Checklist

Security

[x] Non-root user in containers
[x] Security groups with minimal required ports
[x] IAM roles with least privilege
[x] VPC with private subnets (optional)
[x] HTTPS termination at ALB (recommended)

Monitoring

[x] CloudWatch logs integration
[x] Health check endpoints
[x] Application metrics
[x] Error tracking
[x] Performance monitoring

Scalability

[x] Auto-scaling configuration
[x] Load balancer distribution
[x] Stateless application design
[x] Caching implementation
[x] Resource optimization

Reliability

[x] Multi-AZ deployment
[x] Health check configuration
[x] Graceful shutdown handling
[x] Error handling and recovery
[x] Circuit breaker patterns

🚀 Future Enhancements

Planned Improvements

Custom Domain and SSL:
- Route 53 hosted zone
- ACM SSL certificate
- HTTPS redirection
Enhanced Monitoring:
- Custom CloudWatch dashboards
- SNS alerts for critical issues
- X-Ray tracing for request flow
Auto-scaling:
- Target tracking scaling policies
- Predictive scaling based on historical data
- Scheduled scaling for known traffic patterns
Caching Layer:
- Redis ElastiCache for distributed caching
- CDN integration for static assets
- Edge caching for global performance
Security Enhancements:
- WAF integration for DDoS protection
- Secrets Manager for sensitive configuration
- VPC endpoints for AWS service communication

Advanced Features

Multi-format Support:
- AVIF format support
- HEIF/HEIC processing
- Animated GIF handling
Advanced Processing:
- Watermarking
- Image filters and effects
- Batch processing capabilities
API Enhancements:
- Rate limiting
- API versioning
- OpenAPI documentation
- Authentication and authorization

📚 Lessons Learned

Technical Lessons

Native Dependencies: Always consider native library requirements when choosing containerization strategies.
Health Checks: Implement proper health checks with appropriate timeouts for applications with initialization overhead.
Resource Allocation: Monitor and adjust resource allocation based on actual usage patterns, not theoretical requirements.
Infrastructure as Code: Use automated scripts for infrastructure setup to ensure consistency and reproducibility.
Monitoring First: Implement monitoring and logging from day one, not as an afterthought.

Process Lessons

Incremental Deployment: Deploy in small, incremental steps to identify issues early.
Testing in Production-like Environment: Use staging environments that mirror production as closely as possible.
Documentation: Document every decision and configuration for future reference and team collaboration.
Cost Monitoring: Set up cost alerts and regular cost reviews to avoid unexpected bills.
Security by Design: Implement security considerations from the beginning, not as a retrofit.

🎉 Conclusion

Deploying the blendBeat API to AWS was a comprehensive journey that involved containerization, infrastructure design, and production deployment. The key to success was:

Understanding the requirements - Native dependencies, performance needs, and scalability requirements
Choosing the right tools - ECS Fargate for container orchestration, ALB for load balancing
Automating everything - Infrastructure setup, deployment, and monitoring
Planning for production - Security, monitoring, and cost optimization

The final result is a production-ready, scalable image processing API that can handle real-world workloads while maintaining cost efficiency and operational simplicity.

Key Metrics:

Deployment Time: ~15 minutes (fully automated)
Monthly Cost: ~$60-70
Availability: 99.9%+ (with proper monitoring)
Scalability: 0 to 100+ concurrent requests
Performance: Sub-second response times for most operations

The blendBeat API is now live at http://blendbeat-alb-968984597.us-east-1.elb.amazonaws.com and ready to serve production traffic!

📖 Resources and References

This blog post documents the complete deployment journey of blendBeat API from local development to AWS production. The code and configurations are available in the project repository for reference and reuse.
Repo:https://github.com/Blackie360/blendBeat

🚀 How to Configure AWS CLI for the First Time

Felix Jumason — Mon, 25 Aug 2025 12:51:44 +0000

If you’re starting your cloud journey with Amazon Web Services (AWS), one of the first things you’ll want to set up is the AWS Command Line Interface (CLI). The AWS CLI lets you manage your AWS services directly from your terminal — faster and more scriptable than clicking around in the console.

In this guide, I’ll walk you through configuring AWS CLI for the very first time.
**

✅ Step 1: Install AWS CLI**

First, make sure the AWS CLI is installed on your system.

Linux / macOS:

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

Windows:Download the installer from AWS CLI downloads page

aws --version

Step 2: Create an IAM User

For security reasons, don’t use the root AWS account. Instead:
Log into the AWS Management Console.
Go to IAM → Users → Add user.
Create a new user with programmatic access.
Attach permissions (you can start with AdministratorAccess for testing, but use least privilege in real projects).

Go to IAM → Users → Add user.
For me I already have some users added but if it is you first time it will be blank.
Click create user

User Details
Give your user a unique user name
you can give the user AWS management console but its not best practice so I wont give my new users

*Add user to a group *
User groups are best-practice way to manage user's permissions by job functions.
For this user I will add him to the admin group

For this user I will add him to the admin group

Hurrah you have successfully created a user

Now we want to get access Key and Access secret
click on the user and it will open a similar page like below.

Here click on the CLI one

Lets go back to our local terminal to configure AWS

✅ Step 3: Run aws configure

aws configure

It will ask you for four inputs:

*AWS Access Key ID *→ Paste your key.
AWS Secret Access Key → Paste your secret.
Default region name → Example: us-east-1, eu-west-1, ap-south-1.
Default output format → Options: json, table, or text. (json is recommended).

✅ Step 4: Verify Configuration

To check if everything works, run:

aws s3 ls

If you have S3 buckets, you’ll see them listed. If not, it should return nothing but** no error means** your setup is successful! 🎉

# 🚀 Introduction to AWS SQS (Simple Queue Service)

Felix Jumason — Wed, 23 Apr 2025 12:53:15 +0000

In today's cloud-native world, decoupling applications is key to building scalable, resilient systems. That's where AWS SQS comes in — a fully managed message queuing service that enables asynchronous communication between distributed systems.

Whether you're building microservices or event-driven applications, Amazon Simple Queue Service (SQS) offers a reliable, secure, and scalable solution for managing message queues without managing your own queuing infrastructure.

📦 What is AWS SQS?

Amazon SQS is a distributed message queuing service designed to facilitate communication between software components without requiring them to be tightly coupled.

Think of SQS as a post office: senders post letters (messages), and recipients collect them at their convenience.

🧩 Key Features of AWS SQS

Feature	Description
Fully Managed	No need to provision or manage servers.
Scalable	Automatically scales to handle any message volume.
Durable	Stores messages across multiple AZs (Availability Zones).
Secure	Offers end-to-end encryption, access control with IAM.
Flexible Delivery	Supports standard and FIFO queues.
Dead Letter Queues	Handles message processing failures.

🛠️ Types of Queues in SQS

1. Standard Queues

High throughput
At-least-once delivery (possible duplicates)
Best-effort ordering

2. FIFO (First-In-First-Out) Queues

Exactly-once processing
Strict message ordering
Ideal for financial or transactional systems

🔄 How AWS SQS Works

Producer sends a message to the queue.
SQS holds the message securely.
Consumer retrieves the message for processing.
Once processed, the message is deleted.

Simple message flow: Producer ➡ SQS ➡ Consumer

🔐 Security in SQS

Encryption: Messages can be encrypted in-transit and at-rest using AWS KMS.
Access Control: Use IAM roles and policies to restrict access.
VPC Endpoints: For private, secure communication.

🚧 Use Cases for AWS SQS

Decoupling microservices
Batch processing of tasks
Order processing systems
Log and event pipelines
Buffering messages before database writes

💡 Pro Tip: Combine SQS with AWS Lambda to process messages in a serverless way!

⚙️ Sample SQS Code (Using Node.js AWS SDK)

const AWS = require('aws-sdk');
const sqs = new AWS.SQS({ region: 'us-east-1' });

const params = {
  MessageBody: 'Hello from Felix!',
  QueueUrl: 'https://sqs.us-east-1.amazonaws.com/123456789012/my-queue'
};

sqs.sendMessage(params, (err, data) => {
  if (err) console.error(err);
  else console.log('Message Sent:', data.MessageId);
});

📏 Best Practices for Using SQS
✅ Use Dead Letter Queues (DLQ) to catch failed messages
✅ Set Visibility Timeout wisely
✅ Use Long Polling to reduce cost and increase efficiency
✅ Monitor with Amazon CloudWatch
✅ Secure queues with IAM policies

🌍 Real-World Example: Order Management System
In an e-commerce app:

A customer places an order.

The app sends an order message to an SQS queue.

A backend service processes the order from the queue.

Another service sends out notifications or invoices asynchronously.

Architecture of e-commerce using SQS queues

🧮 Pricing Overview
SQS is pay-as-you-go, charged by:

Number of requests (first 1M/month free)

Payload size

Data transfer (if applicable)

It’s cost-effective for both startups and enterprise-grade applications.

🧠 Conclusion
Amazon SQS plays a crucial role in decoupling services, buffering workloads, and increasing reliability of modern cloud applications. It’s a backbone service for developers building scalable, event-driven, and fault-tolerant systems on AWS.

Forem: Felix Jumason

Building a Secure Home Lab on a Raspberry Pi with Tailscale, Pi-hole, and Nextcloud

Who this is for and what you get

A light threat model (what you are actually protecting)

Hardware and OS choices

Architecture: how the pieces fit together

Install Docker Engine and Compose on the Pi

Step-by-step: from a fresh Pi to both stacks

Screenshots: Pi-hole and Nextcloud over Tailscale

Pi-hole admin dashboard

Nextcloud Files

Pi-hole: full Docker files

docker-compose.yml

.env (template; copy from this example)

Commands

Pi-hole: DNS filtering without exposing the whole LAN

What Pi-hole does

DNS, port 53, and systemd-resolved

Upstream DNS and privacy

Nextcloud: full Docker files

docker-compose.yml

.env (template; copy from this example)

Commands

Nextcloud: your files on hardware you control

Stack overview

First-time install and trusted domains

HTTPS without opening the router

Tailscale: tailnet, MagicDNS, and ACLs

Join the Pi to your tailnet

Access control lists (ACLs)

Operational security: updates, backups, and firewall

Updates

Backups

Host firewall

Common pitfalls (talk fodder)

Before you go live: checklist

Closing

References (official docs)

Building an AI-Powered Community Assistant with Google Cloud Platform,Vercel AI SDK, and Calendar API

The Problem That Started It All

Introducing CommunitySync: Powered by GCP

The Architecture: GCP at the Core

Google Cloud Platform Services Used

Tech Stack Highlights

Integrating Google Calendar API: The Deep Dive

Setting Up Google Cloud Platform

OAuth 2.0 Flow Implementation

Google Calendar API Tools

1. List Events (listEvents)

2. Create Event (createEvent)

3. Update Event (updateEvent)

4. Delete Event (deleteEvent)

5. Check Availability (checkAvailability)

Token Management with GCP

Google Gemini AI SDK Integration

Setting Up Google Gemini

Connecting Gemini to Calendar Tools

Tool Calling with Gemini

Key Features Powered by GCP

1. Natural Language Calendar Management

2. Real-Time Synchronization

3. Secure OAuth Integration

4. Proactive AI Assistance

Challenges and Solutions with GCP Integration

Challenge 1: OAuth Token Management

Challenge 2: Google Calendar API Rate Limits

Challenge 3: AI Tool Selection with Gemini

Challenge 4: Real-Time Calendar Synchronization

GCP Best Practices Implemented

1. Secure Credential Management

2. Efficient API Usage

3. Error Handling

4. Token Refresh Strategy

What Makes This GCP Integration Special

1. Seamless Google Services Integration

2. Production-Ready OAuth Implementation

3. Type-Safe API Integration

4. Scalable Architecture

Lessons Learned from GCP Integration

1. Google Calendar API is Powerful but Complex

`docker-compose.yml`

`.env` (template; copy from this example)

`docker-compose.yml`

`.env` (template; copy from this example)

1. List Events (`listEvents`)

2. Create Event (`createEvent`)

3. Update Event (`updateEvent`)

4. Delete Event (`deleteEvent`)

5. Check Availability (`checkAvailability`)