DEV Community: minnogit

Updating an Android app without the Play Store: a manifest, an APK and a read-only share

minnogit — Fri, 30 Oct 2026 15:00:57 +0000

We hand out Android tablets to people who use our app in the field. Most of the devices are ours, nobody signs in with a personal Google account, and we do not want the app in a public store. Still, when a release is mandatory, every tablet has to pick it up, and whoever publishes the release should not need a developer's laptop and an adb cable.

This article describes how we update the app without a marketplace: a small JSON manifest, a single APK, two authenticated endpoints on the backend, and a publishing path built on a read-only NFS share and a WebDAV folder. I keep the hostnames and paths generic on purpose.

Why the app is not in a store

The app is built for police forces. It is part of a service we provide to them under contract, and it works together with our backend. A listing in a public store would put the APK within reach of anyone, and anyone who holds a copy can decompile it.

Keeping the file out of a public listing does not make reverse engineering impossible. It narrows who can get the file in the first place. The real boundary stays on the backend, where every call is authenticated and scoped to a tenant.

Some customers also want to use tablets they already own, which we do not manage. That rules out the approach of enrolling devices in a management system of our own, so we deliver the update ourselves.

What I wanted from the design

The fleet is small and known. Updates can be mandatory. The tablets already log in to our backend and carry a JWT, so the backend is the one place every device is willing to talk to. Adding a public static web server just for APKs would mean a second thing to secure, so I decided against it and let the backend serve the files.

I also wanted the publishing side to be boring. One person uploads two files and the tablets do the rest.

Two files, one version at a time

The share contains exactly two files: a manifest and the APK. There is no version history and no per-device targeting.

{
  "version": "1.4.2",
  "force": true,
  "note": "Mandatory update with fixes for the inspection form.",
  "size": 48213377,
  "sha256": "9f2c...e41a"
}

The manifest has no URL field. An earlier idea was to put the download URL in the manifest, so the APK could carry its version in the file name. I dropped it. With a fixed file name, the manifest cannot point the app anywhere: the app downloads from the backend it is logged in to, and the file is always the same one. Having one fixed name was also easier to explain to the person who publishes.

size and sha256 describe the APK. The app uses them to check that the download is complete before it tries to install anything.

What happens on the tablet

After login the app calls GET /api/app-version and compares the version in the manifest with the one it is running. If the manifest is newer and force is true, the app blocks the normal screens until the update is installed. If force is false, it offers the update and lets the user postpone.

The download is GET /api/app-apk, with the same bearer token as every other call. The response carries Content-Length, which is what lets the app draw a real progress bar with percentage and megabytes. When the file is complete, the app compares size and sha256 with the manifest and hands the APK to the Android package installer.

Android puts two conditions on this. The first is that the app needs the "install unknown apps" permission, which since Android 8 is granted per app, so someone has to allow it once on each tablet. The second is that an update must be signed with the same key as the installed version and must have a higher versionCode.

The signature check is the real safety net. Whoever can write to the share cannot make a tablet install an APK signed with a different key. They could still make every tablet download a file, so the write credential deserves care, and the signing key stays off the server entirely.

The two endpoints

Both endpoints sit behind the same middleware as the rest of the API: JWT validation and the tenant header. Both read from a directory given by one environment variable, APP_RELEASES_PATH, so no path is hard-coded.

/api/app-version returns the manifest as it is, or a 404 if the file is missing. /api/app-apk streams the APK with Content-Type: application/vnd.android.package-archive, Content-Length and a Content-Disposition header, or a 404.

Where the files live

The backend runs in a container on one machine, while the people who publish upload to another. I wanted a path between the two that the backend can only read.

On the file server, the directory is exported over NFSv4, read-only, to the private network of the application nodes. It is a dedicated export. The account that can write through WebDAV only ever reaches this directory and nothing else on the server.

# /etc/exports on the file server
/export/releases   10.0.0.0/16(ro,sync,no_subtree_check)

On the backend node the export is mounted read-only, and the container gets the same directory as a read-only bind mount at the same path:

# /etc/fstab on the backend node
fileserver:/releases  /mnt/releases  nfs4  _netdev,auto,nofail,noatime,ro,tcp  0 0

# docker-compose.yml
volumes:
  - "${APP_RELEASES_PATH:-/mnt/releases}:${APP_RELEASES_PATH:-/mnt/releases}:ro"

The default value after :- makes the compose file start even when the variable has not been set yet. If the mount is missing, the directory on the host is empty and the endpoints answer with an error. I accepted that: the container still starts and the failure is visible.

The directory is owned by the web server user, with mode 0755 for the folder and 0644 for the files. The backend reads them as "other", so there is no need to line up user ids across machines.

Publishing with WebDAV

The WebDAV folder is served by the Apache that already runs on the file server, with mod_dav and a dedicated account.

Alias /releases /srv/releases
<Directory /srv/releases>
    Dav On
    Options -Indexes
    AuthType Basic
    AuthName "Releases"
    AuthUserFile /etc/apache2/htpasswd_releases
    <RequireAll>
        Require method GET HEAD OPTIONS PUT MOVE DELETE PROPFIND
        Require user publisher
    </RequireAll>
</Directory>

Two details are worth explaining. Require method sits inside a RequireAll because several Require lines at the same level are combined with OR, so a bare method restriction next to Require user would let any authenticated user use any method. And the folder is never listed publicly: there is no directory index, and every request needs credentials.

A plain PUT is not atomic, and an APK is tens of megabytes. The backend can start reading a file that is still being written. So each file is uploaded under a temporary name and then renamed with MOVE, which is a rename on the same filesystem. The order matters too. The APK goes first and the manifest last, because the manifest is what the tablets read to find out that a new version exists.

BASE=https://files.example.com/releases

curl --netrc-file ~/.netrc -T app.apk "$BASE/app.apk.tmp"
curl --netrc-file ~/.netrc -X MOVE "$BASE/app.apk.tmp" \
     -H "Destination: $BASE/app.apk" -H "Overwrite: T"

curl --netrc-file ~/.netrc -T version.json "$BASE/version.json.tmp"
curl --netrc-file ~/.netrc -X MOVE "$BASE/version.json.tmp" \
     -H "Destination: $BASE/version.json" -H "Overwrite: T"

In my tests the PUT answered 201, the MOVE answered 201 for a new file and 204 when it overwrote one, and a wrong password gave 401. The credentials live in a .netrc file with mode 600, so the password never appears on the command line or in the shell history.

I wrapped the four commands in a small script for Linux and one for Windows. It checks every status code, deletes the .tmp file if a step fails, and at the end downloads both files again to compare their sha256 with the local ones.

Two limits I know about

Between the MOVE of the APK and the MOVE of the manifest there are a few seconds in which the new APK sits next to the old manifest. A tablet that starts a download in that window sees a sha256 that does not match and discards the file. It tries again at the next check, which is acceptable for a fleet that checks at every login.

The other limit is that a release cannot be rolled back on devices that have already installed it, because Android refuses to install an APK with a lower versionCode. The share keeps a single version, so a bad release is fixed by publishing a new build with a higher version, and the previous APK has to be kept by whoever builds it.

There is also no staged rollout. Every tablet that checks after the manifest is replaced gets the new version, and for this fleet I prefer that to the extra machinery.

Terminator layouts from the command line: from two to five terminals

minnogit — Thu, 29 Oct 2026 14:12:00 +0000

One of the first things I do every morning at work is open a few terminals. I use Terminator, a terminal emulator for Linux that splits one window into several terminals. A saved arrangement of splits is called a layout, and Terminator can open a layout directly at startup.

The first time, I built my layout from the preferences window. It works, but the generated configuration is full of fields you don't need (uuid, size, position, last_active_term). Writing layouts by hand turned out to be shorter and easier to change, and everything can be done from the terminal. Here are the layouts I tested with Terminator 2.1.6, from two to five terminals.

How a layout works

A layout is a tree:

a Window at the root;
splits inside it: HPaned puts two children side by side, VPaned stacks them one above the other;
Terminal as the leaves.

Each element has a name (any name you like, as long as it is unique within the layout), a type and a parent. The two children of a split also have an order: 0 is the left or top one, 1 the right or bottom one. Without other options each split is 50/50, and ratio changes it.

Layouts live in ~/.config/terminator/config, under the [layouts] section. If you have never changed Terminator's preferences, the file doesn't exist yet:

sudo apt install terminator
mkdir -p ~/.config/terminator
nano ~/.config/terminator/config

The layouts below go under [layouts]. If the file already exists, add them to that section instead of creating a second one.

Two terminals side by side

+--------+------------------+
|        |                  |
|  left  |      right       |
|        |                  |
+--------+------------------+

[layouts]
  [[two]]
    [[[window]]]
      type = Window
      parent = ""
    [[[split]]]
      type = HPaned
      parent = window
      ratio = 0.3
    [[[left]]]
      type = Terminal
      parent = split
      order = 0
    [[[right]]]
      type = Terminal
      parent = split
      order = 1

With ratio = 0.3 the left terminal takes 30% of the width. Remove the line for two equal halves.

Two columns, the first split in two

+-------------+-------------+
|  top left   |             |
+-------------+    right    |
| bottom left |             |
+-------------+-------------+

  [[three]]
    [[[window]]]
      type = Window
      parent = ""
    [[[columns]]]
      type = HPaned
      parent = window
    [[[left_split]]]
      type = VPaned
      parent = columns
      order = 0
    [[[top_left]]]
      type = Terminal
      parent = left_split
      order = 0
    [[[bottom_left]]]
      type = Terminal
      parent = left_split
      order = 1
    [[[right]]]
      type = Terminal
      parent = columns
      order = 1

The first child of columns is not a terminal but another split, and that is all it takes to nest them.

A grid of four

+-------------+-------------+
|             |             |
+-------------+-------------+
|             |             |
+-------------+-------------+

  [[grid]]
    [[[window]]]
      type = Window
      parent = ""
      maximised = True
    [[[columns]]]
      type = HPaned
      parent = window
    [[[left]]]
      type = VPaned
      parent = columns
      order = 0
    [[[right]]]
      type = VPaned
      parent = columns
      order = 1
    [[[t1]]]
      type = Terminal
      parent = left
      order = 0
    [[[t2]]]
      type = Terminal
      parent = left
      order = 1
    [[[t3]]]
      type = Terminal
      parent = right
      order = 0
    [[[t4]]]
      type = Terminal
      parent = right
      order = 1

This is the layout I open every morning. maximised = True makes the window fill the screen.

A spiral of five

This one follows a geometric rule: split the screen in two side by side, then split the second half again, alternating the direction each time.

+-----------+-----------------+
|           |        2        |
|           +--------+--------+
|     1     |        |   4    |
|           |   3    +--------+
|           |        |   5    |
+-----------+--------+--------+

The terminals get smaller at each step, so the font gets smaller with them. The font belongs to a profile, and each terminal can use a different one. Profiles go under [profiles]:

[profiles]
  [[large]]
    font = Monospace 12
    use_system_font = False
  [[medium]]
    font = Monospace 10
    use_system_font = False
  [[small]]
    font = Monospace 8
    use_system_font = False

  [[spiral]]
    [[[window]]]
      type = Window
      parent = ""
    [[[s1]]]
      type = HPaned
      parent = window
    [[[t1]]]
      type = Terminal
      parent = s1
      order = 0
      profile = large
    [[[s2]]]
      type = VPaned
      parent = s1
      order = 1
    [[[t2]]]
      type = Terminal
      parent = s2
      order = 0
      profile = medium
    [[[s3]]]
      type = HPaned
      parent = s2
      order = 1
    [[[t3]]]
      type = Terminal
      parent = s3
      order = 0
      profile = medium
    [[[s4]]]
      type = VPaned
      parent = s3
      order = 1
    [[[t4]]]
      type = Terminal
      parent = s4
      order = 0
      profile = small
    [[[t5]]]
      type = Terminal
      parent = s4
      order = 1
      profile = small

Each split is the second child (order = 1) of the previous one, and the type alternates between HPaned and VPaned. The first terminal, the largest, uses large, the next two medium and the last two small.

Fonts and colors per terminal

A profile can also change the font family and the colors, so the two smallest terminals can look different from the others. For them I use Terminus, a monospace font designed to stay sharp at small sizes, and a dark green background:

sudo apt install fonts-terminus
fc-list : family | grep -i terminus

On Debian the package installs the TTF version, and the family name is Terminus (TTF). With just Terminus, Terminator doesn't find the font and falls back to another one with badly spaced letters, so check the exact name with fc-list. The small profile becomes:

  [[small]]
    font = Terminus (TTF) 9
    use_system_font = False
    background_color = "#0f2a1d"
    foreground_color = "#9fe8b0"

A different background helps to recognize a terminal at a glance, for example the ones following logs. foreground_color only changes plain text: the colors of the prompt (user in green, path in blue) come from bash's PS1, not from Terminator.

Opening a layout

terminator --list-layouts     # check that Terminator reads them
terminator --layout=grid

If a Terminator window is already open, the new command doesn't start a new program: by default Terminator runs as a single instance, and the request goes to the instance already running. That instance still has the configuration it read at startup, so a layout added afterwards is unknown to it, and you get a window with a single terminal. Close all Terminator windows before trying a new layout, or start a separate instance with -u (--no-dbus):

terminator -u --layout=grid

A command in each terminal

Each terminal can start with a command, for example a connection to a server:

    [[[t1]]]
      type = Terminal
      parent = left
      order = 0
      command = "ssh admin@server01; exec bash"

The ; exec bash part matters: without it the terminal closes as soon as the command ends, for example when the SSH session drops. With it, you are left with a local shell in the same terminal.

A launcher for GNOME

The command is already a single line, so in the terminal an alias is enough:

echo "alias tgrid='terminator --layout=grid'" >> ~/.bashrc

To open it from the GNOME menu or the dock, I create a .desktop file:

mkdir -p ~/.local/share/applications
cat > ~/.local/share/applications/terminator-grid.desktop <<'EOF'
[Desktop Entry]
Type=Application
Name=Terminator (grid)
Comment=Terminator with four terminals
Exec=terminator --layout=grid
Icon=terminator
Terminal=false
Categories=System;TerminalEmulator;
EOF

desktop-file-validate ~/.local/share/applications/terminator-grid.desktop checks the file. The launcher then appears in the activities search under "Terminator (grid)", and from there you can pin it to the dock. For more layouts, one file per layout with a different Name and Exec.

One launcher for all layouts

With several layouts, one file each gets tedious. A .desktop file can also declare actions: GNOME shows them when you right-click the icon, in the dock or in the applications list. So one launcher is enough, with an action for each layout, and a small script can generate it from Terminator's configuration:

#!/usr/bin/env bash
# Creates a GNOME launcher for Terminator with one action per configured layout.
# The actions appear when you right-click the icon (dock or applications list).
# Run it again after adding or removing a layout.
set -euo pipefail

dest="${XDG_DATA_HOME:-$HOME/.local/share}/applications/terminator-layouts.desktop"
mkdir -p "$(dirname "$dest")"
mapfile -t layouts < <(terminator --list-layouts 2>/dev/null | grep -v '^default$')

{
  echo "[Desktop Entry]"
  echo "Type=Application"
  echo "Name=Terminator layouts"
  echo "Comment=Terminator with a saved layout"
  echo "Exec=terminator -u"
  echo "Icon=terminator"
  echo "Terminal=false"
  echo "Categories=System;TerminalEmulator;"
  # action identifiers may only contain letters, digits and hyphens
  ids=()
  for l in "${layouts[@]}"; do ids+=("$(printf '%s' "$l" | tr -c 'A-Za-z0-9-' '-')"); done
  echo "Actions=$(printf '%s;' "${ids[@]}")"
  for i in "${!layouts[@]}"; do
    l="${layouts[$i]}"
    echo
    echo "[Desktop Action ${ids[$i]}]"
    echo "Name=$l"
    echo "Exec=terminator -u --layout=$l"
  done
} > "$dest"

desktop-file-validate "$dest"
echo "Created $dest with ${#layouts[@]} layouts: ${layouts[*]}"

I saved it as ~/bin/terminator-layouts. A normal click opens a plain Terminator, a right-click lists the layouts. Every action uses -u, so the layout opens even when another Terminator window is already running with an older configuration.

A dashboard layout

The spiral turned out to be a good shape for a monitoring dashboard: one large terminal for the overview and smaller ones for details:

btop, the overview of CPU, memory, disks, network and processes, in the large terminal;
atop, detailed system metrics, with one line per CPU core;
wavemon, Wi-Fi link quality and signal level;
nvtop, the GPU (AMD, Intel or Nvidia);
nload, network traffic in and out.

sudo apt install btop atop wavemon nvtop nload fonts-unifont

Two more profiles. retro uses GNU Unifont, a pixel font that covers almost all of Unicode, so btop's graphs keep every symbol and get an old-computer look. It stays sharp at 12 points, a multiple of its pixel grid. tiny is the green Terminus profile at 7 points, for the two smallest terminals:

  [[retro]]
    font = Unifont 12
    use_system_font = False
  [[tiny]]
    font = Terminus (TTF) 7
    use_system_font = False
    background_color = "#0f2a1d"
    foreground_color = "#9fe8b0"

The layout is the spiral, with a title for each terminal and a command:

  [[dashboard]]
    [[[window]]]
      type = Window
      parent = ""
      maximised = True
    [[[s1]]]
      type = HPaned
      parent = window
    [[[btop]]]
      type = Terminal
      parent = s1
      order = 0
      profile = retro
      title = btop
      command = "btop; exec bash"
    [[[s2]]]
      type = VPaned
      parent = s1
      order = 1
    [[[atop]]]
      type = Terminal
      parent = s2
      order = 0
      profile = small
      title = atop
      command = "atop; exec bash"
    [[[s3]]]
      type = HPaned
      parent = s2
      order = 1
    [[[wifi]]]
      type = Terminal
      parent = s3
      order = 0
      profile = small
      title = wifi
      command = "wavemon; exec bash"
    [[[s4]]]
      type = VPaned
      parent = s3
      order = 1
    [[[gpu]]]
      type = Terminal
      parent = s4
      order = 0
      profile = tiny
      title = gpu
      command = "nvtop; exec bash"
    [[[net]]]
      type = Terminal
      parent = s4
      order = 1
      profile = tiny
      title = network
      command = "nload wlp2s0; exec bash"

A few things I learned while putting it together:

the font size decides whether a program starts at all: atop refuses to run in less than 60 columns by 24 lines, so it needs the larger top-right terminal or a small font;
nload without arguments picks the first network device, which on my laptop is an idle Docker bridge. wlp2s0 is my Wi-Fi interface: ip -br link lists yours;
without title, some terminals show "None" in their title bar;
not every console program behaves in Terminator. s-tui, which I tried first for CPU temperature and frequency, filled its terminal with control sequences instead of graphs, so I left it out.

Other tools

Terminator splits a window on your desktop. If you also need splits on a remote server, or sessions that survive a disconnection, the tool is a terminal multiplexer like tmux or Zellij, which work inside any terminal, including over SSH. Zellij describes layouts in files, similar to what I did here.

Access control and cost monitoring for LLM models on AWS Bedrock

minnogit — Tue, 27 Oct 2026 08:55:00 +0000

I recently created an IAM user for an Android app that uses LLM models on Amazon Bedrock. I wanted two things: the app should be able to call only the models I picked, and I wanted to know at any time how much it was costing. This article describes how I set up both, and where the AWS documentation corrected a wrong idea I had.

The IAM user and the policy

The user has a single policy, which allows invoking four models in eu-west-1 and nothing else:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "BedrockInvokeSpecificModels",
            "Effect": "Allow",
            "Action": [
                "bedrock:InvokeModel",
                "bedrock:InvokeModelWithResponseStream"
            ],
            "Resource": [
                "arn:aws:bedrock:eu-west-1::foundation-model/qwen.qwen3-vl-235b-a22b",
                "arn:aws:bedrock:eu-west-1::foundation-model/google.gemma-3-4b-it",
                "arn:aws:bedrock:eu-west-1::foundation-model/google.gemma-3-12b-it",
                "arn:aws:bedrock:eu-west-1::foundation-model/google.gemma-3-27b-it"
            ]
        },
        {
            "Sid": "BedrockGetModelInfo",
            "Effect": "Allow",
            "Action": [
                "bedrock:GetFoundationModel"
            ],
            "Resource": [
                "arn:aws:bedrock:eu-west-1::foundation-model/qwen.qwen3-vl-235b-a22b",
                "arn:aws:bedrock:eu-west-1::foundation-model/google.gemma-3-4b-it",
                "arn:aws:bedrock:eu-west-1::foundation-model/google.gemma-3-12b-it",
                "arn:aws:bedrock:eu-west-1::foundation-model/google.gemma-3-27b-it"
            ]
        }
    ]
}

Each model is listed by ARN, so if I want to add one in the future I have to do it explicitly. You could use a wildcard to allow all of them, but for an app installed on a device I prefer a closed list.

The tag on the user

For costs, I added a tag to the user: key bedrock, value tablet. You can do it from the IAM console or from the CLI:

aws iam tag-user --user-name <user-name> --tags Key=bedrock,Value=tablet

A second IAM user, which I use for something else, has the same bedrock key with the value inno. This way the same tag groups different users, and the values tell them apart.

My initial plan was a bit different. I thought AWS couldn't attribute costs to an IAM user, and that the tag was the way around that. That is no longer true: Bedrock records the identity behind each call (IAM user or role), and that data reaches Cost Explorer without changing the policy or the app's code. For CUR 2.0 reports you need a new export instead, created in Data Exports with the option "Include caller identity (IAM principal) allocation data", which adds the line_item_iam_principal column. For this case Cost Explorer is enough, and I didn't create the export. The tag is still useful for another reason: it adds a grouping dimension, for example by team, application or device, that you can use in filters and budgets.

Activating the tag as a cost allocation tag

A tag on an IAM user doesn't show up in billing data by itself. It has to be activated:

Open Billing and Cost Management, Cost allocation tags section.
Filter by type IAM principal.
Select the bedrock tag and press Activate.

Activation is done from the organization's management account, or from a standalone account. From a member account the console returns the error Cost allocation tags are managed at the payer account level.

In cost data the tag is called iamPrincipal/bedrock. There are three limits to know before expecting numbers:

the tag only appears after the user has made at least one call to Bedrock;
activation is not retroactive, so earlier costs are not tagged;
the tag can take up to 24 hours to appear in Cost allocation tags after the first call and up to another 24 to activate, and cost data can then arrive with a further delay of up to 24 hours.

Looking at costs in Cost Explorer

Once the data has arrived, in Cost Explorer I filter on the Amazon Bedrock service and group by the iamPrincipal/bedrock tag. The finest level of detail is a cost per usage type per day, so you can't see the cost of a single request. For that you need Bedrock's invocation logs, which are a different path and which I haven't enabled.

The budget

To avoid discovering an out-of-scale bill at the end of the month, I created a plan in AWS Budgets. In my case, spending on LLM calls is less predictable than spending on the other AWS resources I use, which is why I need the budget here more than elsewhere. I chose a custom cost budget with these parameters:

recurring monthly period, with a fixed amount;
scope by tag: the iamPrincipal/bedrock tag, with the values of the IAM users to watch (in my case tablet and inno);
service filter: Amazon Bedrock;
an alert at 80% of the amount, sent by email. It can also go to Slack, but I haven't set that up.

The tag filter also offers a value for untagged costs. That is what the service filter is for: without it, I expect that value to also count the untagged costs of the account's other services, though I haven't verified it. With both filters, the budget should count all Bedrock spending, tagged or not.

If the untagged value is left out, the budget only sees tagged spending. An IAM user calling Bedrock without the tag stays out of the count and doesn't trigger the alert. Either way, it's worth checking Cost Explorer from time to time for untagged Bedrock spending and, if there is any, finding out which user generates it and tagging it.

A budget only alerts: it doesn't stop the spending. If you need a real block, you have to set up an action tied to the threshold, or revoke the user's credentials.

Things to keep in mind

If calls go through a gateway (LiteLLM, API Gateway or a homemade service), the cost is attributed to the gateway's role and not to the end user. To tell users apart, you need to pass session tags when the gateway assumes the role.
An IAM user's credentials are long-lived keys. If the Android app contains them, anyone who extracts the APK can use them: consider temporary credentials, which offer the same cost attribution options.
Attribution by identity can be combined with application inference profiles if you also need a split by application, but it requires changing the policy: you have to add the profiles' ARNs, as well as those of the models in the regions involved.

Summary of the steps

Create an IAM user with a policy limited to the chosen models.
Add a tag to the user (here bedrock=tablet).
Activate the tag in Cost allocation tags, type IAM principal.
Wait for the first call and up to a couple of days to see the data in Cost Explorer.
Create a monthly budget filtered on the tag.

Sources

Da Markdown a PDF con tabelle larghe e diagrammi Mermaid

minnogit — Mon, 26 Oct 2026 09:10:00 +0000

Volevo trasformare in PDF alcuni file Markdown che contengono tabelle larghe e diagrammi Mermaid. Ho provato convertitori online, la stampa su PDF di CUPS e l'esportazione di VS Code, e ogni volta c'era qualcosa che non andava: le tabelle uscivano dalla pagina, o i diagrammi erano illeggibili o rotti. La combinazione che alla fine funziona è pandoc con il filtro mermaid-filter e weasyprint come motore del PDF, senza LaTeX.

Installazione

sudo apt install pandoc weasyprint
npm install -g mermaid-filter

mermaid-filter disegna i diagrammi con Mermaid dentro un Chromium lanciato da puppeteer. Se hai già Chrome, si può farglielo usare con la variabile CHROME, come vedi nello script qui sotto.

Un comando solo

Il comando di pandoc da solo non basta, perché servono anche un foglio di stile e un file di configurazione per Mermaid, e dopo un po' non ricordavo più dove fossero. Ho messo tutto in uno script che si porta dietro il CSS e la configurazione e li scrive in una cartella temporanea. Si salva come md2pdf in una cartella del PATH e si rende eseguibile con chmod +x.

#!/usr/bin/env bash
# uso: md2pdf file.md [file.pdf]
# CHROME=/percorso/chrome per far usare a mermaid-filter un Chrome già installato
set -euo pipefail

in="$(realpath "$1")"
out="$(realpath -m "${2:-${1%.md}.pdf}")"
work="$(mktemp -d)"
trap 'rm -rf "$work"' EXIT

cat > "$work/pandoc.css" <<'CSS'
@page { size: A4; margin: 1cm; }

body {
  font-size: 9pt;
  font-family: sans-serif;
  line-height: 1.5;
}

img {
  display: block;
  margin: 0 auto;
  max-width: 100%;
  height: auto;
}

table {
  width: 100%;
  table-layout: fixed;
  border-collapse: collapse;
  overflow-wrap: break-word;
}

td, th {
  border: 1px solid #ccc;
  padding: 6px;
  text-align: left;
  font-size: 8pt;
  overflow: hidden;
}
CSS

# Con htmlLabels false il testo dei nodi resta testo SVG: weasyprint non
# disegna le etichette HTML (foreignObject) che Mermaid usa di default.
echo '{"flowchart":{"htmlLabels":false}}' > "$work/.mermaid-config.json"

if [ -n "${CHROME:-}" ]; then
  printf '{"executablePath":"%s","args":["--no-sandbox"]}' "$CHROME" > "$work/.puppeteer.json"
fi

# mermaid-filter legge i due file di configurazione dalla cartella corrente
cd "$work"
MERMAID_FILTER_FORMAT=svg pandoc -F mermaid-filter \
  -t html5 --pdf-engine=weasyprint --css=pandoc.css \
  -o "$out" "$in"

Si usa così:

md2pdf articolo.md              # crea articolo.pdf
md2pdf articolo.md uscita.pdf

Se il Markdown ha un front-matter YAML in testa, va tolto prima, altrimenti finisce nel testo del PDF.

Perché la configurazione di Mermaid

Con MERMAID_FILTER_FORMAT=svg i diagrammi restano vettoriali e si leggono bene anche ingranditi. Ma la prima volta che ho provato, i riquadri dei diagrammi erano vuoti: le forme c'erano, il testo no. Mermaid di default scrive le etichette dei nodi dentro un elemento HTML incorporato nell'SVG (foreignObject), e per quanto ho capito weasyprint non lo disegna. La riga htmlLabels: false nel file .mermaid-config.json fa scrivere le etichette come normale testo SVG, e il problema sparisce. mermaid-filter legge quel file dalla cartella corrente, per questo lo script entra nella cartella temporanea prima di lanciare pandoc.

L'alternativa è lasciare il formato png (il predefinito del filtro), ma i diagrammi non sono più vettoriali.

Perché il CSS

Le parti del foglio di stile che contano sono poche:

@page con margini di 1 cm, per usare bene l'A4.
table-layout: fixed e overflow-wrap: break-word, che sono quello che tiene le tabelle larghe dentro la pagina: le colonne si dividono lo spazio in parti uguali e il testo lungo va a capo, anche nel mezzo di una parola se serve (un nome come devto_synced_hash in una colonna stretta si spezza in due righe).
text-align: left nelle celle: senza, il testo giustificato in colonne strette lascia spazi enormi tra le parole.
il font a 9pt nel testo e 8pt nelle tabelle. Sono valori che ho scelto a occhio: con i 7pt con cui avevo cominciato il PDF si leggeva a fatica. Se hai tabelle con molte colonne puoi scendere ancora.

Ho provato lo script su una tabella con otto colonne e su un'altra con percorsi e comandi lunghi, e in entrambi i casi sono rimaste dentro la pagina.

Lanciarlo da VS Code

Per non aprire il terminale ogni volta ho aggiunto un task di VS Code, cioè un comando salvato che parte dal menu. Va messo in .vscode/tasks.json nel progetto, oppure in tasks.json nella cartella di configurazione utente (~/.config/Code/User/ su Linux) per averlo in tutti i progetti:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Markdown → PDF",
      "type": "shell",
      "command": "${env:HOME}/bin/md2pdf \"${file}\"",
      "problemMatcher": [],
      "presentation": { "reveal": "silent", "panel": "shared" }
    }
  ]
}

Con un file Markdown aperto si lancia da Ctrl+Shift+P, scegliendo «Tasks: Run Task» e poi «Markdown → PDF». Il PDF compare nella stessa cartella del file. ${file} è il file aperto nell'editor e ${env:HOME} evita di dipendere dal PATH, perché VS Code potrebbe non conoscere la cartella dove hai messo lo script. Per una scorciatoia da tastiera si aggiunge in keybindings.json:

{
  "key": "ctrl+alt+p",
  "command": "workbench.action.tasks.runTask",
  "args": "Markdown → PDF",
  "when": "editorLangId == markdown"
}

Un limite dei diagrammi piccoli

Un diagramma molto piccolo, per esempio con due soli nodi, viene ingrandito fino a occupare tutta la larghezza della pagina. mermaid-filter lo salva con una larghezza fissa di 800 e weasyprint lo adatta alla pagina, mentre max-height sulle immagini, nelle mie prove, non ha cambiato nulla. I diagrammi di un articolo vero hanno di solito più nodi e vengono della misura giusta, quindi per me non è un problema, ma è una cosa da sapere.

Rendere pubblico un repo: cosa ho controllato prima del primo push

minnogit — Sat, 24 Oct 2026 10:24:38 +0000

Questo articolo fa parte della serie «Un repo per i miei articoli». Per rendere pubblico lo strumento descritto in Tenere gli articoli di Dev.to in Git e accorgersi quando il portale cambia, devto-workbench, sono dovuto partire da un repo nuovo, perché in quello degli articoli ci sono le bozze. Qui racconto come convivono i due repo, cosa ho controllato prima del primo push e perché ho messo un hook di git che lo fa da solo.

Perché non bastava cambiare la visibilità

Su GitHub la visibilità appartiene all'intero repo, non a una cartella: un monorepo con una parte pubblica e una privata non esiste. Il problema vero però è la storia. Rendere pubblico il repo degli articoli avrebbe mostrato ogni versione di ogni bozza, comprese quelle poi riscritte o tagliate, e i messaggi dei commit. Prima era tutto in un solo repo, e solo una parte di quel contenuto poteva diventare pubblica:

flowchart TB
  subgraph prima["Un solo repo privato"]
    A["articles/ e assets/<br>articoli e bozze"]
    B["skill di scrittura<br>la mia voce"]
    C["web/<br>server e pagina"]
    D["scripts/<br>importazione"]
    E["skill di sync"]
  end
  A --> P["resta privato"]
  B --> P
  C --> U["va nel repo pubblico"]
  D --> U
  E --> U

La soluzione è separare i due repo: lo strumento in un repo pubblico, gli articoli in uno privato che include il primo come submodule. Un submodule è un repo dentro un altro, con un puntatore a un commit preciso: il repo privato non tiene una copia del codice, ricorda soltanto quale versione usa.

flowchart LR
  subgraph priv["Repo privato"]
    A["articles/ e assets/"]
    B["skill di scrittura"]
    S["tools/devto-workbench<br>puntatore a un commit"]
  end
  subgraph pub["Repo pubblico devto-workbench"]
    C["web/, scripts/<br>skill di sync"]
  end
  S -->|"punta al commit"| C

git submodule add https://github.com/minnogit/devto-workbench.git tools/devto-workbench

Il repo pubblico è nato con un solo commit iniziale, invece di estrarre i file dello strumento insieme alla loro storia. Estraendo la storia mi sarei portato dietro i messaggi dei commit che toccano anche gli articoli.

Il prezzo sono due cose da ricordare. Chi clona il repo privato deve usare git clone --recurse-submodules (oppure git submodule update --init dopo un clone normale), altrimenti la cartella dello strumento resta vuota.

La seconda riguarda le modifiche allo strumento. In entrambi i percorsi il repo privato continua a puntare alla versione vecchia finché non registra il nuovo commit con un commit suo:

flowchart LR
  subgraph A["Percorso A: modifico dentro il submodule"]
    A1["modifico i file in<br>tools/devto-workbench"] --> A2["commit e push<br>vanno nel repo pubblico"] --> A3["nel repo privato:<br>commit del nuovo puntatore"]
  end
  subgraph B["Percorso B: modifico in un clone separato"]
    B1["modifico i file nel<br>clone del repo pubblico"] --> B2["commit e push<br>vanno nel repo pubblico"] --> B3["nel repo privato:<br>git submodule update --remote"] --> B4["nel repo privato:<br>commit del nuovo puntatore"]
  end
  A3 --> F["il repo privato usa<br>la versione nuova"]
  B4 --> F

Nel percorso A si lavora dentro la cartella del submodule, con commit e push nel repo pubblico, e poi nel repo privato si fa il commit che aggiorna il puntatore. Nel percorso B si lavora in un clone separato del repo pubblico. Poi, nel repo privato, si scarica l'ultima versione dello strumento e si registra il nuovo puntatore:

git submodule update --remote tools/devto-workbench
git add tools/devto-workbench
git commit -m "Aggiorna il submodule devto-workbench"

Se si dimentica update --remote, la cartella resta alla versione vecchia anche se su GitHub c'è già quella nuova.

Controllare prima, non dopo

Un segreto (una chiave API, un token, una password) si può cercare in due momenti: prima che il codice parta dal mio computer, oppure dopo che è arrivato su GitHub. Il secondo, da solo, su un repo pubblico arriva tardi.

GitGuardian, collegato a GitHub come app, ascolta gli eventi allo stadio post-receive, cioè dopo che il codice è stato inviato, e descrive come risposta gli incidenti e gli avvisi. Su un repo pubblico questo significa che l'avviso arriva quando il segreto è già visibile a chiunque. Il riferimento è la pagina How Internal Monitoring works.

GitHub ha una sua protezione sul push. Secondo la documentazione quella a livello di utente è attiva di default e vale per i repo pubblici su GitHub.com, mentre quella a livello di repo è disattivata di default.

C'è poi un motivo pratico: se il segreto è già arrivato, ripulire costa molto. Riscrivere la storia con un force-push non basta, perché GitHub tiene un riferimento per ogni pull request e i vecchi commit restano raggiungibili dai loro indirizzi diretti. Per quanto ne so può ripulirli solo il supporto di GitHub.

Servono quindi controlli sul computer, prima che il codice parta.

L'hook che lo fa da solo

Ho aggiunto ggshield, la riga di comando di GitGuardian, il servizio già collegato a GitHub. Si può lanciare a mano su tutta la storia:

ggshield secret scan repo .

La risposta è stata «No secrets have been found». Il passo che conta è farlo partire da solo. ggshield lo installa come hook di git:

ggshield install --mode local -t pre-commit
ggshield install --mode local -t pre-push

Il pre-commit blocca il segreto prima che entri nella storia. Il pre-push è la seconda barriera, subito prima dell'invio. Per aggirarli, secondo la documentazione del pre-commit, basta git commit -n oppure SKIP=ggshield git commit.

Provare l'hook con un token finto

Per vedere se l'hook funziona conviene committare un token finto, ma non uno qualunque. Un ghp_ seguito da 36 caratteri casuali non viene riconosciuto: l'hook parte, risponde «No secrets have been found» e il commit passa. Un token finto con il checksum corretto invece viene riconosciuto come «GitHub Personal Access Token» (con validità «Invalid») e il commit è rifiutato. Se il commit di prova passa, va annullato con git reset --hard e il reflog ripulito.

I limiti degli hook

Sono locali e non vengono versionati: chi clona il repo non li ha.
Il pre-push di ggshield per default non scansiona i push con più di 50 commit (dalla documentazione, configurabile con max-commits-for-hook). Con una storia lunga conviene lanciare a parte la scansione completa con scan repo.

Cosa un hook non vede

Un hook cerca segreti. Non sa se nel repo c'è qualcosa che non dovrebbe esserci, e queste cose le ho controllate a mano:

Il server legge articles/ e assets/ dalla cartella da cui lo lancio e le crea se mancano, quindi un git add -A distratto dal repo pubblico le metterebbe in un commit. Stanno nel .gitignore, insieme a .mcp.json: nel repo c'è un .mcp.json.example con percorsi e segreti finti.
Ogni commit porta nome ed email dell'autore, e su un repo pubblico li legge chiunque. Per il repo nuovo ho scelto l'indirizzo noreply, nella forma <id>+<utente>@users.noreply.github.com, e l'ho impostato prima del primo push con git commit --amend --reset-author --no-edit: dopo, cambiare l'autore vorrebbe dire riscrivere una storia già pubblicata.
Durante le scansioni ggshield crea nella cartella corrente un file .cache_ggshield, con dentro l'hash dei segreti trovati. Con un git add -A distratto finirebbe nel commit, quindi va nel .gitignore.
Uno scanner di segreti non dice se tra i file tracciati ci sono file di configurazione personali, file di terzi senza avviso di copyright o una licenza che manca. Per questo prima di pubblicare conviene leggere l'elenco con git ls-files.

Il repo è pubblico e tutti i suoi commit hanno l'autore noreply.

Un server MCP per una wiki in Markdown: stdio per modificare, HTTP per servire

minnogit — Sat, 24 Oct 2026 08:36:12 +0000

Questo articolo fa parte della serie «Un repo per i miei articoli». Riguarda il server MCP di una wiki LLM: una wiki di concetti tecnici in Markdown che un agente come Claude Code scrive, collega e interroga, con gli articoli pubblicati come fonti. Per farlo gli serve un'interfaccia con regole precise su cosa può leggere e cosa può scrivere, e per questo ho scritto wiki-mcp-api, un server MCP in TypeScript costruito su @mastra/mcp. Racconto come è fatto e perché lo stesso server si usa in due modi: in locale per modificare la wiki, via HTTP solo per servirla ad altri.

Due cartelle con ruoli diversi

Il server non contiene nessuna wiki. Legge due cartelle indicate dall'ambiente: WIKI_PATH, con le pagine, che si possono scrivere, e RAW_PATH, con le fonti da cui nascono le pagine, in sola lettura. Una terza variabile, WIKI_DOMAIN, è una riga che descrive di cosa parla quella wiki e finisce nelle istruzioni inviate al client. Con la stessa installazione posso così servire due wiki diverse, ciascuna con la sua configurazione.

Il confine tra le due cartelle sta nel codice. writePage risolve il percorso, controlla che resti dentro WIKI_PATH e accetta solo file .md. Le letture delle fonti passano da tool separati, che rifiutano percorsi assoluti e ...

I tool

In stdio i tool sono undici:

Tool	A cosa serve
`wikiSearch`, `wikiListPages`, `wikiReadPage`	cercare, elencare e leggere le pagine
`wikiGraph`, `wikiStatus`	grafo dei link e conteggi per tipo e stato
`wikiWritePage`, `wikiAppendLog`	scrivere una pagina, aggiungere una voce al registro
`wikiListRaw`, `wikiReadRaw`	elencare e leggere le fonti
`wikiChecksum`, `wikiRawDiff`	riconoscere una fonte già vista e vedere cosa è cambiato

Scrivere senza rompere la wiki

wikiWritePage valida il frontmatter con zod prima di scrivere: tipo tra un elenco fisso, almeno un tag, fonti come lista, aggiornato nel formato YYYY-MM-DD e stato tra bozza, stabile e da-rivedere. Le quattro pagine di servizio (index, log, sources, overview) sono esenti. Se il frontmatter non va, l'errore dice quale campo e perché, e l'agente può correggere da solo.

Per le scritture concorrenti c'è un lock sul singolo file (proper-lockfile). Evita che due scritture si mescolino, ma non risolve un conflitto tra due autori che scrivono cose diverse.

La ricerca

wikiSearch ordina per rilevanza con un punteggio in stile TF-IDF, con pesi per campo (il titolo conta più dei tag e i tag più del contenuto) e senza normalizzazione sulla lunghezza della pagina. Restituisce pochi risultati, 10 con una query e 50 senza: i client MCP troncano le risposte lunghe per proteggere il contesto, e un taglio casuale rischia di perdere proprio le pagine più rilevanti. Nei risultati ci sono metadati e uno snippet, non l'intero contenuto.

Aggiornare una fonte che è cambiata

Le fonti sono file e cambiano: un articolo viene corretto, un documento ampliato. All'ingest, wikiChecksum calcola lo sha256 del file e il registro sources.md lo associa alle pagine che ne sono nate. Alla sessione successiva basta ricalcolare il checksum di ogni fonte: se è diverso da quello registrato, la fonte è cambiata. Il checksum individua quali fonti sono cambiate senza doverle rileggere tutte, e il confronto è sul contenuto e non sul nome, quindi una fonte rinominata non risulta nuova.

Dice però solo che qualcosa è cambiato, non cosa. Se all'agente basta rileggere il file aggiornato per decidere cosa modificare nella wiki, spesso non si accorge delle differenze, soprattutto con file grandi, oppure le sottovaluta e non le riporta nelle pagine. Per questo wikiRawDiff confronta la versione vecchia del file, quella che aveva il checksum registrato e che ritrova nella storia git di raw/, con quella attuale, e restituisce le differenze. L'agente valuta solo quelle e aggiorna le pagine che le riguardano. Quando un diff di testo non c'è, ripiega sul confronto per checksum e sulla lettura della fonte. Serve quindi che raw/ stia in un repo git.

stdio e HTTP

Il server ha due ingressi con scopi diversi. In stdio, lanciato dal client sulla stessa macchina, si usa per lavorare sulla wiki: espone tutti i tool, scrittura compresa. L'agente scrive le pagine come modifiche non committate del repo della wiki, che si rivedono e si committano a mano. Così ci sono le due garanzie che il server non dà da solo: l'attribuzione, perché il commit è di chi esegue l'agente, e un controllo umano, perché il diff si rivede prima di committare.

In HTTP il server serve la conoscenza ad altri, quindi è di sola lettura. Richiede un token Bearer (senza MCP_HTTP_TOKEN il processo non parte) e non gestisce TLS, che va messo a monte con un reverse proxy. Un client remoto non ha né attribuzione né controllo umano, e il lock evita solo la corruzione concorrente.

Per lo stesso motivo da remoto si servono di default solo le pagine, cioè la conoscenza già elaborata. I tool sulle fonti (wikiListRaw, wikiReadRaw, wikiRawDiff, wikiChecksum) restano fuori, perché raw/ può contenere materiale non pensato per altri, come bozze. Si riattivano con MCP_HTTP_EXPOSE_RAW=true, valore esatto, e all'avvio il server dice se le fonti sono esposte. I test coprono la differenza tra i due ingressi: per controllare che servissero li ho lanciati senza la modifica e falliscono.

Possibili miglioramenti

I valori di tipo sono fissati nel codice: concetto, soggetto, procedura, normativa, entita e analisi. Per una wiki con altre categorie andrebbero resi configurabili.
La ricerca non ha un indice: a ogni query il server controlla tutti i file e ricalcola il punteggio su tutte le pagine, e la cache evita solo di rileggere e riparsare i file non modificati. Non l'ho misurato su wiki grandi, dove un indice in memoria potrebbe servire.
L'accesso HTTP ha un solo token condiviso e niente TLS.
Il server stdio non ha una modalità di sola lettura: i tool di scrittura ci sono sempre.
wikiRawDiff richiede git sulla macchina che lancia il server, e per i PDF anche pdftotext.

Il progetto ha una CI su GitHub Actions che lancia lint e test a ogni push su main e a ogni pull request. Come ho reso pubblico lo strumento della serie, controllando i segreti prima del push, è raccontato in Rendere pubblico un repo: cosa ho controllato prima del primo push.

Tenere gli articoli di Dev.to in Git e accorgersi quando il portale cambia

minnogit — Fri, 23 Oct 2026 08:45:00 +0000

Scrivo su Dev.to da due posti: dall'editor del portale e da file Markdown in un repo Git, con l'aiuto di Claude Code, come racconto in Un agente AI come editor dei miei articoli Dev.to. Il portale non tiene la storia delle modifiche, e con due punti di scrittura prima o poi uno dei due sovrascrive l'altro senza che nessuno se ne accorga. Per questo ho scritto uno strumento che tiene gli articoli come file, mi dice quando un lato è cambiato rispetto all'altro e non sceglie mai al posto mio quando sono cambiati entrambi. Si chiama devto-workbench, è in Python e usa solo la libreria standard.

Un file per articolo

Ogni articolo è un file articles/<id>-<slug>.md. Il front-matter ha una riga per campo, nella forma chiave: <valore JSON>, così non serve nessuna libreria per leggerlo. Sotto c'è il body_markdown esattamente come lo restituisce Dev.to:

---
id: 1234567
title: "Titolo"
published: false
tags: ["git", "linux"]
url: "https://dev.to/..."
canonical_url: "https://dev.to/..."
cover_image: null
devto_synced_hash: "sha256 del body come era su Dev.to all'ultimo sync"
stato: "revisionata"
reviewed: true
---

Il testo dell'articolo...

L'identificatore è l'id, non il nome del file, che dipende dal titolo e può restare indietro. Il testo non va normalizzato: niente spazi tolti, niente markdown «ripulito». Il motivo è l'hash di cui parlo subito.

Perché un hash e non una data

Per sapere se il portale è cambiato la prima idea è confrontare le date di modifica. Negli elenchi /articles/me e /articles/me/unpublished il campo edited_at è vuoto, quindi non c'è niente da confrontare.

Ho usato l'hash. devto_synced_hash è lo sha256 del body remoto all'ultimo sync riuscito. Per ogni articolo lo strumento mette a confronto tre cose: l'hash del body locale, quello del body remoto e quello salvato. Da lì ricava lo stato:

Stato	Significato	Cosa si fa
allineato	nessuno ha cambiato nulla	niente
remoto più recente	è cambiato solo il portale	pull
locale da pushare	è cambiato solo il file	push
conflitto	sono cambiati entrambi, in modo diverso	decido io
solo su Dev.to / solo locale	manca un lato	importo o creo

Non faccio merge automatici del testo. Su prosa un merge a righe mi sembra produrre risultati incoerenti, e in caso di conflitto preferisco guardare le due versioni e scegliere io.

La pagina web

Dalla radice del repo con gli articoli:

python3 /percorso/di/devto-workbench/web/server.py

e poi http://localhost:8787. Il server legge articles/ dalla cartella da cui lo lancio, oppure da ARTICLES_DIR. Fa anche da proxy verso l'API di Dev.to: il browser da solo non può mandare l'header api-key (lo blocca il CORS), quindi la chiave la aggiunge il server leggendola dall'ambiente.

La pagina ha tre viste, elenco, card e kanban, e mostra per ogni articolo lo stato di sync. Un pulsante compare solo quando l'azione non è ambigua: «Scarica in locale» per un articolo solo su Dev.to, «Scarica aggiornamento» quando è cambiato solo il portale, «Manda online» quando è cambiato solo il file. In caso di conflitto non c'è nessun pulsante di scrittura, solo «Differenze», che mostra il confronto riga per riga, unificato o fianco a fianco.

Il kanban e il campo stato

Il kanban ha quattro colonne: Bozza, Revisionata, Pronta, Pubblicato. Trascinare una card tra le prime tre scrive il campo stato nel front-matter del file, senza chiamare Dev.to. La colonna Pubblicato non accetta il drop: pubblicare è un'azione a parte e non si fa trascinando una card.

«Pubblicato» non ha un valore proprio in stato: lo ricava il server da published: true. Se fosse scritto in due posti, prima o poi i due direbbero cose diverse. stato e reviewed sono campi solo locali. Non vanno mai su Dev.to, non entrano nell'hash e si scrivono nel file solo se diversi dal valore di default, così spostare una card cambia una riga sola. Lo stato di sync resta un badge sulla card, indipendente dalla colonna.

Con Claude Code

Gli articoli stanno in un repo privato che include il tool come submodule git. Nel repo del tool c'è una skill per Claude Code, devto-articles, che descrive le operazioni in cui il controllo a hash evita di sovrascrivere una modifica altrui: creare un articolo nuovo, pull, push, conflitti, pubblicazione. Per parlare con Dev.to usa un server MCP, nel mio caso un fork di devto-mcp. Non contiene le norme di scrittura, che sono la mia voce e restano in un repo privato.

La skill è testo, non codice: se l'agente non la segue, il controllo non scatta da solo. Per questo la pagina web fa lo stesso controllo per conto suo prima di ogni pull e push.

Esportare solo gli articoli pubblicati

Volevo alimentare una wiki con gli articoli, senza esporre le bozze. scripts/export_published.py copia in un'altra cartella solo gli articoli con published: true:

python3 scripts/export_published.py --dest /percorso/altro-repo/raw/devto

Il body resta identico byte per byte e il front-matter si riduce a id, title, url e tags. Il motivo è che il server della wiki che uso calcola il checksum sull'intero file: con reviewed o devto_synced_hash dentro, ogni articolo risulterebbe modificato a ogni sync. Una seconda esecuzione senza novità non scrive nulla, --dry-run mostra cosa farebbe, --prune toglie gli articoli esportati che non sono più pubblicati e la destinazione non può coincidere con la cartella degli articoli.

Lo stesso si può fare dalla pagina web, lanciando il server con EXPORT_DEST=/percorso/altro-repo/raw/devto. Il pulsante «Esporta pubblicati» mostra prima l'anteprima, poi esporta e stampa il comando per il commit nell'altro repo, che resta a mano. La destinazione si decide solo all'avvio: una richiesta alla pagina non può sceglierla.

Lo script ha dei test con unittest. Per controllare che i test servissero a qualcosa ho indebolito di proposito la regola sul published, e quello giusto ha fallito.

Cosa non fa

Non fa merge del testo: in caso di conflitto sei tu a decidere.
Non pubblica dalla pagina web. Non l'ho ancora implementato, e vorrei una conferma esplicita prima di mandare qualcosa online.
L'ho provato solo su Linux con Python 3.14. Il codice usa la sintassi X | None, quindi serve almeno la 3.10. Su Windows non l'ho provato.
Lo script di esportazione esporta quello che dice il front-matter locale. La pagina, in anteprima, segnala invece gli articoli pubblicati sul portale che nel file sono ancora bozze e che l'esportazione salterebbe.

Questo articolo fa parte della serie «Un repo per i miei articoli». Nella serie c'è anche Un server MCP per una wiki in Markdown: stdio per modificare, HTTP per servire, sul server della wiki costruita dagli articoli pubblicati, e Rendere pubblico un repo: cosa ho controllato prima del primo push, su cosa controllare prima di rendere pubblico un repo.

Il codice e il README sono su github.com/minnogit/devto-workbench, con licenza MIT.

Aprire una PR da fork verso il maintainer e i problemi che non mi aspettavo

minnogit — Tue, 20 Oct 2026 12:52:31 +0000

Ho un fork Python di un server MCP per Dev.to (devto-mcp, partito dal progetto pubblico Arindam200/devto-mcp) che uso ogni giorno con Claude Code. Ci ho trovato dentro un paio di bug reali (uno rendeva impossibile aggiornare un articolo, mancava l'header di autenticazione sulla richiesta; l'altro faceva restituire 404 quando si cercava di leggere una propria bozza) e li ho risolti per me. A quel punto mi sono fatto la domanda che probabilmente si fa chiunque tocchi un fork per la prima volta: ha senso proporre queste fix al progetto originale?

Non l'avevo mai fatto. Ecco cosa ho imparato facendolo.

Guardare il terreno prima di scrivere

Prima ancora di pensare a come strutturare la PR, ho controllato lo stato del repository originale: l'ultimo push risale a maggio 2025, e le uniche due Pull Request aperte (maggio e luglio 2025) sono entrambe un badge promozionale scollegato dal codice, non una revisione reale. Anche l'unica PR mergiata in passato era un badge. Non è un quadro di manutenzione attiva: non mi aspettavo un merge, ma ho deciso di procedere comunque, come caso di studio.

Prima di aprire una PR conviene guardare la cronologia delle altre, per farsi un'idea realistica di cosa aspettarsi.

Guardare anche gli altri fork, non solo l'originale

Un repository pubblico su GitHub ha spesso decine di fork, e conviene controllarli prima di scrivere la propria fix: qualcun altro potrebbe averla già risolta, magari meglio, o aver introdotto nel frattempo una regressione da non ripetere. Ho confrontato tutti i fork esistenti con l'originale: quasi tutti fermi al momento della creazione, uno solo con del lavoro reale sopra, ed è quello che ho letto con attenzione.

Guardare il lavoro altrui serve a confermare che la propria soluzione è quella giusta, e a volte a raccogliere un'idea isolata da tenere in un backlog per dopo.

Isolare le modifiche: perché non lavorare sul proprio main

Fatta la ricerca, restava da preparare cosa proporre davvero. Qui è emerso un problema pratico: il mio branch main locale, nel tempo, aveva accumulato anche cose mie personali (un file TODO.md, note nel README specifiche del mio fork), e nessuna di queste doveva finire nella PR verso l'originale. Ma ci sarebbe finita per forza, se avessi aperto la PR direttamente da lì.

La soluzione più pulita: creare un branch dedicato a partire dal main dell'upstream, non dal mio, e portarci sopra solo i commit che voglio proporre con git cherry-pick:

git fetch upstream
git checkout -b fix/draft-articles-auth upstream/main
git cherry-pick <hash-commit-1> <hash-commit-2>
git push origin fix/draft-articles-auth

Il vantaggio pratico: qualsiasi cosa io committi dopo sul mio main (il TODO.md, un README personalizzato) non tocca mai questo branch, a prescindere da quando la committo: il branch della PR resta «congelato» a cosa gli ho esplicitamente portato con cherry-pick. L'unica accortezza è tenere i commit atomici: mai mescolare nello stesso commit una fix genuina con roba personale, altrimenti il cherry-pick selettivo smette di essere semplice.

Un dettaglio da sapere se i commit non sono indipendenti tra loro (nel mio caso, il secondo riusa una funzione introdotta dal primo): non si possono isolare separatamente, ma si possono comunque proporre insieme in un'unica PR. L'alternativa, «impilare» due PR separate dove la seconda dipende dalla prima, ha senso solo se ci si aspetta che vengano revisionate in tempi diversi. Con un maintainer fermo da maggio 2025, quella complessità in più non ripaga: meglio una PR sola, ben descritta.

Il dettaglio che mi ha fatto perdere tempo: il branch tracciava il repo sbagliato

Il push da riga di comando è andato a buon fine, e l'errore è comparso altrove, per cui sul momento non capivo da dove venisse. main l'avevo ottenuto clonando il mio fork (git clone .../minnogit/devto-mcp.git), e Git imposta di default il tracking sul remote da cui si clona: origin/main, cioè il mio fork, dove ho sempre avuto permessi di scrittura. Il branch nuovo l'ho creato con git checkout -b fix/draft-articles-auth upstream/main, e quel comando imposta il tracking su upstream/main, dove non ho scrittura. Poi ho fatto git push origin <branch> (senza -u): il branch è arrivato sul mio fork, ma la configurazione di tracking è rimasta puntata a upstream.

Da riga di comando questo non si vede, perché specifico sempre origin come destinazione del push. È emerso aprendo VSCode: la sua interfaccia si fida della configurazione di tracking invece di guardare cosa esiste sul server, quindi mi proponeva di «sincronizzare» verso upstream, e il push falliva.

Fix, una riga:

git branch --set-upstream-to=origin/fix/draft-articles-auth fix/draft-articles-auth

Si poteva evitare con git push -u origin fix/draft-articles-auth, che al primo push imposta il tracking su origin, oppure creando il branch con --no-track: git checkout -b fix/draft-articles-auth --no-track upstream/main.

Aprire la PR: due percorsi diversi, un errore in comune

Da riga di comando, gh pr create accetta titolo e descrizione via flag (--title, --body-file per un testo su più righe salvato in un file):

gh pr create \
  --repo Arindam200/devto-mcp \
  --base main \
  --head minnogit:fix/draft-articles-auth \
  --title "..." \
  --body-file pr-body.md

Da VSCode, ho avuto un errore diverso e più subdolo: No commits between main and fix/draft-articles-auth. La causa, per quanto ho capito: l'interfaccia aveva impostato come «base repository» il mio fork, non l'originale, e siccome il mio main conteneva già gli stessi commit (i due fix li avevo cherry-pickati proprio da lì), il confronto risultava vuoto. Serve cambiare esplicitamente il repository di base, non solo il branch: nella schermata di creazione PR (o sul sito, dietro il link «compare across forks») vanno impostati due selettori distinti, repository di base (l'originale) e repository di confronto (il proprio fork).

Sulla lingua della descrizione

Il repository originale (README, issue, le altre PR) è tutto in inglese. Ho scritto titolo e descrizione della PR in inglese, anche se i miei commit restavano in italiano (non li ho toccati, e va benissimo così: la storia dei commit non deve necessariamente combaciare con la lingua della conversazione attorno alla PR). Ha senso scrivere per il pubblico che effettivamente la leggerà.

Perché ho aperto la PR comunque

Con un repository fermo da maggio 2025, la PR probabilmente non verrà mai guardata. Ho deciso di aprirla comunque: i commit erano già pronti e puliti, il costo marginale era basso, e anche se resta ignorata resta pubblica, quindi chi incontra lo stesso bug potrebbe trovarla, con la fix già pronta. Il mio fork intanto continua a funzionarmi perfettamente, a prescindere dall'esito.

La PR è qui, se vuoi vedere com'è venuta: Arindam200/devto-mcp#4.

Un agente AI come editor dei miei articoli Dev.to

minnogit — Sun, 18 Oct 2026 18:18:37 +0000

Tengo tutti i miei articoli Dev.to (pubblicati e bozze) sotto controllo di versione in un repository Git privato, devto-articles, e li scrivo e pubblico con l'aiuto di Claude Code, collegato a Dev.to tramite un server MCP, devto-mcp (un mio fork di Arindam200/devto-mcp). Lo racconto perché l'agente lavora anche da editor, prima ancora che da postino verso Dev.to, e quello alza la qualità del testo finale più di quanto farebbe da solo un buon editor di testo.

L'agente come editor

Concretamente, cosa fa in più rispetto a «scrivi il markdown e mandalo»: prima di tutto legge un paio di articoli già presenti nel repo per intonarsi a tono e struttura, invece di scrivere con la voce media di un modello linguistico. Poi applica una checklist esplicita contro i pattern tipici della prosa generata: via l'em-dash usato come connettore universale, via il contrasto fittizio «non è X, è Y» usato come effetto retorico invece che per correggere un vero equivoco del lettore, via le aperture e chiusure da manuale (tipo «Nel mondo di oggi...» o «In conclusione...»), via il lessico da traduzione automatica.

Questo stesso articolo ne è un esempio concreto. La prima stesura conteneva oltre dieci em-dash e un paragrafo di chiusura costruito proprio sul contrasto fittizio segnalato sopra. Li ho fatti notare, l'agente ha riletto il testo e li ha corretti uno per uno, mostrandomi il diff prima di rimandarlo a Dev.to. Ecco una correzione, da una versione intermedia di questo articolo:

Prima: «Non è mai autopilota, e la differenza non è cosmetica: cambia chi decide cosa finisce pubblicato, anche quando non sono io a battere per primo le parole sulla tastiera.»

Dopo: «In pratica chi decide cosa viene pubblicato sono io, anche quando le prime parole le scrive l'agente.»

La checklist che ha usato per farlo (sette divieti fissi e due cose da evitare, con le fonti da cui vengono) è ora parte permanente della skill che uso per scrivere, e si ripete a ogni articolo nuovo o rivisto, non solo su questo.

Un altro aspetto: di solito l'articolo nuovo non parte da me che scrivo prosa da zero, ma da una sessione di lavoro già conclusa nella stessa conversazione, di cui l'agente ha già tutto il contesto (un bug risolto, una PR aperta). Le informazioni non le avevo mai messe per iscritto in forma di articolo: gli chiedo di scriverlo dopo, a lavoro finito, e il testo lo stende l'agente a partire da quello che abbiamo fatto insieme, non da una narrazione inventata.

C'è poi una parte meno visibile ma altrettanto concreta: prima di sovrascrivere un file già sincronizzato con Dev.to, l'agente confronta lo stato locale con quello remoto e si ferma a chiedere se trova un disallineamento, invece di procedere alla cieca. Su un archivio che continuo a modificare anche a mano dal portale, questo controllo fa la differenza tra un assistente che aiuta a scrivere e uno che, ogni tanto, cancella silenziosamente qualcosa che avevi scritto altrove.

Conviene essere precisi su cosa intendo con «editor». Dev.to distingue tre livelli di dichiarazione dell'uso dell'AI: scritto a mano, «AI-assisted» e «Fully Autonomous», quest'ultimo per i contenuti generati soprattutto da agenti o LLM. Questo articolo è dichiarato «AI-assisted». Anche quando lo stende materialmente l'agente a partire da una sessione di lavoro, il testo racconta cose che ho fatto davvero (bug risolti, decisioni prese insieme, comandi eseguiti) e non materiale inventato per l'occasione. Nessuna riga esce senza che io l'abbia riletta e senza una mia conferma esplicita prima della pubblicazione. In pratica chi decide cosa viene pubblicato sono io, anche quando le prime parole le scrive l'agente.

Perché tenere gli articoli in un repository

Le motivazioni sono più d'una, e questa (avere un editor che lavora sugli stessi file con git, cronologia e diff) è la principale. Le altre:

Backup versionato indipendente da Dev.to: se il portale perde dati, cancella per errore una bozza o cambia formato, ho comunque una copia con tutta la storia delle modifiche, non legata alla disponibilità o alle scelte di un servizio terzo.
Portabilità verso altre piattaforme: avere il testo grezzo in Markdown in un repository mio, senza dipendenze dal formato interno di Dev.to, rende più semplice riusare gli stessi articoli come base per pubblicarli altrove, in futuro, senza doverli prima esportare o estrarre dal portale.

Il meccanismo di sincronizzazione, in breve

Questa parte è tecnica, ma serve a capire perché posso lasciare scrivere l'agente sui miei file senza temere di perdere lavoro: ogni file tiene traccia, nel front-matter, dell'hash SHA-256 del corpo dell'articolo così com'era su Dev.to all'ultimo sync riuscito (devto_synced_hash). Prima di scrivere in un senso o nell'altro, l'agente ricalcola l'hash remoto attuale e lo confronta con quello salvato. Se combaciano, l'operazione è sicura. Se no, è un conflitto, e qui non c'è un git merge che decide da solo: le due versioni mi vengono mostrate entrambe e la scelta su quale prevale resta mia. La riscrittura vera e propria, quando serve unire i due testi in un discorso coerente, la fa l'agente, ma solo dopo che gliel'ho chiesto e prima di rimandarla a Dev.to.

Per un push, i passaggi in sequenza sono questi:

sequenceDiagram
    actor Io
    participant Agente
    participant Repo as File nel repo
    participant Devto as Dev.to

    Io->>Agente: correggi questo paragrafo
    Agente->>Repo: modifica il file
    Agente->>Repo: legge devto_synced_hash
    Agente->>Devto: legge il body remoto
    Devto-->>Agente: body_markdown attuale
    Agente->>Agente: calcola lo sha256 del body remoto
    alt gli hash coincidono
        Agente->>Devto: update_article
        Agente->>Repo: aggiorna devto_synced_hash e committa
    else gli hash sono diversi
        Agente->>Io: mostra le due versioni
        Io->>Agente: sceglie quale prevale
    end

Un progetto per pubblicare su Dev.to da un repository Git, dev-to-git, descrive solo la direzione dal repo verso il portale, e le proprietà dell'articolo si controllano da lì. Io modifico gli articoli anche a mano dal portale, quindi mi serve un controllo nelle due direzioni, non solo da qui verso Dev.to.

In pratica, per un articolo nuovo l'agente non scrive prima un file provvisorio in articles/. Scrive il body altrove e chiama create_article per farlo esistere su Dev.to come bozza. Solo con la risposta in mano (id, url, hash del body riletto da remoto) scrive una volta sola il file definitivo in articles/<id>-<slug>.md e lo committa nel mio repository. La pubblicazione su Dev.to e il commit nel repo sono due passaggi distinti, entrambi necessari.

Un'alternativa altrettanto legittima è partire dal portale: creo io la bozza a mano nell'editor di Dev.to, e l'agente la importa nel repo con la stessa operazione di pull che usa per rilevare modifiche fatte da lì. Ogni modifica successiva ripete il controllo dell'hash prima di ripushare con update_article. La pubblicazione (published: true) è uno dei passaggi che l'agente conferma sempre esplicitamente prima di eseguire, perché è visibile pubblicamente e non banale da annullare in modo pulito.

Cosa cambia davvero

Scrivere in Markdown invece che nella textarea del portale è comodo, ma da solo si otterrebbe anche incollando poi il testo a mano. Il vantaggio vero è avere un editor che conosce la mia voce da un corpus reale di articoli precedenti, applica una checklist esplicita contro i tic della prosa generata prima di consegnare, e si ferma a chiedere invece di sovrascrivere alla cieca quando qualcosa non torna. La parte tecnica del sync rende tutto questo possibile senza rischiare di perdere lavoro. È infrastruttura di supporto, e il lavoro che conta è quello di scrittura descritto sopra.

Gestione repo script sul server

minnogit — Thu, 25 Jun 2026 09:39:51 +0000

Come deployo gli script bash del mio repo git sul server

Ho un repository git con decine di script bash che uso per la gestione del server (backup, restic, virtualhost, slack, deploy, ecc.).

Alcuni script si richiamano tra loro. Devono quindi stare in una directory che sia nel PATH e che corrisponda ai path.

La soluzione che ho adottato è questa:

/opt/scripts/              ← git clone del repo
/usr/local/sbin/script.sh  → symlink → /opt/scripts/script.sh

Perché funziona

Il repo sta in /opt/scripts/ — una directory dedicata, separata dai binari di sistema. Non si mescola con altro, non porta .git/ o file di configurazione in mezzo agli eseguibili.
I symlink stanno in /usr/local/sbin/ — così gli script sono raggiungibili via PATH ed eventuali path hardcoded continuano a funzionare.
Gli aggiornamenti sono semplici — un git pull in /opt/scripts/ aggiorna tutto, e i symlink puntano già ai file aggiornati.

Come si fa

sudo -i
git clone <url-del-repo> /opt/scripts
chmod +x /opt/scripts/*.sh
ln -s /opt/scripts/backup_all.sh /usr/local/sbin/
ln -s /opt/scripts/check_system_health.sh /usr/local/sbin/
# ... e così via per ogni script che serve

Perché non clono direttamente in `/usr/local/sbin/`

Perché nel repo ci sono anche file non eseguibili: .git/, template .tpl, file .txt, script .bat per Windows. Mettere tutto in /usr/local/sbin/ sporca il PATH e rischia interferenze con git clean o git status.

Con i symlink invece in /usr/local/sbin/ finiscono solo gli script che effettivamente servono, e il repo resta isolato e pulito in /opt/scripts/.

Come estrarre una singola tabella da un file dump MySQL

minnogit — Tue, 19 May 2026 09:08:59 +0000

A volte ho a disposizione solo il dump .sql di un intero database e mi serve una tabella. Aprire un file di svariati gigabyte con un editor di testo è scomodo, e importare tutto su un server locale per recuperare poche righe è uno spreco. Basta un piccolo script che estrae solo la tabella che interessa, con i suoi dati.

Lo script

#!/usr/bin/env bash
# uso: estrai-tabella nome_tabella dump.sql > tabella.sql
awk -v target="-- Table structure for table \`$1\`" '
  BEGIN { header = 1 }
  /^\/\*!40103 SET TIME_ZONE=@OLD_TIME_ZONE/ { footer = 1; in_t = 0 }
  /^-- (Table structure for table|Temporary view structure for view|Final view structure for view|Dumping routines|Dumping events)/ { header = 0; in_t = ($0 == target) }
  (header || in_t || footer) && !(in_t && /^DROP TABLE/)
' "$2"

Si usa così, con il nome della tabella e il dump generato da mysqldump:

estrai-tabella nome_tabella dump_completo.sql > nome_tabella.sql
mysql nome_database < nome_tabella.sql

Come funziona

Un dump di mysqldump è diviso in blocchi, ognuno introdotto da un commento come -- Table structure for table seguito dal nome della tabella. Lo script stampa tre parti:

l'intestazione, cioè le righe prima del primo blocco: impostano la codifica e disattivano il controllo delle chiavi esterne;
il blocco della tabella scelta, dal suo commento fino al commento del blocco successivo, quindi struttura, dati e trigger;
il piè di pagina, che rimette a posto le impostazioni cambiate dall'intestazione.

La riga DROP TABLE IF EXISTS del blocco viene tolta. Prima usavo un intervallo di sed tra DROP TABLE e UNLOCK TABLES, ma lasciava fuori l'intestazione e i trigger, che mysqldump scrive dopo UNLOCK TABLES. Con il DROP dentro, importare quel file cancellava la tabella esistente, e con essa anche i suoi trigger, che il file non ricreava.

Cosa succede all'import

Se la tabella esiste già, l'import si ferma con l'errore Table 'nome_tabella' already exists e non cancella nulla. Per sostituirla la cancello io prima con DROP TABLE. Se è referenziata da una chiave esterna, anche il DROP si ferma (Cannot drop table ... referenced by a foreign key constraint) finché non disattivo i controlli con SET FOREIGN_KEY_CHECKS=0.
Le chiavi esterne della tabella vengono ricreate. Grazie all'intestazione, l'import funziona anche se la tabella a cui puntano non c'è ancora.
I trigger della tabella vengono ricreati.

Limiti

Ho provato lo script con mysqldump 9.7 e un server MySQL 8.4, importando una tabella con un trigger, una con una chiave esterna e una vuota in un database nuovo. Non l'ho provato con MariaDB né con versioni più vecchie di mysqldump: i commenti di separazione dovrebbero essere gli stessi, ma è un'ipotesi.
Se il dump è stato creato con --skip-comments, i commenti che separano i blocchi non ci sono e lo script non trova la tabella.
I trigger riportano un DEFINER, cioè l'utente che li ha creati (nella mia prova root@localhost). Se importo su un altro server, quell'utente deve esistere, altrimenti la creazione del trigger fallisce. Questo non l'ho provato.
Viste e stored procedure non vengono estratte, anche se dipendono dalla tabella.
awk legge il dump fino in fondo, anche dopo aver stampato il blocco. Su file molto grandi ci mette il tempo di una lettura completa, che non ho misurato.

Stabilizzazione dell'Infrastruttura: Gestire il Connection Pooling tra Proxy e Backend

minnogit — Mon, 18 May 2026 13:58:20 +0000

Nel mantenimento di architetture web complesse, l'ottimizzazione del dialogo tra il Proxy (nel nostro caso Apache) e i nodi di backend è un passaggio cruciale per garantire la fluidità dei servizi. Recentemente abbiamo analizzato una situazione di saturazione delle risorse che ci ha permesso di approfondire la gestione dei socket TCP, il comportamento dei pool di connessione e la complessa natura dei timeout multilivello.

In questo articolo vedremo come abbiamo identificato il problema, gli strumenti di monitoraggio utilizzati e come configurare correttamente i timeout per proteggere il proxy, senza penalizzare i portali che richiedono elaborazioni lunghe.

1. I primi segnali: Errori di Fork

Il punto di partenza della nostra analisi è stata una serie di messaggi nei log di Apache che indicavano difficoltà nel gestire nuovi processi, non un crash improvviso:

[error] (11)Resource temporarily unavailable: apr_thread_create: unable to create worker thread
[error] (11)Resource temporarily unavailable: fork: avocado_create: pool_task

Questi errori di fork compaiono quando il server raggiunge i limiti imposti dal sistema operativo o dalla configurazione dell'MPM (Multi-Processing Module). I worker esistenti rimangono occupati troppo a lungo, impedendo la creazione di nuovi thread per servire le nuove richieste in ingresso.

2. Monitoraggio e Analisi del Traffico

Per capire perché Apache stesse saturando i worker, abbiamo utilizzato alcuni comandi shell per analizzare lo stato delle connessioni di rete in tempo reale.

Analisi quantitativa per backend

Per osservare come variava il carico verso un nodo specifico (nel nostro caso il .106), abbiamo utilizzato un monitoraggio continuo:

watch -n 1 "netstat -atpn | grep 172.31.41.106 | wc -l"

Questo comando ci ha permesso di notare che il numero di connessioni non scalava verso il basso come previsto, indicando una persistenza anomala dei socket.

Analisi della distribuzione delle connessioni

Un altro comando fondamentale è stato quello per mappare la provenienza del traffico e identificare eventuali anomalie nella distribuzione dei client:

netstat -ntu | awk '{print $5}' | cut -d: -f1 | sort | uniq -c | sort -n

L'analisi dettagliata ha rivelato un numero elevato di connessioni in stato CLOSE_WAIT. Questo stato indica che il backend ha già terminato la sua parte di connessione, ma il proxy non ha ancora chiuso il socket lato suo. Un vero e proprio "limbo" TCP.

3. Disaccoppiare i Timeout: Applicazione vs Infrastruttura

Per risolvere questo scenario, è fondamentale fare chiarezza sulla differenza tra due concetti spesso confusi:

Timeout Applicativo: È il tempo richiesto dal codice sorgente per completare un'operazione (es. una query complessa o la generazione di un file pesante). Un timeout applicativo troppo lungo espone il server al pericolo di elaborazioni infinite, mantenendo il backend occupato e saturando le risorse computazionali.
Timeout Infrastrutturale (o di Rete): È il tempo massimo concesso per la trasmissione dei dati e la gestione dei socket tra i vari nodi della rete.

Il problema esaminato in questa analisi riguardava specificamente il timeout della comunicazione infrastrutturale tra il proxy e l'applicazione, ovvero i socket rimasti orfani che bloccavano i thread di Apache. L'implementazione applicativa interna al backend è ininfluente: che si tratti di un'architettura o di un'altra, se la gestione del socket TCP lato proxy fallisce, l'infrastruttura si satura.

4. Timeout per route: cosa si può e cosa no

Durante le indagini abbiamo esplorato la possibilità di creare configurazioni di timeout differenziate a seconda della route (URL path), in modo da isolare i percorsi più lenti da quelli più veloci.

Il limite che abbiamo incontrato è più circoscritto di quanto sembrasse: dentro un singolo balancer:// il path non seleziona il membro. A decidere quale BalancerMember serve la richiesta è l'algoritmo di bilanciamento (lbmethod), non l'URL richiesto, quindi differenziare i timeout per route agendo sui membri dello stesso cluster non può funzionare per costruzione.

Non è invece vero che il timeout non sia granularizzabile: timeout è un parametro documentato di worker/BalancerMember ("Socket timeout in seconds. The number of seconds Apache httpd waits for data sent by / to the backend", con default pari a ProxyTimeout), e la configurazione che adottiamo più avanti ne è la prova, dato che imposta connectiontimeout sul singolo membro. Per differenziare davvero per route servono worker distinti: balancer separati indirizzati da ProxyPass diversi, oppure ProxyPass verso URL di backend distinti.

C'è però un'insidia che rende l'operazione fragile, e che spiega perché molti tentativi sembrano non avere effetto: il worker sharing. I worker sono identificati dall'URL di backend, e se l'URL di uno è prefisso di quello di un worker definito dopo, il secondo non viene creato e i suoi parametri vengono ignorati, con un warning nell'error log. La documentazione indica il rimedio: ordinare le definizioni partendo dagli URL più lunghi.

Nel nostro caso abbiamo comunque applicato la strategia in modo uniforme all'intero blocco proxy, perché non dipende dall'ordine delle direttive e regge meglio le modifiche successive.

5. La Soluzione: Il Ruolo di `connectiontimeout`

In molti dei nostri portali è indispensabile mantenere timeout globali alti per consentire l'esecuzione di script applicativi lunghi ed elaborazioni pesanti. Abbassare indiscriminatamente il timeout del proxy avrebbe interrotto servizi legittimi.

La soluzione definitiva che ha azzerato i CLOSE_WAIT e risolto gli errori di fork, pur mantenendo il supporto agli script lunghi, è stata il passaggio alla sintassi balancer:// sfruttando il parametro connectiontimeout.

Configurazione applicata:

<Proxy balancer://frontoffice>
    # node04 - Configurazione ottimizzata
    BalancerMember http://172.31.41.106:8080 route=4 connectiontimeout=2 retry=10 hcmethod=TCP hcinterval=5 hcpasses=2 hcfails=1

    ProxySet lbmethod=bybusyness
    ProxySet stickysession=ROUTEID
</Proxy>

ProxyPass "/" "balancer://frontoffice/"
ProxyPassReverse "/" "balancer://frontoffice/"

Perché questa configurazione è risolutiva?

Il segreto sta nella separazione tra il timeout di risposta globale e il timeout di connessione iniziale:

connectiontimeout=2 (La vera protezione): Questo parametro agisce solo sulla fase di handshake TCP iniziale. Se il backend è congestionato, bloccato o non risponde entro 2 secondi, Apache desiste immediatamente e libera il proprio worker. Questo previene l'accumulo di processi appesi in Apache che causavano gli errori di fork.
Mantenimento degli script lunghi: Una volta stabilita la connessione nei primi 2 secondi, il proxy concede all'applicazione tutto il tempo configurato nel timeout globale per terminare le sue elaborazioni pesanti.
Health Checks attivi (hcinterval=5): Apache interroga il backend ogni 5 secondi. Se un nodo fallisce i controlli TCP, viene temporaneamente isolato dal cluster, evitando di inviare traffico a un server saturo.

6. Conclusioni e Manutenzione Futura

La risoluzione degli errori di fork ci ha ricordato che la stabilità di un'infrastruttura richiede di configurare correttamente i limiti della rete, senza per questo sacrificare le necessità dell'applicazione (come le elaborazioni lunghe).

Per evitare derive configurative e mantenere l'uniformità su tutta la flotta di server, la distribuzione di queste direttive BalancerMember e la gestione dei relativi VirtualHost verrà centralizzata e gestita tramite Puppet Server. L'automazione è l'unica via per garantire che queste best practice rimangano stabili e documentate nel tempo.

Cheat Sheet di Emergenza per il futuro:

Isolamento rapido: netstat -atpn | grep CLOSE_WAIT per contare i socket orfani.
Analisi client: netstat -ntu | awk '{print $5}' ... per verificare la distribuzione degli IP.
Regola d'oro: Separare sempre il tempo concesso all'applicazione per elaborare i dati dal tempo concesso alla rete per aprire la connessione (connectiontimeout).