DEV Community: Smyekh David-West

How to Actually Use AI to Build Production Software, End to End

Smyekh David-West — Sat, 18 Apr 2026 08:54:56 +0000

The stack, the tools, and the step-by-step workflow nobody hands you at the start.

The Blueprint

Before you build, here's the full plan. You may bookmark this and come back to whatever stage you're at.

The Foundation

Before You Write a Line of Code: Use the CLI, Not Just the Browser
First, a Word on Vibecoding vs. Knowing What You're Doing

The Stack

1. Database and Cloud Infrastructure: Oracle Cloud (OCI)
2. Hosting and DNS: Cloudflare
3. Backend: FastAPI, Python That Actually Moves
4. Schema Management: Liquibase vs. ORMs
5. Version Control and CI/CD: GitLab
6. Frontend: Start Vanilla, Graduate When Ready
7. Mobile: Flutter and Fastlane

The Build

The Bigger Picture: Architecture Is the Job Now
Step-by-Step: From Idea to Production
Stack Summary

Tools laid out. Time to build.

There's never been a better time to build software. You can open Claude or Gemini, describe an idea, and watch functional code appear in seconds. But here's the thing nobody tells you in the hype reels: the code is only as good as the decisions behind it.

With so many tools flooding the market, including Lovable, Bolt, Cursor, and a dozen others, developers and especially newcomers are drowning in choice paralysis. The real question isn't whether AI can write your code. It can. The question is, what stack do you point it at, and how do you use the AI properly in the first place?

This matters more than most people realise. Mature, well-documented technologies are easier for AI models to work with because they've been trained on years of documentation, Stack Overflow threads, GitHub repos, and real-world usage. When you pick an obscure or newly released framework, you're not just fighting the learning curve yourself. The AI is fighting it too. And that means more hallucinations, more debugging, more time lost.

So here's a practical, opinionated guide on what to use when you're building something you actually intend to ship and how to use the AI properly while you do it.

Before You Write a Line of Code: Use the CLI, Not Just the Browser

Most people start with Claude or Gemini in a browser tab. That's fine for exploring ideas, generating boilerplate, or asking conceptual questions. But once you have an actual project, you're leaving significant capability on the table if you stay in the browser.

The real power comes from the Claude Code CLI and the Gemini CLI, command-line tools that let the AI agent read your actual codebase, understand the context of your project, and make changes across files with awareness of how everything fits together.

Here's why this matters: when you paste code into a browser chat, the AI only sees what you paste. When you use the CLI inside your project, the agent can navigate your file structure, read your existing modules, understand your schema, check your config files, and make decisions based on the whole picture, not just a fragment.

A note on terminals: VS Code has a built-in terminal, and it's useful for quick things like creating folders, or running a one-off command. But for your actual AI CLI sessions, download and use Warp. Warp is a modern terminal with a genuinely better experience than the default options on Windows or Mac. It has AI features built in, a clean interface, and it handles long-running CLI sessions much more comfortably than the cramped terminal panel inside VS Code. The habit to build is using VS Code for writing and editing code and using Warp for running your Claude Code or Gemini CLI sessions. They complement each other well.

Getting started with Claude Code:

Make sure you have Node.js installed (version 18 or higher). You can check by running node -v in your terminal.
Install Claude Code globally: npm install -g @anthropic-ai/claude-code
Authenticate with your Anthropic account: claude login
Open Warp, navigate into your project folder: cd your-project-name
Start a session: claude

Getting started with Gemini CLI:

Make sure you have Node.js installed.
Install it: npm install -g @google/gemini-cli
Authenticate: gemini auth
Open Warp and navigate into your project: cd your-project-name
Start a session: gemini

Once you're inside a CLI session in Warp with your project loaded, you can ask the agent things like

"What does the authentication flow look like in this codebase?"

"Add input validation to the user registration endpoint, consistent with the patterns already in this project."

That level of context-awareness is the difference between AI as a code generator and AI as an actual collaborator.

Think of the browser as your brainstorming and planning phase. Warp with the CLI is where you build.

Before you push anything to GitLab, add one more tool to your Warp workflow: CodeRabbit. CodeRabbit is an AI code review tool, and the habit worth building is running it locally against your uncommitted changes before they ever leave your machine.

Install the coderabbit CLI and run:

coderabbit review --plain --type uncommitted

What this does is review everything you've changed but not yet committed, the same way a senior engineer would if they were looking over your shoulder before you pushed. It flags logic issues, security concerns, inconsistent patterns, missing error handling, and things the AI that wrote the code may not have caught because it was focused on making the feature work rather than making it defensible. Running it before you commit means you're catching problems at the cheapest possible moment, before they're in the pipeline, before they're in a merge request, and before they've touched production.

The --plain flag keeps the output readable in the terminal rather than formatted for a browser. In Warp, the output renders cleanly and you can scroll through the review the same way you'd read a colleague's notes. If something CodeRabbit flags isn't clear, paste it into your Claude or Gemini CLI session and ask for an explanation or a fix.

The workflow in Warp then becomes: write code in VS Code, switch to Warp, run coderabbit review --plain --type uncommitted, address what it surfaces, then commit and push. That sequence gives you two sets of AI eyes on every change before it hits the pipeline: the model that wrote the code and the model reviewing it. They catch different things.

First, a Word on Vibecoding vs. Knowing What You're Doing

If you're a pure vibecoder, someone who delegates every architectural decision to the AI, this guide is especially for you. AI will make choices for you, and sometimes those choices are fine. But often, they're fine for a prototype. Not for production.

I built a smart plant sitter for a hackathon last year using Flet for the frontend. Got it working. Hacked my way through the bugs and was proud of it. But it was limited and not particularly polished by my standards.

Smyekh David-West

Nov 13 '25

I Built a Voice-Controlled Plant Sitter in Python with Goose & Gemini CLI

#ai #python #opensource #tutorial

Comments

8 min read

Later, I tried to use Flet for a separate production project entirely, and it had so many issues I couldn't hack through them. No amount of debugging was going to get me where I needed to be. The issues weren't bugs in my code; they were limitations in the technology itself. Some frameworks and libraries simply aren't mature enough to live, exist, and thrive in production. I moved to Next.js, and I typically fall back on vanilla JS, HTML, and CSS because basics are important and I'm a proponent of Gall's Law.

Gall's Law, for those unfamiliar, states that all complex working systems evolved from simpler working systems. In other words, get the simple version working first, then build complexity on top of it. A framework that skips that foundation tends to crack under real-world pressure.

The lesson here is that pet projects and production apps are different species. Production demands polish, reliability, and critical decisions made upfront. An idea is no longer enough. Claude and Gemini can generate a hundred groundbreaking ideas before breakfast. What sets you apart is architecture, the decisions about how things fit together, why, and in what order.

You don't need to know everything. Experienced engineers still Google things constantly. But you do need to know enough to steer. That's what this guide is for.

1. Database and Cloud Infrastructure: Oracle Cloud (OCI), the Slept-On Giant

Let's start with the one that surprises people: Oracle Cloud Infrastructure, or OCI.

Most developers reaching for a cloud platform default to AWS, and some go with Google Cloud (GCP) or Azure. These are solid choices, but they come with significant complexity and cost, especially early on. Here's how they compare:

Category	Oracle Cloud (OCI)	AWS	GCP	Azure
Free Tier	Very generous (Always Free includes Autonomous DB, compute, storage)	Limited, expires after 12 months	Limited, some always-free	Limited, some always-free
Database maturity	Oracle DB has been in production since 1979	RDS wraps third-party databases	Cloud SQL/AlloyDB are solid but younger	Azure SQL is solid, Microsoft-backed
Learning curve	Moderate	Steep	Moderate	Steep
AI familiarity	Good	Excellent, most AI training skews AWS	Good	Good
Cost at scale	Competitive, often cheaper	Expensive if not managed	Competitive	Competitive

Pro Tip: In AWS, if your app goes viral and you serve 10 TB of data, you could be looking at a surprise bill of roughly $900. In OCI, that same bill is $0. Architecture is as much about the ledger as it is about the code.

Oracle's database has a legacy that AWS, GCP, and Azure simply can't match on the same terms. It's been battle-tested in some of the most demanding enterprise environments on the planet for over four decades. The Autonomous Database offering on OCI handles a lot of the operational burden for you, including patching, backups, and performance tuning, which is exactly what you want when you're a small team or solo developer trying to ship.

One concrete number worth knowing: OCI gives you the first 10 TB of outbound data transfer free every month. AWS starts charging after 100 GB. That is a 100x difference in your egress allowance, and for a startup serving real users, that gap shows up very quickly in your monthly bill.

One thing worth addressing directly: you may have seen YouTube videos comparing API performance benchmarks with flashy graphics of requests per second across different database and backend combinations. Those comparisons are often testing systems at a scale you won't touch for a long time, and they rarely reflect the architecture you'd actually be building. Paired with FastAPI on the backend, Oracle's database handles performance very comfortably for the vast majority of real-world production applications. You don't need to let those benchmarks drive your early decisions.

The OCI interface is surprisingly clean. If you get stuck, screenshot the console and paste it into Claude or Gemini to walk you through it step by step. It works.

One more thing worth saying upfront: the right way to set up OCI is not to click through the console and configure things manually. That approach works for a first look, but it doesn't scale, it doesn't reproduce cleanly across environments, and it leaves your security configuration undocumented and easy to get wrong. The better approach is to provision everything with Terraform from the start.

Terraform is an infrastructure-as-code tool that lets you define your entire cloud environment in configuration files, what compute to spin up, what networking rules to apply, which IAM policies to attach, which secrets to store in Vault, and what security lists to enforce. You write it once, apply it, and your infrastructure exists exactly as described. If you need a staging environment, you apply the same configuration with different variables. If something breaks, you have a complete record of what was provisioned and why.

Starting with Terraform on OCI means your security lists, IAM policies, and Vault secrets are codified alongside your application code, version-controlled in GitLab, and reviewable. That's a significantly more defensible position than manually clicking through the OCI console and hoping you remember what you configured six months later. The AI can write your Terraform configuration for you. Give it your architecture and ask it to scaffold the OCI provider setup, and you'll have a working starting point within minutes.

2. Hosting and DNS: Cloudflare, Far More Than a Domain Registrar

A lot of people's first instinct for domain registration and hosting is GoDaddy. It's heavily marketed and familiar. But once you go with Cloudflare, it's genuinely hard to go back.

Category	Cloudflare	GoDaddy
Primary strength	CDN, DDoS protection, edge hosting, DNS	Domain registration, basic hosting
Performance	Global CDN across 330+ cities worldwide	Standard hosting from a single region
Security	Built-in DDoS protection, WAF, SSL	Paid add-ons for most security features
Developer tools	Workers, Pages, R2, KV, D1, Wrangler CLI	Limited developer-facing tooling
Free tier	Generous, Pages, Workers, and CDN free to start	Minimal
AI familiarity	Excellent	Basic

When Cloudflare says "edge," it means your site is served from whichever of their 330+ city locations is closest to the person loading it. When GoDaddy hosts your site, it's served from one place. If that one data centre is in Dallas and your user is in Lagos, they're waiting for the full round trip. With Cloudflare, a user in Lagos is likely hitting a nearby node. That's not a small difference in practice.

Cloudflare Pages lets you deploy static frontends and full-stack apps directly from a GitHub or GitLab repo. Cloudflare Workers lets you run serverless backend logic at the edge, meaning it executes close to your user's location, reducing latency significantly. Cloudflare R2 is object storage without egress fees, which is a major and often invisible cost with AWS S3.

A word on Wrangler: Cloudflare's command-line tool is called Wrangler, and it's how you develop, test, and deploy Cloudflare Workers and Pages locally before pushing them live. Instead of deploying blind, you run wrangler dev to simulate the edge environment on your own machine. Claude and Gemini both know Wrangler's syntax well, so you can ask the AI to write or debug your wrangler.toml configuration, generate Worker scripts, or set up bindings to R2 storage and KV namespaces. Run Wrangler from Warp for a cleaner experience, the same way you'd run your AI CLI sessions.

For any production project, you want your site behind Cloudflare regardless. The DDoS protection alone is worth it, and the free SSL certificates mean you're not leaving security to chance.

GoDaddy is fine for buying a domain. That's about where its utility ends for serious development.

3. Backend: FastAPI, Python That Actually Moves

Backend choice is where a lot of decisions get religious. Let's cut through it.

FastAPI is a Python web framework built specifically for building APIs quickly and cleanly. It comes with automatic request validation, data serialisation, and interactive API documentation generated from your code, all out of the box.

Here's how it compares to the common alternatives:

Category	FastAPI	Node.js / Express	.NET (C#)	Spring Boot (Java)	Laravel (PHP)	Ruby on Rails
Language	Python	JavaScript	C#	Java	PHP	Ruby
Speed	Very fast (async-first)	Fast	Very fast	Fast	Moderate	Moderate
Learning curve	Low-moderate	Low-moderate	Steep	Steep	Moderate	Moderate
Type safety	Built-in via Pydantic	Optional via TypeScript	Built-in	Built-in	Partial	No
Auto API docs	Yes (Swagger + ReDoc)	No	Partial (Swagger add-on)	Partial (Swagger add-on)	No	No
AI familiarity	Excellent	Excellent	Good	Good	Good	Moderate
Verbosity	Low	Low	High	Very high	Moderate	Low
Best for	APIs, microservices, AI-adjacent services	Full-stack JS apps, real-time	Enterprise systems, Windows ecosystems	Large enterprise backends	Content-heavy web apps, rapid prototyping	Full-stack web apps, startups

A few notes on the alternatives worth calling out specifically:

.NET (C#) is a serious, high-performance framework backed by Microsoft. It's genuinely excellent for enterprise environments, especially where the rest of the organisation is already running Windows infrastructure. But it carries real weight. The ecosystem is verbose, the setup is heavier, and if you're building as a solo developer or small team, you'll spend more time on configuration than on your actual product. The AI can write C# competently, but the debugging surface is larger.

Spring Boot (Java) is one of the most widely deployed backend frameworks in the world, particularly in large enterprises and financial institutions. If you've ever applied for a job and seen "5 years Spring Boot experience required," this is why. It is genuinely battle-hardened. But it is also genuinely complex. Annotations, dependency injection, and the sheer volume of configuration it expects from you make it a steep climb for anyone not already comfortable in the Java ecosystem. For a solo developer building with AI assistance, the verbosity alone makes debugging slower.

Node.js with Express is a natural choice if your frontend is already in JavaScript and you want to stay in one language end-to-end. The AI handles it well and the ecosystem is enormous. The trade-off is that JavaScript's loose typing means errors that Python would catch at definition time often only surface at runtime. TypeScript helps, but it adds a build step and its own complexity. For teams already living in JavaScript, Express or its more opinionated cousin Fastify makes sense. If you're choosing a language from scratch, Python's readability and FastAPI's structure give you a cleaner starting point.

Laravel (PHP) is worth more respect than it typically gets in developer discourse. Modern PHP is not the PHP of 2008. Laravel ships with a clean ORM, authentication scaffolding, a task queue, and good documentation. It has a large community and deploys easily to almost any shared hosting environment, which matters when you're early and cost-conscious. The honest limitation is that the AI's training data for Laravel is thinner than for FastAPI or Express, which means you'll hit more friction when the generated code needs debugging. It remains a solid choice if you already know PHP.

Ruby on Rails pioneered a lot of what we now consider standard in web frameworks: convention over configuration, built-in ORM, database migrations as code, and scaffolding. It's still used in production by serious companies. The challenge today is momentum. The Rails community has shrunk relative to its peak, which means fewer recent training examples for the AI and a smaller pool of developers to hire from if your project grows. For solo projects and quick prototypes it remains genuinely pleasant to use.

FastAPI wins for this stack for a specific combination of reasons: Python's readability makes it easier to evaluate AI-generated code rather than just accepting it, the async-first design handles real-world I/O efficiently, the automatic documentation means your API is self-describing from day one, and the AI models are exceptionally well-trained on FastAPI patterns. When something goes wrong, the error messages are clear and the debugging path is short. That combination matters more than benchmark scores when you're shipping something real.

Go (Golang) deserves an honourable mention. It is genuinely fast, its concurrency model is elegant once you understand it, and production Go services tend to be lean and reliable. But you have to learn it first. Go's error handling, interface system, and approach to concurrency are different enough from most languages that you can't just point the AI at a problem and trust the output without understanding it. Once you have the foundation, it's a strong choice for high-throughput services. Without it, you're flying blind when something breaks unexpectedly.

The core point stands throughout: mature frameworks are easier for AI to work with because the models have been trained on years of real-world usage. FastAPI paired with Oracle DB handles production traffic comfortably for the kind of applications most developers are actually building. The YouTube benchmark videos are testing someone else's scale, not yours.

4. Schema Management: Liquibase vs. ORMs, and Why the Distinction Matters

This one trips people up, so let's define the terms first.

What is an ORM?

ORM stands for Object-Relational Mapper. It's a layer of code that lets you interact with your database using the programming language you're already writing in, rather than writing raw SQL. SQL, or Structured Query Language, is the language databases speak natively. Instead of writing SELECT * FROM users WHERE id = 1 directly in SQL, an ORM lets you write something like User.query.get(1) in Python, and it translates that into SQL behind the scenes.

Popular ORMs include SQLAlchemy (Python), Prisma (Node.js), Hibernate (Java), and Django's built-in ORM. They feel natural to start with, especially when AI is generating the code, because they keep everything in one language. The problem is that they abstract away too much of the database. In production, you'll eventually hit a situation where the ORM's migration logic conflicts with your actual schema, or where you need precise control over how a change is applied across environments like development, staging, and production.

That's where Liquibase earns its place.

Category	Liquibase	ORM Migrations (SQLAlchemy, Prisma, etc.)
Control	Full control over every schema change	High-level abstraction, less manual control
Database-agnostic	Yes, works across Oracle, Postgres, MySQL, etc.	Often framework/language-specific
Rollback support	Built-in, explicit rollback scripts	Varies, often manual and error-prone
Audit trail	Yes, changelog tracks every change ever made	Partial
Learning curve	Moderate (free courses and certification available)	Low initially, painful at scale
AI familiarity	Good, Claude and Gemini understand changesets and changelogs well	Excellent

Liquibase uses changelogs and changesets, a versioned history of every change ever made to your database schema. You can roll forward, roll back, and audit exactly what changed, when, and why. In a production environment, this is invaluable.

The courses are free on Liquibase's website and you can get certified, which is a genuine bonus.

It also means you can steer the AI confidently when it generates migration scripts, because Claude and Gemini both handle Liquibase XML, YAML, and SQL changelogs reliably.

Oracle DB vs. PostgreSQL vs. MongoDB:

Category	Oracle DB	PostgreSQL	MongoDB
Type	Relational (SQL)	Relational (SQL)	Document (NoSQL)
Maturity	45+ years	30+ years	~15 years
Best for	Enterprise, complex transactions	General purpose, advanced queries	Flexible schema, rapid prototyping
ACID compliance	Full	Full	Partial
Cost	Free on OCI always-free tier	Free (open source)	Free tier, paid tiers on Atlas
AI familiarity	Good	Excellent	Excellent

A quick explanation on ACID: ACID stands for Atomic, Consistent, Isolated, and Durable. It's the set of guarantees a database makes about your transactions. In plain terms, a transaction either fully completes or it doesn't happen at all.

Here's why this matters in practice: imagine you're transferring money from a Savings table to a Checking table. You deduct from Savings, then add to Checking. If the power cuts out between those two steps, what happens to the money? With a fully ACID-compliant database, it doesn't vanish. The whole transaction either lands or it rolls back. It's either in Savings or in Checking. There's no in-between state where it's nowhere. No vibes allowed in the ledger. For anything involving money, user accounts, orders, or sensitive records, this guarantee is non-negotiable.

PostgreSQL is the community favourite for relational databases and genuinely excellent. But if you're already on Oracle Cloud, it's worth knowing that Oracle 23ai introduces native AI Vector Search. This means you don't need a separate vector database like Pinecone to build AI-powered search or recommendation features. You can keep your relational data and your AI embeddings in the same database. For anyone building AI-assisted features into their product, that's a meaningful simplification to your stack.

MongoDB's schema-less nature is appealing for prototypes because you don't have to define your structure upfront. But in production, that same flexibility becomes a liability when your data is inconsistent and your queries are slow. For any serious transactional application, go relational.

5. Version Control and CI/CD: GitLab Is Doing More Than You Think

Most people reach for GitHub by default, and it's a solid choice. But GitLab, especially if you're building a serious project, deserves a closer look, primarily because of how deeply integrated its CI/CD tooling is.

CI/CD stands for Continuous Integration and Continuous Deployment. In plain terms: every time you push code, a pipeline automatically runs, testing it, building it, and deploying it, so you're not doing those steps manually every single time. Once it's set up, it works in the background and you just make edits.

GitLab manages all of this through a single file in your repository called .gitlab-ci.yml. This file defines your pipeline stages, what runs, when, and in what order. And here's where AI becomes genuinely useful: Claude and Gemini can write these files for you.

Open Warp, navigate into your project, start a CLI session, and ask: "Write a GitLab CI/CD pipeline for this FastAPI project that runs tests, builds a Docker image, and deploys to OCI". You'll get a working draft. You can also paste in a failing pipeline log and ask the AI to diagnose it. The full version with Docker image building and registry pushes is covered in Step 4 of the walkthrough.

A basic .gitlab-ci.yml for a FastAPI project might look like this:

stages:
  - test
  - build
  - deploy

test:
  stage: test
  image: python:3.11
  script:
    - pip install -r requirements.txt
    - pytest

build:
  stage: build
  script:
    - docker build -t my-app .

deploy:
  stage: deploy
  script:
    - ./deploy.sh
  only:
    - main

Beyond the local review habit, CodeRabbit integrates directly with GitLab and can be configured to automatically review every merge request your team opens. Once connected, it posts a structured review as a comment on the MR, covering the same ground as the local review but scoped to the diff between your branch and main. For solo developers it's a useful second pass. For small teams it functions as an always-available reviewer who has read the entire codebase and never gets tired.

The combination worth aiming for is: local coderabbit review --plain --type uncommitted before you commit, GitLab MR review automatically when you push a branch, and the pipeline running tests and deployment after the review. By the time code reaches your production branch it has been looked at by the model that wrote it, the model that reviewed it locally, CodeRabbit on the MR, and your test suite. That is a meaningfully more robust process than most small teams run, and none of it requires a dedicated QA engineer.

The key habit to build: when a pipeline fails, copy the logs from GitLab and paste them directly as a prompt into Claude or Gemini. Don't try to debug from memory. The AI will read the exact error and tell you what went wrong. This alone saves hours.

GitLab also has a clean interface, project management tooling, and a container registry built in, meaning you're not cobbling together five different services to manage your project.

6. Frontend: Start Vanilla, Graduate When Ready

Here's my standing recommendation: vanilla HTML, CSS, and JavaScript first.

Not because frameworks are bad. React, Next.js, Vue, these are all excellent. But the fundamentals matter. Gall's Law applies here too. When you understand what a framework is abstracting, you become dramatically better at using it and debugging it.

For production, the progression looks like this:

Use Case	Recommendation
Static sites, simple pages	Vanilla HTML/CSS/JS
Content-heavy sites, SEO-critical	Next.js
Interactive dashboards	React
Full-stack with server-side rendering	Next.js
Rapid prototyping	Any, keep it simple

The advantage of vanilla is zero build tooling, zero dependency conflicts, and full transparency about what your code is doing. The advantage of Next.js is server-side rendering, file-based routing, and first-class deployment on Vercel or Cloudflare Pages.

When you use AI to build a Next.js app, you'll hit some debugging. That's fine. Push through it and you'll understand the framework better than if it had just worked the first time.

7. Mobile: Flutter and Fastlane, With Realistic Expectations

For mobile app development, Flutter deserves its spot on this list. It's Google's cross-platform framework using the Dart language, and it lets you build iOS and Android apps from a single codebase. Claude and Gemini can generate significant amounts of working Flutter code with clear prompts. The widget system is well-documented and AI familiarity with it is solid.

The honest truth: building the app is the easy part. Getting it through Apple's App Store review process and Google Play's requirements is its own discipline. There are real hoops, developer accounts, code signing certificates, privacy policies, age ratings, and binary review rounds.

This is where Fastlane earns its place. Fastlane is an open-source automation tool specifically built for mobile app deployment. It automates the painful parts: building your app, running tests, managing code signing, taking screenshots, and submitting to the App Store or Play Store. You define your deployment workflow in a Fastfile, and Fastlane executes it.

Claude and Gemini both understand Fastlane's configuration structure well. You can ask the AI to generate a Fastfile for your Flutter project that handles both iOS and Android submission, then iterate from there. Combined with a GitLab CI/CD pipeline, you can set up a workflow where a push to your main branch automatically triggers a Fastlane deployment to both stores. Your release process becomes automated and repeatable rather than a manual scramble every time.

The Bigger Picture: Architecture Is the Job Now

Here's what I keep coming back to: ideas are cheap now. Ask Claude or Gemini for startup ideas, feature ideas, marketing angles and you'll have a hundred in an hour. The bottleneck has shifted entirely to implementation and, more specifically, to architecture.

Architecture means knowing which database fits your data model, knowing how your frontend and backend will communicate, knowing where your bottlenecks will be before you hit them, knowing how to manage schema changes without breaking production, and knowing how your code gets from your laptop to a live server.

You don't need to know everything before you start. You need to know enough to make good decisions and recognise bad ones. The rest you learn as you go, and the AI helps fill the gaps when you have the baseline to evaluate what it's telling you.

Don't chase the $1M ARR, 24k-user story without asking yourself: if I wanted to build that, where would I actually start? Because the answer requires architecture. It requires picking a stack, understanding why, and knowing how to steer when things go sideways.

Step-by-Step: From Idea to Production

This is the part most guides skip. Here's how to actually start and finish.

Step 1: Open VSCode and Start in the Browser

Download and open Visual Studio Code from code.visualstudio.com. It's free and the most widely supported editor for AI-assisted development.

Before touching any terminal, start in the browser with Claude (claude.ai) or Gemini (gemini.google.com). Use this phase to describe your project, plan the architecture, generate your initial project structure and boilerplate, and decide on your folder layout before you write a single file.

If you've never done this before, just say so. Tell the AI:

"I want to build [your idea]. I'm new to this. What should my project structure look like, what commands do I need to run to set it up, and what should I do first?"

It will walk you through it step by step and tell you what to install if you're missing anything.

Step 2: Move to Warp for CLI Sessions

Download Warp from warp.dev and open it alongside VS Code. This is your AI CLI environment.

In Warp, navigate into your project folder:

cd your-project-name

Start a Claude Code or Gemini CLI session from here. From this point, the AI can see your entire codebase. Ask it context-aware questions like:

"What's the best way to add authentication to this project based on what's already here?"
"Review my current folder structure and suggest improvements."
"Write tests for the endpoints in users.py."

Keep VS Code open for editing and writing code, and use its built-in Source Control sidebar for staging changes and writing commit messages. Use Warp for AI CLI sessions, running builds, CodeRabbit reviews, and anything that benefits from a full-screen terminal. They work together; use each for what it's best at.

One Warp feature worth knowing about specifically is its tab panel. Warp lets you open multiple tabs in the same window and switch between them instantly, and once your project has a few moving parts this becomes genuinely useful. A practical setup is one tab per concern: one for your Claude or Gemini CLI session, one for running the Terraform workflow, one for your GitLab pipeline commands and log watching, one for CodeRabbit reviews, and one for general project commands like starting your FastAPI server locally or running tests. Everything lives in one window and you switch between contexts without losing your place in any of them.

This is a small thing that compounds over a full working session. The alternative is constantly interrupting your AI CLI session to run a different command, or juggling multiple terminal windows. The tab setup keeps each workflow isolated and visible.

Before you commit anything, make it a habit to run CodeRabbit in Warp first:

coderabbit review --plain --type uncommitted

Read what it surfaces, address the issues worth fixing, and then commit. This takes two minutes and consistently catches things that both you and the AI that generated the code missed. It is the easiest quality gate you can add to your workflow because it requires no configuration and runs entirely locally.

Step 3: Structure Your Backend as a Modular Monolith

When your AI starts generating backend code, guide it toward a modular monolith structure. This is an architecture pattern where your application lives in a single deployable unit, one backend service, but is organised internally into distinct modules, one per feature.

Each module contains three files.

schema.py defines the data structures, what the data looks like.
service.py contains the business logic, what the application does with the data.
controller.py handles the API endpoints, how the outside world interacts with the feature.

A project structure should follow this template:

app/
├── users/
│   ├── users_schema.py
│   ├── users_service.py
│   └── users_controller.py
├── products/
│   ├── products_schema.py
│   ├── products_service.py
│   └── products_controller.py
├── orders/
│   ├── orders_schema.py
│   ├── orders_service.py
│   └── orders_controller.py
└── main.py

You’ll notice I use explicit names like users_schema.py instead of just schema.py. While traditional architecture often favors generic names inside a folder, explicit naming is an "AI-First" strategy. When you are working with an AI agent across multiple files, generic names like schema.py can lead to "context drift" where the AI confuses the User schema with the Product schema. By being explicit, you ensure that every file carries its own identity, making it easier for you and the AI to single out exactly what needs to change without ambiguity.

This structure does several things for you. Features are easy to identify and isolate. Debugging is faster because you know exactly which file to look in for any given problem. AI collaboration is cleaner because you can point the agent at a specific module without it touching unrelated code. And when your project grows, it gives you a blueprint to extract a module into its own microservice if you ever need to.

Tell the AI explicitly: "When generating backend code for this project, use a modular monolith structure with schema, service, and controller files per feature."

Step 4: Containerise Everything with Docker and Docker Compose

Once your backend structure is in place, the next question is how it actually runs, both on your machine during development and on the OCI VM in production. The answer is Docker, and for orchestrating multiple services together, Docker Compose.

Docker packages your application and everything it needs to run into a container. A container is a self-contained, isolated environment that behaves the same way on your laptop, on a teammate's machine, and on a server in OCI's data centre. No more "it works on my machine." If it runs in the container, it runs everywhere the container runs.

Docker Compose takes this further by letting you define and run multiple containers together using a single YAML file called docker-compose.yml. This is where it becomes genuinely useful for a modular monolith: instead of running one giant process, each concern gets its own container on the same VM. Your FastAPI backend runs in one container. Your Next.js frontend runs in another. Liquibase runs its migrations in another. A reverse proxy like Caddy or Nginx sits in front of all of them and routes incoming traffic to the right place.

This is not Kubernetes. It does not require a cluster, a cloud-native team, or a certification to operate. It is one VM, several containers, one Compose file. And given the compute and storage OCI provides on its always-free tier and low-cost instances, a single VM handles this comfortably for most production workloads.

It is also the building block you need before Kubernetes ever makes sense. Every concept you learn here, images, containers, networking between services, health checks, environment variables, you carry directly into Kubernetes when the time comes. But that time is not now. Start here.

A docker-compose.yml for a typical project on this stack looks like this:

services:
  proxy:
    image: caddy:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
    depends_on:
      - backend
      - frontend
    healthcheck:
      test: ["CMD", "caddy", "version"]
      interval: 30s
      timeout: 10s
      retries: 3

  backend:
    image: your-app-backend
    build:
      context: ./backend
    expose:
      - "8000"
    env_file:
      - .env
    depends_on:
      - redis
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  frontend:
    image: your-app-frontend
    build:
      context: ./frontend
    expose:
      - "3000"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000"]
      interval: 30s
      timeout: 10s
      retries: 3

  worker:
    image: your-app-worker
    build:
      context: ./worker
    env_file:
      - .env
    depends_on:
      - redis

  liquibase:
    image: liquibase/liquibase
    volumes:
      - ./liquibase:/liquibase/changelog
    env_file:
      - .env
    command: >
      --changelog-file=changelog/db.changelog-root.yaml
      --url=${DB_URL}
      --username=${DB_USER}
      --password=${DB_PASSWORD}
      update

  redis:
    image: redis:alpine
    expose:
      - "6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  caddy_data:

A few things worth noting in this file:

Caddy handles HTTPS automatically. Point your domain at the VM, configure a Caddyfile with your domain name, and Caddy requests and renews TLS certificates from Let's Encrypt without any manual steps. Nginx works equally well and the AI knows both, but Caddy requires significantly less configuration to get HTTPS working correctly. Ask the AI to generate a Caddyfile that routes your domain to your backend and frontend containers and it will produce a working starting point.

The expose keyword makes a port available only between containers on the same internal network. The ports keyword maps a container port to the host machine. Your backend and frontend use expose because they should never be directly reachable from the internet. Only Caddy uses ports because it is the only thing that should be.

Liquibase runs as a container too. It connects to your Oracle database, applies any pending changesets, and exits. In production you run it as part of your deployment pipeline before the backend starts. The AI can generate both the Liquibase container configuration and the migration files based on your Pydantic schemas.

The .env file holds your database credentials, API keys, and anything else that should never be committed. These values are injected into the containers at runtime. On the OCI VM, they come from OCI Vault via your startup scripts or a secrets management integration. Locally, they live in a .env file that is listed in your .gitignore. Deciding what belongs in your pipeline's CI/CD variables versus what belongs in OCI Vault is worth a moment's thought, and the AI can help you make that call — more on this in the CI/CD step.

When you SSH into your VM and run docker ps, a healthy setup looks something like this:

CONTAINER ID   IMAGE                  COMMAND                  CREATED        STATUS                  PORTS                                                         NAMES
a1b2c3d4e5f6   your-app-backend       "uv run uvicorn app…"    2 days ago     Up 2 days (healthy)     8000/tcp                                                      app_backend
b2c3d4e5f6a7   your-app-frontend      "docker-entrypoint.s…"   2 days ago     Up 2 days (healthy)     3000/tcp                                                      app_frontend
c3d4e5f6a7b8   your-app-worker        "uv run arq app.wor…"    2 days ago     Up 2 days                                                                             app_worker
d4e5f6a7b8c9   caddy:alpine           "caddy run --config…"    2 days ago     Up 2 days (healthy)     0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp, 443/udp            caddy_proxy
e5f6a7b8c9d0   redis:alpine           "docker-entrypoint.s…"   5 weeks ago    Up 5 days (healthy)     6379/tcp                                                      app_redis

Every service running, every health check green, Caddy the only thing exposed to the internet. That is what a clean deployment looks like.

How this connects to your GitLab pipeline

Your .gitlab-ci.yml builds the Docker images, pushes them to GitLab's built-in container registry, and then triggers a deployment on the OCI VM. A deploy stage for this setup looks like this:

stages:
  - test
  - build
  - deploy

test:
  stage: test
  image: python:3.11
  script:
    - pip install -r backend/requirements.txt
    - pytest backend/

build:
  stage: build
  script:
    - docker build -t registry.gitlab.com/yourusername/your-project/backend:$CI_COMMIT_SHA ./backend
    - docker build -t registry.gitlab.com/yourusername/your-project/frontend:$CI_COMMIT_SHA ./frontend
    - docker push registry.gitlab.com/yourusername/your-project/backend:$CI_COMMIT_SHA
    - docker push registry.gitlab.com/yourusername/your-project/frontend:$CI_COMMIT_SHA
  only:
    - main

deploy:
  stage: deploy
  script:
    - ssh ubuntu@your-oci-vm "cd /app && docker compose pull && docker compose up -d"
  only:
    - main

The $CI_COMMIT_SHA tags each image with the exact commit that produced it. This means you always know which version of the code is running in each container, and rolling back is as simple as pulling an earlier tag and restarting. The deploy stage SSHes into the VM, pulls the newly built images, and restarts the relevant containers with zero downtime from the other running services.

When something goes wrong during a deployment, the logs tell you exactly which container failed and why. Copy them from GitLab and paste them as a prompt. The AI will diagnose whether it is a build error, a misconfigured environment variable, a failed health check, or a networking issue between containers, and tell you what to change.

Step 5: Write Your Schemas in Python, Manage the Database with Liquibase

Define your data models in schema.py using Pydantic, which FastAPI uses natively. These Python classes describe what your data looks like:

from pydantic import BaseModel

class UserCreate(BaseModel):
    name: str
    email: str
    password: str

class UserResponse(BaseModel):
    id: int
    name: str
    email: str

For the actual database schema, the tables and columns in Oracle, use Liquibase changesets. Ask the AI to generate them based on your Pydantic models: "Based on these Pydantic schemas, write Liquibase changesets in YAML format to create the corresponding database tables."

Your Liquibase changelog keeps a versioned record of every schema change. Every time you add a column, rename a table, or add an index, it goes through a new changeset. This gives you full rollback capability and a clean audit trail.

Step 6: Provision Oracle Cloud with Terraform

Create a free account at cloud.oracle.com. The Always Free tier gives you an Autonomous Database, compute instances, and object storage.

Before you touch the OCI console to configure anything meaningful, write your infrastructure as code. This is not the advanced step it might sound like. It is the right starting point, and the AI will help you get there.

Terraform works by reading .tf configuration files and applying them against your cloud provider. For OCI, you start by defining the provider and your credentials, then describe the resources you need. Ask Claude or Gemini in a Warp CLI session: "Write a Terraform configuration for an OCI project that provisions an Autonomous Database, a compute instance for my FastAPI backend, a VCN with security lists for HTTP, HTTPS, and SSH, IAM policies scoped to least privilege, and a Vault for storing secrets".

The AI will generate a set of files. The structure typically looks like this:

infra/
├── main.tf          # provider config and root module
├── variables.tf     # environment-specific values
├── outputs.tf       # values to export (e.g. DB connection string)
├── network.tf       # VCN, subnets, security lists
├── compute.tf       # your FastAPI server instance
├── database.tf      # Autonomous Database
├── iam.tf           # policies and dynamic groups
└── vault.tf         # OCI Vault and secrets

Note: Before Terraform can talk to OCI, you'll need a few values that only exist in the console: your tenancy OCID, user OCID, region, and a generated API key fingerprint. These go into your variables.tf or a local terraform.tfvars file and are never committed to GitLab. If you're not sure where to find them, ask the AI: "Walk me through finding my OCI tenancy OCID and setting up an API signing key for Terraform". It will give you the exact navigation path through the console, and you can screenshot anything confusing and paste it directly into the chat.

A few things worth understanding in each file before you apply:

Security lists are OCI's firewall rules. They define which ports are open to the internet and which are locked down. Your FastAPI backend should only accept traffic on the ports it needs, typically 443 for HTTPS and a restricted port for database connections. Your database should not be publicly accessible at all. The Terraform configuration makes these rules explicit and auditable.

IAM policies define what can access what within your OCI tenancy. The principle here is least privilege: your compute instance should only have the permissions it actually needs to do its job, nothing broader. When IAM is configured manually through the console it's easy to accidentally grant too much. When it's in a .tf file it's readable, reviewable, and version-controlled.

OCI Vault is where your secrets live: database passwords, API keys, third-party credentials. Your application reads them from Vault at runtime rather than having them hardcoded in environment files or committed to your repository. Ask the AI to generate both the Vault configuration in Terraform and the Python code in your FastAPI service that retrieves secrets from Vault on startup.

Once your files are ready, initialise and apply from Warp:

cd infra
terraform init
terraform plan
terraform apply

terraform plan shows you exactly what will be created before anything happens. Read it. If something looks wrong, ask the AI to explain what a specific resource block does before you apply. Once you're satisfied, apply provisions everything.

Tip: Newer versions of OCI Autonomous DB support TLS, or wallet-less, connections, which are significantly easier to configure with FastAPI than the older wallet zip file approach. Once your database is provisioned, ask the AI: "Help me enable TLS connections on my OCI Autonomous Database and configure FastAPI to connect without a wallet."

From this point forward, any infrastructure change goes through a .tf file, gets committed to GitLab, and gets applied via Terraform. You can add a Terraform stage to your GitLab CI/CD pipeline so infrastructure changes are applied automatically alongside code deployments, giving you a single pipeline that handles both application and infrastructure.

If apply throws errors, copy the output from Warp and paste it as a prompt. The AI will read the error, identify whether it's a credentials issue, a resource limit, a policy conflict, or a configuration mistake, and tell you exactly what to change.

Step 7: Push to GitLab and Set Up CI/CD

Create a GitLab account at gitlab.com and create a new project.

This is one place where you stay in VS Code rather than switching to Warp. VS Code has a built-in Source Control panel, the branch icon in the left sidebar, and it handles the parts of Git that are most error-prone to do manually: staging individual files, writing commit messages, and reviewing exactly what's changed before it goes anywhere. Click the files you want to stage, write your commit message in the text field, and commit directly from there without touching the terminal.

For the initial setup, you'll need the terminal once. Open VS Code's built-in terminal or use Warp for this part:

git init
git remote add origin https://gitlab.com/yourusername/your-project.git

After that, your day-to-day flow is: make changes in VS Code, run coderabbit review --plain --type uncommitted in Warp to review before committing, stage and commit through the VS Code Source Control sidebar, then push. You can push directly from the sidebar too using the sync button, or from Warp if you prefer the explicit git push. Either works, but keeping the staging and commit message writing in VS Code means you always have a visual diff in front of you when you're deciding what to include in a commit.

Now ask the AI to generate your .gitlab-ci.yml pipeline file. Give it context: "I have a FastAPI backend deployed on OCI and a Next.js frontend on Cloudflare Pages. Write a GitLab CI/CD pipeline that runs my tests on every push and deploys to production when I push to main."

Once this is in place, your deployment process is automated. You make an edit, push it, and the pipeline handles the rest.

What goes in CI/CD variables vs. OCI Vault

GitLab CI/CD has its own secrets store: the variables you set under Settings > CI/CD > Variables in your project. These are injected into the pipeline environment at runtime and are the right place for anything the pipeline itself needs to do its job: your OCI registry credentials so the build stage can push images, your SSH private key so the deploy stage can connect to the VM, and any tokens needed to authenticate with external services during the build.

OCI Vault is for secrets your running application needs after it is deployed: database passwords, third-party API keys, encryption keys, and anything else your FastAPI backend reads at startup or during request handling. These never touch the pipeline directly.

The distinction is about who needs the secret and when. If the pipeline needs it to build or deploy, it goes in GitLab CI/CD variables. If the running container needs it to serve requests, it goes in OCI Vault.

In practice the line is usually clear, but edge cases come up. A good prompt for the AI is: "Here is a list of the secrets in my application. For each one, tell me whether it belongs in GitLab CI/CD variables or OCI Vault, and why." Give it your actual list and it will reason through each one, flag anything that looks like it might be in the wrong place, and explain the security rationale behind each decision. It is a quick sanity check that saves you from accidentally exposing something that should be locked away, or over-engineering the Vault integration for something that only the pipeline ever touches.

Note: GitLab CI/CD variables marked as "masked" are redacted from pipeline logs. Variables marked as "protected" are only available on protected branches. Use both for anything sensitive. The AI can generate the exact SSH key setup and OCI authentication configuration for your deploy stage if you ask it to.

When a pipeline fails: open the failed job in GitLab, copy the log output, and paste it directly into Claude or Gemini as a prompt. Say: "This is my GitLab CI/CD pipeline log. It failed. What went wrong and how do I fix it?" Nine times out of ten, you'll have your answer in under a minute.

That's the full loop. From idea to codebase to deployed infrastructure, with AI working alongside you at every stage and a pipeline handling everything after that.

A final word: logs are your best friend.

When something breaks, and something always does, the logs tell you exactly where. Not approximately. Not probably. Exactly. This is one of the underrated benefits of building with a stack that has clear separation of concerns. When your backend, frontend, worker, proxy, and database each run in their own container with their own logs, a failure doesn't hide. It surfaces in one place, in one service, with a traceable reason. Copy those logs, paste them into Claude or Gemini, and you'll have a diagnosis in under a minute. The more deliberately you've structured your project, the more your logs reward you when things go sideways. Treat them as the source of truth, not an afterthought.

Stack Summary

Layer	Technology	Why
Terminal	Warp	Better AI CLI experience outside VS Code
Cloud / DB	Oracle Cloud (OCI) + Autonomous Database	Mature, 10TB free egress, enterprise-grade
Hosting / CDN	Cloudflare Pages + Workers + Wrangler	330+ city edge network, DDoS protection, no egress fees
Backend	FastAPI (Python)	Fast, readable, excellent AI familiarity
Schema management	Liquibase	Versioned, rollback-capable, production-safe
Containerisation	Docker + Docker Compose	Isolated services, consistent environments, Kubernetes on-ramp
Frontend	Vanilla JS → React / Next.js	Start simple, graduate when ready
Mobile	Flutter + Fastlane	Cross-platform build, automated deployment
Version control / CI/CD	GitLab + .gitlab-ci.yml	Integrated pipelines, paste logs to debug
Infrastructure	Terraform (from day one)	Reproducible, codified infrastructure
Code review	CodeRabbit	AI review before commit and on every MR

The tools are remarkable. Use them. But use them on a foundation solid enough to build on, and use them properly, with a codebase the AI can actually see.

Cover photo by Jo Lin on Unsplash

Axios Hijack Post-Mortem: How to Audit, Pin, and Automate a Defense

Smyekh David-West — Thu, 02 Apr 2026 01:09:47 +0000

On March 31, 2026, the axios npm package was compromised via a hijacked maintainer account. Two versions, 1.14.1 and 0.30.4, were weaponised with a malicious phantom dependency called plain-crypto-js. It functions as a Remote Access Trojan (RAT) that executes during the postinstall phase and silently exfiltrates environment variables: AWS keys, GitHub tokens, database credentials, and anything present in your .env at install time.

The attack window was approximately 3 hours (00:21 to 03:29 UTC) before the packages were unpublished. A single CI run during that window is sufficient exposure.
This post documents the forensic audit and remediation steps performed on a Next.js production stack immediately after the incident.

Why This Happened: The SemVer Caret Problem

Most projects define axios like this:

"axios": "^1.7.9"

The caret (^) permits any compatible minor or patch release. It means npm install can silently resolve to a newly published 1.14.1 if it satisfies the range. No prompt, no warning, no diff you would notice without inspecting the lockfile.

This is the core tension in SemVer: convenience versus determinism.

The Fix: Pin to the Golden Version

"axios": "1.14.0"

No caret. No tilde. Exact version.

Why 1.14.0 specifically? It is the last clean release before the March 31 hijack. It also includes the patch for CVE-2025-27152, an SSRF vulnerability fixed in 1.8.2, so you are not trading one vulnerability for another.

Versions to avoid:

1.14.1 — compromised (RAT injected)
0.30.4 — compromised (RAT injected)

Use --save-exact to prevent npm from re-adding the caret on install:

npm install axios@1.14.0 --save-exact

What If Axios Is a Transitive Dependency?

If axios is not a direct dependency in your project but a dependency of another package, pinning it in package.json may not be sufficient. npm can still resolve a different version deeper in the tree.

Use the overrides field in package.json to force the exact version project-wide, regardless of what upstream packages request:

"overrides": {
  "axios": "1.14.0"
}

This applies to npm 8.3 and above. For yarn, the equivalent is resolutions. For pnpm, use overrides under the pnpm key in package.json.

Forensic Audit: Were You Hit?

Even if package.json looks correct, package-lock.json may have resolved the malicious metadata during the attack window if npm install ran between 00:21 and 03:29 UTC.

The following checks were performed on the production server via SSH.

1. Lockfile Entropy Check

Run both grep patterns. The first checks for the malicious dependency name and version in the axios context. The second checks for the raw version string regardless of JSON nesting depth, which is relevant in package-lock.json v2 and v3 formats:

# Check 1: Malicious dependency name and axios version context
grep -E "plain-crypto-js|axios.*(1\.14\.1|0\.30\.4)" package-lock.json

# Check 2: Raw version string, catches nested lockfile structures
grep -E "\"version\": \"(1\.14\.1|0\.30\.4)\"" package-lock.json

Critical gotcha: run this from the correct directory. A "file not found" error is not a clean result. It means grep never inspected anything. The correct workflow:

user@server:~$ grep -E "plain-crypto-js|axios.*(1\.14\.1|0\.30\.4)" package-lock.json
grep: package-lock.json: No such file or directory   # Wrong directory. Not a clean result.

user@server:~$ cd project
user@server:~/project$ grep -E "plain-crypto-js|axios.*(1\.14\.1|0\.30\.4)" package-lock.json
grep: package-lock.json: No such file or directory   # Still wrong. Keep navigating.

user@server:~/project$ cd frontend
user@server:~/project/frontend$ grep -E "plain-crypto-js|axios.*(1\.14\.1|0\.30\.4)" package-lock.json
# No output = clean

No output from the final command means no malicious indicators found in the lockfile.

2. Filesystem Dropper Verification

The RAT executes via a postinstall script registered by plain-crypto-js. If the directory exists in node_modules, the dropper has already run:

user@server:~/project/frontend$ ls node_modules/plain-crypto-js 2>/dev/null \
  && echo "CRITICAL: Malicious package found!" \
  || echo "Clean: No dropper found."
Clean: No dropper found.

If either check returns a positive result: rotate all secrets immediately. This includes credentials you might overlook under pressure:

Application secrets: database passwords, third-party API keys, cloud provider credentials
CI/CD pipeline secrets: NPM_TOKEN, VERCEL_TOKEN, AWS_ACCESS_KEY_ID, and any other tokens injected as environment variables during the build. These are present in the environment at npm install time and are a primary target of this class of attack.

Treat every credential present in the build environment during the compromised install as leaked. Review your cloud provider audit logs for anomalous API calls originating from the build environment before doing anything else.

Automating Prevention in CI/CD

Pinning resolves the immediate exposure. The following three controls prevent recurrence.

A. Lockfile Integrity Enforcement

Use npm ci instead of npm install in your build pipeline. It installs exactly what is recorded in package-lock.json and fails if the two files are out of sync. No silent resolution, no opportunistic upgrades.

For Docker-based builds, this belongs in the Dockerfile:

RUN npm ci

B. Dependency Scan as a Kill-Switch

Add a pre-build security stage that greps the lockfile for known-malicious strings. If an upstream package is hijacked again, deployment is blocked before a single container is built.

GitLab CI example (shell executor, Docker available on runner):

stages:
  - security
  - deploy

dependency_scan:
  stage: security
  tags:
    - oci-runner
    - production
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
  script:
    - echo "Scanning for malicious dependency versions..."
    - |
      if grep -E "(\"axios\".*\"(1\.14\.1|0\.30\.4)\"|plain-crypto-js)" \
        "$CI_PROJECT_DIR/frontend/package-lock.json"; then
          echo "SECURITY ALERT: Malicious dependency detected. Blocking deployment."
          exit 1
      fi
    - echo "Malicious version scan passed."
    - echo "Running npm audit..."
    - docker run --rm
        -v "$CI_PROJECT_DIR/frontend:/app"
        -w /app
        node:20-alpine
        npm audit --audit-level=high

Implementation notes:

Do not use -r in the grep. That flag recurses into directories and is incorrect when targeting a specific file.
Use $CI_PROJECT_DIR for absolute paths. Relative paths are fragile if any earlier step changes the working directory. This is the same "wrong directory" failure mode demonstrated in the manual audit above.
npm audit runs in a throwaway container. If the shell runner does not have Node installed directly, a temporary node:20-alpine container handles it without modifying the runner host.

GitHub Actions equivalent:

- name: Audit for Malicious Axios Versions
  run: |
    if grep -E "plain-crypto-js|axios.*(1\.14\.1|0\.30\.4)" package-lock.json; then
      echo "Security Alert: Malicious dependency detected!"
      exit 1
    fi

- name: npm audit
  run: npm audit --audit-level=high

C. npm audit with Failure Thresholds

npm audit --audit-level=high causes CI to fail on any vulnerability rated High or Critical. It covers a broader class of supply chain issues beyond this specific incident and adds minimal overhead to the pipeline.

npm audit --audit-level=high

One important caveat: for a zero-day or freshly published hijack, npm audit may not flag the package until a security advisory has been formally ingested into the npm advisory database. During the initial hours of an active attack, the manual grep stage in section B is the more reliable immediate control. The two approaches are complementary, not interchangeable.

D. Egress Restriction on Build Runners

As a systemic long-term control, restrict outbound network traffic from your build environment to a known allowlist of domains. A RAT cannot exfiltrate environment variables if the build server is blocked from making outbound requests to unknown IPs or domains.

Most cloud providers offer security groups or firewall rules at the instance level. For OCI, this is configured via the VCN's security list or network security groups. The build runner should be permitted to reach package registries, your container registry, and your deployment target and nothing else by default.

One layer deeper: blocking standard HTTP/S egress is not sufficient against advanced RATs. DNS exfiltration is a documented technique where data is encoded and tunnelled out via DNS queries, which most firewall rules pass freely. If your threat model warrants it, implement DNS filtering and logging on build runners either via a resolver that blocks non-allowlisted domains, or a logging layer that surfaces anomalous query volumes. This is the logical next control once HTTP/S egress is locked down.

Worth knowing: If supply chain risk is a recurring concern for your stack, look into Socket or Snyk. Both offer malicious package detection that goes beyond standard vulnerability scanning by analysing package behaviour rather than just matching against known CVEs. npm audit tells you about published advisories. These tools flag suspicious patterns before an advisory exists. Both have free tiers suitable for open source projects and solo developers; private commercial repositories require a paid plan.

Summary

Action	Priority
Pin axios to `1.14.0`(no caret)	Immediate
Add `overrides` in `package.json` if axios is a transitive dependency	Immediate
Grep lockfile for `plain-crypto-js` and bad versions, from the correct directory	Immediate
Check whether `node_modules/plain-crypto-js` exists	Immediate
Rotate all secrets if either check is positive	Immediate
Switch CI builds to `npm ci`	This sprint
Add dependency scan stage to pipeline	This sprint
Add `npm audit --audit-level=high` to CI	This sprint
Restrict build runner egress to known domains	Next sprint
Implement DNS filtering and logging on build runners	Next sprint

Supply chain attacks exploit the trust relationship between developers and the package registry. The plain-crypto-js incident demonstrates that a single compromised maintainer account is sufficient to poison any project that does not lock its dependencies with exact versions.

Pin your versions. Audit your lockfiles. If your build logs show npm install activity on March 31, rotate credentials first and investigate second.

Cover photo by Clint Patterson on Unsplash

Rebooting a Production VM on Oracle Cloud: A Reference Guide

Smyekh David-West — Mon, 30 Mar 2026 17:19:18 +0000

Commands, explanations, and real output — for engineers who want to understand what's actually happening, not just copy-paste their way through it.

☁️ Pre-Flight Checklist

Before we taxi down the runway, here’s your flight plan. Keep this handy to navigate your flight path. Welcome aboard the cloud! ☁️

🌥️ Takeoff

Prerequisites

⛅️ Cruising Altitude

Part 1 — Pre-Reboot Checklist
Part 2 — Running the Reboot
Part 3 — Post-Reboot Verification
Part 4 — Measuring Time to Recovery (TTR)

🌤️ Landing & Taxi

Quick Reference: All Commands
Troubleshooting Reference

Enjoy your flight! ☁️

There's a specific kind of anxiety that comes with running sudo reboot on a server with real users on it. You know the system should come back, but "should" feels a lot less reassuring at the moment your SSH session freezes. This guide removes the guesswork. It covers everything from reading your apt upgrade output intelligently, to verifying your stack is healthy after the reboot, to measuring your actual recovery time with real commands and real numbers so that the next time you need to do this, it's a procedure, not a gamble.

Prerequisites

This guide assumes:

Ubuntu 22.04 on an OCI Compute instance (ARM or x86)
Docker + Docker Compose managing your services
All long-running services configured with restart: always in your docker-compose.yml
SSH access to the instance

If restart: always isn't set on your services, your containers will not come back after a reboot. Check this first.

services:
  backend:
    image: your-backend-image
    restart: always  # ✅ restarts automatically after reboot or crash

  migrations:
    image: your-migrations-image
    # no restart policy  # ✅ correct — this should run once and exit

restart: always tells Docker to relaunch the container whenever it stops — whether from a crash or a full system reboot. The one exception to be deliberate about is one-shot containers like database migrations: they're designed to run once and exit cleanly, so no restart policy is the right call for those.

Part 1 — Pre-Reboot Checklist

Never reboot without completing this checklist. It takes under two minutes and prevents the most common post-reboot problems.

1.1 Verify no critical process is mid-flight

docker ps

What to look for:

STATUS	Meaning
`Up 2 days (healthy)`	Safe to reboot
`Up 3 minutes`	Something recently restarted — investigate
`Restarting (1)`	Container is crash-looping — fix before rebooting
`Up 2 hours (unhealthy)`	Health check is failing — fix before rebooting

If everything shows Up [days/weeks] (healthy), you are clear.

Why this matters: If a database migration container is mid-run, or a background job is processing a large task, a reboot will kill it mid-execution. You want to reboot during a quiet moment.

1.2 Validate your Compose configuration

cd ~/your-project
docker compose config

Expected output: Your full resolved docker-compose.yml printed to the terminal, with no errors.

Why this matters: docker compose config resolves all environment variables and validates YAML syntax. If there's a broken variable reference or a typo in your file, this command catches it now — not after the reboot when containers silently fail to start. A common mistake is editing a .env file or docker-compose.yml and not realising you've introduced a syntax error. This is your safety net.

1.3 Read your `apt upgrade` output

When you run sudo apt update && sudo apt upgrade -y before a reboot, the output tells you exactly what changed on your system. Don't skip past it.

Here's a real upgrade output and what each part means:

The following packages will be upgraded:
  containerd.io coreutils docker-ce docker-ce-cli
  docker-ce-rootless-extras docker-compose-plugin docker-model-plugin
  gitlab-runner gitlab-runner-helper-images libnftables1 nftables
  python3-pyasn1

How to read this list:

Package	What it is	Reboot needed?
`docker-ce`, `containerd.io`, `docker-ce-cli`	The Docker engine and its runtime	Recommended
`docker-compose-plugin`	The `docker compose` CLI plugin	No
`nftables`, `libnftables1`	Linux kernel firewall/networking	Yes
`coreutils`	Fundamental Linux utilities (`ls`, `cp`, etc.)	Recommended
`gitlab-runner`, `gitlab-runner-helper-images`	CI/CD runner agent	Service restarts during upgrade
`python3-pyasn1`	Python crypto library	No

The rule of thumb: If the upgrade touches anything in the kernel, networking stack, or container runtime — reboot. If it's only application-level packages — a reboot is optional but never harmful.

1.4 Understand the service restart messages

After apt upgrade, Ubuntu's needrestart tool prints which services were restarted automatically and which were deferred:

Restarting services...
 systemctl restart irqbalance.service ssh.service rsyslog.service ...

Service restarts being deferred:
 systemctl restart networkd-dispatcher.service
 systemctl restart systemd-logind.service

"Restarting services" — These were restarted immediately. Your SSH connection stayed alive because ssh.service restarts in-place without dropping existing sessions.

"Service restarts being deferred" — These require a full reboot to apply safely. systemd-logind manages user sessions; restarting it mid-session can cause issues, so Ubuntu defers it to the next clean boot.

No containers need to be restarted.

This line means Docker detected that running container images are still current — no container needed to be replaced. This is expected if you haven't rebuilt your application images.

1.5 Check available disk space

df -h /

Example output:

Filesystem      Size  Used Avail Use% Mounted on
/dev/sda1        48G   12G   36G  23% /

You want at least 20% free on your root partition. Docker image pulls and accumulated log files are the two most common causes of a full disk, which can prevent containers from starting after a reboot.

Tip: The apt upgrade process often reclaims space automatically by pruning unused Docker build cache layers. In a real upgrade run, this printed:

Total reclaimed space: 4.165GB

Part 2 — Running the Reboot

Once the checklist is complete:

sudo reboot

What happens next, step by step:

The OS sends SIGTERM to all running processes, giving them time to shut down cleanly.
Docker receives the signal and stops all containers gracefully.
The kernel shuts down and the VM restarts.
Your SSH session prints Connection to [ip] closed by remote host. and terminates. This is normal.

How long to wait: OCI ARM instances (Ampere A1) typically reboot in 45–90 seconds. Wait at least 60 seconds before trying to reconnect.

ssh -i ~/.ssh/id_rsa ubuntu@YOUR_IP

Part 3 — Post-Reboot Verification

Run these checks in order. Each one builds on the last.

3.1 Check the Docker daemon

sudo systemctl status docker

Expected output:

● docker.service - Docker Application Container Engine
     Loaded: loaded (/lib/systemd/system/docker.service; enabled)
     Active: active (running) since Mon 2026-03-30 15:55:51 UTC; 5min ago

Key things to check:

Active: active (running) — the daemon is running ✅
enabled — it is configured to auto-start on every future boot ✅

If the daemon isn't running:

sudo systemctl enable docker   # ensure it starts on future reboots
sudo systemctl start docker    # start it now

3.2 Check all containers are up

docker ps

Example output:

CONTAINER ID   IMAGE              COMMAND        CREATED      STATUS                  PORTS    NAMES
fc46f84c7bd5   app-backend        "uv run uvi…"  2 days ago   Up 5 minutes (healthy)  8000/tcp app_backend
a3e9a2eeb160   redis:alpine       "docker-ent…"  2 weeks ago  Up 5 minutes (healthy)  6379/tcp app_redis
f4afe2edb00c   caddy:alpine       "caddy run …"  4 weeks ago  Up 5 minutes (healthy)  80, 443  caddy_proxy

What to check:

Every service you expect should be present. If one is missing, it crashed on startup.
STATUS should be Up or Up (healthy). (health: starting) is fine for the first 30 seconds after boot.
The CREATED timestamp does not reset on reboot — it reflects when the container was first created with docker compose up. This is normal.

If a container is missing or in a restart loop:

docker compose logs [service_name] --tail=50

This shows the last 50 log lines for that specific service, which will usually tell you exactly why it failed.

3.3 Watch the live logs

cd ~/your-project
docker compose logs -f --tail=20

The -f flag follows the log stream in real time. --tail=20 shows the last 20 lines per service as a starting point.

What healthy output looks like:

app_gate    | 127.0.0.1 - - [30/Mar/2026:16:00:00 +0000] "GET / HTTP/1.1" 200 4140
app_backend | INFO: 127.0.0.1:58562 - "GET /health HTTP/1.1" 200 OK
caddy_proxy | {"level":"info","msg":"received request","uri":"/config/"}
app_redis   | * Ready to accept connections tcp

What a transient (non-critical) error looks like:

app_worker | redis.exceptions.ConnectionError: Error while reading
            from redis:6379 : (104, 'Connection reset by peer')
app_worker | 15:56:15: Starting worker for 1 functions: process_message
app_worker | 15:56:15: redis_version=8.6.1 mem_usage=1.38M clients_connected=1

This pattern — an error followed immediately by a successful connection message — is normal during cold starts. When all containers launch simultaneously, a dependent service (like a worker) may attempt its first connection before its dependency (like Redis) has finished initialising. The container retries and connects successfully on the next attempt. This is expected behavior.

What a critical error looks like:

app_backend | sqlalchemy.exc.OperationalError: connection refused
app_backend | [after 5 retries] giving up

A critical error is one that does not resolve on its own. If you see continuous errors without a recovery line following them, press Ctrl+C and investigate that service.

3.4 Check additional system services

If you run a CI/CD runner or similar agent alongside Docker:

sudo gitlab-runner status

Expected output:

gitlab-runner: Service is running

If it's not running:

sudo gitlab-runner start

Part 4 — Measuring Time to Recovery (TTR)

TTR is the total time from sudo reboot to the moment your application is serving healthy responses. Measuring it gives you accurate data for maintenance window planning and user communications.

4.1 Measure OS boot time

systemd-analyze

Example output:

Startup finished in 3.617s (kernel) + 19.608s (userspace) = 23.225s
graphical.target reached after 18.845s in userspace

Breaking this down:

Phase	Time	What's happening
Kernel	3.6s	The Linux kernel loads into memory and initialises hardware drivers
Userspace	19.6s	All systemd services start in parallel (networking, Docker, SSH, etc.)
Total	23.2s	OS is fully booted

4.2 Find the bottleneck in the boot sequence

systemd-analyze blame | head -20

This lists every service sorted by how long it took to start, slowest first:

12.186s docker.service
 4.821s cloud-init.service
 1.204s snapd.service
   38ms docker.socket

In this case, Docker itself accounted for 12 of the 23 total seconds. This is normal — Docker has to read its state from disk, re-attach networks, and prepare to launch containers.

Why this is useful: If your boot time is unexpectedly long, systemd-analyze blame tells you exactly which service is the bottleneck.

4.3 Find the exact moment containers started

docker inspect --format='{{.Name}}: {{.State.StartedAt}}' $(docker ps -q)

Example output:

/app_ftp_bridge:  2026-03-30T15:55:57.766Z
/app_worker:      2026-03-30T15:55:57.695Z
/app_backend:     2026-03-30T15:55:57.646Z
/app_gate:        2026-03-30T15:55:57.830Z
/app_admin:       2026-03-30T15:55:57.742Z
/app_redis:       2026-03-30T15:55:57.794Z
/caddy_proxy:     2026-03-30T15:55:57.615Z

Every container launched within the same second. This is because Docker starts all containers in parallel as soon as the daemon is ready. Note: this timestamp reflects when Docker launched the container process, not when the application inside it was ready to serve traffic. A container may take a further 5–30 seconds to pass its health check after this point.

4.4 Build your full TTR timeline

Combining the data from the above commands:

Event	Time (relative to reboot)
`sudo reboot` executed	T+0s
SSH connection closed	T+~5s
Kernel boot complete	T+~8s
Userspace boot complete (OS ready)	T+~28s
Docker daemon ready	T+~28s (12s of the userspace phase)
All containers launched	T+~28s
Redis accepting connections	T+~30s
Backend `/health` returning 200	T+~35s
All health checks passing	T+~55s
Total TTR	~55–60 seconds

4.5 Use TTR to plan user communications

With a measured TTR, you can set honest expectations.

Internal / engineering team:

"Maintenance reboot at [time]. Expected downtime: ~2 minutes."

The 2-minute internal window gives a buffer above the measured ~60 seconds for anything unexpected.

External users:

"Scheduled maintenance in progress. Services will be restored within 5 minutes."

The 5-minute external window is deliberately conservative. If a container fails its first health check and requires a full restart cycle (up to 5 retries × 5 seconds = 25 extra seconds), you're still within your stated window. Under-promise, over-deliver.

Quick Reference: All Commands

# --- PRE-REBOOT ---
docker ps                              # check container states
docker compose config                  # validate compose file syntax
df -h /                                # check available disk space

# --- REBOOT ---
sudo reboot                            # initiate the reboot

# --- POST-REBOOT ---
sudo systemctl status docker           # confirm daemon is running
docker ps                              # confirm containers are up
docker compose logs -f --tail=20       # watch live logs
sudo gitlab-runner status              # check runner (if applicable)

# --- TTR MEASUREMENT ---
systemd-analyze                        # total OS boot time
systemd-analyze blame | head -20       # per-service boot time breakdown
docker inspect --format='{{.Name}}: {{.State.StartedAt}}' $(docker ps -q)
                                       # exact container start timestamps

Troubleshooting Reference

Symptom	Likely cause	Fix
Container missing from `docker ps`	Crashed on startup	`docker compose logs [service] --tail=50`
Container stuck in `(health: starting)` after 2+ minutes	Health check command failing	`docker inspect [id]` → check `Health.Log`
Docker daemon not running	Not enabled in systemd	`sudo systemctl enable docker && sudo systemctl start docker`
SSH times out for more than 3 minutes	VM didn't boot cleanly	Check OCI console → instance serial console for kernel panic output
All containers up but app unreachable externally	Reverse proxy (Caddy/Nginx) issue	`docker compose logs caddy --tail=50`
Persistent container errors after cold start	Dependency started before its dependency was ready	Wait 60 seconds, then re-check — most resolve automatically

Cover photo by BoliviaInteligente on Unsplash

Why the Best Errors Are ORA Errors: A Love Letter to Loud Failures

Smyekh David-West — Mon, 29 Dec 2025 05:57:53 +0000

Picture this: you're deploying to production on a Friday afternoon. Your code runs smoothly in development, passes all your tests, and then quietly corrupts user data in prod. No error messages. No warnings. Just silent data corruption that takes weeks to discover and months to untangle.

Now picture the alternative: Oracle Database throws an ORA-00001 unique constraint violation the moment you try to insert duplicate data in development. The error is immediate and precise and tells you exactly which constraint you violated. You fix it in five minutes and move on with your life.

Which scenario would you prefer? If you chose the first one, we need to talk about why loud, explicit errors are actually your best friends as a developer.

The Oracle Philosophy: Fail Fast, Fail Clearly

Oracle Database has been around since 1979, and in that time it's developed a reputation for being strict, unforgiving, and sometimes downright pedantic. This isn't a bug; it's the entire point. Enterprise databases were built with a core principle: it's better to reject questionable operations loudly than to accept them silently and create data integrity problems down the line.

Consider the classic ORA-00904 error for invalid identifiers. When you write a query that references a column like uid, Oracle might throw this error and force you to use p_uid instead. At first glance, this seems annoying. Why can't the database just figure out what you meant? But here's what's actually happening: Oracle is protecting you from ambiguity. In a complex system with multiple schemas, packages, and procedures, a column reference that could mean two different things is a disaster waiting to happen. By forcing explicit qualification, Oracle ensures that six months from now, when someone else is reading your code (or when you've forgotten your own clever shortcuts), the intent is crystal clear.

This same protective instinct appears in Oracle's handling of bind variables. Consider the ORA-01745 error that occurs when you try to use :uid as a bind variable name. Oracle rejects this with "invalid host/bind variable name" and forces you to use something like :p_uid instead. On the surface, this feels unnecessarily restrictive. You might wonder why Oracle cares what you name your variables, especially since uid seems like a perfectly reasonable name for a user identifier. But here's what's actually happening: uid is a reserved keyword in Oracle SQL. By rejecting :uid as a bind variable name, Oracle protects you from creating queries where it's ambiguous whether you're referring to the reserved keyword or your bind variable. Six months from now, when you or another developer reads this query, there's no confusion about what :p_uid refers to. The naming convention (using a prefix like p_ for parameters) becomes self-documenting. What seems like pedantry is actually preventing ambiguity, protecting against potential SQL injection vulnerabilities, and ensuring the database can properly parse and cache your statements. Oracle doesn't just protect you from ambiguous column references; it also protects you from unsafe query construction practices that could compromise your entire application.

The ORA error codes themselves are a feature worth appreciating. When you see ORA-01400, you immediately know you've got a NOT NULL constraint violation. ORA-02291 means a foreign key constraint failed. These aren't vague "something went wrong" messages; they're diagnostic breadcrumbs that lead you directly to the problem. Every Oracle developer learns to recognize these codes, and that shared vocabulary makes debugging and collaboration significantly easier.

Modern Web Frameworks Are Learning the Same Lesson

FastAPI and Pydantic have brought this same philosophy to the Python web development world, and the results are striking. When you define a Pydantic schema for your API endpoint, you're not just documenting what the payload should look like. You're creating an enforcement mechanism that protects your application from malformed data.

Here's what makes this powerful: if a field isn't explicitly defined in your Pydantic model, it won't appear in the validated payload. No sneaky extra fields slipping through. No undocumented parameters causing weird side effects. If a client sends data your schema doesn't expect, Pydantic catches it immediately and returns a detailed validation error. The alternative approach, accepting any JSON that gets sent and hoping your application code handles it correctly, is how you end up with production bugs that are nearly impossible to trace.

The beauty of this strict validation is that it doesn't just catch mistakes; it documents intent. When another developer looks at your Pydantic models, they see exactly what your API expects. When they try to send the wrong data type, they get immediate feedback about what went wrong. This is the same principle Oracle has been practicing for decades: make the implicit explicit, and fail loudly when expectations aren't met.

The difference between Pydantic's approach and truly silent failures is worth examining. While Pydantic doesn't always throw loud errors for every possible issue (for instance, extra fields might be silently ignored depending on your configuration), it gives you the tools to make validation as strict as you need. You can configure it to forbid extra fields, require specific data types, and validate complex business rules. The point is that you're given the mechanism to fail explicitly rather than letting problems propagate silently through your system.

Liquibase and the Error Chain

Liquibase provides an interesting case study in how tools can amplify or suppress error signals from underlying systems. When you're using Liquibase with Oracle Database, you get the best of both worlds: Liquibase's change tracking and rollback capabilities combined with Oracle's precise error reporting.

If a migration fails because it violates a database constraint, Liquibase doesn't swallow that error or translate it into something generic. Instead, it passes through the ORA error code and message, giving you the full context you need to understand what went wrong. This transparency is crucial. It means you can leverage Oracle's diagnostic capabilities even when working through an abstraction layer.

This behavior contrasts sharply with tools that try to be too helpful by wrapping errors in their own error-handling logic. When an ORM or migration tool catches a database error and then throws a generic "migration failed" exception, you've lost valuable information. The original error code might tell you exactly which constraint was violated or which column had a type mismatch, but now you're left guessing. Liquibase gets this right by staying out of the way and letting the database speak for itself.

The Silent Killers: When Errors Don't Happen

The most dangerous errors aren't the loud ones that stop your code from running. They're the silent ones that let bad data or an invalid state slip into your system. These are the issues that compound over time, creating data integrity problems that are extraordinarily difficult to unwind.

Consider what happens when a system accepts invalid email addresses because there's no validation at the input layer. The data gets stored and processed, and eventually someone tries to send an email to "user@@example..com", and it fails. Now you have to trace back through potentially months of data to figure out where the invalid address came from, whether it represents a real user, and how to fix it without losing legitimate information. If you had simply validated the email format strictly at the input boundary and thrown an error for malformed addresses, this problem never would have existed.

Or imagine an application that allows NULL values in a database column that represents a critical business relationship, like the customer ID on an order. Without a NOT NULL constraint, someone's buggy code can create orders that aren't attached to any customer. These orphaned records break reports, corrupt analytics, and create customer service nightmares when users can't see their orders. A simple constraint would have prevented the bug from ever making it to production by failing immediately when the invalid data was attempted.

The pattern here is clear: the cost of fixing a bug grows exponentially with how long it takes to discover. Errors that fire immediately when invalid data is introduced are cheap to fix. Errors that only manifest after the data has propagated through multiple systems, been aggregated in reports, and influenced business decisions are catastrophically expensive to fix.

Exception Handling: Anticipating vs. Discovering Problems

Understanding how to handle errors properly requires recognizing a crucial distinction between two fundamentally different categories of errors. There are errors we can anticipate and handle gracefully, and there are errors that indicate fundamental problems with our code. Think of these as recoverable errors versus programming errors.

Recoverable errors are situations where the system is working exactly as designed, but the specific operation can't complete. A perfect example is ORA-00001, the unique constraint violation. When a user tries to register with an email address that's already in the database, Oracle throws this error. Your application should catch this specific error code, recognize what happened, and show the user a helpful message like "This email is already registered. Did you mean to log in instead?" You anticipated this possibility, you built handling for it, and the error becomes part of your normal application flow. This is good exception handling because it transforms a technical database error into a user-friendly experience.

Programming errors tell a different story entirely. These are ORA errors that reveal bugs in your code. Consider ORA-01722, the invalid number error that occurs when you're trying to insert text into a numeric column. This shouldn't be caught and handled gracefully because it indicates your code is fundamentally broken. You've somehow allowed non-numeric data to reach a point where it's being inserted into a numeric field. This error should bubble up loudly in development, crash your tests, and force you to fix the root cause rather than papering over it with exception handling. Catching and suppressing this error would be dangerous because it masks a deeper problem in your data flow or validation logic.

The powerful insight here is that Oracle's explicit, numbered error codes let you make this distinction clearly in your code. When you write your exception handling, you can catch the specific ORA codes you expect (like ORA-00001 for duplicate keys or ORA-02291 for foreign key violations) and let everything else fail. This is far better than databases or frameworks that give you one generic "database error" exception, forcing you to either catch everything (thereby hiding real bugs) or catch nothing (thereby making legitimate error cases crash your application).

This classification principle extends to how you think about monitoring and alerting in production as well. Recoverable errors are business metrics. Tracking how many users tried to register with duplicate emails this week tells you something about your user experience and might suggest you need clearer messaging or better duplicate detection. Programming errors, on the other hand, are incidents that need immediate investigation. If you're seeing ORA-01722 in production, someone needs to page an engineer because something in your validation layer has failed.

The practical application of this thinking changes how you structure your error handling code. Instead of wrapping entire sections of code in broad try-catch blocks, you write targeted exception handlers for the specific, expected error conditions, and you let unexpected errors propagate naturally. This approach gives you graceful handling for normal error conditions while maintaining visibility into actual bugs. Oracle's error code system makes this pattern easy to implement because each error has a distinct, meaningful identity.

Development Errors as Production Insurance

The frequency and timing of errors during development directly predict your production stability, but not in the way most developers think. Here's the counterintuitive truth: more errors during development often means fewer problems in production. When you're constantly hitting constraint violations, type mismatches, and validation errors while writing code, it means your defensive layers are working. Each error that fires in development is a potential production incident that will never happen.

Think carefully about what it means when you write code and Oracle doesn't throw errors. Either your code is perfect (unlikely), or your validation is too permissive. The most dangerous development experience is when everything "just works" without any constraint violations. This often means you don't have enough constraints defined, and the problems are being deferred until production when real users with real data hit edge cases you never tested.

Consider a concrete example. Imagine you're building a feature that processes financial transactions. In development with your clean test data, everything works smoothly. No errors at all. You deploy to production and suddenly you're getting data integrity issues because real-world amounts can be negative, null, have trailing spaces, or be formatted in ways your test data never was. Users in different locales are sending currency amounts with comma decimal separators instead of periods. Transaction timestamps are coming in with unexpected timezone offsets. None of these scenarios appeared in your sanitized test data.

If you had stricter constraints and validation in place, you would have hit errors during development the moment you tried to insert your first test transaction. Oracle would have rejected negative amounts if you had a CHECK constraint requiring positive values. It would have rejected null amounts if you had a NOT NULL constraint. These early errors would have forced you to think through all these cases before deployment, to write validation logic that handles different number formats, to decide on a clear policy for how your application handles edge cases. Instead, your lack of errors in development was actually hiding the absence of proper validation.

The timing of errors also matters enormously. Errors caught during unit tests cost you maybe a minute to fix. Errors caught during integration tests might cost an hour because you need to understand how multiple components interact. Errors caught during staging deployment might cost a day because you need to coordinate with other teams and re-test everything. Errors discovered in production cost exponentially more because now you're dealing with real user data, potential data corruption, customer support issues, and emergency fixes that bypass your normal development process. Oracle's immediate, explicit errors push problems as far left in the development cycle as possible.

This principle should fundamentally change how you think about setting up your development environment. Your development database should be stricter than production if anything. Turn on every constraint you can think of. Use the most restrictive validation rules. Make your development environment the place where problems surface immediately and obviously. Some teams do the opposite, running with relaxed constraints in development to make things "easier" and then tightening up for production. This is backwards. You want problems to be impossible to miss during development, when fixing them is cheap and low-stakes.

The best development teams measure themselves not by how few errors they see in development, but by how many errors they catch before code reaches production. A healthy development process involves constantly running into constraint violations and validation errors, fixing them immediately, and building up layers of defense that prevent entire categories of problems. When you can deploy code to production and be confident it won't hit data integrity errors, it's not because your code is magically perfect. It's because you've already hit and fixed every error condition during development.

The Cost of Retrofitting Strictness

One of the most painful lessons teams learn is what happens when they try to add constraints to existing systems with dirty data. This scenario plays out constantly in organizations that started without proper validation and are now trying to improve their data quality. When you attempt to add a NOT NULL constraint to a column that already contains null values, Oracle refuses with a clear error. When you try to add a unique constraint to data that has duplicates, Oracle tells you exactly how many rows violate the constraint.

At first, this feels like Oracle being difficult. You know you need this constraint for future data integrity, so why won't the database just add it? But Oracle is actually protecting you from making a bad situation worse. If it allowed you to add a constraint that existing data violates, you'd have inconsistent enforcement. New rows would be subject to the constraint while old rows would continue to violate it. Your application code would become a minefield of special cases, trying to handle records that shouldn't exist according to your current business rules.

The error forces you to confront your data quality problems head-on. You need to decide: do you delete the violating rows? Update them to valid values? Create a migration strategy that grandfathers in old data under different rules? These are hard questions, but they're questions you need to answer anyway. Oracle's refusal to paper over the problem ensures you make these decisions consciously and deliberately rather than ignoring them.

Many teams discover years of accumulated data quality issues when they try to add their first constraints. They find customer records with no email addresses, orders with no shipping addresses, transactions with invalid status codes, or relationships that violate referential integrity. Each of these discoveries represents a category of bug that has been silently corrupting data for months or years. The pain of cleaning up this data is real, but it's nothing compared to the alternative of continuing to accumulate bad data indefinitely.

This reinforces a key insight: it's far cheaper to build systems with proper constraints from the start than to retrofit them later. Every project that begins without proper validation, thinking they'll "add it later when we have time," is building technical debt that compounds with interest. The longer you wait, the more dirty data accumulates, and the more expensive the cleanup becomes. By the time teams realize they need constraints, they often have millions of rows of questionable data and no easy way to fix it.

Error Messages as Developer Experience

The quality of error messages is actually a form of developer tooling, though it's rarely discussed in those terms. Oracle's structured error codes create a shared vocabulary across teams and even across companies. When someone asks for help with ORA-02291, experienced developers immediately know they're dealing with a foreign key constraint issue without needing additional context. They know to look for a child record referencing a non-existent parent, or a delete operation trying to remove a parent that still has children.

This searchability and recognizability makes errors much less frustrating than vague messages. When you see "operation failed" or "unexpected error occurred," you have nowhere to start. You can't Google it effectively because these phrases are too generic. You can't ask colleagues for help because there's no specific identifier to reference. You're stuck digging through logs, adding debug statements, and trying to reproduce the problem with more verbose error output.

Compare this to seeing ORA-01400. You can immediately search for that specific code and find documentation explaining it means "cannot insert NULL into column." You can find Stack Overflow discussions of common causes. You can search your own codebase for other places where you've handled this error. The error code serves as a handle that lets you grab onto the problem and manipulate it. It transforms a frustrating "something's wrong" into a specific, actionable diagnosis.

This shared vocabulary also improves team communication and knowledge transfer. When you write in a pull request comment "this change fixes the ORA-01722 we were seeing in the import job," everyone on the team knows you're talking about invalid number conversion. The error code carries precise meaning without requiring lengthy explanation. New team members learn these codes quickly because they encounter them in discussions, documentation, and error handling code. The codes become part of your team's technical language.

The structure of error messages matters too. Oracle errors typically include not just the code but the specific object that caused the problem. ORA-01400 will tell you which table and which column rejected the NULL value. ORA-02291 will tell you which foreign key constraint failed. This specificity turns errors into debugging shortcuts. You don't need to guess which of your twelve database calls caused the problem; the error points directly to the source.

This principle applies beyond Oracle as well. Any system that provides structured, specific, searchable error codes is giving you better developer experience than systems with generic error messages. The investment in creating a good error code system pays dividends every time a developer encounters a problem, because it reduces the time from "something's wrong" to "I know exactly what's wrong and how to fix it."

The Principles: Building Systems That Fail Well

All of this points to a set of core principles for building reliable systems. First, prefer precise failure modes over accepting questionable input. Use database constraints, schema validation, and type systems to define exactly what valid data looks like, and reject everything else. This doesn't mean being unnecessarily rigid. It means being explicit about what your system can handle.

Second, fail early and loudly in development. The later an error is discovered, the more expensive it is to fix. Configure your development environment to be stricter than production, if anything, so that problems surface when they're cheap to address. This is why Oracle's behavior of throwing errors for ambiguous references is actually a feature: it catches potential issues before they become actual problems.

Third, distinguish between errors you can handle and errors that indicate bugs. Build explicit exception handling for recoverable error conditions, but let programming errors bubble up and break things. The visibility of errors is crucial for maintaining code quality over time.

Fourth, treat errors as learning opportunities and testing guidance. Every time you encounter an error that catches a real problem, that's an opportunity to prevent the same problem from happening again. Write a test that verifies the constraint works. Add monitoring that alerts if similar issues start occurring in production. The goal is to make errors progressively less surprising by systematically eliminating their causes.

Finally, invest in good error messages and error codes. Clear, specific, searchable error identifiers make debugging faster and knowledge sharing easier. They're not just nice to have; they're essential infrastructure for maintaining complex systems.

Embracing the Error-Driven Development Mindset

The shift from seeing errors as annoyances to seeing them as quality signals requires a change in mindset. When Oracle throws an ORA error, that's not the database being difficult. It's the database protecting you from yourself. When Pydantic rejects your payload, that's not the framework being pedantic. It's catching a potential bug before it can cause damage.

Enterprise systems like Oracle were built to protect data and give developers high-signal diagnostics because the cost of data problems in enterprise contexts is enormous. But these principles apply just as much to smaller systems and modern web applications. The worst errors are the quiet ones that let bad state sneak into production. The best errors are explicit, precise, and actionable. They save you time by telling you exactly what to fix.

The next time you see an ORA error, take a moment to appreciate what it's telling you. The error isn't the problem. It's the solution to a problem you didn't know you had yet. And that's exactly the kind of help you want from your tools.

Cover photo by Brett Jordan on Unsplash

Oracle 23ai's Phantom Vector Memory: A Troubleshooting Guide

Smyekh David-West — Wed, 17 Dec 2025 07:41:38 +0000

☁️ Pre-Flight Checklist

Before we taxi down the runway, here’s your flight plan. Keep this handy to navigate your flight path. Welcome aboard the cloud!

🌥️ Takeoff

Prerequisites
A Quick Primer on Oracle Architecture
The Mission: Allocate Vector Memory

⛅️ Cruising Altitude

The First Attempt: ALTER SYSTEM
The Roadblock: A Two-Layer Problem
The Breakthrough: The docker exec Recovery
The Proof: Trust the Startup Log, Not the Parameter

🌤️ Landing & Taxi

Understanding Oracle Parameter and Memory Views
Recovery Cheat Sheet
Conclusion
The "IAM Policy": Why Our dev User Needed GRANTs

Enjoy your flight! ☁️

As part of my work with Oracle Cloud Infrastructure (OCI) and its powerful database features, I've been diving into the new AI Vector Search capabilities in Oracle Database 23ai. The free containerized version is the perfect lab for this.

To get started with high-performance HNSW indexes, you need to allocate a dedicated memory pool by setting the vector_memory_size parameter.

A single SQL command and a restart led me down a rabbit hole of cryptic errors, misleading outputs, and a locked-out database. It turned into a fantastic troubleshooting session that taught me some valuable lessons about the inner workings of Oracle's multitenant architecture, especially in the Free edition.

If you've found yourself staring at a vector_memory_size that stubbornly reads 0 or fighting the dreaded ORA-12514 error, this log of my troubleshooting journey is for you.

Prerequisites

This article assumes you have already successfully installed and are running the Oracle 23ai Free container, as detailed in the "The Ultimate Guide to Oracle 23ai on Apple Silicon.". This article begins where that one left off.

This guide assumes you have the environment from Part 1 running. If you haven't set up your dev user yet, pause here and go back.

A Quick Primer on Oracle Architecture

Before we dive into the troubleshooting, let's clarify a few key Oracle terms. Understanding these concepts is crucial to grasping why the problem occurs and how the solution works.

CDB (Container Database): Think of this as the master database that manages the overall instance. In the free container, its name is FREE. You rarely connect here for development, but it's where major configuration, like memory allocation, is ultimately managed.
PDB (Pluggable Database): This is an isolated, independent database that runs inside the CDB. For all application application development, you connect to the PDB. In our case, its name is freepdb1. The ORA-12514 error happens because this PDB isn't available when the main CDB instance is down.
SGA (System Global Area): This is the shared memory region that a database instance uses to store data and control information. When we set vector_memory_size, we are telling Oracle to carve out a piece of the SGA specifically for vector indexes. The STARTUP log shows the actual composition of the SGA, which is why it's more reliable than the SHOW PARAMETER command.

The Mission: Allocate Vector Memory

The first step to using AI Vector Search is to tell Oracle to set aside a dedicated chunk of RAM for it by setting the vector_memory_size parameter.

🌩️ Note: The 23ai Free edition is limited to 2 GB of RAM. Dedicating too much memory to vectors can starve other critical database processes. A setting of 1G (50% of total memory) is risky. It's wiser to start with a more conservative value.

I decided to start with 500M.

The First Attempt: `ALTER SYSTEM`

Following the documentation, I connected using my sql-sys alias and ran the standard ALTER SYSTEM command. Using SCOPE=SPFILE is the robust way to make a configuration change persist across restarts.

-- Connect using my sql-sys alias or as SYS
ALTER SYSTEM SET vector_memory_size=500M SCOPE=SPFILE;

The system responded with a reassuring System altered.. To apply the change, a database restart is required. The easiest way with Docker is to restart the container itself.

docker restart oracle-free

This is where the journey should have ended. But instead, it's where the trouble began.

The Roadblock: A Two-Layer Problem

After the container restarts, a developer's natural first step is to connect as their day-to-day dev user and check if the vector_memory_size parameter was applied. This is where we hit our first wall: a permissions layer.

-- Connecting as the dev user from Part 1
SQL> show parameter vector_memory_size;

ORA-00942: table or view does not exist

This is our first critical lesson. Our dev user, with basic CONNECT and RESOURCE roles, can create tables but cannot see instance-level configuration. This is a security feature, not a bug. To investigate further, we must switch to our administrative SYSuser.

Now, continuing as SYS, we can properly check the parameter. However, this reveals the second part of our problem: a configuration layer.

-- Now connected as SYS (e.g., via sql-sys alias)
SQL> SHOW PARAMETER vector_memory_size;

NAME                   TYPE        VALUE
---------------------- ----------- ------------------------------
vector_memory_size     big integer 0

It was still zero. My change seemed to have vanished. To understand why, I ran some diagnostic checks:

--1ST CHECK
SQL> SHOW CON_NAME;

CON_NAME
------
FREEPDB1

--2ND CHECK
SQL>SELECT NAME, ISPDB_MODIFIABLE
FROM V$SYSTEM_PARAMETER
WHERE NAME = 'vector_memory_size';

NAME
---
ISPDB
---
vector_memory_size
TRUE

Interpretation: I was connected in the PDB (FREEPDB1), and the parameter is indeed PDB-modifiable. Yet, the SHOW PARAMETER command still reported 0. This indicated a discrepancy between the stored parameter value and the actual runtime allocation, a common quirk in the Oracle Free edition.

🌩️ A Note on the Permissions Fix
Before proceeding, let's quickly fix the issue for our dev user. As SYS, run the following GRANT statements:
GRANT SELECT ON SYS.V_$PARAMETER TO dev;
GRANT SELECT ON SYS.V_$SYSTEM_PARAMETER TO dev;
GRANT CREATE INDEX TO dev;
This is necessary because commands like SHOW PARAMETER query special, protected data dictionary views (e.g., V$PARAMETER) that are owned by the SYS user. For security and stability, non-administrative users like our dev account do not have permission to see this instance-wide configuration by default.

These GRANT statements provide our developer with the specific, read-only access they need to do their job, without making them an administrator.

My investigation into CDB vs. PDB settings led me to try applying the change at the root and performing a full SHUTDOWN/STARTUP.

This led to a catastrophic failure:

Database closed.
Database dismounted.
ORACLE instance shut down.
ERROR:
ORA-12514: Cannot connect to database. Service
freepdb1 is not registered with
the listener at host 127.0.0.1 port 1521.

I was locked out. Trying to reconnect with my sql-sys alias failed with the same ORA-12514 error.

>>> sql-sys 

Copyright (c) 1982, 2025, Oracle. All rights reserved. 
ERROR: ORA-12514: Cannot connect to database. 
Service freepdb1 is not registered with the listener at host 127.0.0.1 port 1521. 
(CONNECTION_ID=Qgik7CZCByPgYwIAEaywBw==) 
Help: https://docs.oracle.com/error-help/db/ora-12514/ 

Enter user-name:

A quick check of the Docker container status confirmed the issue:

docker ps

STATUS
Up 19 minutes (unhealthy)

This command showed the oracle-free container as (unhealthy), further indicating that the database instance inside was not fully operational.

🌩️ What ORA-12514 Really Means
This error means the listener is running, but the database service you're asking for (freepdb1) hasn't registered with it. This happens when the main database instance is down or the Pluggable Database (PDB) is closed. In my case, the entire instance was down because PDBs do not auto-open by default in the Free edition after a CDB restart. Therefore, FREEPDB1 remained closed, leading to its listener unregistration.

Did you know? Remember how we restarted the container in Part 1? That actually closes our PDB, which is why we need to manually open it here.

The Breakthrough: The `docker exec` Recovery

This is the critical lesson for anyone running Oracle in Docker. When you SHUTDOWN the instance from within a SQL session, you can't just run STARTUP because your client is no longer connected to anything. I encountered this with the SP2-0640: Not connected error when attempting STARTUP after the shutdown.

You must re-enter the container and start the instance as SYSDBA.

Exec into the container with sqlplus as sysdba:

docker exec -it oracle-free sqlplus / as sysdba

You'll be greeted with a message that tells you everything you need to know:
```
Connected to an idle instance.
```
Start the database:
```
STARTUP;
```

The Proof: Trust the Startup Log, Not the Parameter

This is the moment of truth. The output that followed was the breakthrough:

Total System Global Area 1603373280 bytes
Fixed Size               5007584 bytes
Variable Size            352321536 bytes
Database Buffers         704643072 bytes
Redo Buffers             4530176 bytes
Vector Memory Area       536870912 bytes  <-- VOILA!
Database mounted.
Database opened.

There it was: Vector Memory Area 536870912 bytes. That's our 500M!

🌩️ The Deceptive Parameter
My ALTER SYSTEM command had worked from the beginning. The SHOW PARAMETER view in the PDB is misleading for this setting in the Free edition. The startup log and V$VECTOR_MEMORY_POOL are the authoritative sources. Trust the startup log and V$VECTOR_MEMORY_POOL as the authoritative sources!

Final Steps: Bringing the Database Fully Online

The instance was up, but the PDB was still closed. You must open it manually.

-- 1. Open the Pluggable Database
ALTER PLUGGABLE DATABASE ALL OPEN;

-- 2. Verify the PDB Status
SELECT name, open_mode FROM v$pdbs;
-- You should see FREEPDB1 in READ WRITE mode

-- 3. Switch into the PDB for your work
ALTER SESSION SET CONTAINER = FREEPDB1;

-- 4. Final verification of vector memory pool allocation within the PDB
SELECT pool, alloc_bytes, used_bytes FROM V$VECTOR_MEMORY_POOL;

-- 5. Verify total SGA and vector memory allocation
SHOW SGA;

Expected Outputs for Step 4 & 5:

-- STEP4
POOL         ALLOC_BYTES   USED_BYTES
------------ ------------  ----------
1MB POOL     469762048     0
64KB POOL     50331648     0

-- STEP 5
Total System Global Area 1603373280 bytes
Fixed Size                  5007584 bytes
Variable Size             520093696 bytes
Database Buffers          536870912 bytes
Redo Buffers                4530176 bytes
Vector Memory Area        536870912 bytes

Explanation:

Each pool manages a specific block size of vector memory.
ALLOC_BYTES shows total allocated memory for that pool.
USED_BYTES shows how much memory is currently in use. 0 usage indicates the system is ready but no active vector operations are running yet.
The “Vector Memory Area” line appears because of the ALTER SYSTEM SET vector_memory_size=500M SCOPE=SPFILE;
- It confirms that ~512 MB (close to your configured 500 MB) was successfully allocated on startup.
- This memory is used for AI Vector Search features like storing vector embeddings and building vector indexes.
- The ALLOC_BYTES in Step 4 (~520 MB combined) matches this total, confirming your vector memory configuration is active and healthy.

Understanding Oracle Parameter and Memory Views

Oracle provides several ways to inspect configuration parameters and memory allocation, but their scope and reliability can differ. Understanding these views is crucial for accurate troubleshooting.

First, a quick note on Oracle's V$ views: these are dynamic performance views that provide access to current performance, resource usage, and session activity information. The V typically stands for "view," and the $ is part of Oracle's naming convention for these special views, which are often built on top of underlying X$ tables. They give you a real-time snapshot of the database instance's state.

`SHOW PARAMETER <parameter_name>`

This SQL*Plus command is a convenient way to quickly check a parameter's value. However, as we saw with vector_memory_size in the Free edition, it can sometimes report a default or 0 even when the parameter is actively allocated at runtime. Its output often reflects the value stored in the SPFILE or a default, not necessarily the currently active runtime value, especially for dynamically allocated memory components.

`V$SYSTEM_PARAMETER`

This dynamic performance view shows the current system-wide parameter values, typically reflecting what's in the SPFILE or the last ALTER SYSTEM command. It's useful for understanding the intended configuration. The ISPDB_MODIFIABLE column indicates if a parameter can be changed at the PDB level.

`V$PARAMETER`

Similar to V$SYSTEM_PARAMETER, but it shows parameter values for the current session. For system-level parameters like vector_memory_size, its value will often mirror V$SYSTEM_PARAMETER.

`V$SGA`

This view provides a breakdown of the System Global Area (SGA) components and their sizes. After a successful STARTUP with vector_memory_size configured, you should see Vector Memory Area listed here with its allocated size. This is a reliable source for confirming the actual memory allocation.

SQL> SHOW SGA;
Example Output (excerpt):
Total System Global Area 1603373280 bytes
Fixed Size                  5007584 bytes
Variable Size             352321536 bytes
Database Buffers          704643072 bytes
Redo Buffers                4530176 bytes
Vector Memory Area        536870912 bytes  <--Confirms allocation within SGA

This output directly correlates with the STARTUP log and visually confirms that the Vector Memory Area has been carved out of the total SGA. Remember, in the Oracle Free edition, the total SGA is limited, so increasing one component might implicitly reduce others if SGA_TARGET is constrained.

`V$VECTOR_MEMORY_POOL`

This view is specifically designed to show the details of the vector memory pool. It's the most direct and authoritative source for confirming the active vector memory allocation. If this view shows your configured size, you can be confident that vector search memory is active.

SELECT pool, alloc_bytes, used_bytes FROM V$VECTOR_MEMORY_POOL;

Recovery Cheat Sheet

If you get locked out with ORA-12514, here is your recovery sequence:

# 1. (Optional) Check Docker container status - it will likely be unhealthy
docker ps

# 2. Connect to the idle instance from your host terminal
docker exec -it oracle-free sqlplus / as sysdba

Then, inside the SQL> prompt:

-- 3. Start the database instance
STARTUP;

-- 4. Open the pluggable databases
ALTER PLUGGABLE DATABASE ALL OPEN;

-- 5. (Optional) Switch to your PDB to continue work
ALTER SESSION SET CONTAINER = FREEPDB1;

--6. (Optional) Verify vector memory pool allocation
SELECT pool, alloc_bytes, used_bytes FROM V$VECTOR_MEMORY_POOL;

-- 7. (Optional) Verify overall SGA breakdown
SHOW SGA;

With the database fully online and vector memory confirmed, I was finally ready to get back to building.

🌩️ A Note on Privileges: It's important to note that this entire troubleshooting process was done with SYSDBA privileges. This is a prime example of the principle of least privilege in action. My day-to-day dev user rightfully lacks the permissions to alter system parameters or restart the database. Using the superuser for these administrative tasks is not only necessary but is also a validation of a secure and well-designed workflow, separating experimental and operational access models.

Conclusion

The key takeaway is to trust the startup log, V$SGA, and V$VECTOR_MEMORY_POOL. These provide the ground truth of what's happening in the SGA. While SHOW PARAMETER and V$SYSTEM_PARAMETER are useful for intended configuration, the startup sequence and direct memory pool queries reveal the real story of runtime allocation. By understanding the roles of the CDB and PDB and mastering the docker exec recovery flow, you can confidently manage your Oracle instance and unlock its most powerful features.

Happy building and vectorizing! ☁️

The "IAM Policy": Why Our `dev` User Needs `GRANT`s

In a cloud environment like OCI, a Cloud Architect never gives a developer or service full administrative access. Instead, they create fine-grained IAM (Identity and Access Management) policies. An IAM policy explicitly states who can do what on which resources.

Our GRANT commands in Part 2 were the database equivalent of an IAM policy. We encountered an ORA-00942 error because our dev user, by default, had no policy allowing it to view the system's configuration.

The fix was not to grant the DBA role, but to create a precise policy:
GRANT SELECT ON SYS.V_$PARAMETER TO dev;

This is the Principle of Least Privilege in action, and it's the most important concept in cloud security.

Object vs. System Privileges: A Cloud Analogy

Oracle's security model, which separates Object Privileges (acting on a table) from System Privileges (acting on the whole database), mirrors the separation of concerns in OCI.

Object Privileges are like permissions on a specific OCI resource (e.g., writing to a specific Object Storage bucket). The RESOURCE role lets you create your own resources.
System Privileges are like tenancy-level permissions (e.g., the ability to launch new Compute instances or view network configurations).

Our dev user could manage its own "resources" (tables) but needed a specific policy (GRANT) to view "tenancy-level" configuration (V$PARAMETER).

Anatomy of a Secure Developer Role

This is the final "IAM policy" for our developer, enabling them to build AI applications securely.

-- These SQL commands should be executed once as the SYS user
-- in your SQL client (e.g., SQLcl, SQL Developer, or via 'docker exec -it oracle-free sqlplus / as sysdba').
-- Ensure you are connected to the FREEPDB1 container if running from SYS.

-- 1. The right to log in (authenticate).
GRANT CONNECT TO dev;

-- 2. A role to create their own resources (tables, views).
GRANT RESOURCE TO dev;

-- 3. The right to use storage space (a quota on a resource).
ALTER USER dev QUOTA UNLIMITED ON dev_data;

-- 4. The policy to inspect specific system configurations.
GRANT SELECT ON SYS.V_$PARAMETER TO dev;
GRANT SELECT ON SYS.V_$SYSTEM_PARAMETER TO dev;

-- 5. The policy to create a specific type of resource (an index).
GRANT CREATE INDEX TO dev;

With this secure foundation, our developer is ready to build.

Cover Photo by BoliviaInteligente on Unsplash

No More VMs: Run Oracle Database 23ai Natively on Apple Silicon in Seconds

Smyekh David-West — Mon, 08 Dec 2025 10:09:07 +0000

⚡️ 30-Second Quick Start (Copy/Paste and Run)

docker run -d --name oracle-free -p 1521:1521 \
  -v oracle-data:/opt/oracle/oradata \
  -e ORACLE_PWD=OracleIsAwesome \
  container-registry.oracle.com/database/free:latest-lite

This starts Oracle 23ai Free instantly — no VM, no installer, no configuration. Just run and connect.

☁️ Pre-Flight Checklist

Before we taxi down the runway, here’s your flight plan. Keep this handy to navigate your flight path. Welcome aboard the cloud!

🌥️ Takeoff

Why This Changes Everything
Prerequisites
Get Started in 60 Seconds: The Docker Command

⛅️ Cruising Altitude

4 Ways to Connect to Your New Database
Managing Your Database Container
Understanding Data Persistence: Your Data is Safe
Best Practice: Create a Dedicated Developer User

🌤️ Landing & Taxi

Why 23ai Might Be the Only Database You Need
Conclusion
Bonus: Faster Connections with Shell Shortcuts

Enjoy your flight! ☁️

For years, developers on macOS have faced a common hurdle: running Oracle Database locally meant clunky VMs, slow performance, and a drain on system resources. Personally, the thought of setting up a dedicated environment or firing up my UTM Linux VM was always daunting.

Thankfully, that's not the case anymore.

Oracle's Oracle Database 23ai Free is available as a native ARM64 container image for Apple Silicon (M1–M4). This allows developers to run a full Oracle Database locally on macOS using Docker—no emulation, no VMs, and no workarounds. It makes Oracle feel as easy to spin up as Postgres for my FastAPI projects, and that’s a huge improvement for local development.

Why This Changes Everything

Before this release, the developer experience was painful:

No Native Support: Oracle databases required an x86 architecture, forcing Mac users to run a heavy Linux VM.
Slow and Inefficient: Virtualization is resource-intensive, leading to slow startup times, high RAM usage, and significant battery drain.
Complex Setup: Configuring VMs and networking was a constant source of friction.

Now, with the native ARM64 container, you get:

Significantly faster startup: Running natively on Apple Silicon eliminates emulation overhead and reduces startup time to under a minute.
Reduced resource usage: No full VM means dramatically lower CPU/RAM consumption and smoother performance.
Simplified workflow: It behaves like any standard Docker container—pull, run, connect, done.

Prerequisites

An Apple Silicon Mac: (M1, M2, M3, M4, etc.)
Docker Desktop: Make sure it's installed and running.

Get Started in 60 Seconds: The Docker Command

Open your terminal and run this single command. Replace <your-password> with a password of your choice.

docker run -d --name oracle-free -p 1521:1521 \
  -v oracle-data:/opt/oracle/oradata \
  -e ORACLE_PWD=<your-password> \
  container-registry.oracle.com/database/free:latest-lite

Example:

docker run -d --name oracle-free -p 1521:1521 \
  -v oracle-data:/opt/oracle/oradata \
  -e ORACLE_PWD=OracleIsAwesome \
  container-registry.oracle.com/database/free:latest-lite

What does `-d` do?

The -d flag runs the container in detached mode, meaning it runs in the background without blocking your terminal. With -d, the container starts in the background and you can continue using your terminal immediately.

For first-time setup, some developers prefer to see the startup logs in real-time to confirm everything is working. If that's you, omit the -d flag:

docker run --name oracle-free -p 1521:1521 \
  -v oracle-data:/opt/oracle/oradata \
  -e ORACLE_PWD=OracleIsAwesome \
  container-registry.oracle.com/database/free:latest-lite

Without -d, the container runs in the foreground and you'll see all the logs directly as the database initializes. Wait for the message DATABASE IS READY TO USE! to appear.

🌩️ Important: If you run without -d, pressing Ctrl + C will stop the container entirely. If this happens, don't worry—just restart it in the background:
# 1. Start the container in the background
docker start oracle-free

# 2. Confirm the container is running (check the STATUS column)
docker ps

# 3. Follow the logs to see when the database is ready
docker logs -f oracle-free
Once you see DATABASE IS READY TO USE!, press Ctrl + C to exit the log view. This time, the container will keep running in the background because it was started with docker start.

What does `-e ORACLE_PWD` do?

The -e flag sets an environment variable inside the container. ORACLE_PWD sets the initial password for the SYS and SYSTEM administrative users. If you omit this, the container won't start.

What does `-v oracle-data:/opt/oracle/oradata` do?

The -v flag is crucial for data persistence. It creates a Docker named volume called oracle-data and maps it to the /opt/oracle/oradata directory inside the container—the location where Oracle stores its database files.

This separates your data from the container's lifecycle. If you stop, remove, or update the oracle-free container, the oracle-data volume remains safely on your system. Without this line, all data and schema changes would be lost forever when the container is removed.

Checking When Your Database is Ready

If you started the container in detached mode (with -d), you can check the startup progress anytime:

# Follow the logs to see when the database is ready
docker logs -f oracle-free

Wait for the logs to display the message: DATABASE IS READY TO USE!

Once you see this message, press Ctrl + C to exit the log view. The container will keep running in the background.

4 Ways to Connect to Your New Database

Once the container is running, you can connect to it using your favorite SQL tool.

Your Connection Cheat Sheet

No matter which tool you use, these are your connection details:

Item	Value
Host	`localhost`
Port	`1521`
Service Name	`freepdb1`
Admin Users	`system` (default) or `sys` (requires `AS SYSDBA`)
Password	The one you set (e.g., `OracleIsAwesome`)
Connect String	`localhost:1521/freepdb1`

# Quick Copy/Paste Connection Defaults
HOST=localhost
PORT=1521
SERVICE_NAME=freepdb1

# Admin users (created automatically)
SYSTEM / <your-password>
SYS / <your-password>  (connect as SYSDBA if needed)

Why freepdb1? The Oracle container uses a Multitenant Architecture.

CDB (Container Database - FREE): This is the root database that manages the overall instance. You rarely connect here for development.
PDB (Pluggable Database - freepdb1): This is an isolated, independent database running inside the CDB. For all application development, you should connect to the PDB.

🌩️ Practical takeaway: For all development work, always connect to freepdb1, not the root container.

A Quick Note: `SYS`, `SYSTEM`, and `AS SYSDBA`

You will often see AS SYSDBA in Oracle documentation. Here’s a simple guide:

SYS User: The true superuser. It owns the database's core data dictionary and can do anything. To connect as SYS, you must use the AS SYSDBA clause, which activates system-level privileges. It's used for fundamental operations like starting or stopping the database.

SYSTEM User: A default administrator account with extensive rights, but less powerful than SYS. It's practical for administrative tasks like creating new users (as shown later).

AS SYSDBA: This is a special privilege, not a user. It tells the database you're connecting with the highest level of authority.

🌩️ Rule of Thumb: Use SYS AS SYSDBA only when necessary. For creating users or granting general permissions, SYSTEM is fine. For application work, always use a dedicated, non-admin user.

1. For the CLI Fans: SQLcl

If you prefer the command line, Oracle SQLcl is the modern tool of choice.

Install SQLcl:
```
brew install sqlcl
```
Add SQLcl to your PATH:
Note: The version number (25.3.0.274.1210) might be different for you. Check the correct path in /opt/homebrew/Caskroom/sqlcl/.
```
echo 'export PATH=/opt/homebrew/Caskroom/sqlcl/25.3.0.274.1210/sqlcl/bin:$PATH' >> ~/.zshrc
```
Reload your terminal configuration:
```
source ~/.zshrc
```
Confirm it's working:
```
sql -v
```

Connecting with SQLcl
Once installed, connecting is a one-liner:

# Connect as the default admin user 
# (good for creating other users)
sql system/OracleIsAwesome@localhost:1521/freepdb1

# Or, connect as the superuser for powerful database operations
sql sys/OracleIsAwesome@localhost:1521/freepdb1 as sysdba

2. Connect Using the Built-In SQL*Plus (No Installation Needed)

The Docker container comes with the classic SQL*Plus tool pre-installed. You can use docker exec to run it directly from your Mac's terminal without installing any client software or even entering the container's shell.

Run this single command on your terminal:

# As the default admin user
docker exec -it oracle-free sqlplus system/OracleIsAwesome@localhost:1521/freepdb1

# As the superuser
docker exec -it oracle-free sqlplus sys/OracleIsAwesome@localhost:1521/freepdb1 as sysdba

Or, if you created your dedicated developer user:

docker exec -it oracle-free sqlplus dev/DevPassword123@localhost:1521/freepdb1

This command directly connects you to the database and drops you into an interactive SQL*Plus session.

3. For the GUI Lovers: SQL Developer

If you prefer a graphical interface, use the free SQL Developer.

Download: Oracle SQL Developer Downloads
Click the + icon to create a new connection.
Fill in the details from the cheat sheet above.
Click Test. If it says "Success," click Connect.

4. For the VS Code Enthusiasts: Oracle SQL Developer Extension

In VS Code, go to the Extensions marketplace and search for "Oracle SQL Developer Extension for VS Code".
Install the official extension from Oracle.
Click the Oracle Database icon in the activity bar.
Click the Create Connection button.
Fill in the connection details. Crucially, make sure you select Service Name for the connection type, not SID.
Click Connect. You can now browse your schema and run queries directly from VS Code.

Test your Connection

Once connected, you have a couple of ways to interact with your database directly within VS Code:

SQL Worksheet: Right-click on your connection in the Oracle Database panel and select Open New SQL Worksheet. This opens a standard editor where you can write and execute queries.
SQLcl Terminal: Right-click the connection and choose Open SQLcl in Terminal. This launches an integrated terminal running Oracle's modern command-line interface, SQLcl. You may be prompted to enter your password (e.g OracleIsAwesome).

To test your connection, open a worksheet or SQLcl session and run this simple query:

-- Test your connection with a simple query!
SELECT 'Connected in VS Code!' AS status FROM dual;

You should see the result directly in VS Code, confirming your setup is complete.

When you're done, you can right-click the connection and select Disconnect.
The next time you want to use it, simply click the connection name again.

If you didn't save your password during setup, VS Code will prompt you for it before reconnecting. However, if you checked the "Save Password" box when creating the connection, it will reconnect instantly with a single click.

Managing Your Database Container

Your container, named oracle-free, persists on your system. You don't need to run the docker run command again.

Start the database:
```
docker start oracle-free
```
Stop the database:
```
docker stop oracle-free
```
Check if it's running:
```
docker ps
```
View live logs (useful for debugging):
```
docker logs -f oracle-free
```

"Remove Everything" Cleanup Commands

# Completely remove the container (does not delete your data volume)
docker rm oracle-free

# Remove the container and its stored data
docker rm oracle-free
docker volume rm oracle-data

Understanding Data Persistence: Your Data is Safe

One of the most common questions when working with Docker containers is: "What happens to my data?"

The good news is that your database is safer than you think.

What Deletes Your Data (and What Doesn't)

These actions are SAFE — your data persists:

Stopping the container: docker stop oracle-free
Removing the container: docker rm oracle-free
Restarting your Mac
Updating the container to a new version

Your data will ONLY be deleted if you explicitly run:

docker volume rm oracle-data

This is the only command that permanently destroys your database files. Docker will even warn you if the volume is still in use.

The Critical Rule: Always Attach Your Volume

Here's something crucial to understand: when you recreate a container (after running docker rm oracle-free), you must include the -v oracle-data:/opt/oracle/oradata flag in your docker run command.

Why? Here's the key distinction:

The volume persists automatically — it exists independently on your system.
The container does NOT remember it — containers are stateless.

Think of it like this: Your database files are stored in a safe deposit box (oracle-data volume) at the bank (Docker). When you create a new container, you need to explicitly give it the key (-v oracle-data:/opt/oracle/oradata) to access that box.

Example: Recreating Your Container (Updates, Restarts, or Recovery)

Whether you're updating to a newer image, recovering from an accidental deletion, or just want a fresh container, the process is the same. Your data persists through it all. Let's say you removed your container and want to start fresh:

Step 1: Pull the Latest Image (Optional but Recommended)

Before recreating your container, it's a good idea to check for updates:

docker pull container-registry.oracle.com/database/free:latest-lite

Example output when downloading a newer version:

If you already have the latest version, Docker will tell you:

⚡ Tip: Docker keeps old images even after pulling a new latest tag. If you want to clean up the old one, run:
  docker image prune

Step 2: Create a New Container

# Create a new container with the SAME volume attached
docker run \
  --name oracle-free \
  -p 1521:1521 \
  -e ORACLE_PWD=OracleIsAwesome \
  -v oracle-data:/opt/oracle/oradata \
  -d container-registry.oracle.com/database/free:latest-lite

🌩️ Note: The -d flag runs the container in detached mode (in the background). Unlike the initial docker run command in this guide, which attaches to your terminal and shows live logs, using -d starts the container and immediately returns you to your command prompt. The container keeps running in the background, and you can view its logs anytime with docker logs -f oracle-free.

What happens:

Docker detects the existing oracle-data volume
It reuses it (does NOT create a new one)
Your database comes back exactly as you left it — all tables, users, and data intact

Important: Passwords Are Preserved

When you restore from an existing volume, the -e ORACLE_PWD flag is ignored. Your database already has passwords stored in the datafiles, so SYS and SYSTEM keep their original passwords. If you created a dev user, it still exists with its password unchanged.

The -e ORACLE_PWD flag only matters when starting with a fresh database (no volume or a new volume name).

Best Practice: Create a Dedicated Developer User

The goal of this guide is to move beyond a simple demo and set you up with a professional development environment that mirrors real-world best practices. To do this, we will address two fundamental principles: one for security and one for database health.

1. Security: The Principle of Least Privilege

First, you should never use the powerful SYSTEM or SYS accounts for everyday application development. Doing so is a security anti-pattern that violates the principle of least privilege. Our first step is to create a dedicated, less-privileged dev user specifically for our application.

2. Database Health: Separating User Data from System Data

Second, we must address a specific quirk of this "lite" container. To provide the quickest possible startup experience, it intentionally defaults to using its own critical SYSTEM tablespace for all user data. While this is fine for a temporary "Hello, World!" test, it is a major anti-pattern for building real applications. The SYSTEM tablespace is reserved for the database's core metadata; mixing your app's data with it can risk database stability and would never be allowed in a production environment.

To build our application on a proper foundation, we will override this default by creating a separate tablespace for our dev user. This ensures our local setup behaves like a real-world database, making our application more robust and portable.

The following steps show the complete, professional method for creating a new user that adheres to both of these best practices.

🌩️ These commands should be run as the SYS user. Connect using your the full docker exec command.
docker exec -it oracle-free sqlplus sys/OracleIsAwesome@localhost:1521/freepdb1 as sysdba

Step 1: Create a Dedicated Tablespace

Create a new tablespace named dev_data where your user's tables and data will be stored. This is a critical best practice for database health and management.

CREATE TABLESPACE dev_data DATAFILE '/opt/oracle/oradata/dev_data01.dbf' SIZE 100M AUTOEXTEND ON;

Step 2: Create the `dev` User

Now, create the dev user and assign your new tablespace as its default home right from the start.

CREATE USER dev IDENTIFIED BY DevPassword123 DEFAULT TABLESPACE dev_data;

🌩️ Note: Feel free to replace DevPassword123 with a secure password of your own. Just remember to update it in the shortcut scripts later!

Step 3: Grant Storage Quota

Allow the user to store data in their new dev_data tablespace.

ALTER USER dev QUOTA UNLIMITED ON dev_data;

Step 4: Grant Permissions

Finally, grant the user the rights to connect to the database (CONNECT) and create objects like tables and views (RESOURCE).

GRANT CONNECT, RESOURCE TO dev;

You can now type exit to leave the SQL*Plus session.

To connect as your new dev user, you can use the docker exec command again. Once connected, run the following quick test to confirm everything works as expected.

First, connect:

docker exec -it oracle-free sqlplus dev/DevPassword123@localhost:1521/freepdb1

Now, at the new SQL> prompt, test your schema:

-- Confirm your schema works
CREATE TABLE hello (msg VARCHAR2(50));
INSERT INTO hello VALUES ('Welcome to your dev schema');
SELECT * FROM hello;

After confirming it works, you can exit the session.

Note: To make switching between your dev user and admin users easier, check out the bonus section at the end of this article for a helpful script you can add to your shell configuration.

Why 23ai Might Be the Only Database You Need

Oracle 23ai Free isn't just a traditional relational database. It integrates modern features that allow it to replace other specialized databases in your stack.

Better than Postgres?

Oracle 23ai includes all the robust, enterprise-grade relational features you expect (ACID transactions, advanced SQL, PL/SQL). But it also adds unique capabilities like AI Vector Search, allowing you to build powerful semantic search and RAG applications directly within the database.

Better than MongoDB?

Oracle's JSON Relational Duality Views are a revolutionary feature. They let you work with data as both structured relational tables and flexible JSON documents—simultaneously. The data is stored once, but can be accessed, modified, and queried from either perspective with full ACID compliance. This eliminates the object-relational mismatch and provides the flexibility of a document store with the power of a relational database.

This means your application doesn’t need complex mapping layers — your JSON and relational models stay in sync automatically.

Capability	MongoDB	Oracle 23ai Free
Flexible JSON Storage	✅	✅
Transactional JSON	❌ (Limited)	✅ (Full ACID)
Combine JSON + Relational	❌	✅ (JSON Duality Views)
Built-in AI Vector Search	❌	✅

Conclusion

Running Oracle Database on a Mac is no longer a chore. With native ARM64 containers, it's fast, efficient, and incredibly easy to get started. You get a world-class, enterprise-grade database with cutting-edge AI and JSON features, all running locally on your machine for free.

Happy building! ☁️

Bonus: Faster Connections with Shell Shortcuts

As you work with Oracle, you'll find you sometimes need to perform administrative tasks as a privileged user, but you should use a dedicated dev user for daily work. To make this workflow seamless, you can create a set of shortcuts.

1. Create a Custom Script File

First, place the shortcut functions into a dedicated file. A common and safe practice is to use a hidden file in your home directory. Create and paste the following into a new file named ~/.zsh_oracle_shortcuts.

# Oracle DB connection shortcuts

# Connect as dev user using sqlplus inside the container
function sql-dev() {
    docker exec -it oracle-free sqlplus dev/DevPassword123@localhost:1521/freepdb1
}

# Connect as dev user using local sqlcl client
function sqlcl-dev() {
    # This requires you to have sqlcl installed locally (e.g., via Homebrew)
    sql dev/DevPassword123@localhost:1521/freepdb1
}

# Connect as SYSTEM admin using sqlplus inside the container
function sql-system() {
    docker exec -it oracle-free sqlplus system/OracleIsAwesome@localhost:1521/freepdb1
}

# Connect as SYS superuser using sqlplus inside the container
function sql-sys() {
    docker exec -it oracle-free sqlplus sys/OracleIsAwesome@localhost:1521/freepdb1 as sysdba
}

2. Safely Load the Script in Your `.zshrc`

Now, add the following lines to the end of your ~/.zshrc file. This code safely checks if your shortcut file exists before trying to load it.

# Load Oracle DB shortcuts if the file exists
if [ -f "$HOME/.zsh_oracle_shortcuts" ]; then
  source "$HOME/.zsh_oracle_shortcuts"
fi

3. Reload Your Shell

For the changes to take effect, either restart your terminal or run source ~/.zshrc.

4. Use Your New Shortcuts

You can now connect to your database instantly with these simple commands:

sql-dev: Connect as your developer user.
sqlcl-dev: Connect as your developer user using the local sqlcl tool.
sql-system: Connect as the SYSTEM administrator.
sql-sys: Connect as the SYS superuser.

Changing the Developer Password

If you need to change the dev user's password in the future, follow these three steps:

Connect as an Admin: Log in as SYSTEM or SYS using one of your shortcuts (sql-system or sql-sys).
Alter the User: Run the ALTER USER command with your new password:
```
 ALTER USER dev IDENTIFIED BY MyNewSecret123;
```
Update Your Shortcuts: This is critical. Immediately edit your ~/.zsh_oracle_shortcuts file and update the old password to the new one in both the sql-dev and sqlcl-dev functions. If you don't do this, your shortcuts will stop working.

Keeping Your Shortcuts Working After Container Restarts

Your shell shortcuts will continue working seamlessly after recreating the container, as long as:

Container name matches: --name oracle-free
Volume is attached: -v oracle-data:/opt/oracle/oradata
Passwords are preserved (automatic when using the same volume)

If all three match, your shortcuts work immediately — no reconfiguration needed.

Cover Photo by BoliviaInteligente on Unsplash

I Built a Voice-Controlled Plant Sitter in Python with Goose & Gemini CLI

Smyekh David-West — Thu, 13 Nov 2025 19:02:53 +0000

Ever killed a houseplant because you forgot to water it? I have. Twice.

Here’s how I built a hands-free plant care assistant, the architectural nightmare I ran into, and how an AI subagent helped me solve it.

🪴 The Journey

Here’s a look at the journey from a simple seed of an idea to a fully-grown application. Follow along to see how it grew.

🌱 Planting the Seed

Tools for the Job

🌿 The Growth

The Architecture That Almost Broke Me
The Breakthrough: Embracing Process Isolation
The Last Mile: Making It Real

🌻 The Harvest

The Partner: My Experience Pair Programming with an LLM
The Brains: Making the Reminders "Smart"
Key Lessons Learned
The Final Product on macOS and Windows
Conclusion

Happy reading! 🪴

Mastery requires love. And sometimes, that love leads you into debugging at 2 AM because your ficus deserves better uptime.

I currently have seven houseplants. That's seven different watering schedules, seven different light preferences, and one sometimes very forgetful owner. Keeping up with their routines can become a real chore. I know because I've lost two from the initial nine to forgetfulness. And yes, they all have names, named after characters from Harry Potter.

This simple, real-world problem was the seed for my hackathon project: Smart Plant Sitter.

The theme of the CODETV & Goose Hackathon was to build an app that 'listens, moves, or reacts to anything but your keyboard'. So the vision became to build a voice-only assistant that could manage my plant collection for me. I wanted to be able to say, "Watered Minerva," and have the app remember it for me, no typing required.

Curious to see it in action? A full video demo is waiting for you at the end of the article.

Tools for the Job

To bring this vision to life, I settled on a modern Python tech stack. From the outset, I wanted to follow Gall's Law as my guiding principle:

"A complex system that works is invariably found to have evolved from a simple system that worked."

That principle guided every decision, from the first prototype to the final packaged app.

My plan was to start with the simplest possible working version and evolve it. The tools for this simple system were:

Flet: A fantastic framework for building beautiful, multi-platform desktop UIs with Python that uses Flutter under the hood. I needed a UI that would look the same across different platforms.
FastAPI: A high-performance web framework for creating the backend API that would house all the logic. This is part of my standard stack, so it was a no-brainer.
SpeechRecognition & pyttsx3: The core libraries for handling voice input and text-to-speech output.
Goose & Gemini CLI: My AI development partners in crime for this heist. I used the Gemini CLI within the Goose environment, which gave the AI direct access to my local file system to read, write, and refactor code alongside me.
OpenWeatherMap API: To provide real-time weather data for the user's location. This enables the assistant to offer intelligent, context-aware advice.
Local Data Persistence: A simple plants.json file stored in the system's standard application data directory.
Cross-Platform Design: From the beginning, the app was designed to work on macOS, Windows, and Linux. This influenced decisions like using Flet and writing platform-aware code to store the application's data in the correct system directory for each operating system.

The Architecture That Almost Broke Me

My initial goal was to create a simple, packageable desktop app. The most common advice for this is to run everything in a single process: the Flet GUI on the main thread and the FastAPI server on a background thread.

It seemed simple enough. It was not.

This approach led to a cascade of complex, frustrating, and hard-to-debug issues:

Threading Conflicts: The Flet GUI and the voice session were constantly competing for resources, making the app unresponsive.
Stateful TTS Engines: Text-to-speech libraries like pyttsx3 are stateful and have known threading issues that simple locks can't fix. My app would often speak its first line and then go silent forever.
Blocking I/O: The speech_recognition library blocks the entire thread while it's listening for audio. When run in the same process as the GUI, this would freeze the entire application.
Packaging Complexity: Trying to bundle all these conflicting concerns into a single process for packaging was a nightmare.

The Breakthrough: Embracing Process Isolation

After two days of late-night debugging with my AI subagent, it was clear: we were fighting a losing battle. The root of all these issues was the single-process model. It was the recurring theme in the troubleshooting session.

After several iterations I realised that these libraries were never designed to coexist so intimately. The breakthrough came when we stopped forcing these libraries together and instead embraced a classic software design principle: separation of concerns.

The final, stable architecture is a multi-process client-server model:

The Flet Frontend: It became a pure, lightweight client. Its only job is to display the UI and send HTTP requests to the backend.
The FastAPI Backend: Runs in a completely separate, isolated process. It handles all the heavy lifting: the stateful TTS engine, the blocking speech recognition, and all business logic.

This architecture solved everything. The frontend is always responsive, the voice session runs without interference, and the state is cleanly managed in one place. To achieve this, the main frontend.py script launches a second, identical instance of itself as a subprocess, but passes a special --run-backend flag. The child process sees this flag and starts the FastAPI server, while the parent process continues on to launch the Flet GUI.

# In frontend.py
def start_backend():
    global backend_process
    # Relaunch this same script, but pass a special flag
    # so the new process knows to run the backend server.
    command = [sys.executable, "frontend.py", "--run-backend"]

    # Use DETACHED_PROCESS on Windows to prevent the GUI from freezing
    creation_flags = 0
    if sys.platform == "win32":
        creation_flags = subprocess.DETACHED_PROCESS | subprocess.CREATE_NO_WINDOW

    backend_process = subprocess.Popen(
        command,
        creationflags=creation_flags
    )

The Last Mile: Making It Real

With a stable architecture, I turned to packaging. Because a voice-first app must run locally, packaging wasn’t optional—it was survival. But the real world always has one last challenge.

1. The macOS Microphone Permission Problem

On macOS, my packaged app was being silently blocked from using the microphone. flet pack didn't expose the advanced options needed to fix this. The solution was to use PyInstaller directly, generate a .spec file, and manually add the NSMicrophoneUsageDescription key to the app's Info.plist. This gave me the control I needed and was the final key to a working macOS app.

2. The Windows Reality Check

With the Mac version working, testing on a friend’s Windows laptop reminded me how fragile ‘cross-platform’ can be.
This is where theory meets reality. Working on a borrowed, non-technical machine meant I had to create a perfect, sandboxed development environment that could be wiped clean. It forced me to move beyond my Mac comfort zone and truly understand the OS-level quirks of deployment.

The biggest discovery? Windows has two different application data directories (%APPDATA% and %LOCALAPPDATA%). My frontend was looking in Local, while the backend was writing to Roaming. Finding that bug required hunting through the file system—a reminder that assumptions about "standard" paths don't always hold.

def get_app_data_dir(app_name):
    if sys.platform == "win32":
        return Path(os.getenv("LOCALAPPDATA")) / app_name
    elif sys.platform == "darwin":  # macOS
        return Path.home() / "Library" / "Application Support" / app_name
    else:  # Linux and other Unix-like
        return Path.home() / ".config" / app_name

The Partner: My Experience Pair Programming with an LLM

This project was a true collaboration with an AI subagent. Our partnership had a clear division of labor: I handled the Flet frontend and UX, while the AI took on the heavy lifting for the backend architecture and logic—roughly a 60/40 split in its favor.

My "rule of thumb" when using AI is simple: never let the agent make direct changes. I reviewed every suggestion, understood its implications, and applied the code myself.

My process is deliberate: I start each session with a preamble to guide the overall direction, and I embed strict instructions like "Answer in chat" or "Explain the proposed changes" in my prompts. This allows me to understand the AI's thought process and verify the implications of every change before I apply the code myself.
This human-in-the-loop process was essential.

Here are some real examples from my 48-prompt journal:

Architectural Pivot (Prompts 34-37):

"Refactor the application to run in a single process... Diagnose the resulting critical runtime failure... Revert the architecture back to the stable multi-process model, but implement it in a package-friendly way using sys.executable..."

This was the moment we hit the wall and made the crucial decision to pivot.

Advanced Packaging Attempts (Prompts 46-47):

"Refactor the application's process management from the subprocess module to Python's multiprocessing module... Following a native development pattern, create a minimal Swift 'Launcher' application in Xcode..."

These ambitious attempts to solve a cosmetic issue failed, but they taught us the limits of what was worth optimizing.

Finally, a practical note: this kind of iterative development is compute-intensive. The constant need for the subagent to read multiple files and analyze complex code meant I was glad to have a paid Gemini plan with sufficient credits, as I would have quickly hit the limits of a free tier.

The Brains: Making the Reminders "Smart"

To make the assistant genuinely helpful, I built a small "database" of 12 common houseplants. It includes watering intervals based on maturity, sunlight needs, and care tips. This allows the assistant to cross-reference this data with your plant's age and the real-time weather to give specific, actionable advice.

Key Lessons Learned

Simple Isn't Always Simple: The "obvious" single-process architecture hid enormous complexity. The breakthrough came from embracing the design that fit the tools' constraints.
AI Excels at Iteration, Humans Excel at Direction: The AI was incredible at refactoring, pattern recognition, and proposing solutions. But the strategic pivots and real-world UX validation still required human insight.
Cross-Platform Is a First-Class Concern: You can't bolt on compatibility at the end. Every decision—from file paths to process management—has platform implications.
Testing Beats Theory Every Time: No amount of reading can replace actually running your code on the target platform.

These lessons reshaped how I think about tool choice, architecture, and the creative partnership between humans and AI.

The Final Product on macOS and Windows

macOS

Windows

Conclusion

Building Smart Plant Sitter was a masterclass in the realities of software development. It taught me that architectural elegance is about finding the design that works for your specific constraints. Working with an AI subagent transformed what would have been weeks of work into days, but it also highlighted that AI is a tool that amplifies your skills rather than replacing them.

This project reminded me that software isn't built - it's grown. And that the best AI tools don’t replace developers; they just make our growth faster, and our bugs more interesting.

And now, if you'll excuse me, my ZZ Plant is telling me it's thirsty.

If you’d like to explore the code or replicate the build, you can find the full source code, including my detailed 48-prompt journal. View on GitHub

The downloadable application is available for both macOS and Windows

Beyond Text: Building an AI-Powered Color Matcher in Oracle FreeSQL

Smyekh David-West — Tue, 28 Oct 2025 21:00:53 +0000

☁️ Pre-Flight Checklist

This is a connection flight. Before we taxi down the runway, here’s your flight plan. Keep this handy to navigate your flight path.

Welcome aboard the cloud! ☁️

🌥️ Takeoff

The Core Idea: Colors are Vectors
Step 1: Create Your Color Palette

⛅️ Cruising Altitude

Step 2: The Next Level of PL/SQL - A Reusable Function
A Quick Note: Where is the Embedding Model?
Step 3: The Ultimate Color Search
Step 4: Exploring Different Distance Metrics

🌤️ Landing & Taxi

Conclusion: From Raw Data to a Practical Tool
Next Steps & Going Further

Enjoy your flight! ☁️

In the first part of this series, we introduced the exciting world of AI Vector Search by finding similar cars using Oracle's new VECTOR data type. We learned that vectors act as "GPS coordinates for meaning," allowing us to find conceptually similar items.

But vector search isn't just for text and abstract concepts. It's a powerful tool for searching any data that you can represent with numbers.

In this tutorial, we'll build a genuinely useful tool for web developers and designers: a Color Matcher. We'll use Oracle AI Vector Search to find the closest standard CSS color name to any given hex code. And just like last time, we'll do it all for free. We're using the Oracle FreeSQL sandbox because it gives us instant, browser-based access to a full-featured, modern Oracle 23ai Database without any installation or setup required.

The Core Idea: Colors are Vectors

The magic of this project is that colors are already vectors in disguise. Every color on the screen can be represented by the amount of Red, Green, and Blue it contains. This RGB value is a natural 3-dimensional vector.

A pure, vibrant red is rgb(255, 0, 0), which becomes the vector [255, 0, 0].
A dark, moody blue like rgb(25, 25, 112) becomes [25, 25, 112].
White is [255, 255, 255] and Black is [0, 0, 0].

The VECTOR_DISTANCE between two of these color vectors measures their perceptual similarity. A small distance means the colors look very similar to the human eye. This is the simple but powerful principle we'll use to build our tool.

Step 1: Create Your Color Palette

Create the Table

First, we need a dataset to search against. We will create a table containing all the standard named colors used in CSS.

--Create the table
CREATE TABLE css_colors (
  id NUMBER PRIMARY KEY,
  name VARCHAR2(50),
  hex VARCHAR2(7),
  color_vector VECTOR
);

To run the statement after pasting use crtl + Enter or ⌘ + Enter

The new css_colors table will now appear in the navigator pane on the left. A great feature of FreeSQL is that it automatically persists your work, so this table will be available in future sessions.

Populate the Table

I've placed the complete SQL script, which inserts all 140+ colors, into a GitHub Gist.

The complete SQL script to insert all 140+ colors is available in this GitHub Gist.
Please copy the entire script from the Gist and run it once in a new FreeSQL worksheet to populate the table.

After running the script, the css_colors table will be created and fully populated. You can confirm the data is there with a quick query:

SELECT name, hex FROM css_colors WHERE name IN ('Red', 'Green', 'Blue');

Step 2: The Next Level of PL/SQL - A Reusable Function

Here is where we move beyond simple queries and begin to leverage the true power of FreeSQL as a development platform. Instead of performing the hex-to-vector conversion in an external application, we can build a smart, reusable function directly in the database. This is far more efficient and demonstrates a core capability of a professional database environment. This is the perfect opportunity to level up our PL/SQL skills by creating a reusable function.

Copy and paste this code into your FreeSQL worksheet and run it to create the function:

CREATE OR REPLACE FUNCTION hex_to_vector(p_hex_string VARCHAR2)
RETURN VECTOR AS
  v_hex VARCHAR2(7);
  v_r NUMBER;
  v_g NUMBER;
  v_b NUMBER;
BEGIN
  -- Remove the '#' prefix if it exists
  v_hex := LTRIM(p_hex_string, '#');

  -- Check for valid length
  IF LENGTH(v_hex) != 6 THEN
    RAISE_APPLICATION_ERROR(-20001, 'Invalid hex code: Must be 6 characters long.');
  END IF;

  -- Convert hex pairs to decimal numbers, with error handling
  BEGIN
    v_r := TO_NUMBER(SUBSTR(v_hex, 1, 2), 'XX');
    v_g := TO_NUMBER(SUBSTR(v_hex, 3, 2), 'XX');
    v_b := TO_NUMBER(SUBSTR(v_hex, 5, 2), 'XX');
  EXCEPTION
    WHEN OTHERS THEN
      RAISE_APPLICATION_ERROR(-20002, 'Invalid hex code: Contains non-hexadecimal characters.');
  END;

  -- Return the final result using the string constructor for reliability
   RETURN VECTOR('[' || TO_CHAR(v_r) || ',' || TO_CHAR(v_g) || ',' || TO_CHAR(v_b) || ']');
END;
/

How it Works:

Lines 1-6: The Setup Area

This section defines our tool. It says we're creating a function named hex_to_vector that accepts one piece of text (the hex code) and promises to return a VECTOR. We also set up a few empty "boxes" (variables) to hold our values as we work.

Line 8: Cleaning the Input

The LTRIM function tidies up the input by trimming the # symbol from the left side. This lets us work with just the six important characters of the color code.

Lines 11-13: First Safety Check.

A valid hex color code must contain exactly six characters. This IF statement checks the length. If it's not six, the function stops immediately and uses RAISE_APPLICATION_ERROR to show a helpful, custom error message instead of just crashing.

Lines 16-23: The "Try-Catch" Safety Net.

This BEGIN...EXCEPTION...END block is the most important safety feature.

Inside BEGIN, we try the riskiest part: converting the text characters into the numbers for our vector. The code grabs two characters at a time (e.g., 9B) and converts them from hexadecimal into a regular number (e.g., 155).
The EXCEPTION block is our safety net. If a user enters something invalid like #FFG000, the TO_NUMBER function will fail on the character 'G'. Instead of crashing, the code immediately jumps to the EXCEPTION block, which catches the error and displays our second helpful message.

Line 26: Assembling the Final Vector.

If the input has passed all our safety checks, this final line builds the result. It converts the three numbers for red, green, and blue into text and carefully assembles them into a string with brackets and commas, like '[155,89,182]'. This string is then passed to the VECTOR function, which creates the final vector object. We use this string-building method because it's a very reliable way to create a vector that avoids potential database bugs.

Once you run the script, the function is created. You can see it listed under the Functions tab in the navigator pane on the left. A great feature of FreeSQL is that it automatically saves your functions and tables, so you can come back and use them in future sessions without having to create them again.

A Quick Note: Where is the Embedding Model?

If you're familiar with AI search, you might be wondering: where is the "embedding model"? It's a great question, and the answer reveals the different ways vectors can be created.

Whether you need an embedding model depends entirely on your source data. In practice, there are three main approaches to generating vectors:

1. Natural Vectors (The Color Example)

Our color data (#0000FF) is a direct, universally defined representation of a vector ([0, 0, 255]). The data is already a vector. Our hex_to_vector function isn't an AI model; it's just a decoder that translates one format to another. No model is needed.

2. Feature-Engineered Vectors (The Car Example)

In the first article, we used a vector like [9.5, 8] to represent a car's [Performance, FuelConsumption]. This is a "middle ground." If your source data is structured (e.g., a table with horsepower and mpg columns), you can manually create a vector by defining a formula. For example, Performance = horsepower / 50. This is a classic data science technique called feature engineering. No AI model is needed because a human is defining the logic.

3. AI-Generated Vectors (Text & Image Search)

If your source data is unstructured (e.g., a text description like "a sleek sports car with a roaring V8 engine"), you have no numbers to start with. This is where you must use an embedding model. The AI model reads the text and creates a vector that captures its semantic meaning.

Here’s a summary:

Data Source	Method	Model Needed?	Example
Natural Vector	Direct Decoding	No	Colors (`#FF0000` -> `[255,0,0]`)
Structured Data	Feature Engineering	No	Cars (using `horsepower`, `mpg`)
Unstructured Data	AI Embedding	Yes	Text ("a sleek sports car...")

Understanding this distinction is key to knowing which tools to use for your own vector search projects.

Step 3: The Ultimate Color Search

Now that we have our data table and our helper function, we can perform the search. This single, elegant query combines everything we've built.

Let's find the closest named colors to a custom purple, #9B59B6.

-- Find the 5 closest named colors to a given hex code
SELECT
  name,
  hex,
  ROUND(VECTOR_DISTANCE(hex_to_vector('#9B59B6'), color_vector, EUCLIDEAN), 2) AS distance
FROM css_colors
ORDER BY distance ASC
FETCH FIRST 5 ROWS ONLY;

When you run this, you'll get a result like:

Color	Hex	Distance
MediumOrchid	`#BA55D3`	42.64
MediumPurple	`#9370DB`	44.29
DarkOrchid	`#9932CC`	44.82
SlateBlue	`#6A5ACD`	54.14
BlueViolet	`#8A2BE2`	65.89

It works perfectly! The database calculated the "visual distance" between our custom purple and all 140+ colors in the table and returned the 5 closest matches.

🌩️ A Quick Clarification: The Swatch column is purely for visual presentation in this article. Our SQL query retrieves the raw data—the color name, hex code, and distance—from the database. The database itself simply stores and returns the data, not the visual swatch.

Step 4: Exploring Different Distance Metrics

So far, we've used EUCLIDEAN distance to find the most visually similar colors. But one of the most powerful features of Oracle AI Vector Search is its support for multiple distance algorithms. Each one measures "similarity" in a slightly different way, which can lead to different results.

Let's turn our query into a more powerful educational tool by making the distance metric itself interactive.

-- Find the 5 closest colors using a user-provided hex code AND distance metric
SELECT
  name,
  hex,
  ROUND(VECTOR_DISTANCE(hex_to_vector('&your_hex_code'), 
  color_vector, &distance_metric), 2) AS distance
FROM css_colors
ORDER BY distance ASC
FETCH FIRST 5 ROWS ONLY;

Now, when you run this, FreeSQL will prompt you for both the hex code and the distance metric (e.g., EUCLIDEAN, COSINE, DOT, HAMMING, or MANHATTAN).

A Critical Warning: The Default Metric and the 'Black' Sheep

What happens if you don't specify a metric in the prompt? It's crucial to know that COSINE is the default. If you try to run the query with COSINE (or leave the &distance_metric prompt blank), you'll hit an error:

ORA-03087: unable to convert BINARY_FLOAT or BINARY_DOUBLE NaN (Not a Number) value to NUMBER

This happens because your SELECT query must calculate the distance between your input color and every other color in the css_colors table to find the top 5 closest matches. When the query's process reaches the row for "Black", it attempts to calculate the distance between your color and the vector [0, 0, 0]. Since the "Black" vector has a length of 0, and the Cosine formula involves dividing by the vector's length, this specific comparison fails with a division-by-zero error, stopping the entire query. This is a fantastic practical lesson: always know your defaults and how they interact with your entire dataset.

Comparing The Results

Let's see how the top 5 closest colors to our custom purple (#9B59B6) change when we use different metrics. The original EUCLIDEAN search gave us a list of purples and blues. But other metrics see the world differently.

EUCLIDEAN Distance

This is the metric we used in Step 3, and it's the most intuitive way to measure distance. EUCLIDEAN distance calculates the straight-line, "as the crow flies" path between the two color vectors in 3D space. It's calculated using the Pythagorean formula: sqrt((R1-R2)^2 + (G1-G2)^2 + (B1-B2)^2). As the results from the previous step showed, this metric is excellent for finding colors that are perceptually very similar.

DOT Product Results

ROUND(VECTOR_DISTANCE(hex_to_vector('#9B59B6'), color_vector, DOT), 2) AS distance

The DOT product is a similarity score, not a true distance. It's calculated by multiplying the corresponding R, G, and B values of the input vector and the vector it's being compared to (which happens for every vector in the table): (R1*R2) + (G1*G2) + (B1*B2). A larger value means more similarity. Oracle returns the negative of the dot product so that smaller results are still "closer." This metric favors colors that are bright in the same channels as our input color. This is because a high value in one vector (e.g., a high Red value in your input) only contributes significantly to the total score if it's multiplied by a correspondingly high value in the other vector. The final score is the sum of these products, so it's maximized when brightness in the R, G, and B channels align. Notice how it returns bright, almost white colors, as they have high R, G, and B values that contribute to a large dot product.

Color	Hex	Distance
White	`#FFFFFF`	-108630
Snow	`#FFFAFA`	-107275
GhostWhite	`#F8F8FF`	-106922
Azure	`#F0FFFF`	-106305
MintCream	`#F5FFFA`	-106170

HAMMING Distance Results

ROUND(VECTOR_DISTANCE(hex_to_vector('#9B59B6'), color_vector, HAMMING), 2) AS distance

HAMMING distance simply counts how many components (R, G, or B) are different between two vectors. For [R1, G1, B1] and [R2, G2, B2], it checks if R1 != R2, G1 != G2, and B1 != B2 and sums the true results. The maximum possible distance is 3. This metric is not very nuanced for colors, as it only cares if the values are an exact match or not, which is rare. This is why you see a tie between several colors that all differ from our input purple in all three (R, G, and B) components.

Color	Hex	Distance
AliceBlue	`#F0F8FF`	3
AntiqueWhite	`#FAEBD7`	3
Aqua	`#00FFFF`	3
Aquamarine	`#7FFFD4`	3
Azure	`#F0FFFF`	3

MANHATTAN Distance Results

ROUND(VECTOR_DISTANCE(hex_to_vector('#9B59B6'), color_vector, MANHATTAN), 2) AS distance

The MANHATTAN distance (or "city block" distance) is calculated by summing the absolute differences of each component: |R1 - R2| + |G1 - G2| + |B1 - B2|. It's like traveling on a grid, one axis at a time. The results are very similar to EUCLIDEAN distance, as both measure perceptual difference, but MANHATTAN gives slightly more weight to the sum of individual channel differences than the direct "as the crow flies" distance.

Color	Hex	Distance
DarkOrchid	`#9932CC`	63
MediumOrchid	`#BA55D3`	64
MediumPurple	`#9370DB`	68
SlateBlue	`#6A5ACD`	73
MediumSlateBlue	`#7B68EE`	103

As you can see, the "best" match depends entirely on your definition of similarity. For finding visually similar colors, EUCLIDEAN or MANHATTAN are clearly the best choices. For other tasks, other metrics might be superior. Choosing the right one is a critical part of designing a successful vector search application.

Conclusion: From Raw Data to a Practical Tool

Congratulations! You've built a practical color-matching tool and experienced the power of a professional database environment firsthand.

In this tutorial, you have:

Seen how vector search can be applied to non-text data like colors.
Leveled up your PL/SQL skills by creating a powerful, reusable function.
Experienced how FreeSQL provides a zero-install sandbox to build and test real, data-centric application logic.

This reinforces the power of keeping your logic close to your data. By creating a function directly in the database, we built a fast, efficient, and elegant solution.

Happy building! ☁️

Next Steps & Going Further

The tool you've built is complete, but the concepts can go even further. Here are a few ideas to keep in mind for future projects:

Indexing for Performance

Our table of 140 colors is tiny for an Oracle database. But if you were building a search engine for millions of items, a sequential scan would be too slow. For this, you would add a vector index.

-- Example of creating a vector index
CREATE VECTOR INDEX color_idx ON css_colors (color_vector)
ORGANIZATION INMEMORY NEIGHBOR GRAPH
DISTANCE COSINE;

This command creates an Approximate Nearest Neighbor (ANN) index, which allows the database to find the "closest" vectors almost instantly without having to compare your query with every single row. This is the critical step for taking a vector search prototype to a production-level application.

Exploring Other Use Cases

This vector technique is powerful for internal resource management. Imagine a project manager needs to assign a critical task: "Build a data-driven backend prototype and present it to stakeholders." The required skills could be quantified as a vector, for example: [Python, SQL, PublicSpeaking, Design].

The ideal profile for this specific task might be [9, 8, 7, 1], representing a need for strong Python/SQL, good presentation skills, and no design experience.

Instead of manually searching through employee profiles or relying on memory, the manager could run a query to find the best fit instantly:

-- Find the best available employee for a specific task profile
SELECT
  employee_name,
  current_project_load
FROM employees
WHERE availability = 'Available'
ORDER BY VECTOR_DISTANCE(skill_vector, VECTOR('[9, 8, 7, 1]')) ASC
FETCH FIRST 3 ROWS ONLY;

This query would instantly surface the top 3 available employees whose skills most closely match the task's requirements. It's a data-driven approach that enables fast, effective, and unbiased task allocation within an organization.

Keep exploring what you can build! ☁️

Cover Photo by BoliviaInteligente on Unsplash

Your First AI-Powered Search on Oracle Cloud: A Beginner's Guide to Vectors

Smyekh David-West — Thu, 23 Oct 2025 23:54:22 +0000

☁️ Pre-Flight Checklist

This is a connection flight. Before we taxi down the runway, here’s your flight plan. Keep this handy to navigate your flight path.

Welcome aboard the cloud! ☁️

🌥️ Takeoff

The Core Idea: What is a Vector, Anyway?
Your Free AI Sandbox: No Install Required

⛅️ Cruising Altitude

Step 1: Create Your First Vector-Enabled Table
Step 2: Insert Your Car Profiles
Step 3: Find Similar Cars with SQL
From SQL to Application Logic with PL/SQL

🌤️ Landing & Taxi

Next Steps: Performance and Other Metrics
Conclusion: Your Journey into AI on OCI

Enjoy your flight! ☁️

Let's be honest, as developers, we're used to precise, literal searches. If you query your database for status = 'completed', you get records where the status is exactly 'completed'. But what if you wanted to find things that are conceptually similar? What if you wanted to find a "quick automobile" when your data only contains "fast car"?

That's where the world of AI and vector search comes in, and it's not as scary or complicated as it sounds. In fact, if you know basic SQL, you're already halfway there.

Today, we'll break down the fundamentals of vector search and show you how to run your very first similarity search using nothing but your browser and Oracle's completely free SQL sandbox, a service that's part of the Oracle Cloud ecosystem.

The Core Idea: What is a Vector, Anyway?

Forget the complex math for a second. Think of a vector as GPS coordinates for meaning.

An AI model, called an "embedding model", reads a piece of data and converts it into a list of numbers. For our car example, imagine a vector where the first number is performance (higher is better) and the second is fuel consumption (lower is better).

A "sleek, powerful sports car" might get a vector like [9.5, 8] (High performance, high fuel use).
An "efficient, reliable hybrid" might get a vector like [6, 3] (Medium performance, low fuel use).

The goal of vector search is to find the "nearest neighbors" to a query vector by calculating the distance between these coordinates.

Your Free AI Sandbox: No Install Required

Go to https://livesql.oracle.com/
Sign in with a free Oracle account (or create one).
Once you login, you should see the page layout below

That's it! You have a full-featured Oracle Database ready for your commands.

Step 1: Create Your First Vector-Enabled Table

In Oracle Database 23ai, storing these "meaning coordinates" is incredibly simple with the new VECTOR data type.

Let's create a table to store our car profiles. Copy and paste this into your SQL worksheet:

CREATE TABLE car_profiles (
   id NUMBER PRIMARY KEY,
   car_description VARCHAR2(100),
   performance_consumption_vector VECTOR
);

To run the statement after pasting use crtl + Enter or ⌘ + Enter

Once you create a table, FreeSQL automatically saves it for your next session.

Step 2: Insert Your Car Profiles

A Quick Note: In a real application, an AI model would generate these vectors. For the purpose of this demonstration, we'll create simple, 2-dimensional vectors ourselves to focus on learning the powerful database-side of vector search.

Here are the profiles we'll be working with, where the vector represents [Performance, Fuel Consumption].

ID	Description	Vector	Meaning
1	"Perfect high-performance hybrid"	`[10,2]`	Ideal car profile
2	"Sporty fuel-efficient coupe"	`[9,2.5]`	Slightly less powerful but efficient
3	"Old gas-guzzling truck"	`[4,10]`	Poor fuel economy
4	"Balanced midrange sedan"	`[7,5]`	Decent balance
5	"Economy compact car"	`[6,3]`	Modest power, great fuel economy
6	"Luxury performance SUV"	`[9.5,6]`	Powerful but thirsty
7	"Underpowered city car"	`[3,4]`	Low performance, moderate efficiency

Let's insert this data.

INSERT ALL
  INTO car_profiles VALUES (1, 'Perfect high-performance hybrid', VECTOR('[10, 2]'))
  INTO car_profiles VALUES (2, 'Sporty fuel-efficient coupe', VECTOR('[9, 2.5]'))
  INTO car_profiles VALUES (3, 'Old gas-guzzling truck', VECTOR('[4, 10]'))
  INTO car_profiles VALUES (4, 'Balanced midrange sedan', VECTOR('[7, 5]'))
  INTO car_profiles VALUES (5, 'Economy compact car', VECTOR('[6, 3]'))
  INTO car_profiles VALUES (6, 'Luxury performance SUV', VECTOR('[9.5, 6]'))
  INTO car_profiles VALUES (7, 'Underpowered city car', VECTOR('[3, 4]'))
SELECT * FROM DUAL;

-- To confirm that the data has been inserted into the table
SELECT * FROM car_profiles
ORDER BY id;

In Oracle SQL:

A single-row INSERT INTO ... VALUES (...) statement doesn’t need a source because it’s one direct action.
A multi-row insert ('INSERT ALL') is conceptually a query-based insert.

When you want to insert multiple literal rows (not coming from another table), you don’t have a real source. Oracle solves that by letting you use the DUAL table, which is a built-in one-row, one-column table.

So SELECT * FROM DUAL acts as a placeholder that makes Oracle happy.

Step 3: Find Similar Cars with SQL

The key to vector search is the VECTOR_DISTANCE function. It's like a ruler that measures the distance between our query vector and all the vectors in our table. Let's use it to rank all cars in our database by how similar they are to our "Ideal Car Profile" ([10, 2]). A lower distance means a better match.

SELECT car_description, ROUND(VECTOR_DISTANCE(VECTOR('[10, 2]'), performance_consumption_vector), 2) AS similarity_score
FROM car_profiles
ORDER BY similarity_score ASC

The ROUND()function makes numbers easier to read by limiting how many decimal places are shown.

ASC stands for ASCENDING order — it’s part of the ORDER BY clause in SQL.

Understanding the similarity scores

In the previous query, we compared every car’s vector against our “ideal” car vector [10, 2].

The VECTOR_DISTANCE function measures how far apart two vectors are, just like measuring the straight-line distance between two points on a map.

A lower number means the car is more similar to our ideal profile:

Almost identical: 0.00
Very close: 0.05
Somewhat different: 0.25
Quite different: 0.45

So in our results:

The “Perfect high-performance hybrid” and “Sporty fuel-efficient coupe” are closest to the ideal (0.00).
The “Economy compact car” and “Luxury performance SUV” are also good matches but slightly further.
The “Old gas-guzzling truck” is farthest away, it’s the least similar in performance and fuel use.

This simple ranking shows the core idea behind AI-powered vector search: finding items that are conceptually similar, not just textually identical.

From SQL to Application Logic with PL/SQL

SQL is for asking questions. But what about building application logic? For that, we turn to PL/SQL, Oracle's native programming language that lives inside the database. It lets you use variables, create logic, and handle errors, turning the database into a powerful processing engine.

What is PL/SQL?

PL/SQL (Procedural Language/SQL) was designed to overcome the limitations of pure SQL by adding procedural constructs—variables, loops, and error handling. Its key advantage is its tight integration with the SQL engine, which eliminates network overhead and results in significant performance gains for data-intensive operations.

The Anatomy of PL/SQL

If you're coming from a language like Python, the structure of a basic PL/SQL block will feel surprisingly familiar:

DECLARE
  -- This is your setup area where you declare variables.
BEGIN
  -- This is your main execution block where logic runs.
EXCEPTION
  -- This is your "try...except" block for handling errors.
END;
/

PL/SQL in Action: An Interactive Similarity Report

Let's apply this structure to build a simple, interactive report. The script will ask you to pick a car's ID and then generate a similarity report comparing that car to our "Ideal Car Profile."

Copy and paste this entire block into your worksheet and run it.

DECLARE
  -- 1. Our benchmark: the "Perfect Car Profile"
  ideal_car_profile_vector VECTOR := VECTOR('[10, 2]'); 

  -- 2.  Variables to hold the data we fetch from the table
  selected_car_vector VECTOR;
  selected_car_desc VARCHAR2(100);

  -- 3. Variable to hold the calculated distance (similarity score)
  similarity_score NUMBER;

  -- 4. This will prompt the user to enter a car ID to compare (e.g. 2 for "Sporty fuel-efficient coupe")
  car_id_to_check NUMBER := &car_id_to_compare;

BEGIN
  -- Fetch the chosen car’s vector and description from the table
  SELECT performance_consumption_vector, car_description
  INTO selected_car_vector, selected_car_desc
  FROM car_profiles
  WHERE id = car_id_to_check;

  -- Calculate how far this car is from the ideal
  similarity_score := VECTOR_DISTANCE(ideal_car_profile_vector, selected_car_vector);

  -- Display a readable report
  DBMS_OUTPUT.PUT_LINE('--- Car Similarity Report ---');
  DBMS_OUTPUT.PUT_LINE('Selected Car:      ' || selected_car_desc);
  DBMS_OUTPUT.PUT_LINE('Ideal Profile:     [10, 2] (High performance, Low fuel use)');
  DBMS_OUTPUT.PUT_LINE('Car''s Profile:        ' || TO_CHAR(selected_car_vector)); -- TO_CHAR converts the vector into a readable string
  DBMS_OUTPUT.PUT_LINE('Similarity Score:  ' || ROUND(similarity_score, 2));
  DBMS_OUTPUT.PUT_LINE('(A lower score means a better match!)');

END;
/

When you run this, it will prompt you: Enter value for car_id_to_compare:.

The & syntax is a feature of the SQL client that prompts you for input, allowing us to make the script interactive. And || is used to concatenate strings.

Enter 2 and press Enter. The script will fetch the "Sporty fuel-efficient coupe" and generate a report showing its low similarity score, proving it's a great match!

To make this even clearer, let's imagine a real-world project: building a "Similar Products" feature for an online bookstore.

The Benchmark: A customer is looking at the page for "Project Hail Mary," a popular science-fiction book. The vector for this book, which represents its genre, writing style, and core themes (space, problem-solving, humor), becomes our ideal_profile_vector.
The Candidates: Your database contains vectors for thousands of other books.
The Logic: In the background, the application runs a process just like our simple PL/SQL script. It calculates the VECTOR_DISTANCE between the "Project Hail Mary" vector and all other books in the catalog.
The Result: The books with the lowest distance score are displayed to the customer under a "You Might Also Like..." section. The system would correctly suggest other hard sci-fi novels or books with similar narrative styles, rather than a random cookbook or history textbook, because their "meaning coordinates" are closest.

Our simple, interactive script, which compares one benchmark to one new item, is the tiny engine that powers each one of those individual recommendations. By running that logic for many items, you build a complete feature.

Next Steps: Performance and Other Metrics

Distance Metrics: The default distance metric is COSINE, which is excellent for semantic text search. For our coordinate-based example, EUCLIDEAN (the straight-line distance) is also a great choice. You can specify it like this: VECTOR_DISTANCE(v1, v2, EUCLIDEAN).
Indexing for Speed: Searching through millions of vectors requires an index. Just like a book index helps you find a topic instantly, a vector index helps the database find the "nearest neighbors" without a full table scan.
This is critical for production applications, as it’s the difference between a sub-second response and a query that takes minutes on a large dataset.

CREATE VECTOR INDEX car_profiles_idx ON car_profiles (performance_consumption_vector)
ORGANIZATION INMEMORY NEIGHBOR GRAPH;

Conclusion: Your Journey into AI on OCI

Congratulations! You've just taken your first and most important step into the world of AI-powered search.
You've seen that vectors are just coordinates for meaning, and that Oracle makes it incredibly simple to store, manage, and query them using familiar SQL and PL/SQL.

This skill is a cornerstone for building modern, intelligent applications. Whether you're working with text, images, or any other unstructured data, the ability to find "conceptually similar" items is a superpower. By integrating these AI capabilities directly into the database, Oracle Cloud Infrastructure (OCI) provides a powerful, scalable, and secure platform for your next generation of smart applications. Keep experimenting! Happy Building! ☁️

The Big Picture: Technical Architecture

While our example focused on the core SQL and PL/SQL commands, it's helpful to see how AI Vector Search fits into a larger application architecture. The diagram below from Oracle's official documentation illustrates how an application, the database, and embedding models work together to provide similarity search on your data.

Oracle AI Vector Search Technical Architecture Diagram

Source: Oracle

Next Steps: Generating Vectors in Your Application

In this guide, we manually created vectors to focus on the search functionality. In a real-world application, you would use an AI "embedding model" to automatically generate these vectors from your data (like text descriptions, image pixels, or other attributes).

Ready to take the next step? The official Oracle documentation provides a detailed guide: Oracle AI Vector Search User's Guide. This is the perfect follow-up to what we've covered here.

Cover Photo by BoliviaInteligente on Unsplash

Cloud Architects are Movie Directors: An OCI IAM Story

Smyekh David-West — Thu, 02 Oct 2025 00:36:02 +0000

☁️ Pre-Flight Checklist

Before we taxi down the runway, here’s your flight plan. Keep this handy to navigate your flight path. Welcome aboard the cloud!

🌥️ Takeoff

Introduction: The Blank Set
The Film Crew: Deconstructing Cloud Roles

⛅️ Cruising Altitude

The Cast (OCI Principals)
The Set: Where the Action Happens (Compartments)
The Script (OCI Policies) A Scene in Action: A Practical Walkthrough

🌤️ Landing & Taxi

Bad Directing: Common IAM Pitfalls
Conclusion: A Secure and Efficient Production

Enjoy your flight! ☁️

Introduction: The Blank Set

Starting with a new Oracle Cloud Infrastructure (OCI) tenancy is like standing on an empty movie set. It's a space full of potential—powerful compute, vast storage, and advanced services—but nothing can happen on its own. The lights are off, the cameras aren't rolling, and the actors have no script. This is the core of cloud security: by default, nothing is allowed.

So, how do you safely and efficiently bring a complex application to life in this environment? How do you control who does what, what they can interact with, and what they can't?

The "Aha!" moment comes when you stop thinking about resources as abstract blocks and start thinking of every user and every resource as an actor in a grand production.

The Film Crew: Deconstructing Cloud Roles

In modern software development, titles like "Architect," "Developer," and "DevOps Engineer" are often intertwined, leading to confusion. Our movie production analogy helps clarify their distinct but collaborative functions.

The Director (The Cloud Architect): The Director is the visionary. They are responsible for the overall plot, the characters' motivations, and the story's structure. In the cloud, the Architect designs the master plan—the application architecture, the network layout, the data flows, and, most importantly, the high-level security and IAM strategy. They write the master "script" that governs the entire production.
The Actors & Artisans (The Developers): These are the performers and builders who bring the Director's vision to life. They write the dialogue (code), build the props (features), and act out the scenes (run the application logic). A great developer needs to understand the Director's intent (the architecture) to deliver a compelling and coherent performance.
The Production Crew (The DevOps Engineers): This crew is the master of logistics and automation. They are the stunt coordinators, special effects supervisors, and camera operators. They build and manage the machinery that makes filming efficient and repeatable (CI/CD pipelines), automate the setup and teardown of complex sets (Infrastructure as Code), and ensure the entire production runs smoothly and safely (operations and monitoring). They are the critical bridge between the Director's vision and the practical reality of shooting the film.

While their roles are different, their skills are intertwined. A good Director understands the acting process, and a great Actor knows a bit about directing. Likewise, a great cloud professional understands all three perspectives.

The Cast (OCI Principals)

In our OCI production, there are two types of actors:

Human Actors (Users and Groups): These are the people: the administrators, developers, and operators. To make them manageable, you don't give them scripts individually. Instead, you cast them into roles like "Lighting Crew" or "Sound Engineers." In OCI, these roles are Groups.
Automated Actors (Resources and Dynamic Groups): These are the non-human actors—the "robots," "drones," or "special effects" that perform tasks automatically. You cast these actors into roles using Dynamic Groups, which automatically group resources based on defined rules (e.g., all instances in a specific compartment).

The key question to ask is: "Does this resource need to make its own authenticated API calls to other OCI services?" If yes, it's an automated actor. Here are some common examples:
- Compute Instances (and Docker): A standard virtual machine is the most common type of actor. If this VM is running Docker containers, the permissions granted to the VM can be used by the processes within those containers.
- OKE Worker Nodes: The VMs in a Kubernetes cluster are perfect candidates for a Dynamic Group. This allows you to grant permissions to all your worker nodes at once, so the applications they run can securely access other OCI services like databases or object storage.
- OCI Functions: A Function is a prime example of an actor. When triggered, it might need to read a file or update a database. Placing the Function in a Dynamic Group is the standard way to grant it these permissions.
- API Gateway: A Gateway can also be an actor. It might need to invoke a private backend Function or another service. Placing the Gateway in a Dynamic Group allows it to do so securely.

The Set: Where the Action Happens (Compartments)

You can't film a movie in a single, giant warehouse. You need different sets: a castle, a spaceship, a city street. In OCI, these sets are Compartments.

Compartments are the primary way to organize and isolate your cloud resources. They are the foundational building blocks for a secure production. Instead of having one giant, confusing script for the whole studio, the Director can apply specific rules to each set. For example, the "Stunt-Actors" group might be allowed to use "pyrotechnics" (powerful resources) but only on the "Action-Scene" set (a specific compartment).

Organizing resources into compartments (e.g., by environment, project, or department) is the first and most critical step in building a manageable and secure cloud.

The Script (OCI Policies)

The script dictates every single action and interaction in the production. In OCI, the script is your set of IAM Policies.

This script is built on one fundamental rule: the Principle of Least Privilege. By default, no actor can do anything. The set is dark and silent. An action can only happen if the Director explicitly writes an allow statement in the script.

For example:
Allow group 'Developers' to manage instance-family in compartment 'Development'

This line tells a specific cast of actors (the 'Developers' group) that they are allowed to perform a specific set of actions ('manage instance-family') on a specific set ('Development' compartment).

The Studio Head (The Tenancy Administrator): This is a special role, like the head of the movie studio. They have the ultimate power to approve any script and fund any production. However, they are too busy to be involved in every scene. This role should be used sparingly, as the Director (Architect) should be the one crafting the script for the actual production.

A Scene in Action: A Practical Walkthrough

Let's tie it all together with a real-world scene.

The Scene: A user uploads their profile picture to a web application. The application backend, running on a Compute VM, needs to save this picture to an Object Storage bucket.
The Locations (Compartments): The Compute VM lives in a compartment named App-Prod. The Object Storage bucket, named ProfilePics, lives in a compartment named Assets-Prod.
The Casting (Dynamic Group): We can't give permissions to a single VM; that doesn't scale. Instead, we create a rule to automatically cast all VMs in our app compartment into a role.
- Dynamic Group Name: WebAppServers
- Matching Rule: All {instance.compartment.id = 'ocid1.compartment.oc1..exampleuniqueID'}
The Script (Policy): Now, the Director writes a very specific line in the script. This policy is attached to the Assets-Prod compartment.
- Allow dynamic-group 'WebAppServers' to manage objects in compartment 'Assets-Prod' where target.bucket.name = 'ProfilePics'

This policy is precise. It doesn't just allow any web server to write to any bucket. It says only the actors in the WebAppServers role can manage objects, and only in the specific ProfilePics bucket. That's good directing.

Bad Directing: Common IAM Pitfalls

Even the best directors can make mistakes, especially on their first film. Here are some common IAM anti-patterns framed as "bad directing."

Giving an Actor Keys to the Whole Studio: This is writing an overly broad policy, like Allow group 'Developers' to manage all-resources in tenancy. This is a security nightmare. It's lazy directing and leads to chaos.
Shooting a Movie in One Big Warehouse: This is failing to use compartments, instead putting every single resource into the root compartment. The set is chaotic, it's impossible to know who should be where, and writing a coherent script becomes impossible.
Casting the Studio Head in Every Role: This is using the highly-privileged tenancy administrator account for everyday tasks like development or testing. The Studio Head is powerful but should not be on set. Using this account for daily work dramatically increases the risk of a catastrophic mistake.

Conclusion: A Secure and Efficient Production

Thinking of yourself as a Director changes your perspective. You are no longer just connecting boxes; you are scripting a performance. You are forced to think deliberately about:

Who are my actors? (Users and Resources)
What are their roles? (Groups and Dynamic Groups)
Where can they do it? (Compartments)
What should they be allowed to do? (Policies)

This "director's mindset" is the key to moving beyond a chaotic, insecure collection of resources and creating a well-organized, secure, and efficient cloud environment.

Cover Photo by BoliviaInteligente on Unsplash

Completing Your Local OCI Lab: A Guide to Port Forwarding in UTM

Smyekh David-West — Thu, 18 Sep 2025 11:30:00 +0000

☁️ Pre-Flight Checklist

This is a connecting flight. Before we taxi down the runway, here’s your flight plan. Keep this handy to navigate your flight path.

Welcome aboard the cloud! ☁️

🌥️ Takeoff

Why You Need Port Forwarding

⛅️ Cruising Altitude

How to Set Up Port Forwarding in UTM (macOS + Linux VM)
How Port Forwarding Relates to OCI Networking

🌤️ Landing & Taxi

Conclusion

Enjoy your flight! ☁️

So far in our series, we've built a local, production-like Ubuntu VM and bridged it to our Mac with a shared folder. We have a clean environment and a seamless coding workflow. Now, we face the final hurdle: networking.

You've written a web application, and you're running it inside the VM. How do you test its API from your Mac? How do you debug the frontend in your browser? By default, the VM is a black box.

This is where port forwarding comes in. It’s not just a local convenience; it’s a fundamental skill that helps you understand and debug one of the most critical components of OCI: Security Lists and Network Security Groups (NSGs). This guide will show you how to configure port forwarding in UTM to complete your local OCI lab.

Why You Need Port Forwarding

UTM's default Shared Network mode acts like a home router for your VM. It uses Network Address Translation (NAT) to give your VM internet access while hiding it behind a virtual firewall. This is great for isolation, but it means your Mac can't directly see the services (or "ports") that your VM opens.

Port forwarding is like creating a special rule on that virtual router. It tells UTM, "Any traffic that arrives at this specific port on my Mac should be forwarded directly to that specific port inside my VM."

You need it to:

Access a web server in the VM from your Mac's browser.
SSH into your VM from your Mac's terminal.
Connect to a database or API running in the VM.
Develop with frameworks like React, Flask, or FastAPI inside the VM and view the results on your Mac.

How to Set Up Port Forwarding in UTM (macOS + Linux VM)

In these steps, I’ll show you exactly how to set up port forwarding in UTM, test it with a simple Python web server, and troubleshoot common issues.

Step 1: Configure Port Forwarding in UTM

Make sure the VM is powered off before making network changes. Port forwarding changes can’t be made while the VM is running.

Step 2: Open UTM and Select Your VM

Launch UTM.
In the main UTM window, select your Ubuntu VM from the list on the left.
Right-click and select the edit option to open the VM's configuration.

Step 3: Configure the Network

1. In the “Network” tab:

2. Set Network Mode to Emulated VLAN (Shared Network) (sometimes labelled as “NAT”). Once you do that, a Port Forward option will appear below Network

3. Add a Port Forwarding Rule:

Click New and then set:

Field	Example
Protocol	TCP
Host Address for localhost access) or leave blank for all interfaces.	127.0.0.1
Host Port (Port on your Mac)	8080 (or any open port)
Guest Address (IP of the VM)	use 10.0.2.15 or just leave blank to auto-select
Guest Port (Port on the VM)	80 (or your app’s port)

Example: Forward Mac’s localhost:8080 → VM’s port 80 (where a web server will run).

Use the top labels at the top (i.e., Protocol, Guest Address, Guest Port) to guide you for your entries.

Then save

Step 4: Run a Web Server Inside the VM

Boot into your Linux VM and run:

Install Python (if needed):

sudo apt update
sudo apt install python3 -y

Start a test HTTP server:

sudo python3 -m http.server 80

Note: Port 80 requires sudo. You can also use python3 -m http.server 8080 and adjust the port forwarding accordingly.

Step 5: Test from macOS

From your Mac Terminal, run:

curl http://localhost:8080

You should see an HTML directory listing from the VM — success! Your Mac connected to the VM’s internal web server via localhost:8080, routed through UTM’s NAT — exactly as intended.

If you curl http://localhost:8080 from your Mac without starting the test server, you get curl: (56) Recv failure: Connection reset by peer.

Why You’re Seeing a Directory Listing

That’s the default behaviour of:

python3 -m http.server 80

It serves the current directory’s contents over HTTP. Since you’re likely in / (the root directory) and there are no files there (or permissions restrict listing), the <ul> is empty.

Troubleshooting Summary

Problem	Fix
curl: (7) Failed to connect	Ensure the VM server is running and port forwarding is saved
PermissionError: [Errno 13]	Use sudo for ports below 1024
Nothing shows in the browser.	Try forwarding to guest port 8080 instead of 80

Bonus: Forward Other Services

Service	Guest Port	Host Port	Notes
SSH	22	2222	ssh user@localhost -p 2222
Flask app	5000	5000	Run with host='0.0.0.0'
JupyterLab	8888	8888	Run with Jupyter Lab --ip=0.0.0.0.
FastAPI	8000	8000	Run with uvicorn app:app --host 0.0.0.0 --port 8000
React (Vite)	5173	5173	Run with npm run dev or vite --host (or set "host": true in config)
React (CRA)	3000	3000	npm start — override with .env: HOST=0.0.0.0 if needed

With port forwarding configured, your VM is no longer an isolated box. It's a fully integrated, powerful, and safe extension of your local development environment.

How Port Forwarding Relates to OCI Networking

In OCI, nothing is accessible to the outside world unless you explicitly open a port in a Security List or NSG. Getting a "connection timed out" error because a firewall rule is missing is one of the most common issues developers face.

Port forwarding in UTM is the local equivalent of an OCI ingress rule.

The Problem: Your service is running, but you can't connect.
The OCI Solution: You add an ingress rule to your VCN's Security List for the destination port (e.g., allow TCP traffic on port 443 from source 0.0.0.0/0).
The Local VM Solution: You add a port forwarding rule in UTM (e.g., forward host port 8443 to guest port 443).

By practising this locally, you build the muscle memory for cloud networking. You learn to think about which ports your application needs and how to expose them, dramatically speeding up your debugging process when you deploy to a real OCI environment. It turns an abstract networking rule into a tangible, hands-on concept.

Conclusion

With port forwarding configured, your local lab is complete. You have successfully built an isolated, production-mirroring environment that you can code in and network with, all from the comfort of your Mac.

This three-part journey of setting up the VM, creating a shared folder, and configuring port forwarding was about more than just tools. It was about adopting the workflow of a professional cloud engineer. The initial effort to build this environment pays for itself tenfold in saved time, fewer errors in production, and a deeper understanding of how cloud infrastructure truly works. You've eliminated "it works on my machine" from your vocabulary for good.

Cover Photo by BoliviaInteligente on Unsplash

The OCI Developer's Workflow: Bridging Your Mac and Local VM with a Shared Folder

Smyekh David-West — Mon, 15 Sep 2025 10:52:26 +0000

☁️ Pre-Flight Checklist

This is a connection flight. Before we taxi down the runway, here’s your flight plan. Keep this handy to navigate your flight path.

Welcome aboard the cloud! ☁️

🌥️ Takeoff

The Goal: Edit on Mac, Run in Linux

⛅️ Cruising Altitude

How to Set Up a Shared Folder in UTM (macOS to Ubuntu 25.0 VM)
How This Workflow Benefits OCI Development

🌤️ Landing & Taxi

Conclusion

Enjoy your flight! ☁️

In our previous article, we established why running a local Ubuntu VM is a game-changer for any serious OCI professional. You now have a pristine, production-mirroring environment. But there's a problem: it's isolated. How do you get your Terraform scripts, application code, or Ansible playbooks from your Mac into the VM without a clunky, manual process?

This is where a shared folder becomes the critical bridge in your local OCI lab. It’s not just about convenience; it’s about simulating the deployment and testing workflow of a real cloud environment. You need a way to edit files on your host and immediately test them in a Linux environment that mirrors your OCI instances.

This guide will show you how to set up a persistent, high-performance shared folder using UTM and bindfs, solving the tricky permissions issues along the way.

The Goal: Edit on Mac, Run in Linux

Our objective is to create a folder on your Mac that appears inside your Ubuntu VM as a native directory. You'll be able to use your favourite macOS editor (like VS Code) to write code and instantly compile, run, and test it within the Linux environment.

How to Set Up a Shared Folder in UTM (macOS to Ubuntu 25.0 VM)

These steps will walk you through the process of sharing a folder from your macOS host to your Ubuntu guest VM. This allows you to edit code and manage files on your Mac and have them instantly accessible inside
the VM.

Part 1: Create a Shared Folder on Your Mac (Host)

First, we need a dedicated folder on your Mac that you want to share with the VM.

Open Finder and navigate to where you want to create the folder. For this guide, we'll use the desktop.
Create a new folder. You can name it whatever you like, but for this example, we'll call it UTM_Share.

Tip: You can also do this from the terminal on your mac

cd `/Desktop
mkdir UTM_share

(Optional) Place a test file inside the 'UTM_Share' folder so we can confirm the connection later. You can create a simple text file named hello_from_mac.txt.
cd UTM_share
touch hello_from_mac.txt

Part 2: Configure Sharing in UTM

Next, we need to tell UTM which folder to share and what to call it.

Important: You must shut down your virtual machine before changing its hardware settings, including shared directories.

Shut down your Ubuntu VM.
In the main UTM window, select your Ubuntu VM from the list on the left.
Right-click and select the edit option to open the VM's configuration.
Navigate to the Sharing tab from the list on the left.
Click on the browse button to add a new shared directory.
Navigate to and select the UTM_Share folder you created on your Desktop.
The "Name" field will auto-populate with UTM_Share. This is the "mount tag" we will use inside the VM. You can leave it as is.
Ensure the "Read Only" checkbox is unchecked if you want to write files from within the VM.
Click Save to close the VM settings.

Part 3: Mount the Shared Folder in Ubuntu (Guest)

Now, we'll start the VM and mount the shared directory so we can access the files.

1. Start your Ubuntu VM and login

2. Open a terminal and create a mount point:

sudo mkdir -p /mnt/utm

3. Open `/etc/fstab` with a text editor:

Open your fstab file:

sudo nano /etc/fstab

Add the following to the end

# UTM Shared Folder
share /mnt/utm 9p trans=virtio,version=9p2000.L,rw,_netdev,nofail,auto 0 0

Save with Crtl + O, press Enter, then Ctrl + X.

TROUBLESHOOT STEP

In the UTM docs you’re told to follow this step after:

Apply Mount Now (Without Reboot)

sudo systemctl daemon-reload
sudo systemctl restart network-fs.target
systemctl list-units --type=mount

Now check:

ls /mnt/utm

But you may get this:

Failed to restart network-fs.target: Unit network-fs.target not found.

This is expected in some modern Ubuntu setups (especially 25.04). It’s not a blocker at all. Since network-fs.target isn’t available, just mount manually to confirm it works:

sudo mount /mnt/utm

Now check:

ls -na /mnt/utm

You should see something like:

drwxr-xr-x  3 502 20  96 Jun 26 20:31 .
-rw-r--r--  1 502 20  14 Jun 26 20:30 test.txt

This confirms the shared Mac folder is mounted.

4. Apply the new fstab rules:

sudo systemctl daemon-reexec
sudo mount /mnt/utm

5. Verify the mount:

ls -na /mnt/utm

You should see files like hello_from_mac.txt with UID (e.g., 501) that differs from your linux user.

Part 4: Fixing Permissions Using bindfs

The shared files may not be writable by your Linux user (usually UID 1000). By default, files in /mnt/utm may be owned by macOS UID 501 and GID 20, which doesn’t match your Ubuntu user’s UID/GID (usually 1000:1000). You might get permission denied errors when writing files. Use bindfs to remap ownership.

1. Install bindfs:

sudo apt update
sudo apt install bindfs

2. Check UID and GID:

id -u   # should return 1000
id -g   # should return 1000

3. Check UID/GID of /mnt/utm:

ls -na /mnt/utm

Look for numbers like 501 (UID) and 20 (GID).

4. Create a remapped mount directory:

mkdir ~/utm

5. Add this second mount to /etc/fstab:

Open your fstab file:

sudo nano /etc/fstab

Add this line:

# bindfs mount to remap UID/GID
/mnt/utm /home/smyekh/utm fuse.bindfs map=501/1000:@20/@1000,x-systemd.requires=/mnt/utm,_netdev,nofail,auto 0 0

⚠️ Replace ‘smyekh’ with your actual Linux username if different.

map=501/1000 remaps UID 501 → 1000
@20/@1000 remaps GID 20 → 1000
x-systemd.requires=/mnt/utm ensures it’s mounted after /mnt/utm

Save (Ctrl + O, Enter, Ctrl + X)

6. Reload and mount:

sudo systemctl daemon-reload
sudo mount /home/smyekh/utm

⚠️ Again replace ‘smyekh’ with your actual username.

If you get an error saying the mount point is not empty:

ls -A ~/utm
# If it contains files, it's because /mnt/utm was already populated.
# This confirms sharing is working. You can safely continue.

7. Final Verification

echo "Synced via bindfs!" > ~/utm/test_from_linux.txt

Check your Mac's UTM_Share folder, test_from_linux.txt should be there!

Troubleshooting Summary

Issue	Fix
permission denied when writing to /mnt/utm	Use bindfs to remap UID/GID
network-fs.target not found	Ignore; not critical for UTM/9p
mount: mountpoint is not empty	It’s fine if files are present already
No shared files visible	Confirm UTM Sharing settings and folder path
Files don’t appear on Mac	Ensure writing to ~/utm and not directly to /mnt/utm

You now have a fully working shared folder between macOS and Ubuntu using UTM’s VirtFS and bindfs to handle permissions. This setup is persistent across reboots and ideal for syncing files, sharing projects, and bridging workflows between host and guest environments.

I used the UTM documentation (official UTM VirtFS guide), which explains how to mount shared folders using the 9p filesystem (9pfs) via VirtIO.

How This Workflow Benefits OCI Development

Simulating Code Deployment: In OCI, you don't code directly on the production server. You write code locally and deploy it. A shared folder perfectly mimics this: your Mac is your workstation, and the ~/utm directory in your VM is the "deployed" target.

Testing Infrastructure as Code (IaC): Imagine you're writing a Terraform script to provision an OCI network. You can edit the .tf files in VS Code on your Mac, and because the folder is shared, you can immediately run terraform plan inside the VM. The VM has the OCI CLI and a Linux environment, ensuring your script behaves exactly as it will in a CI/CD pipeline or a bastion host.

Developing and Testing Applications: You can write your Python, Go, or Node.js application on your Mac, and the code is instantly available in the VM to be compiled, run, and tested against Linux-specific dependencies.

Conclusion

This setup combines the best of both worlds: the rich user interface of macOS and the production-parity environment of your Linux VM. Happy coding

You've now engineered more than just a shared folder; you've built a professional workflow. This setup combines the rich UI of macOS with the production-parity environment of your Linux VM, creating a tight feedback loop for developing and testing OCI solutions.

But what about networking? In our next and final guide in this series, we'll tackle the last piece of the puzzle: port forwarding. We'll show you how to access web servers and other services running inside your VM directly from your Mac, completing your local OCI lab setup.

Cover Photo by BoliviaInteligente on Unsplash

DEV Community: Smyekh David-West

How to Actually Use AI to Build Production Software, End to End

The Blueprint

The Foundation

The Stack

The Build

Before You Write a Line of Code: Use the CLI, Not Just the Browser

Getting started with Claude Code:

Getting started with Gemini CLI:

First, a Word on Vibecoding vs. Knowing What You're Doing

I Built a Voice-Controlled Plant Sitter in Python with Goose & Gemini CLI

1. Database and Cloud Infrastructure: Oracle Cloud (OCI), the Slept-On Giant

2. Hosting and DNS: Cloudflare, Far More Than a Domain Registrar

3. Backend: FastAPI, Python That Actually Moves

4. Schema Management: Liquibase vs. ORMs, and Why the Distinction Matters

What is an ORM?

Oracle DB vs. PostgreSQL vs. MongoDB:

5. Version Control and CI/CD: GitLab Is Doing More Than You Think

6. Frontend: Start Vanilla, Graduate When Ready

7. Mobile: Flutter and Fastlane, With Realistic Expectations

The Bigger Picture: Architecture Is the Job Now

Step-by-Step: From Idea to Production

Step 1: Open VSCode and Start in the Browser

Step 2: Move to Warp for CLI Sessions

Step 3: Structure Your Backend as a Modular Monolith

Step 4: Containerise Everything with Docker and Docker Compose

How this connects to your GitLab pipeline

Step 5: Write Your Schemas in Python, Manage the Database with Liquibase

Step 6: Provision Oracle Cloud with Terraform

Step 7: Push to GitLab and Set Up CI/CD

What goes in CI/CD variables vs. OCI Vault

A final word: logs are your best friend.

Stack Summary

Axios Hijack Post-Mortem: How to Audit, Pin, and Automate a Defense

Why This Happened: The SemVer Caret Problem

The Fix: Pin to the Golden Version

What If Axios Is a Transitive Dependency?

Forensic Audit: Were You Hit?

1. Lockfile Entropy Check

2. Filesystem Dropper Verification

Automating Prevention in CI/CD

A. Lockfile Integrity Enforcement

B. Dependency Scan as a Kill-Switch

C. npm audit with Failure Thresholds

D. Egress Restriction on Build Runners

Summary

Rebooting a Production VM on Oracle Cloud: A Reference Guide

☁️ Pre-Flight Checklist

🌥️ Takeoff

⛅️ Cruising Altitude

🌤️ Landing & Taxi

Prerequisites

Part 1 — Pre-Reboot Checklist

1.1 Verify no critical process is mid-flight

1.2 Validate your Compose configuration

1.3 Read your apt upgrade output

1.4 Understand the service restart messages

1.5 Check available disk space

Part 2 — Running the Reboot

Part 3 — Post-Reboot Verification

3.1 Check the Docker daemon

3.2 Check all containers are up

3.3 Watch the live logs

3.4 Check additional system services

Part 4 — Measuring Time to Recovery (TTR)

4.1 Measure OS boot time

4.2 Find the bottleneck in the boot sequence

4.3 Find the exact moment containers started

4.4 Build your full TTR timeline

4.5 Use TTR to plan user communications

Quick Reference: All Commands

Troubleshooting Reference

Why the Best Errors Are ORA Errors: A Love Letter to Loud Failures

The Oracle Philosophy: Fail Fast, Fail Clearly

Modern Web Frameworks Are Learning the Same Lesson

Liquibase and the Error Chain

The Silent Killers: When Errors Don't Happen

Exception Handling: Anticipating vs. Discovering Problems

Development Errors as Production Insurance

The Cost of Retrofitting Strictness

1.3 Read your `apt upgrade` output

The First Attempt: `ALTER SYSTEM`

The Breakthrough: The `docker exec` Recovery

`SHOW PARAMETER <parameter_name>`

`V$SYSTEM_PARAMETER`

`V$PARAMETER`

`V$SGA`

`V$VECTOR_MEMORY_POOL`

The "IAM Policy": Why Our `dev` User Needs `GRANT`s

What does `-d` do?

What does `-e ORACLE_PWD` do?

What does `-v oracle-data:/opt/oracle/oradata` do?

A Quick Note: `SYS`, `SYSTEM`, and `AS SYSDBA`

Step 2: Create the `dev` User