You start off simple enough — username / password authentication in your application. Then, well, someone mentions that traditional passwords are a security vulnerability, so maybe we should use one-time passwords. That inevitably leads to discussions about magic links and multi-factor authentication. Next thing you know, one dev is in a corner, rocking back and forth and muttering something about SAML, and another dev just left — walked out the door, never to be seen again.

Well, not to worry, we've got just the tool for you.

authentik is an open-source identity provider written in Python. I'm going to focus on the self-hosted version, but they also offer a paid enterprise plan if you want some extra support.

The philosophy of open-source tools and self-hosting is a big, complex topic for another post. In the world of SaaS products, you likely don't need to self-host. I quite like hosted identity providers like Clerk and Auth0. They're good and appropriate solutions for different types of apps and companies.

But I just love to self-host tools. Tinkering and toying with Docker, reverse proxies, and sometimes even server hardware is a lot of fun to me. It does add complexity in some (or many) places, but a little extra complexity means you've got a little more control over your tooling.

Self-hosting also allows me to disconnect from the Internet and still be able to work on features and enhancements in my projects. As long as I've already installed the relevant packages or pulled the right Docker images, I can keep working if I'm in a place where I can't (or don't want to) connect to the Internet. This is a small thing, but really important to me.

authentik makes it really easy to self-host your application. Right out of the gates, they provide a Docker Compose example and a Kubernetes example. Getting authentik running took me about 10 minutes using the Docker Compose example. Most of that was reading. This can make authentik a great tool during the proof-of-concept or beta phase of your application, getting authentication out of the way so you can focus on building the cool and unique features of your app.

One of the great things that authentik has waiting for you is a bunch of documentation on integrating with a lot of tools you probably already use. These integrations range from other self-hosted apps like Outline (another favorite of mine) to cloud providers like AWS and even platforms like WordPress.

authentik's integration docs show you how to set up authentik for your existing providers and applications, so no need to dig around for the right configuration. Sure, if you're building your own application, you don't have the luxury of a README (until you write one, of course!), but don't worry — all the documentation you'll need for your choice of providers is at your fingertips. Personally, I'm fan of the OAuth2 provider for most my pet projects, but I also find the Proxy Provider to be a really great tool if you want to secure a static site that doesn't have any means of authenticating users.

This is a pretty nice default login screen, but maybe a mountain road isn't your vibe. You can change this background, add your own company logo, and add your own CSS. Just add your static files to your authentik deployment and modify to your heart's content.

But actually, that's not even the cool part of the customization to me.

authentik has the concepts of Flows and Stages that are used to determine what steps a user should take to log in, log out, and more. First, you define Stages that represent a single step of authentication — something like requiring a user to enter their username or a password. There's a whole lot to choose from. Once you've set up your Stages, you'll create a Flow, stringing those Stages together until you have a complete process to authenticate, register, or even delete a user. Flows can be imported and exported as .yaml files, making it easy to keep your Flows and Stages synced between different environments.

authentik comes with a pretty reasonable set of default Flows and Stages. If you're setting authentik up just to try it out, you might not need to add anything. They do have a couple of example Flows to get you started, though.

Flows and Stages can feel pretty intimidating. On your dev server, I'd recommend basically deleting all of the default Flows and Stages and building up new ones from scratch. It's the easiest way to learn how these pieces fit together. If you accidentally break something in dev, you can always just drop your database and spin up a fresh install.

authentik is an awesome tool and I've only scratched the surface of what it can do for you. As a self-hosted identity provider, it gives you a lot of control on how your services are authenticated. It's great for local development and beyond, and it has a lot of ready-to-go integrations for services you might already use.

If you're interested in further reading, I'd definitely recommend checking out the docs on Outposts and External Sources.

Hopefully this has given you some inspiration to spin up a local instance of authentik and try it out! It will definitely simplify your authentication needs.

So you're building a site and you've got a nice containing element around your content — but wait! Not all the content is the same width! That nice, neat tube of content is not so much a straight tube as a pile of different sized bricks.

It's a common layout problem, but how do we account for these 'breakout' widths in the layout? There's a couple ways we could go about it:

• Encapsulate each component and set widths and margins. (Works fine if you have full control but can be fiddly).
• Force the component out of the containing element with negative margins. (Works fine if there's only a little deviation).
• Use CSS Grid to build a fluid universal grid! (????).

That last one is what we'll be exploring: how to use CSS Grid definitions to allow for consistent component sizing across all breakpoints — no media queries required!

This is a technique that's based on Ryan Mulligan's 'Layout Breakouts' which is based on Josh Comeau's 'Full-Bleed Layout' and is especially useful when creating a fully fluid layout. This also pairs well with fluid type techniques resulting in layouts that TRULY scale with the viewport size.

Setting Up the Grid #

Here's the layout we're going to be building:

If we break apart the design, we've got 4 possible widths for components:

• Full-Width
• Feature
• Popout
• Content

We've also go some special side-anchored elements that 'stick' to one of the screen edges but also honor the other element widths. We'll come back to these later on.

Now that we've categorized the widths, lets start drawing column edges and defining areas:

1. Left margin / Full-Width
2. Left Feature
3. Left Popout
4. Center Content
5. Right Popout
6. Right Feature
7. Right margin / Full-Width

That's a lot of columns!

Yet on mobile, we only need 3 columns, just left margin (1), center content (4), and right margin (7). We want some of these intermediate columns to disappear!

Fortunately, CSS Grid gives us some powerful tools to create the measurements needed—yes, even for the disappearing columns! We won't even have to write any media queries for this one. We can make just ONE definition that works at all sizes.

We'll store our measurements as CSS variables for easy use later on:

Let's break these down.

--gap: clamp(1rem, 4vw, 2rem);

gap will be our side margin, allowing it to stretch up to 2rem at max, with a preferred width of 4vw, but never going below 1rem.

--full: minmax(var(--gap), 1fr);

We're going to use the minmax() function for these next three measurements to say: "If there's room in the CSS Grid, you can expand out to here but then don't go smaller than the minimum".

The full area is going to expand from left edge to right edge (remember we have to split the areas to allow for the other columns) and will double as our margin, so we'll pop in our gap value as our minimum and tell it that it can expand up to 1fr, or basically as much space as the rest of the grid will allow it.

--feature: minmax(0, 12vw);
--popout: minmax(0, 2rem);

The feature and popout both have a minimum value of 0. This is what powers our disappearing columns! As other areas of the grid expand, these will collapse when there's no longer any room for them, essentially taking up no space.

--content: min(clamp(30rem, 52vw, 60rem), 100% - var(--gap) * 2);

And then finally, our content area is our most complex measurement. It's saying, take the minimum value of either:

1. A fluid measurement that can be 30-60rem (with the help of clamp())
2. OR full width minus our gap value (but doubled for both left and right values).

These measurements can be changed to fit the needs of your layout. Specifically the feature and popout maximum values and the first content value. For example, our use of vw for the feature means it will fluidly expand out as the screen grows whereas the popout will remain only 2rem larger on each side than the content column.

Now we can assemble these measurements in a CSS grid column definition. We'll name our column edges with [custom-ident] and use the -start and -end endings to help make assignment easier later on.

The definition is complex, but if we visualize the start and end lines of our columns as well as the measurements, it looks like this:

You can see we have our middle content column, our disappearing feature and popout columns, and finally our full columns that double as our margin.

To finish off the definitions, we need to create column assignments. Because we named our columns with custom identifiers and specified the start and stop lines, we don't have to fiddle with grid numbers. We can assign them directly like:

And if we want to create a default assignment for elements in the grid (which is especially useful if you don't have full control over the markup) you can create one like this:

Now you can attach any of these classes to components in your grid and have them snap to the width you want.

Watch the screen capture below as the grid scales down. You can see the feature and popout columns disappearing as everything transitions to a mobile width, and then expands back up.

You can see a demo of the base setup here:

Nesting Grids #

Now let's go back to our header element. You can see that though the header is full-width, we actually want its inner content to honor the feature width.

Fortunately, because of the flexible nature of this grid definition, we can repeat the definition and then continue using the same column names on the inner structure. Because our grid only goes one layer deep we're free to replicate as much as we need or even break out and use different layout methods for the component interiors.

You can see it in action here:

Anchoring Left and Right #

Remember those side-anchored components? This is where we need to get a little tricky to line everything up.

Going back to our diagram, we want an element to span MOST of the way across the page, but end at the opposite feature edge. We can reuse our column definitions for the first part.

Great! That gives us exactly what we want... except for when we try to nest the grids.

Our original grid definition assumes that our content, while different widths, is centered in the window. We have to rethink our inner grid definition a little bit.

We're shaving off one end of the grid, specifically a full definition. So two things need to happen:

1. We need to adjust our content width to now account for only having one gap.
2. We need our new grid end to stop at the edge of the feature column.

We can achieve this with a new measurement and a new grid definition:

We've replaced the inner content measurement with the new value and combined the feature and full ends with the final line of the template column definition:

[feature-end full-end]

This will allow redefinition inside the new side-anchored component. You will notice that you'll need to supply your own padding for the inner as they no longer have that final margin to prevent it from reaching the new grid edge.

If you want to reverse this to be anchored to the right, you can flip the grid definition, moving the double start to the top like:

You can see a demo of the side-anchored component here:

But What About Tailwind! #

We love using Tailwind at Viget as a Team Accelerator™, and it's straightforward to implement these measurements and definitions in your Tailwind config.

Everything is effectively the same, but you'll call your grid classes like grid-cols-breakout to set the grid, and your columns like col-feature per Tailwind naming conventions.

Forwards to a Fluid Future! #

And there you have it! A media-query-less fluid breakout layout defined with CSS grid!

While the setup is more complicated at first glance, I've found that the more fluid your layout rules are, the FEWER rules you have to write overall! Especially when paired with fluid type, dynamic viewport units, and all the amazing features that are landing in CSS — it's truly a fluid future!

Background #

Postgres Full Text Search (FTS) is a great way to implement site search on a website running Postgres already, without requiring additional infrastructure.

On a recent engagement with a client, we were deciding between Postgres FTS and ElasticSearch. Ultimately we chose FTS because we could spin it up without having to add extra infrastructure, as we would with ElasticSearch.

Since the project was written in Ruby on Rails, we were able to use the excellent PgSearch gem to implement FTS in ActiveRecord.

Multisearch #

As we wanted a general site search, we needed to utilize multisearch. Multisearch combines multiple ActiveRecord models into one search 'document' table that you can search against. For example, if a user searches for some search term, and the search is configured for multisearch, then every single model that we mark as multisearchable will be searched for that term at the same time. See here for more detail.

Search Features #

PgSearch allows for different search features, tsearch, trigram, and dmetaphone. The default is tsearch, which uses the built-in Postgres Full Text Search.

This was great for our use case, since it also comes with highlighting, a feature that was required. The highlighting is from a field returned by Postgres FTS, where it returns the text around the search term for context and bolds the search terms.

Spelling Mistakes #

Unfortunately, tsearch does not handle misspelled words. However, as I mentioned before, PgSearch allows for other search features!

And trigram is a feature that can be installed via a Postgres extension (pg_trgm) that does just that.

Trigram #

• The idea behind trigram search is to split pieces of text into sets of three-letter segments, and compare the sets to one another
• If two trigram sets are similar enough, we assume there was a spelling mistake, and return the document with the correctly-spelled term.
• As a quick example (ignoring whitespace): Consider the word Viget. Viget would make trigrams:

[vig, ige, get]

• Now, consider our evil twin agency, Qiget. They would make trigrams

[qig, ige, get]

• The two trigram sets match very closely, with only one of the trigrams not being the same. Thus, if we were to compare these with pg_trgm, we could reasonably tell that anyone typing 'Qiget' must have been actually looking for 'Viget', and just misspelled it.

Working Trigram into our existing solution #

PgSearch allows us to use multiple search features at once, so we can use tsearch and trigram side by side. Note that we cannot just replace tsearch with trigram due to needing some features in tsearch that are exclusive to it. Here is what an example configuration might look like.

PgSearch.multisearch_options = {
  using: {
    tsearch: {
      prefix: true,
      highlight: {
        MaxFragments: 1
      }
    },
    trigram: { 
      only: [:content]
    }
  }
}

Trigram (and timelines) causing issues #

While it was easy to slot Trigram into our multisearch, it caused a pretty serious performance hit. We were seeing 50x-75x slower searches with both features combined than with just tsearch. We needed to find a way to balance performance with handling misspellings

At the point that handling misspellings became prioritized, the entire search feature was almost fully QA'd and about ready to go out. There wasn't much time left in the budget to find a good solution for the issue.

This thread from the PgSearch repo sums it up pretty well – there were multiple other users that were/are having similar issues as we were. The top-rated comment in this thread is someone mentioning that the solution was to just use ElasticSearch ('top-rated' is doing a lot of heavy lifting. It did have the most likes...at two). We needed to find some sort of middle ground solution that we could act on quickly.

Postgres Documentation saves the day #

In the docs for the Trigram Postgres extension, the writers give an idea for using Trigram in conjunction with Full Text Search. The general idea is to create a separate words table that has a Trigram index on it.

Something like this worked for us. Note that we added an additional step with a temporary table. This was to allow us to filter out words that included non-alphabet characters.

execute <<-SQL
  -- Need to make a temp table so we can remove non-alphabet characters like websites
  CREATE TEMP TABLE temp_words AS
    SELECT word FROM ts_stat('SELECT to_tsvector(''simple'', content) FROM pg_search_documents');

  CREATE TABLE pg_search_words (
    id SERIAL PRIMARY KEY,
    word text
  );

  INSERT INTO pg_search_words (word)
    SELECT word
    FROM temp_words
    WHERE word ~ '^[a-zA-Z]+$';
  
  CREATE INDEX pg_words_idx ON pg_search_words USING GIN (word gin_trgm_ops);
  
  DROP TABLE temp_words;
SQL

This words table is therefore populated with every unique word that exists in your search content table. For us, this table was pretty large.

result = ActiveRecord::Base.connection.execute("SELECT COUNT(*) FROM pg_search_words").first['count']
puts result.first['count']
# => 1118644

Keeping the words table up-to-date #

As mentioned in the docs, this table is separate from your search table. Therefore, it needs to be either periodically regenerated or at least have any new words added to search content also added to this table.

One way to achieve this is with a trigger, which adds all new words (still filtering out non-alphabet characters) that are inserted into the documents table to the words table

create_trigger("pg_search_documents_after_insert_update_row_tr", generated: true, compatibility: 1)
  .on("pg_search_documents")
  .after(:insert, :update) do
  <<-SQL_ACTIONS
    CREATE TEMP TABLE temp_words AS
      SELECT word FROM ts_stat('SELECT to_tsvector(''simple'', ' || quote_literal(NEW.content) || ')');

    INSERT INTO pg_search_words (word)
      SELECT word
      FROM temp_words
      WHERE word ~ '^[a-zA-Z]+$';

    DROP TABLE temp_words;
  SQL_ACTIONS

end

Note that this does not handle records being deleted from the table – that would need to be something separate.

How we used the words table #

Assuming for simplicity the user's search term is a single word, if the search returns no results, we compare the search term's trigram set to the trigram index on the words table, and return the closest match.

Then, we'd show the closest match in a "Did you mean {correctly-spelled word}?" that hyperlinks to a search of the correctly-spelled word

Given more time, I would have liked to explore options to speed up the combined FTS and Trigram search. I'm certain we could have improved on the performance issues, but I can't say for sure that we could have gotten the search time down to a reasonable amount.

A future enhancement that would be pretty simple is to automatically search for that correctly-spelled word, removing the prompt to click the link. We could also change the text to something like "Showing results for {correctly-spelled word}".

Ultimately, I think with the situation at hand, we made the right call implementing Trigram this way. The search is just as fast as before, and now in the case of misspellings, a user just has to follow the link to the correctly-spelled word and they will see the results they wanted very quickly.

In 2022 we changed our dev tooling for new Craft CMS projects. Goodbye complex esoteric Webpack configuration, hello Vite. Goodbye complex esoteric Docker Compose configuration, hello DDEV. This small change in tooling has completely transformed our development experience. We start work faster and avoid wasting billable time debugging Webpack and Docker.

From Webpack to Vite #

Webpack has been the defacto way of bundling JavaScript and front end assets. It’s a powerful tool… but with that great power comes great responsibility complexity.

Vite bills itself as the “next generation” of frontend tooling. Vite is much faster at bundling. But more importantly… its default configurations work great for most website projects.

Before (Webpack) #

Well over 300 lines of configuration spanning three files. Good luck making changes!

After (Vite) #

A crisp 30 - 50 lines of code. Want to switch to TypeScript? Need to drop in a popular front-end framework? Easy! All it takes is adding a plugin and 2-3 lines of config.

Deleting old code has never felt this good!

From Docker to DDEV #

Docker is another development staple. It isolates server infrastructure into virtual “containers.” This helps avoid issues that arise from each developer having a slightly different setup. However, Docker can have a learning curve. Config changes, PHP upgrades and unexpected issues often eat up precious project time.

Enter DDEV! DDEV describes itself as “Container superpowers with zero required Docker skills: environments in minutes, multiple concurrent projects, and less time to deployment.” We’ve found that statement to be 100% true.

Before (Docker) #

Every Craft project has a different Docker config. Bugs and upgrades required deep Docker experience. Last (but not least), it was difficult to run several projects at one time (ports often conflict).

After (DDEV) #

Performance is consistently better than our hand-rolled setup thanks to Mutagen and faster DB import/exports. Simultaneous projects run out of the box. DDEV provides (and maintains) a growing list of helpful shortcuts and DX features.

Getting started #

Ready to make the switch? Here’s how to set up DDEV, Vite and Tailwind on your own Craft project.

Show me the config files already! #

If you would rather see full config files instead of following step by step, check out our Craft Site Starter on GitHub.

DDEV #

Let’s set up a fresh DDEV project and start customizing.

1. Make sure you have DDEV installed on your computer.
2. If you’re a PHPStorm user, install the exceedingly helpful DDEV plugin. VS Code users have a similar plugin too!
3. Follow Craft’s guide for creating a new project (they love DDEV too).

Now you have a fresh .ddev/config.yaml just waiting to be customized.

Node Version #

Open your DDEV config and make sure your Node JS version matches Vite’s recommendations.

Ports for Vite’s dev server #

Next, expose ports that Vite’s dev server uses will use to serve assets.

Routing ports can sometimes be confusing. This diagram might help!

• Vite’s dev server runs inside of DDEV’s web container (a Docker container).
• Until we expose these extra ports, any custom port within DDEV is unavailable to your host machine (your computer).
• When it’s time to configure Vite, we’ll use port 3000
• HTTP and HTTPS traffic must use separate ports.
• We use port 3000 for http traffic and 3001 for https

Run Vite automatically #

Usually, you’ll want Vite to watch and build files automatically after you start a DDEV project. Using web_extra_daemons adds a separate background process (daemon) for Vite.

Use hooks to improve DX #

DDEV’s powerful hooks system can run tasks before or after various DDEV commands. These post-start tasks keep dependencies and schemas up to date every time you start DDEV.

Time for Vite #

Vite is a Node app that’s installed with NPM. Your project will need a package.json. If you don’t have one set up yet, follow NPMs initialization script.

????Why ddev at the start of the command? This let’s us run NPM from within DDEV’s Docker containers. This means you’ll always be using the Node version configured for this project. DDEV has a bunch of shortcuts and aliases for running CLI commands (such as npm, yarn, craft and composer).

Make sure your NPM package is configured for ES Modules #

Our various config files will be using ES Module syntax for imports and exports.

Install Vite! #

Add convenience scripts to package.json #

npm run dev runs Vite in dev mode. It watches and builds your files every save. Files are served through Vite’s dev server.

npm run build bundles your JavaScript, CSS and static images for production. Your deploy process will usually call this script.

Configure vite.config.js #

Running Vite for a server rendered CMS requires some extra configuration. These options put production files in the right spot and keeps Vite’s dev server running on a specific port.

Add JavaScript and CSS files (Entrypoint) #

Vite needs an entry point to determine what JavaScript, CSS and Front End assets it needs to compile. Remember src/js/app.js that we defined in vite.config.js? Let's make that file now.

We’ll also add our CSS as an import in app.js . In plain-old-JavaScript you can’t import CSS files. However, Vite uses this to figure out CSS dependencies for the project.

Once Vite builds everything for production, you end up with a separate CSS file. The Craft Vite plugin includes this automatically with along your JavaScript bundle.

Install the Vite Craft Plugin #

Vite assets have different URLs in dev mode vs. production. In dev mode, assets are served from Vite’s dev server. It uses the ports that we defined in our DDEV & Vite configs.

When Vite builds for production, filenames are hashed (app.js becomes app-BZi_KJSq.js). These hashes change when the contents of the file changes. Browser can cache these files indefinitely. When an asset changes, a whole new file is served.

To help find these hashed filenames, Vite creates a manifest.json file. The manifest associates the name of your asset src/js/app.js to the hashed file that ends up on your server web/dist/assets/app-BZi_KJSq.js

The Craft Vite Plugin by NYStudio107 takes care of all this routing for you.

Configure the Vite Craft Plugin #

Make a new plugin config file in config/vite.php

Include your Vite bundles in Twig #

The script and asset functions includes the appropriate files depending on in if you’re in dev mode or production. Clear out your templates/index.twig file and add the following snippet to your <head> tag.

Whew! ???? We’re at a point now where we can test our integration. Run ddev restart and then ddev launch . You should see “Hello Craft CMS” in your browser console.

Setup Tailwind #

Now that Vite is processing src/css/app.css, it’s time to install Tailwind and really get cooking.

These steps are based on Tailwind’s official installation guide. But make sure to run all commands from within DDEV.

Install packages #

Configure template paths in tailwind.config.js #

Configure postcss.config.js for production #

Add Tailwind directives to src/css/app.css #

You’ll most likely need to run ddev restart again to get Vite to recognize your new Tailwind config.

❓ Do i need to set up live reload of Twig? Turns out it’s already done for you! Styling a Tailwind project means editing Twig files to change styles. It’s super handy to reload your browser every time you save. Normally you’d reach for vite-plugin-restart to get this functionality. However, Tailwind’s JIT mode automatically notifies Vite when CSS has compiled and the page should reload.

That's a wrap! #

That’s all it takes to configure a minimal DDEV and Vite project! We’ve found that both of these tools are easy to extend as a project get more complo'ex. Adding things like Redis or React are just a plugin install and a few lines of config away.

???? If you'd like to see this setup (and more) in a real-world Craft CMS project, check out our Craft Site Starter on GitHub.

Go forth and Vite + DDEV to your heart’s desire.