Adding a second language to a Symfony site usually means duplicating controllers, hardcoding URL prefixes, and scattering locale checks everywhere. holas.pl takes a different approach: locale config lives in one YAML file, routes are generated from a custom PHP attribute, and translations are linked by the filesystem — not by explicit keys.

The Problem with Hardcoded Locales#

The first working version of holas.pl's multilanguage support had around 30 places with patterns like this:

#[Route('/blog/', name: 'blog_list_en')]
public function listEn(int $page = 1): Response
{
    return $this->renderList('en', $page);
}

#[Route('/pl/wpisy/', name: 'blog_list_pl')]
public function listPl(int $page = 1): Response
{
    return $this->renderList('pl', $page);
}

Every route had two methods — one per locale. The real controller logic lived in a private render*() method; the public methods were pure boilerplate that set the locale and delegated. Seven controllers × two locales = 28 methods doing nothing useful.

Adding a third language would mean adding 14 more methods, plus updating templates, the locale listener, and every place that checked 'pl' === $locale. The code didn't scale.

Single Source of Truth — _site.yaml#

The fix starts with centralizing the locale list. Instead of spreading locale knowledge across PHP files, everything lives in content/_site.yaml:

site:
  locales:
    en:
      label: "English"
      og_locale: en_US
      date_format: "M d, Y"
    pl:
      label: "Polski"
      og_locale: pl_PL
      font_preload: fonts/inter-normal-latin-ext.woff2
      date_format: "d.m.Y"

Order matters: the first key is the default locale. Each locale carries its own metadata — og_locale for Open Graph tags, date_format for template rendering, font_preload for Latin Extended characters that only Polish needs.

SiteConfigService reads this file once, caches it, and provides it to the entire application:

interface SiteConfigServiceInterface
{
    /** @return string[] Ordered locale codes, first = default */
    public function getLocales(): array;

    public function getDefaultLocale(): string;

    /** @return array<string, mixed> Config for a single locale */
    public function getLocaleConfig(string $locale): array;
}

Every controller, listener, and route loader injects this interface. No PHP code imports a locale list from framework.yaml or hardcodes ['en', 'pl'].

Custom Route Attribute — #[LocalizedRoute]#

The key innovation is a custom PHP attribute that replaces duplicate route methods:

#[\Attribute(\Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
final class LocalizedRoute
{
    public function __construct(
        public readonly string $name,
        public readonly string $path,
        public readonly array $requirements = [],
        public readonly array $methods = [],
        public readonly int $priority = 0,
    ) {
    }
}

The attribute defines a route for the default locale only. A custom LocalizedRouteLoader scans all controllers, finds #[LocalizedRoute] attributes, and generates {name}_{locale} routes for every configured locale:

#[LocalizedRoute('blog_list', path: '/blog/')]
#[LocalizedRoute('blog_list_paginated', path: '/blog/page/{page}/', requirements: ['page' => '\d+'])]
public function list(string $locale, int $page = 1): Response
{
    // one method handles all locales
}

This single method replaces the two listEn() / listPl() methods from before. The loader generates four routes from the two attributes: blog_list_en, blog_list_pl, blog_list_paginated_en, blog_list_paginated_pl.

The total across all controllers: 28 methods became 14. Every removed method was pure boilerplate.

Route Resolution#

The loader needs to know that /blog/ is the English path but /pl/wpisy/ is the Polish one. A three-step resolution algorithm handles this:

private function resolvePath(
    string $name, string $defaultPath,
    string $locale, string $defaultLocale,
    array $overrides,
): string {
    if ($locale === $defaultLocale) {
        return $defaultPath;                          // EN: /blog/
    }

    if (isset($overrides[$name][$locale])) {
        return '/'.$locale.$overrides[$name][$locale]; // PL: /pl/wpisy/
    }

    return '/'.$locale.$defaultPath;                   // fallback: /pl/blog/
}

1. Default locale — use the attribute's path as-is: /blog/
2. Override exists — prepend /{locale} + the translated path from _routes.yaml
3. No override — prepend /{locale} + the default path: /pl/blog/

_routes.yaml — Translated Path Segments#

Only routes with translated URL segments need overrides. Routes without entries get auto-prefixed:

routes:
  blog_list:
    pl: /wpisy/
  blog_list_paginated:
    pl: /wpisy/strona/{page}/
  blog_category:
    pl: /wpisy/{category}/
  blog_archive:
    pl: /archiwum/{year}/{month}/
  contact:
    pl: /kontakt/
  search:
    pl: /szukaj/

blog_tag has no entry, so blog_tag_pl gets the auto-prefix: /pl/tag/{tag}/. Adding German would mean adding de: entries to the routes that need translation, and nothing for routes where the English path is fine.

Two URL Resolution Patterns#

Templates need to link to pages. There are two fundamentally different cases:

Structural routes come from the router — they're generated by LocalizedRouteLoader and have {name}_{locale} names. Content URLs come from frontmatter slug fields — each en.md and pl.md defines its own URL.

{# Structural: the router knows the path #}
<a href="{{ path('blog_list_' ~ locale) }}">Blog</a>
<a href="{{ path('contact_' ~ locale) }}">Contact</a>

{# Content: look up by directory key #}
<a href="{{ content_url('about', locale) }}">About</a>
<a href="{{ content_url('privacy-policy', locale) }}">Privacy</a>

content_url() is a custom Twig function that looks up a ContentItem by its directory key — the folder name — and returns the URL from its frontmatter. This replaces the old approach of hardcoding slugs per locale in templates.

Co-located Content — The Filesystem as Translation Link#

Content files for the same post live in the same directory:

content/blog/tutorials/my-post/
    en.md  → slug: "blog/my-post"
    pl.md  → slug: "pl/blog/moj-wpis"
    files/ → images served at /media/my-post/

Both files in the same folder are automatically linked as translations. No explicit translation_key field needed. ContentItem::directoryKey() returns the folder name ("my-post"), and TranslationMapBuilder uses it to build a lookup table:

public function build(array $trees): array
{
    $map = [];

    foreach ($trees as $locale => $tree) {
        foreach ($tree->getAllItems() as $item) {
            $key = $item->directoryKey();
            if (null === $key || '' === $item->url()) {
                continue;
            }
            $map[$key][$locale] = $item->url();
        }
    }

    return $map;
}

The result: $map['my-post']['en'] = '/blog/my-post/', $map['my-post']['pl'] = '/pl/blog/moj-wpis/'. This map drives hreflang <link> tags in the HTML head and the language switcher.

Not every post needs both locale files. A post with only en.md won't appear in Polish listings, and the language switcher falls back to the other language's homepage.

Language Switcher — Fallback Chain#

The language switcher seems simple — link to the same page in the other language. In practice, it needs to handle partial translations, tag pages, archive pages, and paginated listings. The fallback chain:

{# 1. Try translation map (page exists in other locale) #}
{% if tk and translation_map[tk][other] is defined %}
    {% set url = translation_map[tk][other] %}
{% endif %}

{# 2. Try controller-provided URL (tag pages) #}
{% if url is null and lang_switch_url is defined %}
    {% set url = lang_switch_url %}
{% endif %}

{# 3. Fallback: archive, paginated listing, or homepage #}
{% if url is null %}
    {% if filter_type is same as('archive') and archive_year is defined %}
        {% set url = path('blog_archive_' ~ other, {year: ..., month: ...}) %}
    {% elseif current_page > 1 %}
        {% set url = path('blog_list_paginated_' ~ other, {page: current_page}) %}
    {% else %}
        {% set url = path('home_' ~ other) %}
    {% endif %}
{% endif %}

Tag pages get special treatment: BlogController translates the tag slug between locales (e.g., security → bezpieczenstwo) and checks whether the other locale has any posts with that tag. If yes, the switcher links to the translated tag page. If no, it falls back to the other locale's blog listing.

On the client side, locale-redirect.js handles first-visit language detection. It reads navigator.language, matches it against the configured locale list (from a data-locales attribute on <html>), and stores the preference in a cookie. On return visits, it redirects to the saved preference. The locale list isn't hardcoded in JavaScript — it comes from the same _site.yaml config, passed through Twig.

Locale Detection#

LocaleListener runs at priority 8 — after Symfony's built-in locale listeners — and detects locale from the URL path:

private function detectLocale(string $path): string
{
    $defaultLocale = $this->siteConfig->getDefaultLocale();

    foreach ($this->siteConfig->getLocales() as $locale) {
        if ($locale === $defaultLocale) {
            continue;
        }

        if (str_starts_with($path, '/'.$locale.'/') || '/'.$locale === $path) {
            return $locale;
        }
    }

    return $defaultLocale;
}

No hardcoded /pl/ check. It iterates the configured locales dynamically. Adding a new locale to _site.yaml is enough for the listener to start detecting it.

Adding a New Language — Zero PHP Changes#

This is the payoff. Adding German to holas.pl requires:

1. content/_site.yaml — add a de: entry with label, og_locale, date_format
2. content/_routes.yaml — add de: overrides for translated route segments
3. translations/messages.de.yaml — German UI strings (nav labels, button text, etc.)
4. content/_tags.yaml — German tag translations
5. Content files — create de.md alongside en.md and pl.md for posts that should exist in German

No PHP files touched. No Twig templates edited. No controller methods added. The route loader generates German routes automatically. The locale listener detects /de/ paths. The language switcher renders a dropdown instead of a toggle link. The translation map includes German URLs.

The 28 locale-specific controller methods and 30 hardcoded locale checks from the first version would have meant editing 20+ files to add German. The configuration-driven approach means editing 5 config files and creating content.

The architecture decisions that make this work — SiteConfigService as the single locale authority, LocalizedRouteLoader generating routes from attributes, co-located content as the translation link — are the kind of decisions that seem like over-engineering when you only have two languages. They're not. They're the difference between "adding a language is a week of work" and "adding a language is an afternoon of config."

Next post covers how the codebase improved through iterative quality rounds — value objects, interfaces, component extraction — with AI handling the systematic review work.

On a static site, there's no server handling requests and no application layer checking the clock. Both features require deliberate implementation — and the right place for both is the build step.

Responsive Images#

The Problem#

Featured images on holas.pl are 1280×720px WebP. On a desktop browser, that's the right size. On a mobile screen 400px wide, the browser downloads a 1280-pixel image to display at 400 pixels — roughly 10× the data actually needed.

The solution is srcset + sizes: tell the browser what image variants exist and how large the image renders at each viewport width, then let it pick the right file. The static site constraint: every variant must exist as a file before any request arrives. There's no resize-on-demand.

Build-Time Variant Generation#

BuildStaticSiteCommand generates variants after copying media files to public/static/media/. It scans for .webp files, reads each file's actual dimensions with getimagesize(), and generates variants via ImageResizerInterface::resize():

$variantWidths = $this->responsiveImageService->getVariantWidths($width);

foreach ($variantWidths as $variantWidth) {
    $this->imageResizer->resize(
        $filePath,
        $dir . '/' . $baseName . '-' . $variantWidth . 'w.webp',
        $variantWidth,
    );
}

ImageResizer::resize() calls ImageMagick:

magick source.webp -resize 640x -quality 82 -strip -define webp:method=6 source-640w.webp

-resize 640x scales to 640px wide, preserving aspect ratio. -quality 82 -strip -define webp:method=6 matches the production image settings and removes EXIF data.

Variant filenames follow a convention: image.webp → image-640w.webp, image-960w.webp. The build skips files that already end in -640w or -960w to avoid re-processing previously generated variants.

ResponsiveImageService#

Two places need to know which variants exist: BuildStaticSiteCommand (which files to generate) and SrcsetExtension (which filenames to reference in HTML). Rather than duplicating the breakpoint logic, both inject ResponsiveImageServiceInterface:

interface ResponsiveImageServiceInterface
{
    /** @return int[] */
    public function getVariantWidths(int $sourceWidth): array;

    public function buildSrcset(string $src, int $sourceWidth): string;
}

The implementation:

public function getVariantWidths(int $sourceWidth): array
{
    if (960 < $sourceWidth) {
        return [640, 960];
    }
    if (640 < $sourceWidth) {
        return [640];
    }

    return [];
}

public function buildSrcset(string $src, int $sourceWidth): string
{
    $base = substr($src, 0, -5);  // strip .webp

    if (960 < $sourceWidth) {
        return sprintf('%s-640w.webp 640w, %s-960w.webp 960w, %s 1280w', $base, $base, $src);
    }
    if (640 < $sourceWidth) {
        return sprintf('%s-640w.webp 640w, %s 960w', $base, $src);
    }

    return '';
}

Images ≤640px wide get no variants — the original is already small enough. buildSrcset() returns '' to signal that no srcset attribute is needed.

If breakpoints ever need to change, there's one place to update.

Featured Image Component#

The responsive_img.html.twig component renders featured images with srcset hardcoded to the 640/960/1280 breakpoints:

<img src="{{ src }}"
     srcset="{{ src|replace({'.webp': '-640w.webp'}) }} 640w,
             {{ src|replace({'.webp': '-960w.webp'}) }} 960w,
             {{ src }} 1280w"
     sizes="{{ sizes|default('(max-width: 48em) 100vw, 720px') }}"
     alt="{{ alt }}"
     width="{{ width|default(1280) }}"
     height="{{ height|default(720) }}">

sizes="(max-width: 48em) 100vw, 720px" tells the browser: below 48em viewport width, the image fills the full viewport; above that, it's constrained to 720px (the content column width). The browser uses this to pick the right srcset entry before downloading anything.

width and height are explicit for Cumulative Layout Shift prevention — the browser reserves the exact space for the image before it loads. Without them, the layout shifts when the image arrives.

Inline Content Images#

Markdown images inside post body render as plain <img> tags. No srcset. A post with a diagram or screenshot at /media/post-dir/diagram.webp would serve the full-size image to mobile too.

The srcset_media Twig filter handles this. In post.html.twig:

{{ content.htmlContent|srcset_media|raw }}

SrcsetExtension::srcsetMedia() finds all /media/*.webp <img> tags with a regex, reads the source image width from the content directory (not the static output), and injects srcset and sizes:

$result = preg_replace_callback(
    '/<img(\s[^>]*)src="(\/media\/[^"]+\.webp)"([^>]*)>/i',
    function (array $matches): string {
        $src = $matches[2];

        // skip if srcset already present
        if (str_contains($matches[1], 'srcset') || str_contains($matches[3], 'srcset')) {
            return $matches[0];
        }

        $width = $this->getSourceWidth($src);
        if (null === $width) {
            return $matches[0];
        }

        $srcset = $this->responsiveImageService->buildSrcset($src, $width);
        if ('' === $srcset) {
            return $matches[0];  // no variants generated — leave as-is
        }

        return sprintf(
            '<img%ssrc="%s" srcset="%s" sizes="(max-width: 48em) 100vw, 720px"%s>',
            $matches[1], $src, $srcset, $matches[3],
        );
    },
    $html,
);

getSourceWidth() looks up the actual source file under content/ (not public/static/), since that's where the original dimensions live. Images with no variants — small inline screenshots ≤640px wide — are left unchanged.

Scheduled Posts#

The Problem#

A post with date: 2026-06-01 shouldn't appear in listings until June 1. The site rebuilds nightly, so a future-dated post simply won't appear in ContentTree::getAllPosts() until the build after its publish date. That part is automatic.

The URL is a different problem. If someone shares the link before the post is live, they get a 404. Better to serve a "coming soon" page at the exact URL the post will occupy.

ContentItem::isScheduled()#

public function isScheduled(): bool
{
    $date = $this->date();

    return null !== $date && $date > new \DateTimeImmutable();
}

One comparison. isDraft() takes priority — a post with both draft: true and a future date is treated as a draft and excluded from all builds.

Static Build: Coming-Soon Pages#

BuildStaticSiteCommand::collectRoutes() collects two categories of post URLs:

• Published posts via ContentTree::getAllPosts() — rendered with the full post template
• Scheduled posts via ContentTree::getScheduledPosts() — rendered with the coming-soon template

Both produce static HTML files at their eventual URL. When the post's date passes and the next build runs, isScheduled() returns false, the URL moves to the published list, and the full post HTML replaces the coming-soon HTML. No redirect, no special handling needed.

The Coming-Soon Page#

The coming-soon template uses the same green terminal aesthetic as the error pages:

{% block robots %}<meta name="robots" content="noindex, nofollow">{% endblock %}

<pre class="coming-soon-terminal"><code>
<span class="coming-soon-terminal__code">COMING_SOON</span>
{% if days_until <= 14 %}
<span class="coming-soon-terminal__text">{{ post.title }}</span>
<span class="coming-soon-terminal__date">Publishing: {{ post.date|date('Y-m-d') }}</span>
{% endif %}
</code></pre>

noindex, nofollow — the page handles direct links gracefully without ranking or passing link equity.

If the publish date is ≤14 days away, the title and date are shown. Further out: just the COMING_SOON code, no date. The 14-day threshold avoids making a public commitment to a specific date that might slip.

Dev Preview Toolbar#

In production, scheduled posts are invisible — they appear only as coming-soon pages at their URLs, not in any listing.

In development, you're writing scheduled post content and need to see it. The Symfony profiler toolbar gets a calendar icon toggle ("Scheduled preview"). When on, scheduled posts appear in listings with a [PLANNED] badge:

{% if post.isDraft() %}
    <span class="post-card-badge post-card-badge--draft">[DRAFT]</span>
{% elseif post.isScheduled() %}
    <span class="post-card-badge post-card-badge--planned">[PLANNED]</span>
{% else %}
    {# pinned / new / recently updated badges #}
{% endif %}

Toggle it off to preview what production will look like. The mechanism mirrors the existing draft preview toggle exactly — same session key pattern (scheduled_preview), same controller structure.

The Build-Step Pattern#

Both features follow the same approach: push work into the build step, keep the serving layer simple.

Responsive images: generate all variants at build time. A few seconds of ImageMagick calls during ddev build saves bandwidth on every mobile page load for the lifetime of the post.

Scheduled posts: pre-render coming-soon pages rather than handling "not yet published" at request time. The static file exists, nginx serves it, no PHP involved.

The build runs once. nginx serves the result to every visitor. Any work that can move to the build step is work the server doesn't have to do.

The build pipeline that makes this possible is covered in Part 2 of this series. The two-container production setup that runs it is in Part 3.

What Lighthouse SEO doesn't check: whether your structured data is complete, how your page renders as a social card, what feed readers see when they subscribe, whether Google can find and index your images without crawling every page.

This post covers the implementation layer beneath that score.

Structured Data#

Structured data is JSON-LD in a <script type="application/ld+json"> block. It tells search engines what a page is, not just what it says. holas.pl uses four schema types.

WebSite + SearchAction#

Every page carries a WebSite schema identifying the site and its search endpoint:

{
    "@context": "https://schema.org",
    "@type": "WebSite",
    "name": "holas.pl",
    "url": "https://holas.pl",
    "author": {
        "@type": "Person",
        "name": "Paweł Holik",
        "url": "https://holas.pl"
    },
    "potentialAction": {
        "@type": "SearchAction",
        "target": {
            "@type": "EntryPoint",
            "urlTemplate": "https://holas.pl/search/?q={search_term_string}"
        },
        "query-input": "required name=search_term_string"
    }
}

The potentialAction enables the Google Sitelinks search box — a search input that appears directly in the Google result for the site. It maps to the Pagefind-powered search at /search/. This is one extra field on an existing schema with no downside.

BlogPosting#

Blog posts carry the richest schema. Beyond headline, description, url, and datePublished, several fields matter for how Google represents the content:

• inLanguage — "en" or "pl", needed for multilingual indexing
• wordCount — computed at parse time by ContentItem::wordCount() (strips HTML tags, counts tokens)
• articleSection — the post category
• keywords — the post tags as a comma-separated string
• image — a nested ImageObject with url, width, and height

{
    "@type": "BlogPosting",
    "headline": "Post title",
    "inLanguage": "en",
    "wordCount": 842,
    "articleSection": "tutorials",
    "keywords": "seo, symfony, static-site",
    "image": {
        "@type": "ImageObject",
        "url": "https://holas.pl/media/post-dir/featured.webp",
        "width": 1280,
        "height": 720
    }
}

Without ImageObject, Google treats the featured image as an unknown attachment. With width and height explicitly set, the image becomes eligible for large preview cards in Google Discover and Search.

BreadcrumbList#

Google can replace the raw URL in search results with breadcrumb navigation — "Home / Blog / tutorials / Post Title". This requires BreadcrumbList schema.

It's rendered in breadcrumb.html.twig alongside the HTML nav. Each crumb is a ListItem with position and item (URL). The last item — the current page — has a name but no URL:

{
    "@type": "BreadcrumbList",
    "itemListElement": [
        { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://holas.pl/" },
        { "@type": "ListItem", "position": 2, "name": "Blog", "item": "https://holas.pl/blog/" },
        { "@type": "ListItem", "position": 3, "name": "tutorials", "item": "https://holas.pl/blog/tutorials/" },
        { "@type": "ListItem", "position": 4, "name": "Post Title" }
    ]
}

CollectionPage + ItemList#

Category, tag, and archive listing pages carry CollectionPage with a nested ItemList. Each entry has a position and url. Only rendered when the listing has posts — an empty category page doesn't get it.

{
    "@type": "CollectionPage",
    "name": "tutorials | holas.pl",
    "mainEntity": {
        "@type": "ItemList",
        "numberOfItems": 5,
        "itemListElement": [
            { "@type": "ListItem", "position": 1, "url": "https://holas.pl/blog/post-name/" }
        ]
    }
}

Social Sharing#

OpenGraph Image Dimensions#

Without og:image:width and og:image:height, platforms like LinkedIn and Slack must fetch the image before rendering the preview card. With them, the card renders immediately:

<!-- blog post (WebP, 1280×720) -->
<meta property="og:image:width" content="1280">
<meta property="og:image:height" content="720">
<meta property="og:image:type" content="image/webp">

<!-- other pages (default og:image, JPG, 1200×630) -->
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:type" content="image/jpeg">

The conditional is in base.html.twig: if a content object with an image is defined (blog post or page with featured image), use the WebP dimensions; otherwise use the defaults for og-default.jpg. The JPG exception exists because og:image is consumed by external crawlers that don't reliably support WebP.

Twitter/X Card#

The base twitter:card type was already present. Three explicit fields were added:

<meta name="twitter:title" content="...">
<meta name="twitter:description" content="...">
<meta name="twitter:image" content="...">

Without them, Twitter/X falls back to OG properties. Explicit meta removes that dependency — if OG processing has any issue, Twitter Card still has the correct values.

article:* Meta#

Blog posts get article-specific OG meta in post.html.twig's og_article_meta block:

<meta property="article:published_time" content="2026-06-21T00:00:00+00:00">
<meta property="article:modified_time" content="2026-06-21T00:00:00+00:00">
<meta property="article:author" content="Paweł Holik">
<meta property="article:section" content="tutorials">
<meta property="article:tag" content="seo">
<meta property="article:tag" content="symfony">
<meta property="article:tag" content="static-site">

article:tag is one element per tag — not comma-separated. The Open Graph spec requires separate elements for multi-value properties.

Feed Readers#

content:encoded#

The default RSS <description> contains only the post excerpt — first paragraph, HTML stripped. content:encoded carries the full post HTML in a CDATA block:

<content:encoded><![CDATA[<p>Full post content...</p>]]></content:encoded>

This requires xmlns:content="http://purl.org/rss/1.0/modules/content/" on the root <rss> element. Feed readers like NetNewsWire, Reeder, and Feedbin render content:encoded inline — subscribers read the full article without leaving their reader.

category and media:content#

Each RSS item gets <category> elements for the post category and each tag:

<category>tutorials</category>
<category>seo</category>
<category>symfony</category>

media:content attaches the featured image as a typed media attachment:

<media:content url="https://holas.pl/media/post-dir/featured.webp"
               medium="image" type="image/webp" width="1280" height="720"/>

Feed readers that render inline images (Feedly, Inoreader) use this for the post thumbnail in the feed list. This requires xmlns:media="http://search.yahoo.com/mrss/" on the <rss> element.

Crawling Signals#

max-image-preview:large#

The default robots behavior limits image previews in Google Search and Discover to standard size. max-image-preview:large opts into full-size previews. Combined with max-snippet:-1 (no restriction on text snippet length), this is the default robots meta on every page:

<meta name="robots" content="max-image-preview:large, max-snippet:-1">

Implemented as the default {% block robots %} in base.html.twig. Child templates override the block for pages that shouldn't be indexed — coming-soon pages use noindex, nofollow, the search page uses noindex.

Image Sitemap#

The standard sitemap lists page URLs. The image sitemap adds <image:image> blocks, giving Google direct visibility into image locations and alt text without crawling every page first:

<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:image="http://www.google.com/schemas/sitemap-image/1.1">
    <url>
        <loc>https://holas.pl/blog/post-name/</loc>
        <image:image>
            <image:loc>https://holas.pl/media/post-name/featured.webp</image:loc>
            <image:title>Alt text from image_alt frontmatter</image:title>
        </image:image>
    </url>

image:title comes from the image_alt frontmatter field — the same text used in the HTML alt attribute. Both the xmlns:image namespace and the image:image block are in sitemap.xml.twig.

What Changed#

The Lighthouse SEO score was 100 before these changes. It's still 100 after them. That score measures the technical floor: crawlability, meta tags, mobile-friendliness.

The changes above operate at a different level. Structured data shapes how search engines represent content in rich results. Explicit social meta ensures correct rendering without relying on platform fallback logic. RSS extensions let subscribers read full posts in their reader. The image sitemap gives Google image visibility without requiring a crawl of every page.

None of it is architecturally complex — most of it is Twig template additions and namespace declarations. The constraint is discipline: every field needs a real value from frontmatter, not a placeholder.

The architecture that makes all of this straightforward is covered in Part 2 of this series — the static generation pipeline that produces complete HTML for every page.

This post goes through what actually drives each number. Most of it isn't optimisation work — it's a side effect of how the site is built.

Performance#

The main reason the performance score is 100 is that nginx serves pre-rendered HTML files with no PHP involved. There is no database query, no template rendering, no framework bootstrap on every request. A file comes off disk and goes to the client. A Raspberry Pi 5 handles this without breaking a sweat.

Everything else follows from there:

Assets are hashed and immutable. JavaScript and CSS files compiled by Symfony's AssetMapper get a content hash in the filename (app-a1b2c3d4.css). nginx serves them with Cache-Control: public, max-age=31536000, immutable — one year, no revalidation. On repeat visits, the browser serves everything from cache. On deploy, the hash changes and the new file is fetched.

JavaScript is minimal and non-blocking. The site uses native ES module imports via a browser-native importmap — no bundler, no webpack, no jQuery. There are seven small JS files: app.js, contact.js, cookie-banner.js, lightbox.js, locale-redirect.js, nav-toggle.js, tagline.js. None of them block rendering. Search is powered by Pagefind, a WASM-based static search index that loads lazily — only on the search page, only when needed.

Images are WebP. Featured images are stored as WebP at 1280×720. No large uncompressed JPEGs.

No render-blocking resources. There is no <link rel="stylesheet"> to an external font CDN, no synchronous third-party script loaded in <head>. The CSS is compiled locally and served as a hashed asset.

Accessibility#

<html lang> is set per locale. Every page has the correct language attribute — lang="en" for English pages, lang="pl" for Polish. This is set in the base Twig template based on the current locale, not hardcoded.

Semantic HTML throughout. The layout uses <nav>, <main>, <article>, <aside>, <footer> — not a sequence of <div> elements. Headings follow a logical hierarchy: one <h1> per page, <h2> for top-level sections, <h3> below that.

Color contrast passes. The site uses a Monokai-derived dark palette: #F8F8F2 text on #242424 background. That's a contrast ratio of 15.5:1, well above the WCAG AA threshold of 4.5:1.

All images have alt attributes. This is enforced in the Twig templates — the <img> tag always outputs the alt text from the content item's frontmatter.

Viewport meta tag is present. Every page includes <meta name="viewport" content="width=device-width, initial-scale=1">.

Best Practices#

HTTPS. The site runs behind Cloudflare, which handles TLS termination. All HTTP requests are redirected to HTTPS.

Security headers. nginx sets the full set on every response:

add_header X-Frame-Options           "SAMEORIGIN"                       always;
add_header X-Content-Type-Options    "nosniff"                          always;
add_header Referrer-Policy           "strict-origin-when-cross-origin"  always;
add_header Permissions-Policy        "camera=(), microphone=(), geolocation=()" always;
add_header Content-Security-Policy   "default-src 'self'; ..." always;

The CSP required some care — wasm-unsafe-eval for Pagefind's WASM bundle, and challenges.cloudflare.com as an allowed frame source for the Turnstile CAPTCHA on the contact form. Everything else is 'self'.

No deprecated APIs. The site doesn't use document.write, XMLHttpRequest, <table> layouts, or anything else Lighthouse flags as a deprecated practice.

No mixed content. Every external resource (Cloudflare Turnstile script) is loaded over HTTPS.

SEO#

Pre-rendered HTML. Crawlers receive complete HTML — every heading, paragraph, code block, and link is in the source. There is no client-side rendering to wait for, no JavaScript required to see the content.

Sitemap with hreflang. The sitemap at /sitemap.xml lists all posts and pages for both locales. Each entry includes <xhtml:link rel="alternate" hreflang="..."> pairs pointing to the EN and PL versions. If a post exists only in one language, the alternate entry is omitted.

hreflang in <head>. Every page includes <link rel="alternate" hreflang="..."> tags for both locales. The language switcher uses the same translation map — built from co-located en.md/pl.md files in each post directory.

Canonical URLs. Each page includes <link rel="canonical" href="..."> pointing to the authoritative URL for that page.

OpenGraph meta. Every page has og:title, og:description, og:image, and og:url. These are populated from frontmatter — title, description, and image fields map directly to the OG tags in the base template.

Descriptive titles and meta descriptions. Frontmatter title and description fields are required. The site doesn't have any pages with default or missing meta descriptions.

What wasn't automatic#

Most of the above follows from the architecture — static files, minimal JS, pre-rendered HTML. But a few things required deliberate work.

Accessibility attributes. The lang attribute, alt text enforcement, heading hierarchy, and semantic element choices all had to be written into the templates. They don't appear by themselves.

The CSP. Getting the Content-Security-Policy right took iteration. Pagefind uses WebAssembly, which requires wasm-unsafe-eval. Cloudflare Turnstile loads from challenges.cloudflare.com and needs a frame-src exception. Every third-party resource requires an explicit CSP exception — adding one without checking breaks the score.

hreflang. The TranslationMapBuilder service builds the {directoryKey → {locale → url}} map from co-located content files. If a post exists only in one locale, the hreflang entry for the missing locale is omitted rather than pointing to a non-existent URL. This required a deliberate fallback in the template, not just a loop over all locales.

The result#

The 4×100 isn't the outcome of an optimisation sprint. It's what you get when a site serves static files, uses minimal JavaScript, has proper HTML structure, and sets the security headers that should be on every production site anyway.

The architecture is described in detail in Part 2 of this series (how Symfony generates the static HTML) and Part 4 (how nginx serves it in production).

notACMS grew out of my own site and for the first release it was one piece: clone the repo, get a full design, start overriding. It worked, but anyone who wanted to build their own look from scratch had to fight against things they didn't need. 1.1.0 fixes this by splitting core from the demo theme.

The core is a skeleton#

templates/, assets/, translations/ are now a minimal wireframe. System fonts, light mode, ~200 lines of CSS. All features work — blog, pages, search, RSS, sitemap, responsive images, contact form — but it looks like a site from the 90s. Deliberately. If you're building your own design, you don't fight a theme that imposes a visual language on you.

The demo theme lives in docs/demo/ and is the default seed — ./notACMS deploy or ddev build will lay it down on first run. Pass --bare if you want the skeleton instead:

./notACMS deploy           # amber-phosphor (default), ready to tweak
./notACMS deploy --bare    # skeleton, build your own from scratch

Everything else — the local override pattern, no core editing, clean git pull — works the same regardless of your choice.

What else shipped in 1.1.0#

Reading time and reading progress on posts and docs. Language switcher as a Twig extension. Post excerpts that no longer leak # from heading anchors. PHPUnit test scaffolding under tests/. AI-agent skills for working with the repo. An old-template compatibility package at docs/customization/old-template/ — one cp -r and you're back to the 1.0.0 look.

1.1.1 — the patch that real use forced#

Preparing this post on holas.pl, deploying to production, I noticed something annoying: ./notACMS deploy --prod backed up and replaced local/ on every run. If you already had content there, it was gone. Deploy couldn't tell "user wants to replace the whole theme" from "user just wants to build their site with existing content."

1.1.1 fixes it so deploy behaves like ddev build: it seeds local/ only when the directory is missing or empty. Content you already have stays untouched. Want to force a re-seed? Pass --bare or --demo explicitly.

The other change is frontmatter-driven navigation labels. Until now every tab in the menu needed a translation key in every locale file — nav.home, nav.about, site.releases and so on. Adding a page meant updating N YAML files. Now menu.label in a page's frontmatter is enough:

---
title: "Architecture guide"
menu:
  label: "Architecture"
  weight: 30
---

A new content_item() Twig function reads it without extra config:

{{ content_item('architecture-guide', 'en').menuLabel() }}

Polish, German, and French demo content got a full review across every page and blog post.

1.1.2 — review-driven hardening#

1.1.2 is what happens when you sit down with the code before tagging and look at it with fresh eyes. Two security bugs surfaced during the review and got fixed before release: an open-redirect through path normalisation (Request::getPathInfo() doesn't collapse repeated slashes, so /<default-locale>//evil.com would have produced a Location: //evil.com cross-origin redirect), and an XSS in the search results page where Pagefind's excerpt was injected into innerHTML without escaping.

The headline feature is canonical URLs. If your default locale is en, /en/blog/ and /blog/ were both reachable and rendered the same content — two indexable URLs for one page. A new event listener now issues 301s from /<default-locale>/... to the unprefixed form before Symfony's router even runs.

Internally, the inline |json_encode|raw JSON-LD blocks scattered across templates are gone. A small StructuredDataBuilder service plus two Twig functions (json_ld() and structured_data()) replace them with a fluent, typed API. JSON_THROW_ON_ERROR is on, so a bad UTF-8 byte in frontmatter raises an exception during render instead of silently shipping <script>false</script>. The bare core templates for contact, default, and projects pages now emit Schema.org markup too — bare deploys no longer have weaker SEO than every customisation example.

The demo as living proof#

The most satisfying part of this release is not the code — it's what ships in docs/demo/. Not the theme. A complete, four-language site that lives in the repository. It has its own manual, architecture docs, styleguide, and a releases blog — all running, all rendered by the same system you get after git clone.

• Manual — install, config, content structure, frontmatter, build commands, deploy, environment variables, troubleshooting
• Architecture — routing, content pipeline, static build, search, multi-language, deployment
• Styleguide — every component documented with real SCSS tokens
• Releases blog — posts about every version, rendered by the system itself

"I trust you that it works, but show me" — this is that. The demo is not an example, it's proof. Multi-language routing, static pre-rendering, Pagefind search, responsive images, contact form, RSS, sitemap — everything runs in the demo content. Someone doing a fresh git clone followed by ddev build sees exactly this site.

Links#

Full changelog with every change categorised: CHANGELOG.md.

Breaking changes and migration from 1.0.0: UPGRADE-1.1.md.

Repository: GitHub / holas1337/notACMS — Apache 2.0.

Building holas.pl involved writing a fair amount of PHP, Twig, and SCSS — and making architectural decisions that would be annoying to undo later. I used Claude Code as an AI pair programmer throughout. This post covers what that workflow actually looks like, where it works well, and where it still needs human judgment.

AGENTS.md — The AI's Instruction Manual#

The first practical insight from this project: an AI assistant is only as good as the instructions it's given. Without explicit guidance, Claude defaults to generating functional but generic code — reasonable choices, but not necessarily the choices you'd make yourself.

The solution is AGENTS.md, a file in the project root that Claude Code reads at the start of every session. It documents:

• Architecture rules — final classes only, no inheritance, interface segregation, value objects over associative arrays
• Code style — strict types on every file, Yoda conditions, blank line before return, PSR-4 namespace convention
• Naming conventions — interface naming (ContentServiceInterface → ContentService), readonly value objects, constructor property promotion
• DDEV commands — how to start the environment, run builds, check code quality
• Content structure — where Markdown files live, how frontmatter works, what the URL slug conventions are

With this context, Claude generates code that follows the project's actual conventions. Reviewing a generated class feels like reviewing a pull request from a teammate who has read the style guide — not reviewing output that needs to be translated into project conventions.

EDITOR_GUIDE.md — Delegating Content Creation#

The same principle applies to content. EDITOR_GUIDE.md documents:

• Title format and length (under 70 characters, technology names included, no clickbait)
• Description format (120–160 characters, no "In this post...", lead with reader benefit)
• Intro structure (2–3 sentences, no greeting, problem first)
• Body conventions (code blocks for all commands, short paragraphs, numbered steps for procedures)
• EN/PL parity requirements (both versions equal depth, same code blocks)
• Frontmatter fields and their formats

With this guide, the content creation workflow becomes:

1. Write the post in rough form — the ideas, the code snippets, the structure
2. Hand it to Claude with: "proofread this, correct the English, translate to Polish, and produce the two .md files with correct frontmatter"
3. Review the result

The guide is specific enough that Claude doesn't need to ask clarifying questions. Title format, slug convention, category values, tag format, image path pattern — it's all documented. The output is ready to commit.

Image Generation with Draw Things and MCP#

Every post needs a featured image (minimum 1200×630px). For holas.pl, images are generated locally using Draw Things via the MCP (Model Context Protocol) integration in Claude Code.

The workflow:

1. Claude Code calls mcp__draw-things__generate_image with a prompt describing the image, 4 parallel variants at 1024×576px with steps=4
2. The best variant is selected from .generated/YYYY-MM-DD-session-name/
3. ImageMagick upscales it to production size:

ddev exec convert .generated/session/image.jpg \
    -resize 1920x1080! -filter Lanczos -quality 92 \
    assets/images/output.jpg

4. The image is moved to content/blog/category/post-name/files/ and referenced in frontmatter

The .generated/ directory is gitignored — it holds expendable previews. Only approved images committed to files/ become production assets.

MCP (Model Context Protocol) is what makes this work: it's a standard interface for connecting AI assistants to external tools. Claude Code connects to Draw Things running locally, Hugging Face Spaces, and other services without leaving the development session. The image generation happens on the local machine — no API quota, no external service, no per-image cost.

What AI Does Well#

Boilerplate and patterns — generating a new service with its interface, value object, and correct import ordering is instant. The structure is consistent with the rest of the codebase because the conventions are documented.

SCSS from description — describing a component layout in words and getting working SCSS back, with the project's variable names, is faster than writing it from scratch.

Translation — Polish and English content at equal quality. The editorial guide's specificity about what "equal quality" means (same code blocks, same depth, not a summary) produces translations that don't need significant editing.

Repetitive structured work — generating nginx redirect lists, updating frontmatter across multiple files, writing sitemap entries — tasks with clear rules but many instances.

Staying in context — Claude Code reads the project files, understands the existing patterns, and generates code that fits without being told what every class does.

Where Human Judgment Is Still Required#

Architecture decisions — which abstractions to introduce, when a value object is warranted, how to structure the content pipeline — these require understanding the trade-offs in a way that goes beyond pattern matching. The AI generates plausible options; the decision is still human.

Design aesthetics — SCSS variables can be generated, but deciding whether the color palette looks right on a dark terminal-style background requires eyes and taste.

Content voice — the editorial guide captures tone conventions, but the actual ideas — what's worth writing about, what angle is interesting — come from experience, not from a prompt.

Reviewing AI output — the code and content still need to be read. AI-generated code is plausible-looking; it takes a developer to notice when something is technically correct but architecturally wrong.

The Practical Result#

The entire site — architecture, frontend, content pipeline, contact form, deployment scripts, this blog post series — was built with Claude Code. The time investment in AGENTS.md and EDITOR_GUIDE.md paid back immediately: less time correcting style, less time explaining the same conventions session after session, more time on the actual work.

The most surprising benefit was content. Writing a post in rough Polish, having it proofread, translated to English, and converted to two properly-structured .md files with correct frontmatter in one step — that removes enough friction that publishing actually happens.

The architecture built this way doesn't just produce maintainable code — it produces measurable results. The next post looks at the Lighthouse scores: what drives each of the four metrics and why most of it follows from the architecture, not from optimisation work.

One of the goals for holas.pl was a development environment as simple as the production one. No database to start, no Docker networking to configure by hand, no five-minute startup sequence. The result is a DDEV-based dev setup that starts with a single command and a production stack that runs in two containers.

Development with DDEV#

DDEV handles the local development environment. The entire setup is in .ddev/config.yaml:

name: holas-pl
type: php
php_version: "8.5"
webserver_type: nginx-fpm
nodejs_version: "22"
omit_containers: [db]
web_environment:
  - APP_ENV=dev

The omit_containers: [db] line is notable — there's no database, so there's no database container. DDEV's default MySQL/MariaDB setup is skipped entirely. ddev start spins up nginx + PHP-FPM and nothing else.

In development the content tree is rebuilt on every request, so editing a Markdown file and refreshing the browser shows the change immediately. No cache to clear. Symfony's debug toolbar is available. Draft posts are visible.

The Build Command#

ddev build runs the full pipeline:

rm -rf var/dart-sass         # remove arch-specific binary (see below)
php bin/console cache:clear
php bin/console sass:build   # compile SCSS via dart-sass
php bin/console asset-map:compile  # fingerprint assets
php bin/console app:build    # render all URLs to public/static/
npx pagefind --site public/static --output-path public/pagefind

After this, public/static/ contains the complete site as HTML files. nginx serves from that directory. The dart-sass step removes the platform-specific binary before the build to force a fresh download — more on this below.

Code Quality Checks#

ddev code-check runs four checks in sequence:

composer validate --strict
composer audit --no-dev         # checks for known CVEs in dependencies
vendor/bin/php-cs-fixer fix --dry-run --diff
vendor/bin/phpstan analyse      # level 6

ddev code-fix auto-fixes PHP CS Fixer issues and re-runs the check. PHPStan level 6 catches missing type hints, wrong argument types, and unknown methods before they reach production.

The Styleguide#

A dev-only page at /styleguide/ documents every component in the UI using the actual CSS classes — not wrappers or snapshots. The page is served only in the dev environment (the controller throws a 404 in production) and is not included in the static build.

The value of the styleguide is in development: changing a component's SCSS immediately updates the styleguide. There's no separate design system to keep in sync.

Asset Pipeline Without Node.js#

SCSS is compiled by symfonycasts/sass-bundle, which wraps dart-sass and requires no Node.js installation. The single entrypoint assets/styles/app.scss imports all partials. In development it compiles on-the-fly. In production php bin/console sass:build runs before the build.

JavaScript modules are handled by Symfony's AssetMapper — no webpack, no Vite, no rollup. Scripts are loaded as plain <script src="..."> tags with content-hashed filenames. The import map registers only the main app.js entrypoint; other scripts (contact form, search, cookie banner) are loaded separately via {{ asset('script.js') }} in templates.

The dart-sass binary problem: symfonycasts/sass-bundle downloads a platform-specific dart-sass binary to var/dart-sass/. The binary compiled on a development machine (x86_64) won't run in the production Docker container (also x86_64 in this case, but the binary path and version can differ). The solution is straightforward: delete the binary before every build and let dart-sass download the correct one for the current platform.

Production: Two Containers#

The production docker-compose.yaml:

services:
  nginx:
    image: nginx:alpine
    volumes:
      - ./docker/nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - .:/app:ro
    depends_on:
      - php

  php:
    build:
      context: .
      dockerfile: docker/Dockerfile
    user: "${UID:-1000}:${GID:-1000}"
    volumes:
      - .:/app

Two containers: nginx and PHP-FPM. No database container. nginx mounts the project read-only; PHP-FPM runs as the host user to avoid file permission issues with the Symfony cache.

The PHP image (docker/Dockerfile) is php:8.5-fpm-alpine with only what's needed: icu-dev (Symfony intl), nodejs and npm (for the Pagefind build step), unzip, git, and Composer.

Deployment#

The entire deployment is a single script ./deploy.sh --prod:

1. docker compose down
2. docker compose build --pull — rebuilds the PHP image from scratch
3. docker compose up -d
4. composer install --no-dev --optimize-autoloader
5. php bin/console cache:clear
6. rm -rf var/dart-sass — remove the arch-specific binary
7. php bin/console sass:build
8. php bin/console asset-map:compile
9. php bin/console app:build — render all static HTML
10. npx --yes pagefind --site public/static --output-path public/pagefind

The build runs inside the PHP container where the correct CPU architecture is known. After step 10, nginx is already serving the previous build's static files. The new files replace them atomically at the filesystem level. There's a brief window where a partial build is live, but for a low-traffic portfolio site this is acceptable without blue-green deployment complexity.

No CI/CD pipeline, no staging environment. Deployment is ssh server, cd holas.pl, git pull, ./deploy.sh --prod.

Compared to WordPress#

The full WordPress production stack required: PHP-FPM, MySQL, a caching layer (Redis or filesystem), a scheduled task runner for wp-cron, and enough RAM to keep MySQL warm. Updates to any component required downtime or careful sequencing.

The current stack is two containers. A Raspberry Pi 5 runs it without memory pressure. Deployment is a shell script. The entire codebase, content, and configuration fits in a single git repository. Backup is git push.

The next post in the series covers the most unconventional part of this project: building the entire site with Claude Code as an AI pair programmer, and using MCP tools to generate featured images locally.

The fix is a global CLAUDE.md — a persistent instruction file that teaches Claude which tool to reach for based on the query type. This post walks through my setup, the decision tree I built, and how you can build one for your own stack.

The Problem: Too Many Tools, No Strategy#

MCP servers give Claude Code superpowers: browser automation, error tracking, documentation lookup, IDE integration. But more tools means more choices, and without guidance Claude makes reasonable but suboptimal picks.

Common failure modes I observed:

• Wrong tool for the job — querying Context7 for "latest Symfony version" (it only has docs, not release metadata) instead of Perplexity
• Expensive path when a cheap one exists — using Grep to search for Symfony routes across multiple files instead of asking JetBrains MCP for a structured route list
• Missing the specialist — not checking Sentry for a production error when the stack trace would immediately reveal the root cause
• Redundant queries — trying multiple tools sequentially when the memory could route to the right one immediately

The solution is explicit routing rules stored in Claude Code's global CLAUDE.md. Claude reads this file at the start of every session, so the decision tree is always available.

My MCP Stack#

Here are the six MCP servers I run and what each does best.

Context7 — Library and Framework Docs#

Context7 serves versioned documentation with code examples. You give it a library name and a question, and it returns the relevant section from official docs.

Workflow: resolve-library-id (find the library) → query-docs (fetch docs for a specific question). It supports versioned lookups — I can query /sylius/sylius/v1.14.6 specifically, not just "latest."

Best for:

• Method signatures and configuration examples
• Migration guides between framework versions
• How-to patterns from official docs (Symfony forms, Doctrine mappings, API Platform filters)

Fails for:

• Current version numbers or release dates (it has docs, not metadata)
• PHP language features (PHP itself isn't a library with versioned docs in Context7)
• Security CVEs or advisories
• Anything that requires real-time information

Perplexity — Current Facts and Research#

Perplexity is an AI-powered web search with four modes: search (web results with citations), ask (AI-synthesized answers via sonar-pro), research (deep multi-source analysis, 30+ seconds), and reason (step-by-step logical reasoning).

Best for:

• Latest version numbers, release dates, EOL schedules
• Security advisories and CVE details
• PHP language features and RFCs (property hooks, asymmetric visibility — these aren't in Context7)
• External service pricing (API costs, hosting comparisons)
• General programming best practices and benchmarks

Key role: Perplexity fills every gap Context7 has. When Context7 returns nothing or returns stale docs, Perplexity almost always has the answer.

JetBrains — IDE-Level Code Intelligence#

This is the MCP server that saves the most tokens. JetBrains MCP connects Claude Code to your IDE's index — the same index that powers autocomplete, go-to-definition, and refactoring. The base JetBrains MCP provides generic tools (file search, symbol lookup, text search, terminal commands), and framework plugins extend it with specialized tools — the Symfony plugin adds route listing, service lookup, Doctrine entity inspection, and Twig analysis.

My typical workflow: I paste a Jira ticket link into the conversation. Claude reads the task via the Atlassian MCP, then uses JetBrains MCP to do a quick code reconnaissance — finding the relevant services, checking route definitions, inspecting entity fields — all before writing a single line of code. This "analyze first" step catches misunderstandings early and gives Claude the context to ask better clarifying questions.

Symfony-specific capabilities (via the Symfony plugin):

• list_symfony_routes_controllers — all routes with controller, path, methods. One call instead of grepping through attributes across dozens of files
• locate_symfony_service — find any service definition by its fully-qualified class name
• list_doctrine_entity_fields — entity fields, types, and relationships in structured format
• list_symfony_commands, list_symfony_forms — console commands and form types at a glance

Token savings example: Finding all routes matching /api/ in a Symfony project:

• Without JetBrains: Grep for #[Route across src/Controller/, read each matching file, parse the route attributes, cross-reference with _routes.yaml. Easily 5-10 tool calls and thousands of tokens of file content.
• With JetBrains: One list_symfony_routes_controllers call returns a structured, filterable list. Done.

Also useful for: Indexed text search (search_in_files_by_text), file search by name, symbol lookup, running terminal commands in the IDE, build/test execution.

Chrome DevTools — Browser Automation#

Chrome DevTools MCP lets Claude control a browser: navigate to URLs, click elements, fill forms, take screenshots, inspect network requests, run JavaScript, and execute Lighthouse audits.

Best for:

• Testing UI changes visually after modifying templates or CSS
• Running Lighthouse performance/accessibility audits
• Debugging frontend issues (checking console errors, network requests)
• Verifying responsive behavior at different viewport sizes

Sentry — Production Error Tracking#

Sentry MCP connects Claude to your error tracking system. It can search issues, retrieve stack traces, analyze errors with Sentry's AI (Seer), and look up release and deployment information.

The workflow that makes this valuable:

1. You notice an error (or a user reports one)
2. Claude queries Sentry: "search for 500 errors in the last 24 hours"
3. Sentry returns the stack trace, affected users count, first/last seen timestamps
4. Claude reads the relevant source file, identifies the root cause, and proposes a fix
5. The entire debug cycle happens without leaving the terminal

Best for:

• Investigating production errors with full stack traces
• Understanding error frequency and patterns (is it new? is it getting worse?)
• Correlating errors with recent deployments

Atlassian/Jira — Task Management#

Jira MCP provides full issue lifecycle management: create, read, edit, transition, comment, and search with JQL.

Best for:

• Reading task specifications before starting work
• Updating issue status as work progresses
• Adding technical comments to issues for team visibility
• JQL searches to find related issues or check what's in the current sprint

The Decision Tree#

The core of the global CLAUDE.md is a routing table that maps query types to the best tool. Here's the actual content from mine:

## Search & Research — Tool Decision Tree

### When to use Context7
**Best for**: library/framework API docs with clean code examples
- Versioned library docs (Sylius, Doctrine, API Platform, Symfony, GitHub Actions)
- Official method signatures, configuration examples, how-to patterns
- Concise, authoritative answers directly from official source
- `resolve-library-id` first, then `query-docs`
- **Fails for**: current version/release info, PHP language features,
  security CVEs, pricing, general programming

### When to use Perplexity
**Best for**: anything current, factual, or not a library doc
- Latest versions, release dates, EOL schedules
- Security advisories, CVEs, vulnerability details
- PHP language features (property hooks, new syntax)
- External service pricing
- General programming best practices, benchmarks
- Supplement when Context7 fails or for real-world context

### When to use WebSearch
- Official blog posts / release announcements
- As last resort or to supplement

The key pattern: each section leads with "best for" (when to pick this tool) and ends with "fails for" (when to skip it). Claude uses both signals — positive routing and negative routing.

The Benchmark Table#

I ran the same 10 query types through Context7, Perplexity, and WebSearch and rated the results. This table lives in the global CLAUDE.md so Claude can reference it when deciding:

The pattern is clear: Context7 is excellent for versioned docs but scores zero on anything requiring current or real-world data. Perplexity covers nearly everything. WebSearch is the strongest for blog posts and release announcements.

Including this table in the global CLAUDE.md gives Claude a quantitative basis for tool selection, not just rules.

How Global Memory Works#

Claude Code supports a global instruction file at ~/.claude/CLAUDE.md. This file is loaded at the start of every conversation, regardless of which project you're working in. It's the right place for tool routing rules because MCP servers are configured globally, not per-project.

Compare this with project-level AGENTS.md:

Structuring the Global CLAUDE.md#

The global CLAUDE.md works best when it's structured like a reference manual, not a narrative. Claude scans it at session start — clear headings and explicit rules make that scan effective.

Tips from my experience:

1. Lead with the decision rule, not the description. "Best for: versioned library docs" is more useful than "Context7 is a documentation server that..."
2. Include failure modes. "Fails for: current versions" prevents Claude from trying Context7 for queries it can't handle.
3. Add a server inventory. List every MCP server with its tools — Claude can reference this when it needs a capability it hasn't used before.
4. Use concrete examples. "Latest Symfony version → Perplexity" beats "use Perplexity for current data."
5. Update when tools change. Added a new MCP server? Update the file. Removed one? Remove its entry. Stale routing rules are worse than no rules.

Build Your Own#

The specific MCP servers don't matter — the pattern does. Whether you use Cursor, Windsurf, or Claude Code, whether you write Python or Go, the principle is the same: teach your AI assistant which tool to reach for.

Step-by-step:

1. List your MCP servers (or equivalent tool integrations) and what each one does
2. Identify overlaps — where can two tools answer the same query? (Context7 and Perplexity both handle Symfony docs, but with different strengths)
3. Benchmark — run the same 5-10 representative queries through each overlapping tool. Rate the results. This gives you data, not gut feeling.
4. Write routing rules — for each tool, write "best for" and "fails for" sections with specific query types
5. Include the benchmark — the table gives your AI a quantitative reference, not just instructions
6. Iterate — the first version won't be perfect. When Claude picks the wrong tool, update the file. Over a few sessions, the routing gets tight.

My global CLAUDE.md started as a list of MCP servers with one-line descriptions. After a few weeks of observing where Claude made suboptimal choices, it evolved into the decision tree above. The benchmark table was the biggest single improvement — it turned vague "prefer X over Y" rules into concrete data Claude could act on.

The investment is small (an hour to set up, a few minutes per update) and the payoff compounds: fewer wasted tokens, faster answers, and less time correcting tool choices mid-conversation.

holas.pl is a static site with one exception: the contact form. Every blog post, category page, and static page is a pre-rendered HTML file served by nginx. The contact form is the only endpoint that runs PHP.

That single exception raises a specific security question: how do you protect a form on a static page from bot submissions and CSRF attacks when there's no session?

The CSRF Problem with Static Pages#

Standard CSRF protection works by embedding a token in the form that is tied to the user's session. When the form is submitted, the server verifies the token matches the one in the session.

Static pages don't have sessions. The contact page is generated once during ddev build and served as a file. It can't generate a per-user token at render time. Symfony's built-in csrf_protection is therefore explicitly disabled on the contact form:

public function configureOptions(OptionsResolver $resolver): void
{
    $resolver->setDefaults([
        'csrf_protection' => false,  // deliberate — static page, no session
    ]);
}

Disabling CSRF protection is the right call here. The alternative — adding a dynamic PHP endpoint just to generate tokens for the form — would reintroduce the PHP-on-every-request problem for a page that otherwise needs none.

Cloudflare Turnstile as the Replacement#

Cloudflare Turnstile is a CAPTCHA alternative that runs client-side, confirms the user is human, and provides a one-time token that can be verified server-side. It replaces CSRF as the bot-prevention layer.

The form flow:

1. The contact page is served as static HTML with the Turnstile widget embedded (site key baked in at build time)
2. Turnstile runs its challenge invisibly; on success it calls window.onTurnstileSuccess(token), which writes the token into a hidden field
3. contact.js intercepts the form submit event and sends the data via fetch() instead of a standard form post
4. The PHP endpoint receives the submission, validates the form fields, then verifies the Turnstile token with Cloudflare's API
5. Only if both pass does the email get sent

Server-side verification is the critical step:

final class TurnstileValidator
{
    public function verify(string $token, string $remoteIp): bool
    {
        try {
            $response = $this->httpClient->request('POST', 'https://challenges.cloudflare.com/turnstile/v0/siteverify', [
                'body' => [
                    'secret'   => $this->secretKey,
                    'response' => $token,
                    'remoteip' => $remoteIp,
                ],
            ]);

            $data = $response->toArray();

            return true === ($data['success'] ?? false);
        } catch (\Throwable $e) {
            $this->logger->error('Turnstile verification failed: '.$e->getMessage());

            return false;
        }
    }
}

The validator fails closed — any exception returns false and blocks the submission. An empty or missing token also returns false immediately.

Minimal PHP Attack Surface#

The entire application's PHP surface in production is two URL patterns:

location ~ ^/(api|pl/api)/ {
    fastcgi_pass $php_upstream;
    fastcgi_read_timeout 30;
}

Everything else — every blog post, every category page, the sitemap, the RSS feed, the search page — is handled by nginx serving static files. PHP-FPM is never invoked for content delivery. The attack surface for the PHP layer is a single POST endpoint.

Content Security Policy#

The nginx config applies a strict CSP on every response:

add_header Content-Security-Policy
    "default-src 'self';
     script-src  'self' challenges.cloudflare.com;
     style-src   'self' 'unsafe-inline';
     img-src     'self' data:;
     frame-src   challenges.cloudflare.com;
     connect-src 'self' challenges.cloudflare.com;"
    always;

The only external domain permitted is challenges.cloudflare.com, which Turnstile requires for its script, iframe, and API call. No Google Analytics, no CDN scripts, no Facebook pixel. script-src has no 'unsafe-inline' and no 'unsafe-eval' — all JavaScript is loaded from hashed files via Symfony AssetMapper.

The 'unsafe-inline' in style-src is a deliberate compromise: Turnstile's widget injects inline styles that can't be avoided without a CSP nonce, and AssetMapper doesn't currently inject nonces. Everything else is locked down.

Additional Security Headers#

add_header X-Frame-Options        "SAMEORIGIN"                       always;
add_header X-Content-Type-Options "nosniff"                          always;
add_header Referrer-Policy        "strict-origin-when-cross-origin"  always;
add_header Permissions-Policy     "camera=(), microphone=(), geolocation=()" always;

Hidden files are denied:

location ~ /\. { deny all; }

HSTS is handled upstream at Cloudflare, so there's no Strict-Transport-Security header in the nginx config — it would be redundant.

The Result#

The contact form works without sessions, without CSRF tokens, and without JavaScript being required for anything other than the form submission itself. The page renders fully as static HTML. Bot submissions are blocked by Turnstile's server-side verification. The PHP endpoint is unreachable for anything other than POST requests to /api/contact.

Compared to WordPress with a contact form plugin, the attack surface went from "PHP running on every request, wp-admin exposed, XML-RPC enabled, 22 plugins any of which could have a vulnerability" to "one POST endpoint with Cloudflare verification."

The next post covers the developer experience — DDEV, the build pipeline, and deployment to production in two Docker containers.

The codebase is open-source under Apache 2.0 — see GitHub / notACMS. It has 368 PHPUnit tests, CI/CD via GitHub Actions, and a local override pattern that lets users customise templates, CSS, and translations without forking.

Architecture#

All content lives in Markdown files with YAML frontmatter:

content/
├── blog/
│   └── tutorials/
│       └── my-post/
│           ├── en.md   ← English version
│           ├── pl.md   ← Polish version
│           └── files/  ← images, served at /media/my-post/
└── pages/
    └── about/
        ├── en.md
        └── pl.md

ContentTreeBuilder scans the filesystem, parses each file with league/commonmark (GitHub Flavoured Markdown + YAML frontmatter), and builds a typed ContentTree — an in-memory index of all posts and pages for a given locale. Tags, categories, archive months, and URL maps are computed from that index.

The static build uses Symfony sub-requests: HttpKernelInterface::handle() with SUB_REQUEST renders every URL through the full kernel without touching the network. If a URL works in development, it will be in the static build. No separate template engine, no build configuration.

Key Features#

• Multi-language — co-located en.md + pl.md in the same directory, automatic translation mapping, hreflang tags, language switcher
• Search — Pagefind WASM-based static index, client-side, no Elasticsearch or Algolia
• Responsive images — automatic srcset generation via ImageMagick, configured variant widths
• Draft & scheduled posts — dev-only preview toggles, scheduled posts automatically published at build time
• Contact form — Cloudflare Turnstile CAPTCHA, tight CSP, single POST endpoint
• Styleguide — dev-only page documenting every component with real CSS classes
• Local override pattern — local/ directory merges on top of base at build time, customise without forking

Tech Stack#

• PHP 8.5, Symfony 7.x
• Twig templates, SCSS (dart-sass via symfonycasts/sass-bundle)
• Symfony AssetMapper (no webpack, no Vite, no Node.js build pipeline)
• nginx + PHP-FPM (two Docker containers in production)
• Pagefind for search
• PHPUnit 13, PHPStan level 6, Rector, PHP CS Fixer

Why Build It?#

Hugo, Jekyll, and Eleventy were obvious candidates. I chose to build a custom Symfony application because I already know Symfony well, and owning the full stack turned out to have real advantages: the same templates, controllers, and content pipeline serve both development and production. There is no "build-time template engine" separate from the "runtime template engine." It's just Symfony.

The full story of why WordPress had to go is in Why I left WordPress. The architecture deep dive is in Symfony as a Static Site Generator.

Open Source#

notACMS is available on GitHub under Apache 2.0. The preparation for release — testing, AI code review, security fixes, the local override pattern — is documented in the open-source series.

After deciding to leave WordPress, the question was what to replace it with. Hugo, Jekyll, and Eleventy were obvious candidates. I chose to build a custom Symfony application instead — not because the existing tools are inadequate, but because I already know Symfony well, and owning the full stack turned out to have real advantages.

The Core Idea#

The site works in two modes:

• Development — Symfony handles requests dynamically. Edit a Markdown file, refresh the browser, see the result. Standard Symfony dev workflow with the profiler toolbar.
• Production build — a single console command renders every URL to an HTML file on disk. nginx serves those files directly. PHP is never called for content delivery.

The same templates, controllers, and content pipeline serve both modes. There is no "build-time template engine" separate from the "runtime template engine." It's just Symfony.

Content Pipeline#

All content lives in Markdown files with YAML frontmatter:

content/
├── blog/
│   └── tutorials/
│       └── my-post/
│           ├── en.md   ← English version
│           ├── pl.md   ← Polish version
│           └── files/  ← images, served at /media/my-post/
└── pages/
    └── about/
        ├── en.md
        └── pl.md

ContentTreeBuilder scans the filesystem, parses each file with league/commonmark (GitHub Flavoured Markdown + YAML frontmatter), and builds a typed ContentTree — an in-memory index of all posts and pages for a given locale. Tags, categories, archive months, and URL maps are computed from that index.

ContentItem is a final readonly value object. No database, no ORM, no migrations. Adding a post means creating a directory with two Markdown files and running the build.

The Build Command — Symfony Sub-requests#

The static build uses a technique that's specific to Symfony and distinguishes this approach from Hugo or Jekyll: it calls HttpKernelInterface::handle() to make sub-requests — internal PHP calls that go through the full Symfony kernel without touching the network.

$request = Request::create($url);
$request->attributes->set('_static_build', true);
$response = $this->kernel->handle($request, HttpKernelInterface::SUB_REQUEST, false);

if ($response->getStatusCode() < 400) {
    file_put_contents($outputPath, $response->getContent());
}

For every URL — blog posts, category pages, tag pages, archive months, static pages, error pages, RSS feeds, the sitemap — the build command creates a request, runs it through Symfony, and writes the HTML to disk. The URL /blog/ becomes public/static/blog/index.html. The URL /sitemap.xml becomes public/static/sitemap.xml.

No separate template engine to learn. No build configuration. If a URL works in development, it will be in the static build.

nginx Serves Everything#

In production, nginx handles all content delivery:

location / {
    try_files /static$uri/index.html /static$uri/index.xml /static$uri $uri =404;
}

# PHP only for the contact form
location ~ ^/(api|pl/api)/ {
    fastcgi_pass $php_upstream;
}

For any incoming URL, nginx tries the pre-rendered HTML file first. PHP-FPM is only invoked for /api/contact — the single dynamic endpoint. Every blog post, category listing, tag page, and static page is a file served directly from disk. A Raspberry Pi 5 handles this trivially.

No Database#

The content tree is built from Markdown files at build time. In production it's cached indefinitely in Symfony's filesystem cache (invalidated and rebuilt on every deploy). In development it's rebuilt on every request so file changes are immediately visible.

There is no MySQL, no schema, no migrations, no connection pooling, no slow queries. Adding content means creating files and running ddev build. Removing content means deleting files. The entire site history is in git.

Multi-language Without a Database#

Both Polish and English content lives in the same directory:

content/blog/tutorials/my-post/
    en.md  → slug: "blog/my-post"      → /blog/my-post/
    pl.md  → slug: "wpisy/moj-wpis"    → /pl/wpisy/moj-wpis/
    files/ → images served at /media/my-post/

Co-location is the translation link. Two locale files in the same directory are automatically treated as translations of each other. TranslationMapBuilder constructs {directoryKey → {locale → url}} for hreflang tags and the language switcher. No translation_key field, no join table, no synchronisation to manage.

Search with Pagefind#

Search is a WASM-based static index built by Pagefind after the HTML files are generated:

npx pagefind --site public/static --output-path public/pagefind

Pagefind reads the pre-rendered HTML, indexes data-pagefind-body regions, and generates a binary index in public/pagefind/. The search page loads this index client-side via a dynamic import(). No Elasticsearch, no Algolia, no server-side search query. The index is a set of static files.

Redesign Simplicity#

Changing the site's appearance means editing Twig templates and SCSS. No React component library to update. No Node.js build pipeline. No WordPress child theme hierarchy. The entire frontend is:

• assets/styles/app.scss — one entrypoint importing partials
• templates/ — Twig templates
• symfonycasts/sass-bundle — compiles SCSS with dart-sass, no Node required

To change the colour scheme: edit _variables.scss. To change the layout: edit a Twig template. Run ddev build and it's done.

Trade-offs#

The main trade-off compared to Hugo or Jekyll is that this is custom code — I maintain it. The upside is that it's exactly what's needed, nothing more. There's no plugin ecosystem to navigate, no upgrade path to worry about, no feature flags for things I'll never use.

The only genuinely dynamic feature — the contact form — is covered in the next post.

This is the first post in a series documenting the migration to a custom Symfony-based static site generator. The next posts cover the architecture, the contact form, the developer workflow, and building the site with AI assistance.

The Update Treadmill#

WordPress ships security updates frequently. Plugins ship updates independently. Themes do too. On a quiet week my update queue had three items. On a bad week it had fifteen. Each one required:

1. Back up the database and files
2. Apply the update
3. Check that nothing broke

That last step is the killer. WordPress plugins interact with each other in ways that are impossible to predict. An update to a caching plugin would break the SEO plugin's output. An update to the SEO plugin would change how sitemaps were generated. Every update was a small gamble.

For a portfolio site that publishes a post every few months, this maintenance overhead is absurd.

Dozens of Plugins for Basic Features#

A fresh WordPress installation does almost nothing useful. To run a respectable portfolio blog you need plugins for:

• SEO — Yoast or Rank Math, with their own settings screens, meta boxes, and update cycles
• Caching — W3 Total Cache or WP Super Cache, with complex configuration and edge cases
• Security — Wordfence or similar, scanning for intrusions, blocking IPs, sending daily reports
• Contact form — Contact Form 7 or Gravity Forms
• Backups — UpdraftPlus or similar, usually pushing to an external service
• Performance — image optimization, lazy loading, minification
• SMTP — because WordPress sends email through PHP mail() by default, which goes to spam

Each plugin is code you don't control, maintained by someone else, potentially abandoned tomorrow, running on every page load.

When I started planning the migration I counted 22 active plugins.

Bot Attacks and Login Problems#

A WordPress login page is a known target. The URL is always /wp-admin/ or /wp-login.php. Every bot on the internet knows this. The result: constant brute-force login attempts, around the clock.

I had Wordfence rate-limiting login attempts, blocking suspicious IPs, and sending me daily attack reports. It worked — but it was another moving part consuming server resources on a site that didn't need user logins at all. The only person logging in was me, once a month.

XML-RPC was another attack vector. WordPress enables it by default for pingbacks and the mobile app. Bots probe it constantly. The fix was an nginx rule to block it — but you only find out about it after seeing the traffic in your logs.

PHP and MySQL on a Raspberry Pi#

holas.pl runs on self-hosted hardware — first a Banana Pi, now a Raspberry Pi 5. These are capable ARM boards, but they are not server-grade machines. Running PHP-FPM and MySQL simultaneously for a blog that changes once a month is wasteful.

A typical WordPress page load on that hardware: PHP parses the request, MySQL runs several queries to fetch post content, navigation data, sidebar widgets, and site options, PHP renders templates, every active plugin executes its hooks. All of this for content that was identical to the last request and will be identical to the next one.

With a static site, nginx serves a pre-rendered HTML file directly from disk. The ARM processor barely wakes up. Pages load faster than WordPress could parse the incoming request.

The Database as a Liability#

Nineteen years of WordPress produces a database with thousands of rows of post metadata, options, post revisions, and transients. It needs:

• Regular backups (and testing that restores actually work)
• Occasional cleanup — WordPress accumulates garbage: post revisions, expired transients, orphaned metadata rows
• Monitoring for corruption after unclean shutdowns
• A MySQL process running continuously, consuming memory

A portfolio blog is a collection of text and images. Storing it in a relational database adds operational complexity without adding value.

What I Kept#

The content. All 26 posts were exported and converted to Markdown files — titles, dates, categories, tags, images. The URLs were preserved exactly: 25 individual post redirects and 43 image path redirects are now baked into the nginx config. Search rankings survived the migration intact.

Everything else — the database, the plugins, the update queue, the /wp-admin/ login page — is gone.

The next post covers what replaced it: a custom Symfony application that generates static HTML files and serves them through nginx, with no PHP involved in delivering content to visitors.

Traefik is a reverse proxy designed for container environments. It watches the Docker socket, discovers running containers, and automatically provisions Let's Encrypt certificates — no certbot, no cron, no manual config per domain.

The setup is split into two parts: a single Traefik instance that runs permanently, and per-service labels that tell Traefik how to route and which domain to certify.

Part 1 — Traefik docker-compose.yml#

This runs once on the server. All other services route through it.

services:
    traefik:
        image: traefik:${TRAEFIK_VERSION}
        container_name: traefik
        command:
            - "--providers.docker=true"
            - "--providers.docker.exposedbydefault=false"
            - "--entrypoints.web.address=:80"
            - "--entrypoints.websecure.address=:443"
            # global HTTP → HTTPS redirect
            - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
            - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
            # Let's Encrypt
            - "--certificatesResolvers.le.acme.email=${ACME_EMAIL}"
            - "--certificatesResolvers.le.acme.storage=acme.json"
            - "--certificatesResolvers.le.acme.tlsChallenge=true"
        restart: always
        ports:
            - 80:80
            - 443:443
        networks:
            - web
        volumes:
            - /etc/localtime:/etc/localtime:ro
            - /var/run/docker.sock:/var/run/docker.sock
            - ./acme.json:/acme.json
        labels:
            - traefik.http.middlewares.gzip.compress=true

networks:
    web:
        external: true

A few things worth noting:

• exposedbydefault=false — Traefik ignores containers unless they explicitly opt in via labels. Nothing gets exposed accidentally.
• TLS challenge — Traefik handles certificate issuance on port 443 directly. No need to temporarily expose port 80 for verification.
• acme.json — certificates are persisted to disk and survive container restarts. Create this file and set strict permissions before the first run:

touch acme.json && chmod 600 acme.json

Traefik will refuse to start if the file has looser permissions.

• External web network — create it once:

docker network create web

Every service that needs HTTP/S routing joins this network.

Part 2 — Staging certificates for testing#

Before going live, test with Let's Encrypt's staging server to avoid hitting rate limits:

# add to traefik command:
- "--log.level=DEBUG"
- "--certificatesresolvers.le.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"

Staging certs aren't trusted by browsers but are functionally identical for testing. Remove these lines when everything works.

Part 3 — Adding a service#

This is where it pays off. Any container gets HTTPS by adding four labels:

services:
    myapp:
        image: myapp:latest
        networks:
            - web
        labels:
            - traefik.enable=true
            - traefik.http.routers.myapp.rule=Host(`myapp.example.com`)
            - traefik.http.routers.myapp.entrypoints=websecure
            - traefik.http.routers.myapp.tls.certresolver=le

networks:
    web:
        external: true

Traefik picks up the container, requests a certificate from Let's Encrypt, and starts routing — no nginx config, no certbot run, no cron. Renewals happen automatically in the background.

Bare-metal alternative#

If you're not using Docker, Certbot with the nginx plugin is the standard approach: apt install certbot python3-certbot-nginx, run certbot --nginx -d mysite.com, and a systemd timer handles renewals. Works well for a single server with a handful of sites. Once you're managing more services, the Traefik approach becomes worth the initial setup.

Hardware specification#

The new setup was put together with maximum responsiveness and stability in mind:

• Unit: Raspberry Pi 5 (8 GB RAM).
• Case: Argon NEO 5 M.2 NVMe — provides effective cooling and direct SSD support through a dedicated interface.
• Storage: Lexar 1 TB M.2 PCIe NVMe NM620. Moving from micro SD to NVMe significantly reduces latency and increases media durability.

Energy efficiency#

One of the key arguments for choosing a Raspberry Pi as a 24/7 server is its low power draw. In the current configuration:

• Idle: Power consumption at 3 W (confirmed by a power meter reading).
• Stress (load): Power consumption rises to 9–12 W.

The performance-to-energy ratio makes this unit an extremely cost-effective solution.

System and OS-level services#

Everything runs on Raspberry Pi OS. At the operating system level (outside Docker) I configured the key management and access services:

• Remote access: A VPN based on the Wireguard protocol (PiVPN) provides a secure tunnel into the home network.
• Management: I use VNC for graphical interface access.
• File sharing: A standard Samba service for fast data access on the local network.

Docker environment#

The key change compared to the previous server is full containerization of network services. Traefik handles routing and automatic SSL certificate issuance.

Within Docker I currently maintain:

1. holas.pl — my website.
2. Nextcloud — a private cloud for data synchronization.
3. Immich — a solution for photo library backup and management.
4. Traefik — a reverse proxy managing incoming traffic.

Growth potential#

Despite running several demanding services, the 8 GB Raspberry Pi 5 shows plenty of headroom in both computing power and RAM. Current utilization allows for adding more containers without any risk of degrading the already running systems. Moving to the NVMe standard means that database operations (especially in Immich and Nextcloud) are now instantaneous.

After a year of internal use it reached v1.0.0, with full Sylius 2.x support, a clean structure, and everything I use day-to-day. Version 1.0.1 followed the next day with cross-platform fixes.

Why Sylius setup is painful without tooling#

Sylius 2.x has a non-trivial local setup. It requires PHP 8.4, Composer, a database, a web server with the correct rewrite rules, Node.js and Yarn for compiling the admin assets (based on Webpack Encore), and the Symfony binary for console tasks. Getting all of those running consistently across developer machines — Windows, macOS, Linux — without a container setup is fragile. Versions drift, environment variables differ, paths conflict.

DDEV solves this by declaring the entire environment as configuration. The boilerplate bakes in the correct versions and wires them together so no one has to figure it out manually.

What it configures#

The .ddev/config.yaml sets:

• PHP 8.4 with apache-fpm (Sylius 2.x requires PHP 8.2+; 8.4 is current stable)
• MariaDB 11.8 — latest stable, with upload_dirs tuned to exclude media/, node_modules/, and backups/ from Mutagen sync on macOS
• Composer 2
• Ports 8123 (HTTP) and 8443 (HTTPS) to avoid conflicts with other local projects
• Xdebug disabled by default — enable with ddev xdebug on when needed

What's included#

ddev-sylius is a DDEV-based project template for Sylius 2.x. Clone it, run two commands, and you have a working local Sylius instance — no manual configuration of PHP versions, database, or web server.

Custom DDEV commands bundled with the boilerplate:

• ddev sylius-install — full Sylius installation from scratch
• ddev cc — clear caches
• ddev dist — install dependencies and build assets (Composer + Yarn)
• ddev yarn <param> — Yarn commands inside the container
• ddev security-checker — scan for known vulnerabilities
• ddev code-check — run coding standards validation
• ddev backup / ddev database-import / ddev files-import — backup and restore database and media
• ddev sylius-cleanup — reset all data (useful when re-testing install flows)
• ddev build-site / ddev rebuild-site — full or partial project rebuild

Tested on Windows 11 with WSL2 (Ubuntu 24.04), macOS Tahoe (Apple Silicon), and Linux with Docker.

Getting started#

git clone https://github.com/holas1337/ddev-sylius my-project
cd my-project
ddev start
ddev sylius-install

That's it. A few minutes later you have a running Sylius storefront with an admin panel, accessible at the DDEV-generated local URL (default https://ddev-sylius-boilerplate.ddev.site:8443).

Day-to-day workflow#

After the initial install, the typical daily commands are:

ddev start             # start the environment
ddev cc                # clear caches after config changes
ddev dist              # rebuild assets after frontend changes
ddev code-check        # check coding standards before committing
ddev backup            # snapshot database before a risky migration

For debugging, ddev xdebug on enables Xdebug, and ddev exec bin/console <command> gives direct access to the Symfony console inside the container.

What changed in 1.0.1#

The day-after release fixed things that showed up during cross-platform testing: macOS-specific adjustments for Mutagen and upload directory exclusions, MariaDB upgraded from 11.4 to 11.8, and phpMyAdmin updated to the latest version.

The repository is on GitHub: holas1337/ddev-sylius. Issues and PRs welcome.

uBlock Origin#

The essential first layer. uBlock Origin (Firefox, Chrome) blocks ads and trackers at the network level. With default filter lists enabled it already blocks most Facebook tracking pixels and social widgets on third-party sites.

Note for Chrome users: Google's Manifest V3 transition limits some uBlock Origin capabilities in Chrome. The full-featured version remains available in Firefox.

Privacy Badger#

Privacy Badger by the Electronic Frontier Foundation (Firefox, Chrome) takes a different approach: instead of using a static blocklist, it learns which trackers follow you across sites and progressively blocks them. Works well alongside uBlock Origin.

Facebook Container (Firefox only)#

Facebook Container is a Mozilla extension that isolates your Facebook session in a separate container tab. Facebook can't see your activity on other sites, and third-party Facebook widgets on other sites can't read your Facebook session cookies.

This is the most effective single extension specifically targeting Facebook's cross-site tracking — and it's built and maintained by Mozilla.

Built-in browser protections#

Both Firefox and Brave ship with enhanced tracking protection enabled by default, which blocks many known trackers including Facebook's. If you use either browser, you already have a solid baseline — the extensions above add more granular control on top.

If you use Chrome, consider switching to Firefox for better default privacy.

Before Let's Encrypt, getting a browser-trusted SSL certificate meant paying $50–$300/year to a commercial CA (Comodo, DigiCert, GoDaddy), going through manual identity verification, and configuring renewal yourself. Let's Encrypt launched in 2015, left beta in April 2016, and changed all of that: free Domain Validation certificates, automated issuance via the ACME protocol, and 90-day validity with built-in renewal tooling. For small servers and personal sites that had been running plain HTTP, this was the first practical path to HTTPS.

The official Certbot client wasn't yet packaged for Debian Jessie, so I used one of the alternative clients — a simple bash script: https://github.com/Neilpang/acme.sh

With this script you can get everything done in about 5 minutes.

Prerequisites#

• Root access to the server
• Apache running on Debian Jessie
• Domain resolving to the server's public IP
• Port 80 open (used by ACME HTTP-01 challenge to verify domain ownership)

For this guide, assume:

/root/.acme.sh/acme.sh   # where the client scripts live
mysite.com               # the domain you want a certificate for
/mnt/www/mysite.com      # the webroot for your site
/etc/apache2             # Apache installation with config files

Step 1 — Download the client#

Go to (or create) /root/.acme.sh/acme.sh and run:

git clone https://github.com/Neilpang/acme.sh

If you don't have git, download the files manually from the project page and unpack them.

Step 2 — Create a symlink for convenience#

ln -s /root/.acme.sh/ /etc/apache2/letsencrypt

Step 3 — Issue the certificate#

Make sure your site is reachable from the internet, then:

./acme.sh issue /mnt/www/mysite.com/ mysite.com

Or, if you have aliases (e.g. www.mysite.com):

./acme.sh issue /mnt/www/mysite.com/ mysite.com www.mysite.com

acme.sh places a temporary file in the webroot, Let's Encrypt fetches it to verify you control the domain, then issues the certificate. The files are saved to:

/root/.acme.sh/mysite.com/

Step 4 — Configure Apache#

Point Apache to the new certificates in your virtual host config:

SSLCACertificateFile  /etc/apache2/letsencrypt/mysite.com/ca.cer
SSLCertificateFile    /etc/apache2/letsencrypt/mysite.com/mysite.com.cer
SSLCertificateKeyFile /etc/apache2/letsencrypt/mysite.com/mysite.com.key

Then reload Apache:

service apache2 reload

Your site should now be served with a Let's Encrypt certificate.

Step 5 — Auto-renewal#

Certificates are valid for 90 days. To renew automatically, create an executable script, e.g. acme_cron:

#!/bin/sh
/root/.acme.sh/acme.sh/acme.sh cron >> /var/log/le-renew.log
service apache2 reload

Drop it in /etc/cron.daily and you're done.

The process isn't complicated — once set up, renewal is fully automatic.

This setup served well until I moved everything to Docker. The modern approach using Traefik handles Let's Encrypt automatically — no scripts, no cron, no manual config. More on that: Let's Encrypt with Docker and Traefik.

There's a cleaner way: temporary email addresses — ready in seconds, no account needed, gone after a few hours.

Guerrilla Mail#

Guerrilla Mail is the simplest option. Open the site, copy the generated address, use it. Any mail delivered there appears immediately — no refresh needed. The inbox is session-based: close the tab and it's gone.

You can also compose outgoing mail from the temporary address, which is occasionally useful for replying to confirmation emails.

Dropmail#

Dropmail goes further. It's the better choice when you need the address to last or to actually receive something reliably.

What Dropmail offers beyond a basic inbox:

• Forwarding to your real address — emails land in your normal inbox, so you don't need to keep a Dropmail tab open. Cancel forwarding at any time.
• Recovery key — save it and you can return to the same address later, even from a different device or browser session
• Two domain types — permanent domains for longer-lived addresses, rotating domains for short-term use
• Telegram bot — receive emails directly in Telegram without opening a browser
• Android app — manage temporary addresses from your phone

No registration, no premium tier needed for any of the above.

Apple Hide My Email#

If you're on Apple devices with an iCloud+ subscription (included with any paid iCloud storage plan starting at 50 GB), you already have a built-in option: Hide My Email.

It generates a unique, random address that forwards to your real inbox — permanently, until you deactivate it. No separate app, no website to visit. It's integrated directly into iOS, iPadOS, and macOS:

• Safari autofill — when you fill in an email field on a website, Safari offers to generate a hidden address automatically
• Settings → iCloud → Hide My Email — create and manage all your addresses in one place, see which ones are active, deactivate or delete any of them
• Sign in with Apple — when you use "Sign in with Apple" and choose to hide your email, Hide My Email generates the address automatically

The key difference from Guerrilla Mail and Dropmail: these addresses are permanent aliases tied to your Apple ID, not throwaway inboxes. You control them, you can disable them, and mail always arrives in your real inbox. It's the most seamless option if you're already in the Apple ecosystem — no friction, no extra tools.

The catch: it requires a paid iCloud+ plan and only works on Apple devices.

When to use which#

Use Guerrilla Mail when you just need a confirmation link and will close the tab in two minutes.

Use Dropmail when you need the address to survive beyond the browser session, or when you want emails forwarded somewhere you'll actually see them.

Use Apple Hide My Email when you're on iPhone/Mac, have iCloud+, and want zero-friction address generation built into the OS — no separate tools, permanent and manageable aliases.

What the site needed to do#

Insurance brokerage is a regulated industry. A broker's website isn't just a brochure — it needs to communicate regulatory status (KNF licence number, professional liability insurance), distinguish the firm from agents (a broker represents the client, not the insurer), and build enough trust that a potential corporate client picks up the phone.

Alfa Consilium's service portfolio covered a wide range: D&O insurance, cargo and carrier liability (OC spedytora / OC przewoźnika), machinery breakdown, leasing brokerage, factoring, receivables management, and risk management with on-site audits. Each service area needed a clear, standalone description — not a wall of text, but enough substance for a decision-maker to understand scope and contact the team.

Design and implementation#

The site was designed with a clean corporate aesthetic: structured layout, clear service navigation, and contact information accessible from every page. Financial sector clients — logistics companies, manufacturers, fleet operators — expect a professional presentation, not a startup landing page.

Implementation was on WordPress with a custom PHP theme built from scratch — no off-the-shelf theme. The template handled three responsive breakpoints: desktop, tablet, and mobile. Responsive design was still far from standard practice in Poland in 2016; most small corporate sites were still fixed-width.

WordPress was the right choice for the client: the content team could update service descriptions and news without developer involvement, and the admin interface required no training.

What was delivered#

• Full visual design (desktop + tablet + mobile)
• Custom WordPress theme in PHP
• Service pages for all insurance and financial product lines
• Contact section with regulatory information (KNF supervision details, professional liability insurance)
• Responsive layout across all three breakpoints

Screenshot from the live site.

The company continues to operate — the original .pl domain now redirects to alfaconsilium.eu.

In 2015, single-board computers were becoming a practical option for a low-power always-on home server. The Raspberry Pi 2 was the obvious choice, but the Banana Pi offered something the Pi couldn't: a SATA port. For a server that would store media files and run backups, a real hard drive was a non-negotiable advantage over SD card storage.

Hardware#

The Banana Pi is built around the Allwinner A20 SoC — a dual-core ARM Cortex-A7 running at 1 GHz. Key specs that made it the right choice:

• CPU: Allwinner A20, 2× 1 GHz (Cortex-A7)
• RAM: 1 GB DDR3
• Gigabit Ethernet (vs 100 Mbit on the RPi 2)
• SATA port — the deciding factor. A SATA HDD is faster, more reliable, and orders of magnitude larger than any SD card

The setup: Banana Pi in a case, 2.5" SATA drive for storage, a 4 GB USB stick for backups.

What it ran#

Running Bananian — a Banana Pi-specific Debian distribution (note: discontinued in 2016, superseded by Armbian) — the server handled:

• Media server (minidlna — stream music and video to TV over DLNA without booting a full PC)
• SSH (headless remote management from anywhere)
• VPN (OpenVPN — safe use of public Wi-Fi, access to the home network remotely)
• VNC (TightVNC — graphical session when needed, e.g. for jDownloader)
• Web server (LAMP stack — this site ran on it, plus a few personal projects)
• Backups (bash scripts on cron, no extra tooling)
• Downloads (aria2 and curl for command-line; jDownloader in graphical mode when needed)

In practice#

Everything ran fast, reliably, and stable around the clock. The real benefit was power consumption: the Banana Pi draws around 4–8 W under typical load. Spinning up an old Core 2 Duo desktop (65 W TDP, plus the rest of the system) just to listen to music made no sense. An hour on the old machine equalled a full day on the Banana Pi.

Banana Pi in its case with a SATA drive and an old 4 GB USB stick for backups.

Banana Pi from the admin console side.

If you have basic Linux admin skills and want a low-power always-on server, the Debian ecosystem gives you everything you need.

This setup eventually reached its limits. In 2026 I replaced it with a Raspberry Pi 5 with NVMe storage and full Docker containerization. Read about it: Raspberry Pi 5: Migration to NVMe and service containerization.