Finding a local tradesman is hard. Building a high-performance search engine to solve that shouldn't be.

In this article, I’ll show you how I built a Programmatic SEO (pSEO) project for the city of Bremen. The goal: To generate over 100 high-performance landing page templates—covering every district and every trade (locksmiths, plumbers, electricians)—fully automated, blazing fast, and offering real value to the user.

We will dive deep into the tech stack: From data acquisition with Python to content generation using local LLMs (Ollama) and final rendering with Hugo.

🏗️ The Architecture

The problem with classic CMS platforms like WordPress is often performance when dealing with hundreds or thousands of pages. That’s why I chose a Static Site Generator (SSG). The site is "built" once and then served as pure HTML.

The Stack:

• Data Source: CSV (cleaned and enriched)
• Logic & Generator: Python (Pandas)
• Content AI: Ollama (running Llama 3 locally)
• Frontend/Rendering: Hugo (Go-based)
• Hosting: Static (e.g., Hetzner/Netlify/Vercel)

Step 1: The Data Foundation (Python & Pandas)

Everything stands or falls with the data. I started with a raw CSV file (handwerker_bremen.csv) containing columns like name, address, rating, zip_code, etc.

The challenge: Data is often "dirty." Zip codes are missing, special characters are broken, and categories are inconsistent.

import pandas as pd
import numpy as np

# Load data
df = pd.read_csv('handwerker_bremen.csv')

# Mapping for clean district names based on Zip Code
PLZ_TO_DISTRICT = {
    "28195": "Bremen-Mitte",
    "28203": "Steintor / Ostertor",
    # ... further mappings
}

def get_district_name(plz):
    return PLZ_TO_DISTRICT.get(str(plz), f"Bremen (Zip {plz})")

# Clean slugs for URLs (e.g., "Locksmith in Bremen Mitte")
def clean_slug(text):
    text = text.lower()
    replacements = {'ä': 'ae', 'ö': 'oe', 'ü': 'ue', 'ß': 'ss', ' ': '-'}
    for old, new in replacements.items():
        text = text.replace(old, new)
    return text

We then group the data by Category and Zip Code. Each of these groups serves as the basis for one of our 100+ unique templates.Python

grouped = df.groupby(['search_category', 'search_plz'])
print(f"Templates to generate: {len(grouped)}")

Step 2: Content Generation with Local AI (Ollama)

This is where it gets interesting. Instead of generic placeholder text ("Here you find a plumber"), I wanted unique introductions for every single one of the 100+ templates. Since API costs can skyrocket with this many pages, I used Ollama running Llama 3 locally on my machine.

The biggest challenge? Hallucinations and cut-offs.

Ollama tends to stop sentences in the middle if the num_predict (token limit) is too low, or it starts rambling.

Our Solution: Prompt Engineering & Fallback Functions

import requests

def query_ollama(prompt):
    payload = {
        "model": "llama3",
        "prompt": prompt,
        "stream": False,
        "options": {
            "temperature": 0.6, # Less creative, more focused
            "num_predict": 200, # Enough room to finish the sentence
        }
    }
    response = requests.post("http://localhost:11434/api/generate", json=payload)
    return response.json().get('response', '').strip()

# IMPORTANT: Cleanly cut off sentences if the AI stops mid-stream
def clean_incomplete_sentence(text):
    if text.strip().endswith(('.', '!', '?')):
        return text
    
    # Cut everything after the last punctuation mark
    last_punct = max(text.rfind('.'), text.rfind('!'), text.rfind('?'))
    if last_punct != -1:
        return text[:last_punct+1]
    return text

The prompt itself assigns the AI a clear role ("Copywriter") and sets hard constraints ("Max 50-70 words", "No headlines").

Step 3: The Hugo Generator

Python doesn't generate HTML directly; instead, it creates JSON files that serve as "Data Files" in Hugo. This keeps logic and design cleanly separated.

The Python script creates a massive bremen_services.json containing the structure for over 100 templates:JSON

[
  {
    "page_slug": "locksmith-bremen-28195",
    "page_title": "Top Locksmith in Bremen-Mitte (28195)",
    "intro_text_ai": "Door slammed shut? Don't panic...",
    "service_list_json": "[...]" 
  },
  ...
]

In Hugo, we use a specific layout (layouts/services/list.html) that iterates over this JSON file and uses resources.FromString to generate virtual HTML pages from these templates.Go

{{ range $index, $page_data := site.Data.bremen_services }}
    {{ $slug := $page_data.page_slug }}
    {{ $filename := printf "services/%s.html" $slug }}
    
    {{/* HTML Content is assembled here */}}
    {{ $html_content := printf "..." }}
    
    {{ $file := resources.FromString $filename $html_content }}
    {{ $file.Publish }}
{{ end }}

Why so complex? Because Hugo is incredibly fast. We can build these 100+ templates and pages in a matter of seconds.

Step 4: UX & Frontend (The "Airbnb Design")

Data is useless if it's presented poorly. Our goal was trust. No one calls a tradesman from a site that looks like it was built in 1998.

We took inspiration from the Airbnb Card Design:

• Plenty of whitespace
• Subtle shadows (box-shadow) that elevate on hover
• Clear "Call to Action" buttons
• "Social Proof" via highlighted ratings

CSS Snippet for the Cards:

.service-card { 
    background: #fff; 
    border-radius: 12px; 
    border: 1px solid #ebebeb; 
    transition: all 0.3s cubic-bezier(0.2, 0, 0, 1); 
    display: flex; 
    flex-direction: column; 
}

.service-card:hover { 
    transform: translateY(-4px); 
    box-shadow: 0 12px 20px rgba(0, 0, 0, 0.08); 
    border-color: transparent; 
}

.btn-primary {
    background: #FF385C; /* The typical Airbnb Red */
    color: white;
    font-weight: 700;
}

Additionally, we implemented an FAQ Accordion which not only helps users ("How much does this cost?") but also delivers structured data via JSON-LD Schema to Google. This massively increases the chance of getting Rich Snippets in search results.

When Syntax Collides: The printf vs. CSS Battle

One of the most technically demanding aspects of this project wasn't the AI generation or the data scraping—it was a subtle syntax collision between Go templates and CSS that nearly derailed the design implementation.

In Hugo, when we generate pages dynamically using resources.FromString, we build the entire HTML structure as a giant string inside a printf statement. This allows us to inject variables like $title or $district directly into the code. However, printf in Go uses the percentage symbol (%) as a formatting verb (e.g., %s for strings, %d for integers).

Here lies the problem: CSS also relies heavily on the percentage symbol. Whether it's width: 100%, flex-basis: 50%, or keyframe animations, the % is omnipresent in modern web design.

When Hugo's compiler encountered a line like .container { width: 100% } inside our string, it panicked. It tried to interpret the % followed by a closing brace } as a variable placeholder, which doesn't exist. This resulted in cryptic build errors or, even worse, the styles breaking silently because the CSS string was malformed during the render process.

The Solution:

To make this work, we had to implement a strict escaping protocol within our templates. Every single instance of a CSS percentage sign had to be doubled to %.

/* WRONG - Causes Hugo Build Failure */
{{ $html := printf "<style> .box { width: 100%; } </style>" }}

/* RIGHT - Escaped for Go Printf */
{{ $html := printf "<style> .box { width: 100%%; } </style>" }}

This seems like a minor detail, but when you are managing hundreds of lines of inline CSS to ensure critical rendering path performance for over 100 templates, "hunting the percent sign" becomes a major part of the debugging process. It taught us a valuable lesson: when mixing languages (Go and CSS) within a single string context, always be aware of reserved characters.

Conclusion

With just about 200 lines of Python code and a well-structured Hugo architecture, we created a scalable, low-maintenance portal based on over 100 templates. If the data changes (new tradesmen, new prices), we simply run the Python script again, Hugo rebuilds, and the update is live.

Programmatic SEO is powerful—if you prioritize quality over quantity. By using local AI generation via Ollama and a high-quality frontend design, this project stands out distinctly from typical "spam directories."

Tech Stack: Python 3.11, Pandas, Ollama (Llama 3), Hugo Extended, HTML5/CSS3.

This article aims at creating a basic understanding of how we generated a HTML snippet with dynamic content which is embeddable on any external site.
A comparable solution is the Twitter post embedding functionality. In our case the content of the embeddable snippet is a list of job offering entries which contains an application link.

Our situation

We have a plattform written in Python / Django which is responsible for letting the user creating and managing job offers for their company. On our platform are multiple companies who are supposed to manage their offers. There are two specific usecases the snippets are aiming at.

1. Generate a HTML snippet of all jobs on the platform
2. Generate a HTML snippet of all jobs of one specific company on the platform

The idea behind those snippets is that they can be embedded on either public pages which list all job offers or for example on specific sites of a company itself (e.g. their own website). So advertisment and distribution of those offers shall primarily happen via HTML snippet embedding.

The management of all job offers happens via our internal platform. The management process of those offers are merely basic CRUD operations and are self explanatory from a technical standpoint. A job offer contains basic fields like a title, a description, some tags and information about the company which is responsible for the offer.

Our approach

After some research we found out that the common way of doing this is via JavaScript. Basically this is pretty self explanatory if you think about it. The code snipped which takes care of the injection looks like the following:

<div id="unique-jobs-id" class="job-class"></div>
<script async src="https://your-url/jobsapi/v1/widget/" charset="utf-8"></script

This is the part the webmaster of the site who wants to embed the offers has to add to his page. Everything else will be handled by JavaScript.

We have a div which serves as container for the list we want to embed. Also we have script which is called asynchronously (so that loading of the rest of the site is in no case blocked by our script). The script fetches the HTML code which contains a list of all job offers and then injects it into the div by an id query selector.

This image should boil down what happens.

Challenges & Considerations

In theory the sketched approach from above seems pretty straight forward. How ever I wanted to emphasize on some things we discussed internally as well as challenges we faced during implementing the approach from above.

1. HTML/CSS class interference

What I mean by that is that the retrieved HTML code from our server may interfere which HTML or CSS code which is already applied on the parent site. The snippet CSS code is embedded into the parent site. Imagine two elements having the same class (for instance .job-list). The retrieved CSS from our API would therefore also apply CSS styling to the parent page and therefore could break the layout of the parent page. This should be kept in mind and ideally should not be possible.

The two easiest solution for that are probably either prefixing every class with a value or using WebComponents with a Shadow DOM. If you prefix all classes with a unique value there is still a little chance that there might be an interference. That is why we went for an open Shadow DOM solution. More on that down below.

2. The HTML Code needs to be generated serverside and be embeddable

For our solution it is neccessary that we retrieve HTML Code from our server which we just can inject into the target site. With Django this was pretty easy since we just could use server side rendering with a Django partial for that.

It would also be possible for instance to return JSON data and generate the needed HTML code with JavaSript on the client side. How ever that felt more tedious for us to do so. So we decided to just append the retrieved HTML code with JavaScript. Also it is important that we add as little JavaScript as neccessary to ensure the parent site performance feels well.

Implementation

On our Django server we have two endpoints:

urlpatterns = [    
path("widget/<uuid>/", job_widget, name="jobs_api.widget"),   
path("jobs/<uuid>/", joblist, name="jobs_api.joblist"),
]

The uuid part is added for multitenancy support. So in case we want to support two different versions of the JavaScript part or just provide a subset of job offers.
The widget endpoint is responsible for delivering the JavaScript part (in our case the JavaScript code for the WebComponent). It looks like the following:

def job_widget(request, tenant_uuid):    
   
	link = f"{request.scheme}://{request.get_host()}{reverse('jobs_api.joblist', args=[tenant_uuid])}"    
	return render(request, "jobs_api/job-widget.js", {"link": link, "tenant_uuid": tenant_uuid}, content_type="application/javascript")

As you can see we are sever side rendering the job-widget.js part instead of just providing it statically. This is for once because of the tenant_uuid for multi tenant support as well as that we are injecting the generated link from above into the script. We do that so that we do not have to hardcode the URL where the JavaScript part fetches the jobs from into the file itself. In case you have a testing or staging system delivery is much easier.

Furthermore we have the endpoint which returns the JobList as HTML. This ofcourse heavily depends on what you want to return. To keep it simple and understandable we stripped some parts of our code here. The example should still be fully comprehensible.

def joblist(request, tenant_uuid):

    jobs = []
    filtered_for_company_id = request.GET.get("c")

    jobs = Job.objects.filter(tenant__uuid=tenant_uuid)

    if filtered_for_company_id:
        company = get_object_or_404(Company, id=filtered_for_company_id)
        jobs = jobs.filter(published_by__company=company)

    jobs = jobs.order_by("-published_on")
    return render(
        request,
        "jobs_api/joblist-snippet.html",
        {"joblist": jobs},
        content_type="text/html",
    )

As you can see we basically return a HTML filled with the job offers. As addition we also check for an URL parameter called c to filter job offers of a specific company. This how ever is really additional and not neccessary.

The rendered HTML file is a simple Django partial with a foreach loop. To keep this article short and informative I will not go in detail about this.

The WebComponent

I also do not want to discuss WebComponents in general. As mentioned before the main benefit for us is the encapsulation from the environment where we want to add our snippet to ensure minimal interference from the parent site. If you want to read about it a good starting point is here.

Lets take a look at the JavaScript part which fetches and embeds the HTML part from above into our component.

const url = "{{link}}"; //Injected from Django
const template = document.createElement('template');
class JobSnippet extends HTMLElement {
    constructor() {
        super();
 
        const shadowRoot = this.attachShadow({mode: 'open'});
        shadowRoot.appendChild(template.content.cloneNode(true));
    }

    connectedCallback() {
        let shadowHost = this.shadowRoot;
        const btns = shadowHost.querySelectorAll('.jobs-show-job-details');

        btns.forEach(element => element.addEventListener('click', function (event) {

            // You can add custom JavaScript functionalities to your WebComponent
            let targetElement = event.target;
			console.log(targetElement);            

        }));
        console.log(`Jobsnippet: JobSnippet added to page`);
    };
    
};

window.customElements.define('job-snippet', JobSnippet);

try {
    const jobDiv = document.getElementById('jobs-{{tenant_uuid}}');
    
    fetch(url)
        .then((response) => {

            if(response.status == 200) {
                response.text().then((html) => {
                    template.innerHTML = html;
                    const jobSnippet = new JobSnippet();
                    jobDiv.appendChild(jobSnippet);
                });
            }
            else{
                console.error('Could not embed snippet')
                response.text().then((error) => console.error('Jobsnippet: ' + error));
            }
        });
    } catch (error) {
        console.error(error);
} 

As you can see a lot of stuff is happening here. Lets start at the very bottom of the script:

try {
const jobDiv = document.getElementById('jobs-{{tenant_uuid}}');

fetch(url)
    .then((response) => {

        if(response.status == 200) {
            response.text().then((html) => {
                template.innerHTML = html;
                const jobSnippet = new JobSnippet();
                jobDiv.appendChild(jobSnippet);
            });
        }
        else{
            console.error('Could not embed snippet')
            response.text().then((error) => console.error('Jobsnippet: ' + error));
        }
    });
} catch (error) {
    console.error(error);
}

This part is responsible for fetching the HTML code we prepared on our server before. We injected the url we need into our script by Django. Now we simply call that URL to retrieve the HTML code. If the call is successful with a 200 we take the response and set the innerHTML of our template element, create the JobSnippet and append it to the div we inserted together with our script. Otherwise we will log the error.

The template element is basically the first thing which is created by our script and serves as a container for our WebComponent. It is special and important for WebComponents. You can read more about it here.

Lets take a look:

const template = document.createElement('template');
class JobSnippet extends HTMLElement {
    constructor() {
        super();
 
        const shadowRoot = this.attachShadow({mode: 'open'});
        shadowRoot.appendChild(template.content.cloneNode(true));
    }

    connectedCallback() {
        let shadowHost = this.shadowRoot;
        const btns = shadowHost.querySelectorAll('.jobs-show-job-details');

        btns.forEach(element => element.addEventListener('click', function (event) {

            // You can add custom JavaScript to your WebComponent
            let targetElement = event.target;
			console.log(targetElement);            

        }));
        console.log("Jobsnippet: JobSnippet added to page");
    };
    
};

As you can see we create a class names JobSnippet which extends HTMLElement. This is responsible for creating a WebComponent. It is called a custom element. Inside the constructor of this element is important that the super() always needs to get called first.

In the following we declare our Shadow DOM for our custom element:

const shadowRoot = this.attachShadow({mode: 'open'});

This line creates s shadow DOM for us with the open mode. Open means that our custom element is still reachable from outside of the element via JavaScript. This can be useful for instance if the person who embeds the snippet needs to apply JavaScript to our custom component. You could also set the mode to closed. In that case the shadow root is not accessible via JavaScript from the outside.

shadowRoot.appendChild(template.content.cloneNode(true));

This adds our retrieved HTML content into our shadow root. Inside the the connectedCallback() function you can add all the functionalities you need to your component. This function gets called after the component has been attached to your page. In our demonstration case we add an onclick functionality to all buttons with a certain class.

The last important part for our custom element is this line:

window.customElements.define('job-snippet', JobSnippet);

This is neccessary to register our custom element and to complete the creation of our custom component.

Conclusion

To summarize things I can say that using a WebComponent for our task felt like the right decision. If you have never worked with WebComponents before the JavaScript setup of it might be a bit confusing but afterwards you will get an understanding pretty quickly. It is really helpful that you can control with the component mode (open or closed) whether the component is accessible from outside via JavaScript or not. The encapsulation feels very useful for purposes like snippet embedding.

What I think is also still worth mentioning that independent of the component mode the parent site is still able to override the styling ob the custom element with a special selector. Basically you can use the pseudo element ::part for accessing the stylings of the shadow DOM. You can read more about it here.
Accessing the styling from the parent site can look like the following:

snippet::part(job-entry-wrapper) {
		color: blue;	
}

This would change the color of the part job-entry-wrapper inside the component job-snippet to blue. It is important to define those parts in your WebComponents HTML:

<div class="jobs-job-conent" part="job-entry-wrapper">

Overall we are pretty happy how things worked out. There were no major confusions or hickups. The implementation worked well and after digging a bit into the WebComponent part I'd would probably do it the same way in the future. Creating the HTML code server side seemed also like the right decision since we could easily integrate it into our custom element.

In this article I want to explain how we created a room booking kiosk solution for one of our customers. I also want to give insights about challenges we encountered as well as talk about things we learned during this project. This will also summarize our thought process and how we finally came up with our technology decision for this project.

Our situation

Our customer has a facility with a variety of different rooms staff members can book via a system which was developed by us in the past. I would describe this system as basic room booking system. The user can open a mobile or a web app and select a timeslot as well as a desired room and then perform a booking. If the room is not occupied at the given slot the booking will be added to the system and be visible to all other users.

The client came up with the idea to equip each bookable room with a simple tablet device which should serve some basic information and also allow the user do perform some basic booking related actions. The tablet is supposed to be installed at a wall inside of the room. The primary purpose of these tablets were the following:

1. Show whether the room is currently occupied
2. If the room is empty allow adhoc bookings for 15/30 minutes
3. Allow to directly stop the current booking of this room
4. Extend the current booking for 15/30 minutes
5. Show basic booking information like until when the room is booked or how long the room is not occupied as well as show a small timetable of todays bookings
6. Set a background image for each tablet and it's room

All of the requirements basically serve the purpose to give the user who booked (or want to book) a room more flexibility and ease the related process. In case he recognizes that the meeting duration is far shorter or longer as expected he can easily stop or extend the current meeting. The user can also quickly and spontaneously book a room by just going into an empty room and press a button on the tablet.

Since the customer had a supply of Amazons Fire Tablets 7 left over the requirment was that the solution should run on these devices.

The requirements for the application itself were paired with some technical constraints the solution had to deliver:

1. The tablet must not dim and the screen must not lock
2. The app must not be closeable and be at the front at all time
3. The app should be easily startable via the home screen of the tablet
4. The app must be fullscreen

Initial outlaying of a possible solution and technology selection

Given the requirements mentioned above we were discussing different approaches on how to implement a solution. Quickly we found out that we need more information about the Fire Tablet 7 to be able to properly choose a technology to tackle the requirements. It was obvious that it was important that our solution had to be able to run in a kiosk mode. The focus had to be on the solution at all times and the user must not be able to close or hide it. We also were not exaclty sure what Android was running on the device and how heavily it got modified by Amazon and what exactly would be the implications of that modifications.

Some questions which came in our mind at that point primarly regarding the technical constraints were:

1. How can we achieve the kiosk mode? Is that something we need to enforce through Android permissions? Can we run a web app in kiosk mode?
2. Is the kiosk mode automatically solving the challenge that the device is not allowed to dim?
3. How can we provide a good update and setup process for the app and tablets?
4. Is this in general rather a web or mobile app case?

After digging a little bit into the tablet we found out that the Fire Tablet 7 had indeed a build in kiosk mode which allows you to pin an app to the foreground. It then is only able to be hidden by performing a certain tap combination as well as entering a pin code. That was really good for us.

Unfortunatly the dimming was not direclty related to the kiosk mode. For instance when pinning a certain app the tablet screen fades black after a certain amount of time (which you can set in the settings max. 30 minutes). Completly disabling dimming is not supported by the Fire Tablet 7.

Regarding the Android version it was indeed heavily modified and the only official way to get apps onto the device was via the Amazon App Store. How ever we found out that it was possible to simply install third party APKs on the device like for instance Chrome or even Google Play. That was a bit sobering because we wanted to avoid getting our potential app into the official Amazon store. That was basically because getting your app in such a store usually takes time and effort. Also depending on the store you are confronted with different bureaucracy obstacles. We still could deploy our app manually in that case but deploying a new version would be quite exhausting and time consuming.

At this point we were still slightly favoring the development of a mobile app due to the following reasons:

• Full control of the device for future requirements
• No hassle with the screen dimming
• Native feeling of the app

But we still had some concerns:

• How can we handle the update process? Does the client have to install the app from the Amazon App Store on each device? Is the update process automated?
• What about app review queues in the Amazon App Store do they take long? What other requirements do we need to fulfill to get our app in there?
• For our team creating a mobile app usually takes more time and effort than creating a web app. Would the extra effort pay off?

Especially the update process of the apps seemed like a big disadvantage for the development of a mobile app (regardless of using the app store or deploying manually). In case there is a bug or we quickly need to change something on the client side we would firstly be confronted with the Amazon App Store review queue and afterwards the client would have to go to each tablet seperately and update the app as soon as the update is available (at least in the worst case). Also we could not rely on something like fastlane to automate the deployment into the store since the Amazon App Store is not supported.

This led us to further research on how to solve this challenge by doing a web app. If we would do a web app we still had two issues to tackle though. Firstly how can we make sure that our web app is running in the kiosk mode of the Fire Tablet 7? Secondly how can we prevent the device from screen dimming without Android permissions?

Regarding the first point we chose a simple approach namely building a progressive web app (PWA). We could easily install the PWA by visiting the website and install it to the home screen. From there we hoped to simply use the build in kiosk mode with the PWA. This would ease the installation and update process enormously. It would not feel as native as a self written Android app but we could make it feel snappy with some extra work. The solution to go for a PWA later on turned out to be not well thought out and would cause some trouble.

For the second challenge we found out that it is possible to prevent the screen from dimming for web apps by an API. Some browser support something called a Screen Wake Lock API. We quickly created a proof of concept (PoC) and could validate that the API works under Chrome. A plain implementation is pretty straight forward:

// Create a reference for the Wake Lock.
let wakeLock = null;

// create an async function to request a wake lock
try {
  wakeLock = await navigator.wakeLock.request('screen');
  statusElem.textContent = 'Wake Lock is active!';
} catch (err) {
  // The Wake Lock request has failed - usually system related, such as battery.
  statusElem.textContent = `${err.name}, ${err.message}`;
}

Taken from the Mozilla developer site

At this point we only had to make sure that Chrome was running on the tablet instead of Amazons default browser Silk. Since we were able to install APKs on the tablet that was quite easy. I also can recommened this site which shows what web apps are currently capable of in what browser.

We were pretty sure that a PWA pinned to the app home screen would be most beneficial for us. We would have a deployment process which was not too effort consuming. Also we could benefit from our web app development expertise and create the app a little faster. The screen dimming would also be no problem due to the Wake Lock API. The benefits of an Android app seemed very minor at this point. Since it is a PWA we would also have no URL bar inside the browser and the app would be fullscreen. So we decided to go for a web app in form of a PWA.

The next question we had to answer was what frontend technology we would use. Our backend is mainly written in Python and Django. So we were playing around with the thought to embed the solution directly in our project and use server side rendering (SSR). How ever we felt like having an official API for this case could be useful and more flexible in the future. Furthermore using a frontend framework would ease the development and result in well a structured solution. I know that there are ways of integrating frameworks like Vue and Angular with Django but the integratrion effort did not seem to match the benefit.

Since we used Vue in the past and felt like we should decouple these systems and have an API we went for a single page application (SPA) with Vue3. In my opinion you could have also gone with plain HTML & Javascript or any other frontend framework at this point. It is rather a matter of taste.

The development

I do not want to get in too much detail regarding the development process itself since it was pretty unspectacular. We were quickly setting up a Vue3 project and started programming. We prefered the composition API over the options API since we felt more comfortable with it. As state handling solution we chose Pinia. As build tool we chose Vite instead of traditional Vue CLI. Both Pinia and Vite felt really good and I can just recommened them both.

Regarding the Wake Lock integration to prevent screen dimming we chose a dependency which would ease the integration and use a little bit. This worked also really well.

What was not as easy as we hoped was the creation of the PWA itself. We found out that Vite's plugin system supports PWA. You can find it here. The setup was good but I felt like the documentation was at some points a little bit unspecific. We managed to set everything up as said in the documentation how ever the required service worker did not register successfully. If you are experienced with PWAs this would be probably a no brainer for you but our issue was that we did not know that it is not enough to simply generate a service worker but we also had to implement a callback like the following in our app to register it and make it working:

registerSW({
  onOfflineReady() {},
})

We did not need this functionality so we thought we could spare it. But without it Chrome would not see our app as PWA.

After we got this issue figured out we could finish the development. I have to add at this point that I feel like PWA development is not that much refined. We were struggling with spamming hard reloads, installing and uninstalling the PWA as well as server restards to always have the latest changes we made inside our app. This might be an issue with our development setup but I thought it is worth mentioning here in case anyone else runs into trouble with this. When developing a PWA make sure you are testing the right version of your app and not some old cached version from the browser.

Testing and encountering a major issue in our plan

During development we tested mainly on our computers with the aspect ratio and dimensions of the Fire Tablet 7. We also had a staging with we could navigate to from the Chrome browser of the tablet. Since the PWA functionality was the last thing we implemented we simply opened the site and tested the app beforehand via the browser of the tablet.

This was a major issue during our development process. After finishing the PWA functionality and testing everything locally we wanted to test the PWA things on the tablet itself. Unfortunatly we found out quickly that the Fire Tablet 7 does not support PWAs. That was major issue for us since it was a requirment to pin the solution to the home screen as well as run the solution in fullscreen. We had not especially tested the PWA functionality on the device since we thought that it is surely supported. That was a major misassumption and since development was nearly completly finished and we had not much time left until a prototyping phase should start we felt like we might be ahead of some extra crunch.

We tried to set the browser to fullscreen mode and put a bookmark to the site on to the home screen of the tablet. But the Fire Tablet 7 neither supports one of it. Our first guess was that we had to create an Android app and embed a webview to our site to it. But that felt so wrong at this point because we consciously decided against creating an app. That would have mean we would get the worst of both worlds. So we kept researching if there is not a more charming solution.

Bubblewrap - our rescue

After some time we stumbled over something interesting called Bubblewrap. The description from the GitHub repository is quite accurate so I will just put it here:

Bubblewrap is a set of tools and libraries designed to help developers to create, build and update projects for Android Applications that launch Progressive Web App (PWA) using Trusted Web Activity (TWA).

That was so fitting to our current situation since we had a working PWA but it was simply not supported by the Fire Tablet 7. We were a little bit hesitant at first because from experience those solutions tend to break some functioanlity or cause some other issues.

A TWA is described as the following:

Trusted Web Activity is a new way to open your web-app content such as your Progressive Web App (PWA) from your Android app using a protocol based on Custom Tabs.

Note: Trusted Web Activity is available in Chrome on Android, version 72 and above.

Our biggest concern at this point was whether the Wake Lock would still be working. We were especially skeptical since the Fire Tablet 7 default browser was Silk. Also PWAs were not supported. If we would use a TWA it would internally probably use Silk to launch it which would mean that the Wake Lock API probably is not supported. How ever as described in the documentation the following behavior is used by a TWA (keep in mind that we had installed the newest Chrome version manually on the tablet).

A Trusted Web Activity will try to adhere to the user's default choice of browser. If the user's default browser supports Trusted Web Activities, it will be launched. Failing that, if any installed browser supports Trusted Web Activities, it will be chosen. Finally, the default behavior is to fall back to a Custom Tabs mode.

We set up Bubblewrap like explained in the setup guide (which was surprisingly easy) and started the process with the following command:

bubblewrap init --manifest=https://my-twa.com/manifest.json

That obviously enforces that you have a version of your website live and running so that Bubblewrap can access your PWA manifest. I'm not sure if Bubblewrap also supports local PWA manifests. We had to fill in some information during the process and everything worked on the first try. After that we simply ran:

bubblewrap build

Et voilà the product was indeed a functional APK file which we could simply install on the Fire Tablet 7. Everything was working like in the PWA. Even the use of the Wake Lock API (probably because the TWA was launched in Chrome and not in Silk). We were really a bit surprised at this point because it did not take more than half a hour to convert our PWA to an APK.  One thing which might be a bit tricky and you should definetly watch out for is the digital asset link between your app and your website. If not set up correctly your app will display a costum browser UI at the top.

Afterwards we simply deployed the APK to the tablet and could easily run updates to our site which were visible after a reload of the TWA. No need of deploying a new APK was neccessary.

Learnings & Conclusion

Finally I quickly want to discuss the takeaways for us of this story.

1. Perform full early tests of your possible technology choice on your target device

Our biggest mistake obviously was that we assumed that a PWA was definetly running on the Fire Tablet 7. If we would have tested that within the PoC our development process might have changed. To make early unverfified assumptions on a unfamiliar system is not good - be sure to verify it.

2. Vue3, Vite & Pinia were a good choice

The technology choice itself felt really good for our use case. We had a small encapsulated and expandable system created with an up to date technology. I definetly can recommend this technology choice for a project at this scale.

3. Amazons Fire Tablets are very limited

This one probably speaks for itself, right? It is not possible to disable screen dimming. By default you only have access to the Amazon App Store. The systems base browser is Silk which is quite unknown and might behave different compared to state of the art browsers. No PWAs or website bookmarking on the home screen is supported.

It is also worth mentioning that after some research it seems like these are not only limitations for the Fire Tablet 7 but also apply to more current versions of the Fire Tablet series. Be sure to double check!

4. Bubblewrap and TWAs seem really good

For our use case and situation we owe the people at the Google Chrome Labs a thank you. The technology worked really well. Of course I can not speak for more complex projects but for our usecase this was really good. The setup and the CLI were charming. We will defenitly keep an eye on it and evaluate more usecases.

5. PWA development felt a little bit clonky

I think this is heavily opinion intensive but the development of the PWA itself did not feel so convincing. This may correlate with a little bit of inexperience in that field but creating the manifest and registering the service workers felt very error prone. If you managed to set up everything correctly the debugging and working with the PWA can also be quite frustrating. It results in some work to reload everything properly after some changes, uninstall and reinstall the app. I think this is also quite error prone. How ever this might be related me not having that much experience in developing PWAs.

In the end we were quite happy with the way how things worked out. I think in the end we would have achieved the same result directly developing an app. How ever the installation and update process would be costly for the client. If you have access to the PlayStore or Apple Appstore I think things could be a bit easier. Learnings were big in this one for us and we were really pleased to see how well the deployment through the TWA finally went.

In this tutorial I want to briefly discuss how to host a static website with Caddy2 and Docker. This means you will have a static website running with HTTPS available at your domain.

Prerequisites:

1. A static website project. This can be a single HTML file for instance.
2. Access to a server where Docker & docker-compose is available
3. A domain you own

What is Caddy?

Caddy is an open source webserver with build in automatic HTTPS. That means you do no need to take care about ensuring that your SSL certificates are valid and most importantly stay valid. In this tutorial Caddy will serve our static HTML project to the viewer (note that Caddy is much more capable of though). You could alternatively also use something like NGINX for example. How ever in that case you would have to take care about your certificates.

Setup

In this tutorial we will use docker-compose to run Caddy. If you plan to proxy multiple services through Caddy you can later on chain them together in that file. There are plenty of other ways to get Caddy going easily like running it manually by downloading or cloning the Git repository or use simple single docker container without docker compose.

Lets get started with setting up Caddy.

1. Create a docker-compose.yml.

The file should have to following content:

version: '3'
services:
  caddy:
    image: caddy:2.1.1-alpine
    ports:
      - 80:80
      - 443:443
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ./personal-site/personal-site:/usr/share/caddy
      - caddy_data:/data
volumes:
  caddy_data:
  # caddy SSL volume      

The file is pretty straight forward I think except maybe for the volumes part. The first line ./Caddyfile:/etc/caddy/Caddyfile mounts our Caddyfile into the container. The Caddyfile is somewhat the configuration file our Caddy server needs. In this file we will later on configure which domain Caddy will use for our server.

The second line ./personal-site:/usr/share/caddy mounts our static website folder into the Caddy share folder. This folder will be later on shared through our server.

In this example we assume that our Caddyfile as well as our personal-site static folder are in the same directory as our docker-compose.yml.

The third line caddy_data:/data is required for our SSL volume.

2. Create a Caddyfile at the specified location of your docker-compose.yml

Fill the Caddyfile with the following:

yousubdomain.domain.domainsuffix {
  root * /usr/share/caddy
  file_server
}

You are telling caddy to serve the folder under /usr/share/caddy. In our docker-compose.yml we specified our static site project folder for this. Make sure you set up a record in your domain management system.

When starting our Caddy server it will be available on port 80 and serve the static site with its assets located in the given folder.

Start the service

With sudo docker-compose up -d you can then start your Caddy server. Remove the -d if you want to see logs and get rid of the detached mode. Caddys first setup might take some time since it will take care of the neccessary certificates.

You can now navigate to your domain with HTTPS as protocol and should see your static site.