DEV Community: Wade Thomas

TanStack Start Basics Part 2 — Connecting to Your Directus Backend

Wade Thomas — Thu, 10 Sep 2026 22:00:04 +0000

Our frontend has been static so far — just hardcoded headings on a few pages. Today we connect it to the Directus backend built earlier in this series, using the official Directus SDK to pull real product data into our TanStack Start app.

Installing the Directus SDK

There are a few ways to talk to Directus from a frontend — the REST API directly, GraphQL — but the SDK is the cleanest option, and what we're using here.

npm install @directus/sdk

Creating the Directus Helper

Inside src/lib, create a new file: directus.ts.

import { createDirectus, rest } from '@directus/sdk'

export const directus = createDirectus('Your_Directus_Project_URL').with(rest())

createDirectus initializes a connection client between your app and your Directus instance. On its own it starts empty — capabilities get added by chaining .with(). Since we're fetching over standard HTTP REST requests, we pair it with the rest() modifier.

Defining Our First Type

Inside src, create types/index.ts:

export interface Products {
  id: string
  name: string
  brief: string
  description: string
  price: number
  sale: number
  quantity: number
  isOnSale: boolean
  category: string
  image: string
}

Writing the Fetch Function

Back in directus.ts:

import { createDirectus, rest, readItems } from '@directus/sdk'
import type { Products } from '@/types'

export const directus = createDirectus('Your_Directus_Project_URL').with(rest())

export async function getProducts(): Promise<Products[]> {
  return directus.request(
    readItems('products', {
      fields: [
        'id',
        'name',
        'brief',
        'description',
        'price',
        'sale',
        'quantity',
        'isOnSale',
        'category',
        'image',
      ],
    }),
  )
}

readItems is a built-in SDK helper that generates a request for fetching multiple items from a given collection. At this point, TypeScript throws:

Type 'Record<string, any>[]' is not assignable to type 'Products[]'.

Fixing the Schema Error

This happens because the SDK doesn't automatically know your database's actual shape — it needs a Schema type passed into createDirectus:

type Schema = {
  products: Products[]
}

export const directus = createDirectus<Schema>('Your_Directus_Project_URL').with(rest())

This declares that a products collection exists and maps to an array of Products. With this in place, the error resolves — and as a bonus, TypeScript now validates and autocompletes the fields array against this type too.

Fetching the Data — Method 1: TanStack Query

Install it:

npm i @tanstack/react-query

Set it up in __root.tsx:

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

// Create a client
const queryClient = new QueryClient()

function RootDocument({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <HeadContent />
      </head>
      <body>
        <QueryClientProvider client={queryClient}>
          {children}
        </QueryClientProvider>
        <Scripts />
      </body>
    </html>
  )
}

Why does RootDocument take a children prop, and why wrap it? __root.tsx wraps your entire application — every route (About, Index, Products) gets passed in as children, rendered inside this HTML shell. Wrapping children with the query provider means every nested route and component now has access to TanStack Query.

Now build the component, src/components/Products.tsx:

import { useQuery } from '@tanstack/react-query'

export default function Products() {
  const { data: products, isLoading: loading } = useQuery({
    queryKey: ['product'],
    queryFn: getProducts,
    staleTime: 5 * 60 * 1000,
    gcTime: 15 * 60 * 1000,
    refetchOnWindowFocus: false,
    retry: 2,
    refetchOnMount: true,
  })

  if (loading) {
    return <div className="container mx-auto p-8">Loading...</div>
  }

  return (
    <div>
      <div className="container mx-auto p-8">
        <h1 className="text-4xl font-medium mb-4">Products</h1>
        <div className="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-6">
          {products?.map((product) => (
            <div key={product.id} className="border rounded-lg p-4">
              <h2 className="text-xl font-bold mb-2">{product.name}</h2>
            </div>
          ))}
        </div>
      </div>
    </div>
  )
}

A quick rundown of the query options:

Option	What it does
`staleTime`	How long fetched data stays "fresh" (5 min) before a refetch is considered
`gcTime`	How long unused data stays cached in memory (15 min) before being cleared
`refetchOnWindowFocus`	Whether switching tabs and back triggers a refetch (off here)
`retry`	Silent retry attempts on failure before giving up (2 here)
`refetchOnMount`	Whether the component checks for stale data and refetches on every mount (on here)

Wire it into the route:

import Products from '@/components/Products'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/products')({
  component: RouteComponent,
})

function RouteComponent() {
  return (
    <div className="p-8">
      <h1 className="font-bold text-5xl text-slate-700">Products</h1>
      <Products />
    </div>
  )
}

Visit localhost:3000/products — real product data, pulled live from Directus.

Fetching the Data — Method 2: Route Loaders

Loaders work a little differently, and only on routes directly — not on standalone components. Remove the Products component from the route and build it in directly:

import { createFileRoute } from '@tanstack/react-router'
import { getProducts } from '@/lib/directus'

export const Route = createFileRoute('/products')({
  loader: async () => {
    const products = await getProducts()
    return products
  },
  component: RouteComponent,
})

function RouteComponent() {
  const products = Route.useLoaderData()

  return (
    <div className="p-8">
      <h1 className="font-bold text-5xl text-slate-700 mb-4">Products</h1>
      <div className="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-6">
        {products?.map((product) => (
          <div key={product.id} className="border rounded-lg p-4">
            <h2 className="text-xl font-bold mb-2">{product.name}</h2>
          </div>
        ))}
      </div>
    </div>
  )
}

The loader runs getProducts before the route renders, and Route.useLoaderData() pulls that resolved data straight into the component — no loading state needed, since the data's already there by the time the page shows up.

Which One Should You Use?

Both approaches call the exact same getProducts function underneath — the difference is where the fetching happens and how the result reaches your component.

TanStack Query shines for data that changes often or benefits from caching, background refetching, and built-in loading states — great for a snappy feel on repeat visits.

Route loaders fetch before the route even renders, so there's no loading spinner at all. That pairs particularly well with TanStack Start's server-side rendering model, since the data can be resolved as part of the initial render rather than after the fact.

Summary

In this part, we:

Installed and configured the Directus SDK
Typed our data with a Products interface and a Schema
Built our first real fetch function using readItems
Rendered a live products grid two different ways — TanStack Query and a route loader

Right now we're only displaying each product's name, but this same pattern carries directly into fuller product cards next — pricing, images, sale badges, and eventually branding and tags once those relational fields come into play.

Found this useful? Follow for more Directus and TanStack Start tutorials, or check out the video version above.

Setting Up Our Frontend with TanStack Start

Wade Thomas — Tue, 08 Sep 2026 15:41:39 +0000

We've finished our backend across this series — a Directus instance running on a VPS managed by Coolify, backed by PostgreSQL and Redis, with a products collection already built and secured with roles and permissions.

Now it's time to build a frontend to actually display that data. For this, we're using TanStack Start, Tailwind CSS, and shadcn/ui. This post covers getting TanStack Start installed and running.

What Is TanStack Start?

Straight from the official docs:

TanStack Start is a full-stack React framework powered by TanStack Router. It provides full-document SSR, streaming, server functions, client/server builds, and more. With Vite and Rsbuild support, it's ready to develop and deploy to the hosting provider or runtime you want.

In short: it offers the same kind of full-stack capability as frameworks like Next.js or Remix, built on top of TanStack Router.

Creating the Project

First, create a folder for your app. I'm naming mine app_fe — "fe" for front end.

Naming convention tip: I use <app-name>_fe for all my frontend project folders — so an e-commerce project would be store_fe. Makes the folder's purpose obvious at a glance.

From inside that folder, run:

npx @tanstack/cli@latest create .

Note the trailing dot. Since we created the folder ourselves beforehand, the dot tells the CLI to install directly into the current directory. Omit the dot if you'd rather the CLI create a new folder for you.

Walking Through the Setup Prompts

The CLI will walk you through a series of choices:

Prompt	Selection
Select Framework	React
Select Toolchain	ESLint
Select Deployment Adapter	None (self-hosting on our own VPS)
Include demo/example pages?	No
What add-ons would you like?	shadcn/ui
Initialize a new git repository?	Yes
Continue with these settings?	Yes

Wait for the install to finish.

Running the App

Navigate into your app directory (if you aren't already there) and run:

npm run dev

Open your browser to http://localhost:3000. Congratulations — your TanStack Start app is up and running.

Editing the Home Page

Open src/routes/index.tsx. Delete everything inside the div, and save — your home page should now be completely blank. This file is your landing page, the first thing visitors see.

Add an h1 tag inside the empty div:

<h1>Home</h1>

Save, and you'll see "Home" rendered on the page. Now let's add some Tailwind styling:

<h1 className="font-bold text-5xl text-slate-700">Home</h1>

Save again — notice Tailwind works right out of the box, no extra configuration needed.

File-Based Routing

TanStack Start runs on TanStack Router, which uses file-based routing. Every file added to the routes folder automatically becomes a navigable page.

Adding an About Page

Create src/routes/about.tsx:

<div className="p-8">
  <h1 className="font-bold text-5xl text-slate-700">About</h1>
</div>

Save, then visit http://localhost:3000/about. Notice the home page lives at localhost:3000/, and the about page lives at localhost:3000/about — TanStack Start handled that routing automatically, purely based on the filename.

Adding a Products Page

Create src/routes/products.tsx the same way:

<div className="p-8">
  <h1 className="font-bold text-5xl text-slate-700">Products</h1>
</div>

Visit localhost:3000/products, and there's your new page. That's as simple as basic routing gets — there's plenty more you can do with nested and dynamic routes, which we'll cover as it becomes relevant.

What Is That `__root.tsx` File?

You've probably noticed a file called __root.tsx sitting in your routes folder. Here's the simplest way to think about it:

Picture any large website — Amazon, YouTube, anything. Every page has a header up top and often a footer at the bottom that never change, no matter what page you're on. But the content in the middle changes depending on where you navigated.

__root.tsx is the file that builds that "never changes" part. It's the frame around every page in your app. Every route you build — home, about, products — gets rendered inside this one file. Write it once, and every page automatically inherits it.

A word of caution: this file is central to how TanStack Router works under the hood. Avoid modifying it until you understand exactly what each piece does — we'll take a closer look at it in an upcoming post, exactly when it becomes relevant to what we're building.

Summary

In this part, we:

Installed and configured a new TanStack Start project
Ran it locally and confirmed Tailwind works out of the box
Learned file-based routing by building About and Products pages
Got introduced to __root.tsx, the file behind every page in the app

That wraps up our frontend setup. Next up, we'll start pulling real data from our Directus backend into this frontend — connecting everything we've built across this series.

Found this useful? Follow for more Directus and TanStack Start tutorials, or check out the video version above.

Directus Basics Part 3 — User Roles & Permissions

Wade Thomas — Fri, 21 Aug 2026 06:08:46 +0000

This is part three of our Directus Basics series. In part one we set up our instance, and in part two we covered relationships between collections. Today we're covering access control — what determines who can see and touch your data.

The Core Concepts

Access control in Directus comes down to three terms:

Permission — applies to one collection and one action (create, read, update, delete, or share). Can be full access, no access, or custom rules.
Policy — a group of permissions bundled together, applied to users or roles.
Role — defines a user's position within a project. A role can hold any number of policies, apply to any number of users, and have child roles of its own.

What Happens Without a Role?

If an administrator creates a user but doesn't assign a role, that user has valid login credentials but still can't access the Data Studio.

Creating a role and assigning the user to it isn't enough either — logging in at that point returns a "No App Access" error. The missing piece is that the role has no access policy attached. The policy is what actually tells the role what its users can and can't do.

The Access Order

Access in Directus flows in a specific direction:

Access Policy → Role → User

In practice: define what level of access a user needs, build an access policy to match, create a role and attach that policy to it, then register the user and assign them to the role.

Default Policies

Every fresh Directus instance ships with two default policies:

Administrator — the role you're signed in as by default, with unrestricted access to everything.
Public — for data that should be visible without logging in. Think of a product catalog on an e-commerce site — forcing a login just to browse products is a poor experience.

Rule of thumb: give the Public policy Read access only. Never Create, Update, or Delete. The public should be able to view data, never manipulate it.

Giving a Collection Public Access

Go to Settings → Access Policies → Public
Under Permissions, click Add Collection
Select products
Click Read, choose All Access
Save

Creating a Custom Access Policy

Let's build a policy for a data-entry team member with limited access.

Go to Access Policies, click Create
Name it DataEntry
Check App Access — leave Admin Access unchecked, since that grants unrestricted control
Save

Directus populates the policy with minimum defaults for its own system collections, but nothing for your custom collections yet.

Add products to it:

Click Add Collection, select products
Click Read, choose All Access
Save

Creating the User Role

Go to User Roles, click Create
Name it DataEntry
Under Policies, click Add Existing, select the DataEntry policy
Save

Creating the User

Go to User Directory, click Create
Fill in first name, last name, email, and password
Under Role, select DataEntry
Save

If you check back on User Roles, you'll see a 1 next to DataEntry under Users, and a matching 1 under Access Policies. That confirms the role, policy, and user are all wired together correctly.

Tip: giving your policy and role the same name (as done here with "DataEntry") makes them much easier to track as your project grows.

Testing Read-Only Access

Log in as the new user. You'll see the products collection, but attempting to edit any field does nothing — expected, since only Read access was granted.

Scrolling to the bottom of a product's detail page, some data is simply missing — those fields belong to other collections the user doesn't yet have permission for. The product image is missing too.

Fixing the Missing File Permission

Back in the DataEntry policy, notice directus_files isn't included among the accessible system collections. Without it, uploaded files — including product images — stay invisible.

Click Add Collection, select directus_files
Click Read, choose All Access
Save

Log back in as the data-entry user, and the product image now appears.

Adding the Thumbnail to List View

In list view, click the + icon on the right
Scroll to image, click the arrow next to it — not the field name itself, or you'll add the raw file ID instead of the thumbnail
Scroll to thumbnail, click outside the dropdown to confirm

Drag column headers to reorder them as needed.

Extending Access to Related Collections

The same missing-permission pattern applies to branding, products_tags and tags — add all to the DataEntry policy with Read access, and the relational fields on products become visible.

Key takeaway: you can't access a relational field in one collection unless you also have permission on the related collection. Both sides of the relationship need coverage.

Custom Field-Level Permissions

Sometimes all-or-nothing collection access isn't granular enough. Directus lets you restrict access down to individual fields.

Let's allow the data-entry user to update only the name field on products:

On the products collection, click the Update action
Choose Use Custom
Click Field Permissions
Check Name
Save, then save again

Logging back in, the data-entry user can now edit the Name field — and nothing else on that collection.

Summary

Concept	Definition
Permission	One collection + one action, set to full/none/custom
Policy	A bundle of permissions, applied to users or roles
Role	A user's position in the project; holds policies, applies to users

Access control in Directus is genuinely one of its most powerful features — this covers the fundamentals, but there's plenty more granularity available as your project grows.

That wraps part three. Next up, we'll look at how everything from this series comes together once we start pulling this data into a real front end.

Found this useful? Follow for more Directus and TanStack Start tutorials, or check out the video version above.

Directus Basics Part 2 — Understanding Relationships (M2O, O2M, M2M)

Wade Thomas — Tue, 18 Aug 2026 00:22:42 +0000

This is part two of our Directus Basics series. In part one, we set up a Directus instance and created our first collection. Today we're covering one of the most powerful features Directus offers: relationships between collections.

By the end of this article, you'll understand three core relationship types — Many to One (M2O), One to Many (O2M), and Many to Many (M2M). There's a fourth type, Many to Any (M2A), which we'll cover in a future post.

Setting Up the Branding Collection

Continuing from our existing Directus instance, let's create a new collection called branding. Select all the additional default fields Directus offers.

Add two fields:

Field	Type
`name`	String (basic input)
`description`	Text (textarea)

Once the collection is set up, add a few entries — I'd recommend at least two different brands so you can see the relationship in action once it's wired up.

Many to One (M2O): Products → Branding

Head over to your products collection. We want to connect a product to a brand.

Logically: many products can belong to one brand. That's a Many to One relationship — many products, to one brand.

Steps:

Create Field → Relational category → Many to One
Key: brand_id
Related Collection: branding
De-select Enable Create Button — you always want to choose a brand from an existing list, not create one on the fly
Save

One to Many (O2M): Branding → Products

Since one brand can have many products, we need to set up the reverse relationship explicitly on the branding collection.

Steps:

Create Field → Relational category → One to Many
Key: products
Related Collection: products
Foreign Key: brand_id — the field we just created on the products side
De-select Enable Create Button
Save

Seeing the Relationship in Action

Go back into your products collection and assign a brand to each product. Make sure at least two products share the same brand so the relationship is visible.

You'll notice each product can only belong to one brand — that's the M2O relationship at work.

Now open the branding collection and click into one of your brands. You'll see the products you just assigned show up automatically — you didn't have to add them manually. Directus handled that because of the relationship you configured.

Many to Many (M2M): Products ↔ Tags

M2M relationships work differently — both sides can have many related records.

A common real-world example: tags on products, used to improve SEO. A single product can have multiple tags, and a single tag can apply to many products.

Create the Tags Collection

Create a new collection called tags, with the same two fields as before:

Field	Type
`name`	String
`description`	Text (textarea)

Add three or four tags before moving on.

Wire Up the M2M Relationship

Back in the products collection:

Create Field → Relational category → Many to Many
Key: tags
Related Collection: tags
De-select Enable Create Button
Do not save yet — scroll down and click "Continue in Advanced Field Creation Mode"
In the sidebar, click Relationship, then find Corresponding Field
Check "Create Field" — under Field Name, you should see products appear
Save

Why the advanced flow? Under Corresponding Field, products appears automatically — that's Directus telling you it's about to create the matching relational field back on the tags collection. Unlike the M2O/O2M setup, you don't have to manually configure both sides — Directus builds the reverse relationship for you.

Now, when you add a tag to a product, Directus automatically links that product under the corresponding tag in the tags collection — no manual syncing required.

Summary

Relationship	Direction	Example
M2O	Many records → one related record	Products → Branding
O2M	One record → many related records	Branding → Products
M2M	Many ↔ many, both directions	Products ↔ Tags

Relationships are one of those Directus features that make a lot more sense once you've built one yourself than they do reading about them — so I'd recommend replicating this setup in your own instance before moving on.

That wraps up part two. In part three, we'll cover Directus permissions — how to control exactly who can see and edit your data.

Found this useful? Follow for more Directus and TanStack Start tutorials, or check out the video version on YouTube.

Directus Collections Explained (Fields, Types & Setup) — Directus Basics Part 1

Wade Thomas — Fri, 07 Aug 2026 21:12:39 +0000

This is Part 1 of a three-part series on Directus fundamentals: Collections (this post), Relationships, and Permissions. New to Directus? Start here.

Introduction

Collections are the bread and butter of the Directus Data Studio. According to Directus's own docs, collections are database tables — with extra metadata and configuration layered on top by Directus.

The part that makes this genuinely beginner-friendly: you never write a single line of SQL. The Data Studio handles all of that for you. Let's build one.

Two Ways to Create a Collection

There are two paths to collection creation inside the Data Studio.

Option 1: Log into your Data Studio and look at the sidebar for the icon that looks like a 3D box — that's Content. Click it, and on the main screen you'll see Create Collection.

Option 2: Scroll down the sidebar to the gear icon — Settings. Click in, and at the top you'll find Data Model. Same deal from there — Create Collection is right on the main screen.

Either path lands you in the same place.

Creating a Collection

Click Create Collection
Name it something intuitive — it should describe exactly what data you're storing. For this example, we're creating a collection called products
Ignore Singleton for now (more on this below)
In the Type dropdown, select Generated UUID
Click Next, select all the boxes offered, and click Finish Setup

What is Singleton? You'd only check this if the collection will ever hold exactly one item — not the case here, since we're storing many products.

What is the Generated UUID? A unique ID automatically assigned to every item in the collection, so you never have to manage IDs manually.

Once created, you land on the collection's screen, ready to build its data structure.

Bonus: under Collection Setup, you can customize how the collection looks — a color, an icon, and a short note describing its purpose. Small detail, but it pays off once your Directus project has a dozen collections in it.

Creating Fields Within a Collection

Fields represent the actual data you're storing — in this case, the data that describes a single product. Every item in the collection shares this same structure, just with different values. Here's the full field breakdown for a products collection:

Field	Type	Notes
`name`	Input (string)	The product's name
`brief`	Textarea	Short description — more room than Input, no special formatting needed
`description`	WYSIWYG	Full rich-text formatting — paragraphs, bullet lists, H1–H4 headings
`price`	Input (decimal)	See Precision & Scale below
`sale`	Input (decimal)	Same setup as `price`
`isOnSale`	Boolean	Toggle the front end can check to decide which price to show
`category`	Dropdown	Product type — e.g. jersey, pants
`quantity`	Input (integer)	Minimum value of 1
`image`	File	Product photo

Setting Up the Price Field (Precision & Scale)

The price field needs a bit of extra configuration. Instead of clicking Save right away, look just below the Save button for Continue in Advanced Field Creation Mode.

In there, you'll find Precision and Scale, defaulting to 10 and 5.

Precision — the total number of digits the field accepts
Scale — how many of those digits sit after the decimal point

Left at the defaults, you'd get something like 12345.67890. For a price field, that's overkill — we want 7 digits total, 2 of them after the decimal point. So: Precision = 7, Scale = 2. Adjust to fit your own use case if you need more decimal precision.

Build sale the exact same way.

Note on relational fields: collection relationships (linking one collection to another) are deliberately left out here — that's a big enough topic to earn its own post, and it's exactly what's coming next in this series.

Adding Your Data

Head to the sidebar and click the box icon — Content. You'll see your Products collection listed. Click Create Item, and fill in the fields with real data.

For this example, add a couple of items — a jersey and a pair of jeans — to see the collection actually holding data.

Summary

That's the foundation of Directus collections: the core field types, how to configure them, and how to get real data in. Next up in this series: relationships — how collections connect to each other, which is where Directus really starts to shine.

Questions or stuck on something? Drop a comment below.

Directus + Coolify: Should You Decouple Postgres & Redis?

Wade Thomas — Thu, 06 Aug 2026 21:25:39 +0000

This is Part 2 of the Directus + Coolify series. If you're new here, start with "Secure Your VPS Before Hackers Do" and the first Directus + Coolify post — the bundled, single-Compose-file setup — before following along with this one.

Introduction

In the first method, we coupled all of the services into one stack using a single Docker Compose file. The network between all services was created automatically, and we didn't have to start them up individually — which removes the risk of a race condition if service startup isn't handled properly.

If you're running a single app, that's genuinely the recommended way to set up Directus on a Coolify-managed VPS. Going in, I assumed there were several good reasons to split the services apart instead — more control over backups, monitoring, restarts, that kind of thing. So before recommending decoupling, I actually tested each of those assumptions on a live Coolify instance.

Most of them turned out to be wrong.

Myth 1: Restarting Directus Restarts the Whole Stack

I expected that restarting Directus inside the bundled Compose file would restart Redis and Postgres along with it. It doesn't. Coolify lets you restart each service in the stack independently — Directus, Database, and Cache each get their own Restart button, right there in the same view. No decoupling needed for this one.

Myth 2: You Need a Separate Database Resource for S3 Backups

Same story. Even with Postgres bundled inside the Directus Compose file, Coolify still gives it its own dedicated Backups option, S3 included. This isn't a separate-resource-only feature.

Myth 3: Scheduled Tasks Require Separate Services

Also not true. Coolify exposes a Scheduled Tasks tab per service, even inside a single bundled stack — complete with a Container name dropdown letting you target the cron job at just the database, or just Directus, without splitting anything apart.

What Actually Holds Up

Two things survived testing.

First: metrics. This one's confirmed directly in Coolify's own documentation — CPU and memory metrics collection is explicitly not available for Docker Compose–based deployments. If you want to see per-container resource usage through Coolify's built-in monitoring, the service needs to be created as its own standalone resource, not bundled inside a Compose file. This is a real, documented limitation of the bundled approach.

Second: sharing a database across multiple apps. This one isn't a Coolify feature at all — it's just how Docker networking works. A database defined inside one app's Compose file lives on that stack's own private network by default. A second, completely separate application can't reach it without deliberately bridging the two networks. If you've got a desktop app and a mobile app that both need to talk to the same Postgres instance, that database needs to exist as its own standalone resource from the start — it can't stay tucked inside one app's Compose file.

So this really comes down to two reasons to decouple, not five — one a genuine Coolify limitation, the other a structural fact about Docker networking. Let's set both of those up properly.

Adding the Resources

Adding the PostgreSQL Database

Dashboard → Add Project
+ Add Resource
Databases → PostgreSQL → Supabase PostgreSQL (with extensions)
Change the name to something human-friendly
Copy your username and password and save them somewhere — you'll need them shortly
Click Save
Click Start, and wait for the database to spin up (this can take a little while)

Once it's up, the status should read "Running (Healthy)."

💡 Enable metrics while you're here. In the sidebar, go to Servers → localhost → Metrics, and enable metrics. Back in your project, under Databases, click your Postgres database, then Metrics — you should now see live CPU/memory usage for it. This is the exact capability that isn't available on a bundled Compose deployment.

Adding Redis Cache

Dashboard → + Add Resource (from the project itself)
Databases → Redis
Rename it to something more convenient
Copy the Redis connection URL — you'll need it shortly
Save, then Start

Once both are running, SSH into your VPS and run:

docker ps

to confirm both containers are up.

The Docker Compose Config for Directus

This is what goes into the empty Compose file for the Directus resource:

services:
  directus:
    image: 'directus/directus:12.2.0'
    ports:
      - '8055:8055'
    volumes:
      - './uploads:/directus/uploads'
      - './extensions:/directus/extensions'
    healthcheck:
      test:
        - CMD-SHELL
        - 'wget --spider -q http://127.0.0.1:8055/server/ping || exit 1'
      interval: 10s
      timeout: 5s
      retries: 5
      start_interval: 5s
      start_period: 30s
    environment:
      SECRET: secretstring
      MARKETPLACE_TRUST: all
      DB_CLIENT: pg
      DB_HOST:
      DB_PORT: '5432'
      DB_DATABASE: postgres
      DB_USER: postgres
      DB_PASSWORD:
      CACHE_ENABLED: 'true'
      CACHE_STORE: redis
      CACHE_AUTO_PURGE: 'true'
      REDIS:
      ADMIN_EMAIL: joepublic@example.com
      ADMIN_PASSWORD: '1234567890'
      CORS_ENABLED: 'true'
      CORS_ORIGIN: 'true'
      CORS_CREDENTIALS: 'true'
      PUBLIC_URL:

Notice the healthcheck already uses 127.0.0.1 instead of localhost — that's the fix from Part 1. Carrying it forward here saves you from hitting the exact same "unhealthy" bug all over again.

Adding Directus

Dashboard → + Add Resource (from the project itself)
Applications → Docker Compose Empty
Paste in the Compose configuration above
Click Save
Network → Connect To Predefined Network → check the box
Services → Directus service → Settings
Add your Directus subdomain — remember to use https:// (e.g. https://directus.yourdomain.com)
Save

Connecting the Services Together

Variable	What it is
`SECRET`	A long, unguessable random string
`DB_HOST`	The name of your Postgres container — run `docker ps` on your VPS to find it
`DB_DATABASE`	The name of the database on your Postgres server (Coolify's default is usually `postgres`, but confirm it against your Postgres service)
`DB_USER`	The database username, from the Postgres service you created earlier
`DB_PASSWORD`	The password from that same Postgres service
`REDIS`	The Redis connection URL from the Redis service you created earlier
`PUBLIC_URL`	Your Directus subdomain

⚠️ Redis URL gotcha: the connection URL follows the format redis://username:password@host:port. Coolify's generated URL includes the username you set when creating the Redis resource — in my case, that username was also redis, so the URL looked like redis://redis:somelongvariable.... Directus doesn't need the username here, just the password, so strip that segment out: redis://:somelongvariable.... If you used a different username when creating your Redis resource, remove that value instead — not literally the word "redis."

Setting Up Environment Variables

Rather than hardcoding any of this directly into the Compose file, move it into Directus's environment variables:

Dashboard → Projects → Services / Directus
Environment Variables
Click + Add, enter the variable name in all caps, and its value
Save
Repeat for: SECRET, DB_HOST, DB_DATABASE, DB_USER, DB_PASSWORD, ADMIN_EMAIL, ADMIN_PASSWORD, and REDIS

Updating the Compose File

Now reference those variables instead of the raw values:

SECRET: '${SECRET}'
DB_HOST: '${DB_HOST}'

...and so on for each variable. Then:

Save
Restart

Launching Directus

Paste your Directus subdomain into the browser, and you should land on your running Directus instance. You can also click Links on the Directus service, then click the subdomain — it'll take you straight to your Directus Studio login.

Same as the last video: sign up for your free license, which arrives by email, and paste it into your Directus instance to unlock everything.

Any questions or hit a different result testing any of these yourself? Drop it in the comments — I'm genuinely curious whether this holds up across different Coolify versions and setups.

Setting Up Directus on a Coolify VPS (And Fixing the "Unhealthy" Error)

Wade Thomas — Fri, 31 Jul 2026 06:56:09 +0000

Introduction

Directus is a backend for developers. It can connect to any SQL database and asset storage, and it provides developer tooling — which the Directus team calls the "Data Engine" — alongside a web application that lets both developers and non-developers manipulate data and assets through a no-code interface called the "Data Studio."

Directus also offers granular access control, meaning end users can only see, manipulate, and interact with the data allowed by their role and access policy — enforced consistently by both the engine and the studio. It's extensible through its own marketplace, and it's completely free, with a free license available.

Directus is also known as a headless CMS — meaning it doesn't ship with a front end attached out of the box, the way WordPress traditionally did. You can pair it with whichever front end you prefer; TanStack Start is my front end of choice.

In this post, I'll self-host Directus on my Coolify-managed VPS, walk through both setup methods, and — since nothing ever works perfectly on the first try — fix the actual errors I hit along the way.

📌 New here? I'd recommend checking out my earlier posts where I set up the VPS itself and installed Coolify on it, before continuing with this one.

Let's Get Started

There are two ways to set up Directus on a Coolify-managed VPS. I'll cover the first one here.

1. Log in to your Coolify Dashboard

In the sidebar menu, go to Projects → +Add
Give your project a name and description, and press continue

2. Add a Resource

After naming your project, you should be redirected to the project's page, where you can add a resource. If that redirect doesn't happen, click Projects in the sidebar, then click into your project, and you should see +Add Resource.

Click +Add Resource
Under Applications, select Docker Compose Empty
A blank Docker Compose file will open
Go to directus.com → Docs → Hosting → Deployment
Scroll down until you find the example Docker Compose YAML file, and copy it
Paste it into your blank Coolify Compose file
Find the directus: service, and under it, image: — update this to the version you want. As of this post, the latest version is 12.2.0:

  image: directus/directus:12.2.0

Scroll to the end and set your own admin email and password — these become your Data Studio login credentials
Click Save at the top

3. Configure the Service

You should now be on the Configuration screen, with a Deploy button (yellow outline arrow) in the top right.

Under Network, check the box
Under Services, click Settings on the directus tab
In the Domain field, enter your subdomain — e.g. https://directus.yourdomain.com. Use https, so Traefik knows to issue a Let's Encrypt certificate for it
Click Save, then Back
Click Edit Compose File at the top, scroll down to PUBLIC_URL, and set it to match your subdomain:

  PUBLIC_URL: https://directus.yourdomain.com

Click Save, close the modal
Click Deploy, then Confirm on the popup
Wait for the deployment to finish

4. Launch Directus

On the Configuration screen, click Links, then click your new subdomain.

The Errors

At this point, your browser will show two errors: a "Not Secure" warning in the address bar, and a "no available server" page.

Back on the Coolify dashboard, you'll notice the Directus instance is showing as unhealthy. Traefik will not route traffic to a service that's failing its health check — which is exactly what's happening here. So the first job is figuring out why the health check is failing.

Diagnosing the Problem

SSH into your VPS to start digging.

Check your running containers:

sudo docker ps

Install jq, so the JSON output we're about to read is actually readable:

sudo apt install jq

Check the health check failure log (grab your Directus container's name from the docker ps output above):

docker inspect --format='{{json .State.Health}}' <your-directus-container-name> | jq

The result looked like this:

{
  "Status": "unhealthy",
  "FailingStreak": 79,
  "Log": [
    {
      "Start": "2026-07-30T18:12:21.445964902-04:00",
      "End": "2026-07-30T18:12:21.502447668-04:00",
      "ExitCode": 1,
      "Output": "wget: can't connect to remote host: Connection refused\n"
    },
    {
      "Start": "2026-07-30T18:12:31.505411263-04:00",
      "End": "2026-07-30T18:12:31.556307544-04:00",
      "ExitCode": 1,
      "Output": "wget: can't connect to remote host: Connection refused\n"
    }
  ]
}

The first clue: "wget: can't connect to remote host: Connection refused". Whatever endpoint the health check is trying to reach, it's being actively refused — not timing out, refused. That distinction matters, and it's the thread that leads to the actual fix.

Inspecting the Docker Compose File

From the Coolify dashboard, select Projects in the sidebar
Click your project
Click the service, then Edit Compose File next to Service Stack

Here's the relevant section:

directus:
  image: 'directus/directus:12.2.0'
  ports:
    - '8055:8055'
  volumes:
    - './uploads:/directus/uploads'
    - './extensions:/directus/extensions'
  depends_on:
    database:
      condition: service_healthy
    cache:
      condition: service_healthy
  healthcheck:
    test:
      - CMD-SHELL
      - 'wget --spider -q http://localhost:8055/server/ping || exit 1'
    interval: 10s
    timeout: 5s
    retries: 5
    start_interval: 5s
    start_period: 30s

The problem is in the wget line — specifically, http://localhost:8055.

Why `localhost` Breaks This

Inside a Linux container, localhost isn't an address — it's a hostname that has to be resolved first, and it typically maps to two addresses at once:

127.0.0.1   localhost   # IPv4
::1         localhost   # IPv6

When wget looks up localhost, the system's resolver hands back both addresses, and wget tries them in whatever order it receives them — which, on many Linux/Alpine base images, tends to prefer IPv6 first.

Checking the container's logs confirms what's actually listening:

docker logs <your-directus-container-name> --tail 150

Directus only bound to IPv4. The startup log says exactly that:

Server started at http://0.0.0.0:8055

0.0.0.0 means "listen on every IPv4 interface" — Directus never opened an IPv6 socket at all. So when wget tries ::1:8055 first, there's genuinely nothing listening there, and the OS doesn't wait around wondering — it immediately sends back a rejection (a TCP RST). That's exactly why the log shows an instant "Connection refused" rather than a slow timeout. A timeout would mean something was reachable but not responding; a refusal means the OS said "nothing's here" right away.

127.0.0.1 sidesteps the whole problem, because it's already a literal IP address — no hostname lookup, no ambiguity about which protocol family to try, no chance of picking the wrong one. It goes straight to the one address where Directus is actually listening.

The Fix

Change localhost to 127.0.0.1 in the health check:

directus:
  image: 'directus/directus:12.2.0'
  ports:
    - '8055:8055'
  volumes:
    - './uploads:/directus/uploads'
    - './extensions:/directus/extensions'
  depends_on:
    database:
      condition: service_healthy
    cache:
      condition: service_healthy
  healthcheck:
    test:
      - CMD-SHELL
      - 'wget --spider -q http://127.0.0.1:8055/server/ping || exit 1'
    interval: 10s
    timeout: 5s
    retries: 5
    start_interval: 5s
    start_period: 30s

Save the change, close the modal, and click Restart in the top right. Wait for the restart to complete — it may look like nothing's happening for a bit, so give it a moment. Once it's finished, close the logs modal, and Directus should show as healthy.

Click Links, then your Directus subdomain, and you should land on the Data Studio login screen. If you get a "Not Secure" error in the browser, this is usually just a stale cache from visiting the subdomain before the fix. Try a hard refresh first (Ctrl+Shift+R). If that doesn't clear it, clear your browser's cache entirely (all time, not just a recent window) — a partial or time-bounded clear may not be enough.

Logging In & Licensing

Enter the credentials you set earlier in the Compose file. You'll be asked whether you have a license or want to install the Core — choose Core for now, and follow the flow to complete sign-up.

At this stage, your instance isn't fully unlocked — you'll need a license. Good news: it's completely free if your business's revenue is under $5M and your team is under 50 people.

Head to directus.com/oig to apply for your key. Once you have it, go to your Directus Studio, click the gear icon (Settings) in the sidebar, click License, and add your key there to unlock all features. Your key is valid for a year.

Got questions, or hit a different error setting this up? Drop a comment below — happy to help troubleshoot.

Coolify: The Complete Manual Setup Guide (For When the Auto-Install Script Won't Cut It)

Wade Thomas — Thu, 23 Jul 2026 03:43:43 +0000

Coolify's one-line install script is great — until it isn't. Right now it officially supports Ubuntu 20.04, 22.04, and 24.04 LTS. If you're running anything newer (Ubuntu's already on 26.04 LTS), the script won't work and you're left doing it manually.

This is that manual walkthrough — set up in the order that fits a security-first VPS workflow rather than the order Coolify's own docs use. If you've been following along with the Ansible playbooks from earlier in this series, this picks up right where that left off.

Minimum Hardware Requirements

CPU: 2 cores
Memory: 2 GB RAM
Storage: 30 GB free

Coolify can technically run below this, but it's not recommended.

Prerequisites

Before touching Coolify itself, you'll need:

SSH access to your VPS
CURL installed
Docker Engine installed

If you're reconnecting to a server you've rebuilt or re-provisioned, clear the old fingerprint first:

ssh-keygen -f '/home/your-path/.ssh/known_hosts' -R 'your-vps-ip'

Installing SSH

If you followed the earlier videos in this series, OpenSSH is already installed. If not:

sudo apt update && sudo apt install -y openssh-server

Confirm it's running and check which port it's listening on (you should have already changed this from the default 22 — see the VPS security video):

sudo systemctl status ssh
sudo ss -tulpn | grep ssh

Installing CURL

sudo apt update && sudo apt install -y curl
curl --version

curl and ca-certificates also get installed as part of the apt-update Ansible playbook below, so this may already be handled.

Running the First Ansible Playbook

Connect Ansible to the VPS:

ANSIBLE_HOST_KEY_CHECKING=FALSE ansible -i ./inventory/hosts vpsDemo -m ping --user root --ask-pass

Then run the update playbook:

ansible-playbook ./playbooks/apt-update.yml --user root -e "ansible_port=22" --ask-pass --ask-become-pass -i ./inventory/hosts

If you haven't set up the Ansible inventory and playbooks from the earlier videos, do that first — this guide assumes they're already in place.

Installing Docker Engine

Remove any conflicting packages first:

sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc | cut -f1)

Add Docker's official GPG key and repo:

sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

Verify it worked:

sudo systemctl status docker
sudo docker run hello-world

Creating a Non-Root Admin User

Coolify's own docs assume you're using the root account. Since root login is disabled as part of the security hardening earlier in this series, we create a dedicated user with passwordless sudo instead.

Run the second playbook to create that user:

ansible-playbook ./playbooks/basic-secure.yml --user root -e "ansible_port=22" --ask-pass --ask-become-pass -i ./inventory/hosts

Then set up that user's SSH directory:

sudo mkdir -p /home/your-sudo-user/.ssh
sudo touch /home/your-sudo-user/.ssh/authorized_keys
sudo chmod 700 /home/your-sudo-user/.ssh
sudo chmod 600 /home/your-sudo-user/.ssh/authorized_keys

Setting Up Coolify's Directory Structure

sudo mkdir -p /data/coolify/{source,ssh,applications,databases,backups,services,proxy,webhooks-during-maintenance}
sudo mkdir -p /data/coolify/ssh/{keys,mux}
sudo mkdir -p /data/coolify/proxy/dynamic

Generating and Adding an SSH Key

sudo ssh-keygen -f /data/coolify/ssh/keys/id.your-sudo-user@host.docker.internal -t ed25519 -N '' -C your-sudo-user@coolify

Add the public key to the authorized_keys file:

cat /data/coolify/ssh/keys/id.your-sudo-user@host.docker.internal.pub | sudo tee -a /home/your-sudo-user/.ssh/authorized_keys

Pulling Coolify's Configuration Files

sudo curl -fsSL https://cdn.coollabs.io/coolify/docker-compose.yml -o /data/coolify/source/docker-compose.yml
sudo curl -fsSL https://cdn.coollabs.io/coolify/docker-compose.prod.yml -o /data/coolify/source/docker-compose.prod.yml
sudo curl -fsSL https://cdn.coollabs.io/coolify/.env.production -o /data/coolify/source/.env
sudo curl -fsSL https://cdn.coollabs.io/coolify/upgrade.sh -o /data/coolify/source/upgrade.sh

Generating Secure Environment Values

⚠️ Only run these once, on first install. Changing them later can break Coolify. Back them up somewhere safe.

sudo sed -i "s|APP_ID=.*|APP_ID=$(openssl rand -hex 16)|g" /data/coolify/source/.env
sudo sed -i "s|APP_KEY=.*|APP_KEY=base64:$(openssl rand -base64 32)|g" /data/coolify/source/.env
sudo sed -i "s|DB_PASSWORD=.*|DB_PASSWORD=$(openssl rand -base64 32)|g" /data/coolify/source/.env
sudo sed -i "s|REDIS_PASSWORD=.*|REDIS_PASSWORD=$(openssl rand -base64 32)|g" /data/coolify/source/.env
sudo sed -i "s|PUSHER_APP_ID=.*|PUSHER_APP_ID=$(openssl rand -hex 32)|g" /data/coolify/source/.env
sudo sed -i "s|PUSHER_APP_KEY=.*|PUSHER_APP_KEY=$(openssl rand -hex 32)|g" /data/coolify/source/.env
sudo sed -i "s|PUSHER_APP_SECRET=.*|PUSHER_APP_SECRET=$(openssl rand -hex 32)|g" /data/coolify/source/.env

Permissions and Docker Setup

Set correct ownership and permissions:

sudo chown -R 9999:root /data/coolify
sudo find /data/coolify -type d -exec chmod 755 {} \;
sudo find /data/coolify -type f -exec chmod 644 {} \;
sudo chown -R your-sudo-user:your-sudo-user /home/your-sudo-user/.ssh

Create the Docker network Coolify expects:

sudo docker network create --attachable coolify

Add your user to the Docker group:

sudo usermod -aG docker your-sudo-user

Starting Coolify

sudo docker compose --env-file /data/coolify/source/.env -f /data/coolify/source/docker-compose.yml -f /data/coolify/source/docker-compose.prod.yml up -d --pull always --remove-orphans --force-recreate

Confirm it's running:

sudo docker ps

Then visit http://YOUR-SERVER-IP:8000 in your browser.

Setup your SSL Certificates

Coolify's reverse-proxy Traefik does this under the hood automatically.
In your DNS records add two A records.

A     @     your-vps-ip-address        14400
A     *     your-vps-ip-address        14400

In you Coolify dashboard go to settings in the left side column. In the input box marked URL type your https Subdomain for Coolify there.

https://coolify.yourdomain.com

Traefik will automatically apply a Let's Encrypt certificate to your Coolify subdomain.

Disable port 8000

Disable port 8000 on your VPS. If your hosting provider allows you to configure a firewall from your dashboard, disable it from there. To disable port 8000, simply write rules that allows the ports you want and block everything else.

Wrap-Up

That's a full manual Coolify install on a hardened, non-root VPS — no automated script required. From here, Coolify handles the rest: connecting your Git repos, setting up applications, and managing deployments.

If you hit issues with the automated script on a newer Ubuntu release, this manual path should get you unblocked. Questions or corrections welcome in the comments.

The Ansible Playbook that will Harden Your VPS

Wade Thomas — Tue, 14 Jul 2026 20:44:28 +0000

Ansible Playbooks — Automate VPS Hardening, User Creation & Removal

Introduction

In this post I'm sharing 3 Ansible playbooks I use to manage my VPS servers. I won't go into great detail on tasks here — if you're new to Ansible check out my previous post and video first.

The three playbooks covered today:

basic-secure.yml — automate VPS hardening
add-vps-user.yml — semi-automated user creation
remove-vps-user.yml — completely remove a user and their privileges

📚 Resources:

Ansible Documentation

Ansible Collection Index

The Basics

A task is broken up into four parts:

Part	Description
Name	A plain-text description of what the task does
Collection	The Ansible content bundle the module belongs to
Module	The tool that executes the action
Parameters	The specific options passed to the module

Playbook 1 — basic-secure.yml

This playbook fully hardens a fresh Ubuntu VPS in a single command. It prompts you for a custom admin username, generates a random 16-character password, configures UFW, installs Fail2Ban, and moves SSH to port 2222.

---
- name: Harden Ubuntu VPS Security Configuration
  hosts: vpsDemo
  gather_facts: true
  vars_prompt:
    - name: 'custom_admin_user'
      prompt: 'Enter the custom username for your main administrator account'
      private: false
  tasks:
    # 1. GENERATE RANDOM PASSWORD
    - name: Generate random password
      set_fact:
        new_admin_password: "{{ lookup('password', '/dev/null chars=ascii_letters,digits,hexdigits length=16') }}"

    # 2. CREATE SUDO USER
    - name: Ensure the custom admin user exists
      ansible.builtin.user:
        name: '{{ custom_admin_user }}'
        password: "{{ new_admin_password | password_hash('sha512') }}"
        shell: /bin/bash
        state: present
        groups: sudo
        append: true

    - name: Allow the admin user to use sudo without a password prompt
      ansible.builtin.copy:
        content: "{{ custom_admin_user }} ALL=(ALL) NOPASSWD:ALL\n"
        dest: '/etc/sudoers.d/{{ custom_admin_user }}'
        mode: '0440'
        validate: /usr/sbin/visudo -cf %s

    # 3. CONFIGURE UFW FIREWALL
    - name: Reset UFW to default settings
      community.general.ufw:
        state: reset

    - name: Set UFW default policies to deny incoming
      community.general.ufw:
        policy: deny
        direction: incoming

    - name: Open Port 80 (HTTP)
      community.general.ufw:
        rule: allow
        port: '80'
        proto: tcp

    - name: Open Port 443 (HTTPS)
      community.general.ufw:
        rule: allow
        port: '443'
        proto: tcp

    - name: Open Custom SSH Port 2222
      community.general.ufw:
        rule: allow
        port: '2222'
        proto: tcp

    - name: Enable UFW Firewall
      community.general.ufw:
        state: enabled

    # 4. INSTALL FAIL2BAN
    - name: Install Fail2Ban
      ansible.builtin.apt:
        name: fail2ban
        state: present
        update_cache: true

    - name: Ensure Fail2Ban is running and enabled on boot
      ansible.builtin.service:
        name: fail2ban
        state: started
        enabled: true

    # 5. HARDEN SSH
    - name: Configure SSH to use custom port 2222
      ansible.builtin.lineinfile:
        path: /etc/ssh/sshd_config
        regexp: '^#?Port\s'
        line: 'Port 2222'
        state: present

    - name: Disable Root SSH Login
      ansible.builtin.lineinfile:
        path: /etc/ssh/sshd_config
        regexp: '^#?PermitRootLogin\s'
        line: 'PermitRootLogin no'
        state: present

    # 6. FIX SYSTEMD SSH SOCKET
    - name: Create systemd override directory for SSH socket
      ansible.builtin.file:
        path: /etc/systemd/system/ssh.socket.d
        state: directory
        mode: '0755'

    - name: Write dual-stack IPv4/IPv6 socket configuration
      ansible.builtin.copy:
        dest: /etc/systemd/system/ssh.socket.d/listen.conf
        mode: '0644'
        content: |
          [Socket]
          ListenStream=
          ListenStream=0.0.0.0:2222
          ListenStream=[::]:2222

    - name: Reload systemd daemon
      ansible.builtin.systemd_service:
        daemon_reload: true

    - name: Restart SSH socket
      ansible.builtin.service:
        name: ssh.socket
        state: restarted

    - name: Restart SSH service
      ansible.builtin.service:
        name: ssh
        state: restarted

    # 7. DISPLAY CREDENTIALS
    - name: Display your new credentials (SAVE THESE IMMEDIATELY)
      ansible.builtin.debug:
        msg:
          - '========================================================'
          - 'NEW SUDO USERNAME: {{ custom_admin_user }}'
          - 'NEW PASSWORD: {{ new_admin_password }}'
          - 'CUSTOM SSH PORT: 2222'
          - '========================================================'

⚠️ Save the displayed credentials immediately — the generated password is only shown once.

Playbook 2 — add-vps-user.yml

Creates a new sudo user with a randomly generated secure password and prints the credentials to your screen.

---
- name: Universal Semi-Automated User Creation Script
  hosts: vpsDemo
  gather_facts: false
  become: true
  vars_prompt:
    - name: 'custom_admin_user'
      prompt: 'Enter the custom username for this new administrator account'
      private: false
  tasks:
    - name: Generate random secure password
      set_fact:
        new_random_password: "{{ lookup('password', '/dev/null chars=ascii_letters,digits length=16') }}"

    - name: Ensure the new user account exists
      ansible.builtin.user:
        name: '{{ custom_admin_user }}'
        password: "{{ new_random_password | password_hash('sha512') }}"
        shell: /bin/bash
        state: present
        groups: sudo
        append: true

    - name: Allow the new user to use sudo without a password prompt
      ansible.builtin.copy:
        content: "{{ custom_admin_user }} ALL=(ALL) NOPASSWD:ALL\n"
        dest: '/etc/sudoers.d/{{ custom_admin_user }}'
        mode: '0440'
        validate: /usr/sbin/visudo -cf %s

    - name: Display New User Credentials
      ansible.builtin.debug:
        msg:
          - '========================================================'
          - 'NEW ADMINISTRATIVE ACCOUNT CREATED SUCCESSFULLY!'
          - 'USERNAME: {{ custom_admin_user }}'
          - 'PASSWORD: {{ new_random_password }}'
          - '========================================================'

Playbook 3 — remove-vps-user.yml

Completely purges a user account, their home directory, mail spool, and sudo privileges from the server.

---
- name: Universal User and Privilege Removal Script
  hosts: all
  gather_facts: false
  become: true
  vars_prompt:
    - name: 'user_to_delete'
      prompt: 'Enter the exact username you want to COMPLETELY delete'
      private: false
  tasks:
    - name: Delete the user's custom sudoers configuration file
      ansible.builtin.file:
        path: '/etc/sudoers.d/{{ user_to_delete }}'
        state: absent

    - name: Remove the user account and purge their files
      ansible.builtin.user:
        name: '{{ user_to_delete }}'
        state: absent
        remove: true   # deletes home directory and mail spool
        force: true    # kills any active processes owned by the user
        ignore_errors: true

    - name: Display Removal Confirmation
      ansible.builtin.debug:
        msg:
          - '========================================================'
          - "SUCCESS: Account '{{ user_to_delete }}' and their sudo privileges"
          - 'have been completely purged from the server.'
          - '========================================================'

Conclusion

I hope these playbooks are useful — grab them, adapt them to your environment and save yourself hours of repetitive manual work. I'll be sharing more playbooks as I build them out.

Blessings. 🙏

Looking for developer templates built on TanStack, Directus, and Tailwind CSS?
🛒 northernrangedigital.lemonsqueezy.com
🌐 northernrangedigital.com

Ansible Installation and Configuration on Ubuntu — Automate Your Server Management

Wade Thomas — Fri, 10 Jul 2026 04:17:07 +0000

Introduction

What is Ansible?

Ansible is an automation language that can describe any IT environment, whether homelab or large-scale infrastructure. It is easy to learn and reads like clear documentation.

If you manage multiple servers and find yourself doing the same configuration over and over — setting up SSH keys, disabling root users, configuring firewalls — Ansible can automate the entire process and dramatically increase your productivity.

It only requires Ansible on the Control Node and Python 3 on the Managed Node.

What is the Control Node?

The system that Ansible is installed on — it controls the remote machines.

What is the Managed Node?

The remote system or host that Ansible controls. Ansible is agentless, meaning you don't need to install Ansible on managed nodes — just Python 3.

Installing Ansible on Ubuntu (Control Node)

sudo apt update
sudo apt install software-properties-common
sudo add-apt-repository --yes --update ppa:ansible/ansible
sudo apt install ansible

Note: Ensure Python 3 is installed on your remote server. Ubuntu 24.04 LTS ships with Python 3 by default.

Create the Inventory Folder and Hosts File

The hosts file maps the remote machines you want to control.

Folder structure:

Ansible/
├── inventory/
│ └── hosts
└── playbooks/
└── apt-update.yml

inventory/hosts

[servers]
vpsServer ansible_host=10.10.100.45
work-ToRule
10.10.45.62

You can give hosts an alias by pairing a name with an IP address. In the example above, vpsServer is an alias for 10.10.100.45.

Your First Playbook — Update Ubuntu and Set Timezone

Create playbooks/apt-update.yml:

- hosts: '*'
  become: true
  serial: 1
  tasks:
    - name: Set system timezone to Trinidad and Tobago time
      community.general.timezone:
        name: America/Port_of_Spain

    - name: Update apt cache
      apt:
        update_cache: yes
        cache_valid_time: 3600

    - name: Upgrade all packages to the latest version
      apt:
        upgrade: dist

    - name: Check if reboot is required
      stat:
        path: /var/run/reboot-required
      register: reboot_required_file

    - name: Reboot the server
      reboot:
        msg: 'Reboot initiated by Ansible due to package upgrades'
        connect_timeout: 5
        reboot_timeout: 300
        pre_reboot_delay: 0
        post_reboot_delay: 30
      when: reboot_required_file.stat.exists

Breaking Down the Playbook

Key	Description
`hosts: '*'`	Target all hosts in inventory. Use an alias, DNS name, or IP to target a single host.
`become: true`	Grants Ansible sudo privileges.
`serial: 1`	Processes servers one at a time instead of all at once.
`tasks`	A list of individual actions to run on the target hosts.

Each task has four parts:

name — a plain-text description of what the task does
Collection (community.general) — the Ansible content bundle the module belongs to
Module (timezone, apt, reboot) — the tool that executes the action
Parameters (name: America/Port_of_Spain) — the specific options passed to the module

📚 Browse all available modules and collections at docs.ansible.com

Running the Playbook

Step 1 — Test connectivity with a ping

ANSIBLE_HOST_KEY_CHECKING=FALSE ansible -i ./inventory/hosts vpsServer -m ping --user root --ask-pass

Flag	Description
`ANSIBLE_HOST_KEY_CHECKING=FALSE`	Skips SSH host key verification — useful for fresh servers
`-i ./inventory/hosts`	Points to your inventory file
`vpsServer`	The target host alias
`-m ping`	Runs the ping module to check connectivity and Python availability
`--ask-pass`	Prompts for SSH password

Once you get a green pong response, you're ready to run the playbook.

Step 2 — Run the playbook

ansible-playbook ./playbooks/apt-update.yml --user root -e "ansible_port=22" --ask-pass --ask-become-pass -i ./inventory/hosts

Flag	Description
`ansible-playbook`	Runs a full automation script instead of a single ad-hoc task
`./playbooks/apt-update.yml`	Path to your playbook file
`--user root`	SSH connection username
`-e "ansible_port=22"`	Injects extra variable to force port 22
`--ask-pass`	Prompts for SSH login password
`--ask-become-pass`	Prompts for sudo password (redundant when logging in as root)
`-i ./inventory/hosts`	Points to your inventory file

Execution Flow

Ansible reads ./inventory/hosts to find the target server's IP
Prompts for SSH password
Prompts for sudo password
Connects to port 22 as root
Opens apt-update.yml and executes each task in order

Conclusion

A big shout-out to Aldo @aldo_cve for recommending Ansible in a previous post — it's been a great addition to my server management workflow.

I hope you found this walkthrough useful. Stay tuned for more posts where I share playbooks I find useful in my day-to-day infrastructure work.

Looking for developer templates built on TanStack, Directus, and Tailwind CSS? Check out my store 👇
🛒 northernrangedigital.lemonsqueezy.com

How to Secure a VPS: The Complete Ubuntu Hardening Guide

Wade Thomas — Thu, 02 Jul 2026 05:26:20 +0000

The moment a VPS gets a public IP, it's already being scanned. Automated bots start hammering the default root account with password guesses within minutes of the server going online — before you've even finished your first apt update.

This guide walks through the baseline hardening I run on every fresh Ubuntu server before deploying anything to it: creating a proper user account, locking down root, setting up a firewall, quieting bot noise on SSH, and auto-banning repeat offenders.

Prefer to follow along on video?

1. Stop Using the Root User

Every Linux server in the world ships with an account named root. That's the problem — hackers already know the username, so they only need to guess the password or find one exploit to get full control. A custom username forces an attacker to guess two unknowns instead of one.

A few other reasons to move off root:

No safety net. Root executes destructive commands instantly, no confirmation. Run rm -rf / as root and it's gone. A standard user needs sudo, which at least forces a pause and a password prompt.
Bots target root specifically. The moment a VPS goes online, automated bots start brute-forcing the root account with thousands of password guesses per minute. Disable root login and that entire attack surface disappears.
No accountability. If more than one person has server access, a shared root login makes it impossible to tell who did what. Individual sudo accounts get logged to /var/log/auth.log, so every command is tied to a specific user.

Create a sudo user

adduser your_username
usermod -aG sudo your_username

-aG breaks down into two flags: -G adds the user to the group that follows (sudo), and -a (append) makes sure the user is added to that group rather than having all their other group memberships wiped out. Together, -aG says: add this user to sudo, keep everything else as-is.

Verify it worked:

groups your_username

Lock down root

Log out of root and back in as your new sudo user first, then:

# Lock the root password
sudo passwd -l root

# Disable root login over SSH
sudo nano /etc/ssh/sshd_config
# set: PermitRootLogin no
sudo systemctl restart sshd

# Confirm root is locked
sudo passwd -S root

2. Set Up a Firewall (UFW)

A firewall closes off everything you're not explicitly using. On a fresh VPS, that means:

Blocking brute-force attempts on ports you don't need exposed
Keeping internal-only services (databases, admin tools) off the public internet
Restricting sensitive ports like SSH to specific IPs, if needed
Dropping unexpected traffic, which softens basic DoS attempts
Closing the door on any hidden vulnerability in something you're running

Ubuntu ships with UFW (Uncomplicated Firewall), which blocks all incoming traffic by default and only opens what you explicitly allow:

# Allow SSH first so you don't lock yourself out
sudo ufw allow OpenSSH
# or: sudo ufw allow 22/tcp

# Allow web traffic if you're hosting a site
sudo ufw allow http
sudo ufw allow https

# Turn it on
sudo ufw enable

# Check status
sudo ufw status verbose

3. Change the Default SSH Port

Within minutes of going live, bots start hammering port 22 — not targeted attacks, just scripts sweeping the internet for the default SSH port. Moving to something non-standard, like 2222, makes those scanners skip right past you.

sudo nano /etc/ssh/sshd_config
# uncomment #Port 22 and change it:
# Port 2222

sudo ufw allow 2222/tcp
sudo ufw reload
sudo systemctl restart sshd

Worth being honest about this one: security researchers call this "security through obscurity," and on its own it's a weak measure — it doesn't make the server harder to break into. What it does do is keep your auth logs from being flooded with bot noise, which makes real suspicious activity much easier to spot. Pair it with SSH keys, disabled password auth, and Fail2Ban for actual hardening.

4. Install Fail2Ban

Fail2Ban watches your logs for repeated failed login attempts and temporarily bans the offending IP at the firewall level.

Why it's worth running:

Free, open-source, and quick to set up
Highly configurable — ban duration, whitelisted IPs, which services to watch
Bans happen at the firewall, so malicious traffic doesn't eat server resources
Can integrate with notifications for real-time alerts

Where it falls short:

Reactive, not preventive — it only acts after a set number of failed attempts have already happened
Can lock out legitimate users who fat-finger a password a few times in a row
Weak against distributed attacks, since it bans by IP and botnets rotate through thousands of them
Vulnerable to IP spoofing
Can conflict with Docker's iptables rules on a Docker host, causing bans to fail or hit the wrong container

Install it:

sudo apt update
sudo apt install fail2ban -y
sudo systemctl start fail2ban
sudo systemctl enable fail2ban

(The -y flag auto-confirms every prompt during install — only use it once you're already certain about the package.)

Wrap-Up

None of these steps make a server unbreakable on their own — a sudo user, a firewall, an obscure SSH port, and Fail2Ban are each individually beatable. Stacked together, they cut off the low-effort, automated attacks that hit every public IP within minutes of going live, and they keep your logs clean enough that you'd actually notice something that isn't normal.

If you found this useful, the video above walks through each step live. Let me know in the comments if you run into anything setting this up on your own box.

What is Redis? The In-Memory Data Store That Makes Your App Faster

Wade Thomas — Wed, 10 Jun 2026 03:44:49 +0000

🎬 This article is a companion to my YouTube video. Watch it here:

Introduction

In this video we are going to talk about Redis — what it is, what it does, and why it is an important part of my back-end stack.

What is Redis?

Redis is a free, open-source, in-memory data store. Unlike PostgreSQL which stores data on disk, Redis stores data entirely in memory — in RAM. This makes it extremely fast. Redis can handle millions of operations per second with sub-millisecond response times.
Redis is most commonly used as a cache, a session store, a message broker, and a real-time data store.

What is Caching?

When your application queries a database, that query takes time — it reads from disk, processes the query, and returns the result. If the same query is made thousands of times per second, you are hitting the database thousands of times unnecessarily.
Caching solves this by storing the result of a query in memory. The first request hits the database and the result is stored in Redis. Every subsequent request gets the result from Redis — which is in memory and therefore much faster — instead of hitting the database again.
Think of it like a shortcut. Instead of driving the long route to the database every time, you take the shortcut through Redis.

What Does Redis Do?

Caching

Store frequently accessed data in memory for fast retrieval. Database query results, API responses, computed values — anything that is expensive to compute and accessed frequently is a good candidate for caching.

Session Storage

Store user session data in Redis instead of the database. Since sessions are read on every request, having them in memory is significantly faster than a database lookup.

Rate Limiting

Track how many requests a user or IP address has made in a given time window. Redis's atomic increment operations make it perfect for implementing rate limiting.
Message Queues and Pub/Sub
Redis supports publish/subscribe messaging and message queues. Applications can publish messages to a channel and subscribers receive them in real time.

Leaderboards and Counters

Redis sorted sets make it trivial to implement leaderboards, counters, and real-time analytics.

Why Directus Uses Redis

Directus uses Redis for two primary purposes.
First, as a cache layer. Directus caches API responses, schema information, and permission lookups in Redis. This dramatically reduces database load and speeds up API response times.
Second, for synchronization across multiple Directus instances. If you run multiple instances of Directus for high availability or horizontal scaling, Redis acts as the shared cache and message bus that keeps them in sync.
For a single Directus instance Redis is optional but recommended. For multiple instances it is required.

Why I Chose Redis

Redis is the industry standard for caching and session storage. It is fast, reliable, widely supported, and Directus has first-class support for it. Adding Redis to the stack costs very little in terms of resources but provides significant performance benefits as the application scales.

Conclusion

Redis is a powerful in-memory data store that makes your application faster and more scalable by caching frequently accessed data and handling real-time workloads. It is a small but important piece of a production-ready back-end stack.
In an upcoming video we will deploy Redis alongside Directus and PostgreSQL on our VPS using Coolify.

References

Redis Website
Redis Documentation
Redis GitHub

🔔 Subscribe to my YouTube channel for the full series on building a modern web app back end from scratch.

DEV Community: Wade Thomas

TanStack Start Basics Part 2 — Connecting to Your Directus Backend

Installing the Directus SDK

Creating the Directus Helper

Defining Our First Type

Writing the Fetch Function

Fixing the Schema Error

Fetching the Data — Method 1: TanStack Query

Fetching the Data — Method 2: Route Loaders

Which One Should You Use?

Summary

Setting Up Our Frontend with TanStack Start

What Is TanStack Start?

Creating the Project

Walking Through the Setup Prompts

Running the App

Editing the Home Page

File-Based Routing

Adding an About Page

Adding a Products Page

What Is That __root.tsx File?

Summary

Directus Basics Part 3 — User Roles & Permissions

The Core Concepts

What Happens Without a Role?

The Access Order

Default Policies

Giving a Collection Public Access

Creating a Custom Access Policy

Creating the User Role

Creating the User

Testing Read-Only Access

Fixing the Missing File Permission

Adding the Thumbnail to List View

Extending Access to Related Collections

Custom Field-Level Permissions

Summary

Directus Basics Part 2 — Understanding Relationships (M2O, O2M, M2M)

Setting Up the Branding Collection

Many to One (M2O): Products → Branding

One to Many (O2M): Branding → Products

Seeing the Relationship in Action

Many to Many (M2M): Products ↔ Tags

Create the Tags Collection

Wire Up the M2M Relationship

Summary

Directus Collections Explained (Fields, Types & Setup) — Directus Basics Part 1

Introduction

Two Ways to Create a Collection

Creating a Collection

Creating Fields Within a Collection

Setting Up the Price Field (Precision & Scale)

Adding Your Data

Summary

Directus + Coolify: Should You Decouple Postgres & Redis?

Introduction

Myth 1: Restarting Directus Restarts the Whole Stack

Myth 2: You Need a Separate Database Resource for S3 Backups

Myth 3: Scheduled Tasks Require Separate Services

What Actually Holds Up

Adding the Resources

Adding the PostgreSQL Database

Adding Redis Cache

The Docker Compose Config for Directus

Adding Directus

Connecting the Services Together

Setting Up Environment Variables

Updating the Compose File

Launching Directus

Setting Up Directus on a Coolify VPS (And Fixing the "Unhealthy" Error)

Introduction

Let's Get Started

1. Log in to your Coolify Dashboard

2. Add a Resource

3. Configure the Service

4. Launch Directus

The Errors

Diagnosing the Problem

Inspecting the Docker Compose File

Why localhost Breaks This

What Is That `__root.tsx` File?

Why `localhost` Breaks This