DEV Community: Edgaras

Comparing Caddy, nginx and Apache Configuration

Edgaras — Mon, 07 Sep 2026 10:30:00 +0000

Caddy, nginx and Apache httpd each serve static files, terminate TLS and reverse-proxy to a backend. They differ most in the configuration language, and in how much of the configuration has to be written at all.

The versions used are Caddy v2.11.4, nginx 1.31.3 mainline and Apache httpd 2.4.68. Every configuration below ran on the official caddy:alpine, nginx:alpine and httpd:alpine images, with localhost and non-privileged ports in place of example.com, port 80 and port 443, and a self-signed certificate for nginx and Apache.

The three projects

	Caddy	nginx	Apache httpd
License	Apache 2.0	2-clause BSD	Apache 2.0
Published by	ZeroSSL, an HID Global company	F5, Inc.	The Apache Software Foundation
Current release	v2.11.4, 2026-06-03	mainline 1.31.3, stable 1.30.4	2.4.68, 2026-06-08
Release lines	One line	Mainline (odd middle number), updated every one to two months; stable (even), about once a year	2.4.x
Official binaries	Static binaries for Linux, macOS, Windows and FreeBSD, plus Debian and Fedora/RHEL packages	Linux packages for RHEL, Debian, Ubuntu, SLES, Alpine and Amazon Linux, and a Windows zip	Source only; Windows binaries come from third-party vendors

What the configuration is written in

Caddy's native configuration format is JSON. Any other format is converted to JSON by a config adapter, and the Caddyfile is the adapter in the standard build. caddy adapt prints the conversion, so this Caddyfile:

example.com {
    root /var/www/html
    file_server
}

produces this:

$ caddy adapt --config Caddyfile --pretty
{
    "apps": {
        "http": {
            "servers": {
                "srv0": {
                    "listen": [
                        ":443"
                    ],
                    "routes": [
                        {
                            "match": [
                                {
                                    "host": [
                                        "example.com"
                                    ]
                                }
                            ],
                            "handle": [
                                {
                                    "handler": "subroute",
                                    "routes": [
                                        {
                                            "handle": [
                                                {
                                                    "handler": "vars",
                                                    "root": "/var/www/html"
                                                },
                                                {
                                                    "handler": "file_server",
                                                    "hide": [
                                                        "./Caddyfile"
                                                    ]
                                                }
                                            ]
                                        }
                                    ]
                                }
                            ],
                            "terminal": true
                        }
                    ]
                }
            }
        }
    }
}

The JSON is what the server runs. The Caddyfile is one way to produce it.

nginx configuration is a directive file. Simple directives end in a semicolon, and block directives use braces. Blocks that can contain other directives are called contexts: events, http, server, location. Everything outside a block is in the main context. A directive is inherited from the enclosing level only when the same directive is absent at the current level.

Apache configuration is also a directive file, scoped by container sections: <VirtualHost>, <Directory>, <DirectoryMatch>, <Files>, <FilesMatch>, <Location>, <LocationMatch>, <Proxy> and <If>. The sections merge in a fixed group order: <Directory> together with .htaccess, then <DirectoryMatch>, then <Files> and <FilesMatch>, then <Location> and <LocationMatch>, and <If> last.

Position in the file matters differently in each of the three.

Caddy: file order is mostly ignored. The adapter sorts HTTP handler directives into a fixed built-in order, and directives of the same name by how specific their matchers are. A route block keeps the written order for everything inside it. Plugin directives are not in the built-in order, so each needs a place set by the order global option or a route block.
nginx: file order decides which regular expression location is tried first. nginx checks the prefix locations first and keeps the longest match. It then tries the regular expression locations in the order they appear and takes the first that matches. If none match, the kept prefix is used. ^~ on the longest prefix skips the regular expression step. = is an exact match and stops the search.
Apache: file order decides within a group, not across groups. A <Location> block always applies after a <Directory> block, because of the group order above. <Directory> is the exception inside its own group: shortest path first, so <Directory "/var/web/dir"> before <Directory "/var/web/dir/subdir">, with file order deciding only between sections naming the same directory.

When more than one block could match a request, each server picks exactly one.

Caddy: the site block with the most specific matching address handles the request. No other site block applies.
nginx: server_name is matched in a fixed order. An exact name first, then the longest wildcard beginning with an asterisk, then the longest wildcard ending with one, then the first matching regular expression. A request matching none of these goes to the default server for that address and port.
Apache: exactly one <VirtualHost> is selected. Directives from the other matching virtual hosts are never merged in.

The same site, three times

The site serves static files from a directory, reverse-proxies /api/ to 127.0.0.1:8080 with the client's Host preserved and X-Forwarded-For and X-Forwarded-Proto set, terminates HTTPS, redirects HTTP to HTTPS, compresses text responses and writes an access log.

Caddy:

example.com {
    root /var/www/html
    encode
    reverse_proxy /api/* 127.0.0.1:8080
    file_server
    log {
        output file /var/log/caddy/access.log
    }
}

nginx:

worker_processes  auto;

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" "$http_user_agent"';
    access_log  /var/log/nginx/access.log  main;

    gzip             on;
    gzip_min_length  512;
    gzip_vary        on;
    gzip_types       text/plain text/css text/xml application/json
                     application/javascript application/xml image/svg+xml;

    server {
        listen       80;
        server_name  example.com;
        return       301 https://$host$request_uri;
    }

    server {
        listen       443 ssl;
        http2        on;
        server_name  example.com;

        ssl_certificate      /etc/nginx/ssl/example.com.crt;
        ssl_certificate_key  /etc/nginx/ssl/example.com.key;

        root /var/www/html;

        location /api/ {
            proxy_pass http://127.0.0.1:8080;

            proxy_set_header Host              $host;
            proxy_set_header X-Real-IP         $remote_addr;
            proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }
}

Apache:

ServerRoot "/usr/local/apache2"

Listen 80
Listen 443

LoadModule mpm_event_module   modules/mod_mpm_event.so
LoadModule unixd_module       modules/mod_unixd.so
LoadModule authz_core_module  modules/mod_authz_core.so
LoadModule mime_module        modules/mod_mime.so
LoadModule dir_module         modules/mod_dir.so
LoadModule alias_module       modules/mod_alias.so
LoadModule log_config_module  modules/mod_log_config.so
LoadModule filter_module      modules/mod_filter.so
LoadModule deflate_module     modules/mod_deflate.so
LoadModule headers_module     modules/mod_headers.so
LoadModule ssl_module         modules/mod_ssl.so
LoadModule proxy_module       modules/mod_proxy.so
LoadModule proxy_http_module  modules/mod_proxy_http.so

User  daemon
Group daemon

ServerName example.com
TypesConfig conf/mime.types
DirectoryIndex index.html

ErrorLog logs/error_log
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\"" combined
CustomLog logs/access_log combined

<Directory "/">
    Require all denied
</Directory>

<VirtualHost *:80>
    ServerName example.com
    Redirect permanent "/" "https://example.com/"
</VirtualHost>

<VirtualHost *:443>
    ServerName    example.com
    DocumentRoot  "/var/www/html"

    SSLEngine on
    SSLCertificateFile    "conf/example.com.crt"
    SSLCertificateKeyFile "conf/example.com.key"

    <Directory "/var/www/html">
        Require all granted
    </Directory>

    AddOutputFilterByType DEFLATE text/html text/plain text/css text/javascript \
                          application/javascript application/json application/xml image/svg+xml

    ProxyRequests     Off
    ProxyPreserveHost On
    RequestHeader set X-Forwarded-Proto "https"
    ProxyPass        "/api/" "http://127.0.0.1:8080/api/"
    ProxyPassReverse "/api/" "http://127.0.0.1:8080/api/"
</VirtualHost>

CustomLog is at server level rather than inside the :443 virtual host. Inside the virtual host it logs HTTPS requests only, and the port-80 redirects are not logged at all. The Caddy and nginx configurations log both.

	Caddy	nginx	Apache
Non-blank lines	9	36	48
Bytes	144	1303	1839
`LoadModule` lines	0	0	13

The ordering is the same for the smallest job, serving one static directory over plain HTTP:

	Caddy	nginx	Apache
Non-blank lines	4	8	15
Bytes	41	113	477
`LoadModule` lines	0	0	5

Why the Caddyfile is shorter

The difference is mostly defaults, not a more compact syntax. The Caddyfile names the site address, and Caddy derives the rest from it.

HTTPS: a site address with a hostname turns on automatic HTTPS, so the Caddyfile needs no certificate directive. nginx needs ssl_certificate and ssl_certificate_key. Apache needs SSLEngine on, SSLCertificateFile and SSLCertificateKeyFile.
The HTTP to HTTPS redirect: Caddy adds it and answers with 308. nginx and Apache each need a second server block or virtual host, which return 301 above.
Directive order: the adapter sorts encode, reverse_proxy and file_server into the built-in order, so no route block is needed.
HTTP/2: Caddy serves it on the HTTPS listener with no directive. nginx needs http2 on;, added in 1.25.1 and off by default. Apache needs mod_http2 and a Protocols line, and the configuration above has neither.

Two more defaults differ, both between nginx and the other two.

nginx writes an access log with no configuration at all, to logs/access.log in its predefined combined format. Caddy and Apache write none until configured.
Caddy and Apache both send Vary: Accept-Encoding on compressed responses with no extra configuration. nginx needs gzip_vary on.

Headers sent to the proxied backend

Each server was configured to proxy everything to 127.0.0.1:8080, with no header directives of any kind, and the backend printed the headers it received. The request carried Host: site.test.

Header at the backend	Caddy 2.11.4	nginx 1.31.3	httpd 2.4.68
`Host`	`site.test`	`127.0.0.1:8080`	`127.0.0.1:8080`
`X-Forwarded-For`	`127.0.0.1`	absent	`127.0.0.1`
`X-Forwarded-Proto`	`http`	absent	absent
`X-Forwarded-Host`	`site.test`	absent	`site.test`
`X-Forwarded-Server`	absent	absent	`localhost`
`Via`	`1.1 Caddy`	absent	absent

Caddy passes the client's Host through unchanged and sets the three X-Forwarded-* headers itself. It ignores any incoming values of those three unless trusted_proxies is configured.

nginx replaces Host with $proxy_host and adds nothing else, which is why the configuration above carries four proxy_set_header lines. $host holds the host without the port, so a request to example.com:8443 reaches the backend as Host: example.com.

Apache replaces Host with the ProxyPass target unless ProxyPreserveHost On is set. mod_proxy_http adds X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Server by default, under ProxyAddHeaders, which has defaulted to on since 2.3.10. X-Forwarded-Proto is not in that set, so the Apache configuration adds it with RequestHeader.

Checking a configuration

	Command	What it does
Caddy	`caddy validate`	Deserializes, loads and provisions every module without starting the config
Caddy	`caddy adapt --validate`	Adapts a Caddyfile to JSON and then validates it
Caddy	`caddy fmt`	Formats a Caddyfile; exits 1 when the output differs from the input
nginx	`nginx -t`	Tests the syntax and tries to open the files the configuration references
nginx	`nginx -T`	The same, and dumps the whole configuration to stdout
Apache	`apachectl configtest`	Parses the configuration files and reports `Syntax OK` or the error
Apache	`httpd -S`	Shows the parsed virtual host settings

Neither nginx nor Apache documents an equivalent of caddy fmt.

Reloading

All three can replace the running configuration without dropping connections, by different mechanisms.

Caddy: caddy reload posts the configuration to the admin API's /load endpoint. The new configuration is provisioned and started before the old one is stopped, so both run briefly. The command fails if the admin endpoint is disabled. The grace period for old connections is eternal by default.
nginx: nginx -s reload signals the master process. The master checks the syntax, opens log files and new listen sockets, starts workers with the new configuration and tells the old workers to shut down. Old workers close their listen sockets, finish serving connected clients and exit. worker_shutdown_timeout caps that wait.
Apache: apachectl graceful sends USR1. Children finish their current request, the parent re-reads the configuration files and re-opens the log files, and each child is replaced from the new generation. apachectl restart sends HUP instead, which kills children immediately and zeroes the mod_status counters.

A configuration with an error is rejected by all three, and the running server keeps the previous configuration. Each was given a valid configuration, then a broken one, then asked to reload:

$ caddy reload --config /etc/caddy/Caddyfile
{"level":"info","ts":1786909867.4621506,"msg":"using config from file","file":"/etc/caddy/Caddyfile"}
Error: adapting config using caddyfile: /etc/caddy/Caddyfile:6: unrecognized directive: this_is_not_a_directive

$ nginx -s reload
2026/08/16 19:51:10 [emerg] 31#31: unknown directive "not_a_directive" in /etc/nginx/nginx.conf:6
nginx: [emerg] unknown directive "not_a_directive" in /etc/nginx/nginx.conf:6

$ apachectl -k graceful
AH00526: Syntax error on line 15 of /usr/local/apache2/conf/httpd.conf:
Invalid command 'NotARealDirective', perhaps misspelled or defined by a module not included in the server configuration

In each case the server continued to answer with the configuration it had before the attempt, and a later reload of a corrected file applied the change.

Apache keeps its ports bound across a restart. A Listen change that conflicts with the existing binding therefore fails and terminates the server, and applying it needs a full stop and start.

nginx can replace its own executable without stopping. Sending USR2 starts a second master from the new binary, WINCH shuts down the old workers, and QUIT retires the old master. The old master keeps its listen sockets throughout, so it can restart its workers with HUP if the new binary misbehaves. Caddy's caddy upgrade replaces the binary on disk only and leaves the running process on the old one.

Caddy is the only one of the three whose open-source build exposes an HTTP API for the whole running configuration: the admin endpoint on localhost:2019, with POST /load, POST /stop, POST /adapt and the /config/ path supporting GET, POST, PUT, PATCH and DELETE, plus Etag and If-Match for optimistic concurrency. nginx documents ngx_http_api_module and the -l control REST API added in 1.29.8 as commercial-subscription features. Apache's documentation states that changes to the main configuration files are recognized only on start or restart.

Apache has one mechanism the others do not: .htaccess, read on every request, so changes take effect without a restart. AllowOverride defaults to None. Where it is enabled, httpd looks for an .htaccess file in the requested directory and in every higher-level directory that also has it enabled, on every request, whether or not the files exist.

Which modules have to be present

The configurations above do not fail in the same way. The Caddy one runs on any standard Caddy binary. The nginx one fails on a binary built without SSL or HTTP/2 support. The Apache one fails unless each of its 13 modules is loaded, and the error names the directive that stopped working, not the module that provides it. Invalid command 'SSLEngine' does not say that the LoadModule ssl_module line is missing. Removing each LoadModule line in turn and running httpd -t on 2.4.68 matches each error to its module:

Module removed	`httpd -t` reports	Provides
`mpm_event_module`	`AH00534: httpd: Configuration error: No MPM loaded.`	The process model. Exactly one MPM must be loaded
`unixd_module`	`Invalid command 'User'`	`User` and `Group`, the account the server runs as
`authz_core_module`	`Invalid command 'Require'`	`Require`, the access rules
`mime_module`	`Invalid command 'TypesConfig'`	Content-Type from the file extension
`dir_module`	`Invalid command 'DirectoryIndex'`	Serving `index.html` for directory requests
`alias_module`	`Invalid command 'Redirect'`	`Redirect` in the port-80 virtual host
`log_config_module`	`Invalid command 'LogFormat'`	`LogFormat` and `CustomLog`, the access log
`filter_module`	`Invalid command 'AddOutputFilterByType'`	Attaching the compression filter by content type
`deflate_module`	`Unknown filter provider DEFLATE`	The DEFLATE filter itself, gzip compression
`headers_module`	`Invalid command 'RequestHeader'`	`RequestHeader`, the `X-Forwarded-Proto` header
`ssl_module`	`Invalid command 'SSLEngine'`	HTTPS, `SSLEngine` and the certificate directives
`proxy_module`	`Cannot load modules/mod_proxy_http.so into server: ... ap_proxy_pre_http_request: symbol not found`	The proxy core and `ProxyPass`
`proxy_http_module`	`Syntax OK`	HTTP support for `ProxyPass`, the `/api/` proxying

The last row is the exception. Without mod_proxy_http the configuration passes the syntax check and the server starts, static files are served normally, and only requests to /api/ fail. Those return status 500 and log AH01144: No protocol handler was valid for the URL /api/hello (scheme 'http').

None of this means recompiling. The official httpd:alpine image ships 130 module files, including all 13 the configuration needs, and its stock httpd.conf loads 25 of them. Adding the missing LoadModule lines is the whole job.

nginx has the equivalent constraint at build time rather than at config time. HTTPS and HTTP/2 support are compile-time options, --with-http_ssl_module and --with-http_v2_module, so whether the nginx configuration above works depends on how the binary was built, not on a directive. Prebuilt packages include them: nginx -V on the official nginx:alpine image reports both, plus --with-http_v3_module and --with-stream. A dynamic module has to match the running nginx exactly, because nginx refuses to load a module whose compiled-in version or module signature differs.

Caddy has no load step at all. caddy list-modules on v2.11.4 reports 132 standard modules in the binary, and every directive in the Caddyfile above comes from that set. Adding anything outside it means a new binary, built with xcaddy, downloaded from the project's download page, or fetched by caddy add-package, which the command-line reference marks experimental. That command replaces the binary on disk and leaves the running process on the old one until it restarts.

Conclusion

The three configuration languages are nothing alike. The length differences come from defaults rather than syntax. Much of what the nginx and Apache configurations write out, Caddy does by default. Enabling a feature also happens in a different place in each server. Apache does it in the config file, nginx at build time, Caddy in the choice of binary. None of this tells you how the three behave under load. That depends on each server's process and connection handling, and the configuration file shows none of it.

UML Activity Diagrams

Edgaras — Tue, 01 Sep 2026 10:00:00 +0000

A UML activity diagram models a process as a set of actions connected by flows. The process does not have to be software. An expense approval that crosses three departments fits the notation as well as a CI pipeline does. Among the UML behavior diagrams, this is the one about steps and their order, not about objects and the messages between them.

What is a UML Activity Diagram?

An activity diagram describes the behavior of a system or an organization as steps in the order they run. You read it from the initial node, along the arrows, to a final node. It shows:

Actions: the individual steps
Control flows: arrows giving the order between steps
Decisions and merges: where the process takes one of several paths, and where those paths come back together
Forks and joins: where the process splits into parallel paths, and where it waits for all of them
Object flows: data or documents moving between steps
Partitions: lanes naming who performs which steps

Why Use Activity Diagrams?

Working out a process before automating it: draw the manual process as it runs today, then mark the actions the new system takes over.
Filling in a use case: a use case diagram names the goal, Place Order, and stops there. The steps go in an activity diagram.
Finding parallelism: some steps can start together and some cannot. The diagram states which, and where the process has to wait.
Recording responsibility: when a process crosses a team or service boundary, lanes show where work passes from one side to the other.

Core Components and Notation

Action and Control Flow

An action is a single step in the process. It is drawn as a rounded rectangle with the step's name inside. A control flow is the solid arrow between two actions, and it means the first action must finish before the second starts. In a hiring process, Screen application and Schedule interview are actions joined by a control flow. A condition in square brackets on an arrow is a guard; the flow is taken only when the condition is true.

Initial and Final Nodes

An initial node is a solid black circle. It marks where the process starts. There are two ending nodes. The activity final node is a solid circle inside a hollow ring; it ends the whole process, including parallel paths that are still running. The flow final node is a circle with an X in it; it ends only the path that reaches it, and the rest of the process continues. The receipt email path of an order process ends at a flow final while the packing path continues.

Decision and Merge Nodes

A decision node is a diamond with one arrow in and several out. Each outgoing arrow has a guard, and the process follows the arrow whose guard is true. One arrow may use the predefined guard [else], taken when no other arrow accepts the flow. A loan application takes the [approved] arrow or the [rejected] arrow, never both. A merge node is the same diamond with several arrows in and one out. It does not wait; each arriving flow continues straight out.

Fork and Join Nodes

A fork is a thick bar with one arrow in and several out. When the flow reaches it, every outgoing path starts at once; where a decision picks one path, a fork starts them all. A join is a thick bar with several arrows in and one out. It waits for every incoming path to arrive, then the process continues as a single flow. An airline check-in forks into Check passport and Weigh baggage, and boarding waits at the join for both.

Object Nodes and Data Stores

An object node is a rectangle between two actions naming the data that moves from one to the other, an Invoice for example. Arrows entering or leaving it are object flows; they carry data, not just order. The same information can be drawn as pins, small squares on the edge of an action, one per input or output. An object node with the keyword «datastore» is a data store: it holds its contents for the whole run of the process, and an action reading from it gets a copy while the original stays in place. A customer register read by both the billing step and the shipping step is a data store.

Partitions

A partition, usually called a swimlane, divides the diagram into rows or columns, one per performer. The performer's name goes in a box at one end of the lane, at the top when lanes run vertically, and every action inside the lane belongs to that performer. An insurance claim diagram gets one lane for the customer, one for the claims handler, and one for accounting. When lanes would make the diagram too wide, write the partition name in parentheses above the action name instead.

Send Signal and Accept Event Actions

Send signal and accept event actions communicate with something outside the process. A send signal action is a box with one pointed end. The process sends the named signal and continues without waiting for a reply. An accept event action is a box with one end notched inward. The flow stops there until the named event arrives. In an order process, Request payment is a send signal. Payment confirmed is the event the process waits for before shipping. An accept event action with no incoming arrow waits the whole time the process runs. Its outgoing flow starts each time the event occurs. A wait for a specific time such as the end of the month is drawn as an hourglass.

Practical Example: Pull Request CI Pipeline

The diagram models what happens after a developer pushes a branch. Two lanes split the work between the developer and the CI server.

The initial node is in the Developer lane. Push branch is the only action the developer performs.
The flow crosses into the CI Server lane and reaches a fork. Run linter and Run unit tests start at the same time.
The join under them waits for both to finish.
The decision routes on the result. [all checks passed] continues to Build container image. [else] goes to Post failure comment.
A Container image object node is between Build container image and Deploy to staging. The image itself is the input of the deploy step.
The two branches meet at a merge node, and the flow ends with the send signal action Notify developer and an activity final node. The pipeline stops as soon as the notification is sent.

Best Practices

Use a flow final to end one path, an activity final to end the whole process: the first flow to reach an activity final also cancels every other path still running.
Write guards that cannot both be true: [total >= 100] beside [total <= 100] can both be true at 100, and the tool then picks the edge.
Do not guard the edges out of a fork when a join collects them: a flow stopped by a failed guard never reaches the join, and the process stops there.
Omit pins when they make the diagram hard to read: an action name like Build container image already names its output.
Break an arrow that would cross the whole diagram with a pair of connectors: the arrow ends at a small labeled circle and continues from the circle with the same label elsewhere on the page.

Conclusion

An activity diagram records how one process runs from start to finish, including any parallel paths. It does not record which objects carry out a step or what messages pass between them. That is what sequence diagrams show. A state machine diagram covers the states one object passes through over its lifetime.

jina-embeddings-v4 as an OpenAI-Compatible Embeddings Server

Edgaras — Mon, 24 Aug 2026 10:30:00 +0000

jina-embeddings-v4 is a self-hosted server for the jina-embeddings-v4 embedding model with an OpenAI-compatible /v1/embeddings endpoint. It runs on a single NVIDIA GPU. An application that calls OpenAI for embeddings can call this server instead. The request and response bodies are the same, so setting the client's base URL is the only change needed.

When this is useful

Text that cannot leave your network: the model runs on your infrastructure, and no external calls are made for embeddings after the weights are downloaded.
Embedding a large dataset: there is no per-request charge.
Existing OpenAI client code: the endpoint accepts the OpenAI request format and returns the OpenAI response format, so the calls in the application need no rewrite. The vectors are 2048-dimensional and unrelated to OpenAI's, so text already embedded with an OpenAI model has to be embedded again.
Multilingual and code retrieval: one model embeds text in many languages, and source code when task is code.

What is in the image

Model: jina-embeddings-v4, 3.8B parameters
Output: 2048-dimensional float32 vectors
GPU memory: 8.1 GB once the model is loaded, and over 10 GB while embedding a text of several thousand tokens
Stack: FastAPI and sentence-transformers

Requirements

An NVIDIA GPU with at least 10 GB of VRAM.
An NVIDIA driver compatible with CUDA 12.4.
Docker, Docker Compose, and the NVIDIA Container Toolkit.

Setup

Create a docker-compose.yml:

services:
  jina:
    image: edgaras0x4e/jina-embeddings-v4:latest
    ports:
      - "8081:80"
    volumes:
      - jina-cache:/root/.cache/huggingface
    environment:
      HF_HOME: /root/.cache/huggingface
      API_KEY: your-api-key-here
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    restart: unless-stopped

volumes:
  jina-cache:

docker compose up -d

The image download is about 7.8 GB, and 14.7 GB unpacked on disk. The prebuilt image needs no build step. Building from source (git clone the repo, then docker compose up -d --build) compiles flash-attn against PyTorch 2.5.1 and CUDA 12.4, which takes 10 to 20 minutes.

The weights are not in the image: on first start the server downloads about 7 GB from Hugging Face and loads them into GPU memory. On later starts the server reads the weights from the volume instead of downloading them again.

When /health returns ok, the server is ready to embed:

curl http://localhost:8081/health

{"status":"ok"}

Embedding text

curl http://localhost:8081/v1/embeddings \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"input": ["The train leaves at eight in the morning"]}'

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [-0.008472833782434464, -0.024404730647802353, 0.007389210630208254, ...],
      "index": 0
    }
  ],
  "model": "jinaai/jina-embeddings-v4",
  "usage": {"prompt_tokens": 8, "total_tokens": 8}
}

The array holds 2048 values. Three are shown.

The response uses the OpenAI list format. data holds one object per input text, each with an embedding array and its index. usage.prompt_tokens counts the input tokens. total_tokens equals it, since embedding produces no output tokens.

input also accepts a list of strings, one request for the whole batch.

The full request body:

Field	Required	Description
`input`	yes	One string or a list of strings
`model`	no	Echoed back in the response. The server always serves the model set by `MODEL_ID`.
`task`	no	`text-matching` (default), `retrieval`, or `code`
`prompt_name`	no	`query` or `passage`. Used only when `task` is `retrieval`, defaults to `passage`.
`encoding_format`	no	Accepted for OpenAI compatibility and ignored. Vectors are always `float32` arrays.

Task adapters

The model produces a different embedding for the same text depending on the value of task. The default, text-matching, is for comparing two texts of the same kind, such as two support tickets or two product descriptions.

retrieval is for search, where a short query is matched against longer documents. Embed the documents with prompt_name set to passage and the query with prompt_name set to query:

curl http://localhost:8081/v1/embeddings \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
        "input": ["when does the train leave"],
        "task": "retrieval",
        "prompt_name": "query"
      }'

code is for source code and code search.

Using the OpenAI Python client

from openai import OpenAI

client = OpenAI(api_key="your-api-key-here", base_url="http://localhost:8081/v1")

resp = client.embeddings.create(
    model="jinaai/jina-embeddings-v4",
    input=["how long does the journey take"],
)
print(len(resp.data[0].embedding))

The task and prompt_name fields are not OpenAI parameters, so the SDK passes them through extra_body:

resp = client.embeddings.create(
    model="jinaai/jina-embeddings-v4",
    input=["SELECT id, name FROM users WHERE active = 1"],
    extra_body={"task": "code"},
)

If the server runs without API_KEY, the OpenAI SDK still rejects an empty api_key string. Pass any non-empty placeholder.

Configuration

Environment variables on the jina service:

Variable	Default	Purpose
`MODEL_ID`	`jinaai/jina-embeddings-v4`	Hugging Face model id. Override only for a fork or finetune with the same architecture.
`HF_HOME`	`/root/.cache/huggingface`	Cache path inside the container. The compose file mounts the `jina-cache` volume there, so a new container reuses the downloaded weights.
`API_KEY`	unset (optional)	Bearer token for `/v1/embeddings`. If unset, the endpoint accepts requests without a token.

The compose file maps host port 8081 to port 80 in the container. If another service already listens on 8081, change the first number in 8081:80.

Source: github.com/Edgaras0x4E/jina-embeddings-v4
Docker image: hub.docker.com/r/edgaras0x4e/jina-embeddings-v4

Deploying PaddleOCR PDF OCR service on Azure Container Apps

Edgaras — Mon, 17 Aug 2026 11:00:00 +0000

paddleocr-pdf-api converts PDFs to markdown over an HTTP API. This post deploys it to Azure Container Apps as a single container app with an HTTP ingress.

Using a Self-Hosted PDF OCR API with PaddleOCR describes the API itself. Read that one first.

Engines and workload profiles

Three OCR engines are available, one per image tag. Each image contains its model weights, and Container Apps has a workload profile for each one.

Engine	Image tag	Models	Needs	Workload profile
`text`	`latest-text-baked`	PP-OCRv5 detection and recognition	CPU	Consumption
`vl`	`latest-vl-baked`	PaddleOCR-VL-1.6 plus PP-DocLayoutV3	~8.5 GB VRAM	Consumption-GPU-NC8as-T4
`structure`	`latest-structure-baked`	PP-StructureV3	~10.5 GB VRAM	Consumption-GPU-NC8as-T4

The Consumption profile allows 0.25 to 4 vCPU and 0.5 to 8 GiB per replica, in a fixed 1:2 ratio. The two GPU profiles are Consumption-GPU-NC8as-T4 and Consumption-GPU-NC24-A100. A T4 has 16 GB of VRAM, which is enough for both GPU engines.

This deployment uses the text engine on the Consumption profile.

The latest tag contains no model weights. OCR_ENGINE defaults to vl, so it downloads PaddleOCR-VL-1.6 and PP-DocLayoutV3 on first run. That download repeats on every replica replacement, so the baked tags are the ones to deploy here.

Setting up the environment

RG=rg-paddleocr
LOC=swedencentral
ENV=env-paddleocr
APP=paddleocr-api

az group create --name $RG --location $LOC

az containerapp env create \
  --name $ENV \
  --resource-group $RG \
  --location $LOC \
  --enable-workload-profiles

Deploying the app

API_KEY=$(openssl rand -hex 16)

az containerapp create \
  --name $APP \
  --resource-group $RG \
  --environment $ENV \
  --workload-profile-name Consumption \
  --image docker.io/edgaras0x4e/paddleocr-pdf-api:latest-text-baked \
  --target-port 8000 \
  --ingress external \
  --cpu 4.0 \
  --memory 8.0Gi \
  --min-replicas 1 \
  --max-replicas 1 \
  --secrets api-key=$API_KEY \
  --env-vars API_KEY=secretref:api-key

This deployment needs no other Azure resource. The models are in the image, and job state is written to the replica's own storage. Mounting Azure Files replaces that storage, and setting DATABASE_URL moves the database to PostgreSQL.

Replica settings

POST /ocr writes the file, records the job as queued, and returns. A background thread does the OCR. No request stays open while a document is processed.

Container Apps adds an HTTP scale rule when you do not define one. It scales on request count, and its minimum is zero replicas. OCR runs without requests, so nothing keeps a replica running.

minReplicas: 0 scales the app to zero while a job is running. Pages already written survive if state persists, and the job resumes on the next request. On ephemeral storage the job and its results are lost.

minReplicas: 1 keeps one replica running, and a job finishes without traffic.

maxReplicas: 1 is not optional here. Jobs are stored in SQLite on the replica's own disk, so each replica has a separate database. A status poll can reach a replica that does not know the job and returns 404. Running more replicas needs PostgreSQL for the records and a shared mount for the uploads. With PostgreSQL every replica sees every queued job, so the replica that claims one may not be the replica that received the upload.

Verifying the deployment

FQDN=$(az containerapp show --name $APP --resource-group $RG \
  --query properties.configuration.ingress.fqdn -o tsv)

JOB_ID=$(curl -s -X POST "https://$FQDN/ocr" \
  -H "X-API-Key: $API_KEY" \
  -F "file=@document.pdf" | jq -r .job_id)

curl -s "https://$FQDN/ocr/$JOB_ID" -H "X-API-Key: $API_KEY"

The models load on the worker thread, so the API answers before OCR can start. A job submitted in that window stays queued until the models are ready.

Making job state survive a restart

/data contains the SQLite database and the uploaded PDFs. Each replica gets ephemeral storage, so both are lost when the replica is replaced. Replacement happens on every revision change.

Setup	Survives replica loss	Requires
SQLite on ephemeral storage	No	Nothing
PostgreSQL through `DATABASE_URL`	Results yes, running job no	A database server
Azure Files mount on `/data`	Yes	A storage account and share

PostgreSQL moves the records off the replica, and several replicas can then share them. The uploaded files stay local.

An Azure Files mount keeps both the SQLite database and the uploaded files. Create a storage account and a file share, then register the share with the environment:

STORAGE=stpaddleocr$RANDOM

az storage account create \
  --name $STORAGE \
  --resource-group $RG \
  --location $LOC \
  --sku Standard_LRS \
  --kind StorageV2

az storage share-rm create \
  --name ocr-data \
  --storage-account $STORAGE \
  --resource-group $RG \
  --quota 100

STORAGE_KEY=$(az storage account keys list \
  --account-name $STORAGE \
  --resource-group $RG \
  --query "[0].value" -o tsv)

az containerapp env storage set \
  --name $ENV \
  --resource-group $RG \
  --storage-name ocrdata \
  --azure-file-account-name $STORAGE \
  --azure-file-account-key "$STORAGE_KEY" \
  --azure-file-share-name ocr-data \
  --access-mode ReadWrite

az containerapp update has no flag for Azure Files mounts, so the mount goes in YAML:

# mount.yaml
properties:
  template:
    containers:
      - name: paddleocr-api
        image: docker.io/edgaras0x4e/paddleocr-pdf-api:latest-text-baked
        resources:
          cpu: 4.0
          memory: 8.0Gi
        env:
          - name: API_KEY
            secretRef: api-key
        volumeMounts:
          - volumeName: ocr-data
            mountPath: /data
    volumes:
      - name: ocr-data
        storageName: ocrdata
        storageType: AzureFile
        mountOptions: "dir_mode=0777,file_mode=0777,uid=0,gid=0,mfsymlinks,nobrl"
    scale:
      minReplicas: 1
      maxReplicas: 1

az containerapp update --name $APP --resource-group $RG --yaml mount.yaml

nobrl is required. Azure Files is an SMB share, and SQLite locks the database with byte-range locks that the SMB client forwards to the server. Those locks fail on SMB, so without nobrl the app cannot open its database and the container does not start.

Locks handled locally are invisible to other clients of the share. That is one more reason maxReplicas stays at 1: two replicas writing the same database file would not see each other's locks.

A completed job survives a replica restart with this mount in place. A job that ran before the mount does not.

Conclusion

Container Apps runs the image without changes. The deployment is a resource group, an environment, and one az containerapp create. Job state that has to outlive a replica adds a storage account, a file share, and nobrl in the mount options.

OCR runs without open requests, so minReplicas: 0 can stop a job in progress, and maxReplicas stays at 1 as long as the database is SQLite.

Bicep template

One file deploys the same resources: the storage account, the share, the environment, the share registration, and the app with the mount.

// main.bicep
param location string = resourceGroup().location
@secure()
param apiKey string
param storageAccountName string = 'stpaddleocr${uniqueString(resourceGroup().id)}'

resource storage 'Microsoft.Storage/storageAccounts@2023-05-01' = {
  name: storageAccountName
  location: location
  sku: { name: 'Standard_LRS' }
  kind: 'StorageV2'
}

resource share 'Microsoft.Storage/storageAccounts/fileServices/shares@2023-05-01' = {
  name: '${storage.name}/default/ocr-data'
  properties: { shareQuota: 100 }
}

resource env 'Microsoft.App/managedEnvironments@2024-03-01' = {
  name: 'env-paddleocr'
  location: location
  properties: {
    workloadProfiles: [
      { name: 'Consumption', workloadProfileType: 'Consumption' }
    ]
  }
}

resource envStorage 'Microsoft.App/managedEnvironments/storages@2024-03-01' = {
  parent: env
  name: 'ocrdata'
  properties: {
    azureFile: {
      accountName: storage.name
      accountKey: storage.listKeys().keys[0].value
      shareName: 'ocr-data'
      accessMode: 'ReadWrite'
    }
  }
  dependsOn: [ share ]
}

resource app 'Microsoft.App/containerApps@2024-03-01' = {
  name: 'paddleocr-api'
  location: location
  properties: {
    managedEnvironmentId: env.id
    workloadProfileName: 'Consumption'
    configuration: {
      ingress: {
        external: true
        targetPort: 8000
      }
      secrets: [
        { name: 'api-key', value: apiKey }
      ]
    }
    template: {
      containers: [
        {
          name: 'paddleocr-api'
          image: 'docker.io/edgaras0x4e/paddleocr-pdf-api:latest-text-baked'
          resources: {
            cpu: json('4.0')
            memory: '8.0Gi'
          }
          env: [
            { name: 'API_KEY', secretRef: 'api-key' }
          ]
          volumeMounts: [
            { volumeName: 'ocr-data', mountPath: '/data' }
          ]
        }
      ]
      volumes: [
        {
          name: 'ocr-data'
          storageName: envStorage.name
          storageType: 'AzureFile'
          mountOptions: 'dir_mode=0777,file_mode=0777,uid=0,gid=0,mfsymlinks,nobrl'
        }
      ]
      scale: {
        minReplicas: 1
        maxReplicas: 1
      }
    }
  }
}

output fqdn string = app.properties.configuration.ingress.fqdn

az group create --name $RG --location $LOC

az deployment group create \
  --resource-group $RG \
  --template-file main.bicep \
  --parameters apiKey=$API_KEY

The deployment prints the app's hostname as the fqdn output.

UML Component Diagrams

Edgaras — Thu, 13 Aug 2026 19:05:51 +0000

A UML component diagram shows the units a software system is assembled from, the interfaces each unit provides, the interfaces it requires, and how those interfaces are wired together. UML 2.5.1 defines a component as a modular part of a system that encapsulates its contents and whose manifestation is replaceable within its environment.

A component diagram describes a system in larger pieces than a class diagram: each component groups several classes into one unit that can be replaced on its own, and hardware does not appear. Architects use it to define boundaries before implementation starts. Teams that own separate services use it to list the operations one service calls on another.

What is a UML Component Diagram?

A component diagram is a structural diagram. It shows:

Components: modular units whose internals are hidden and reachable only through their interfaces.
Provided interfaces: implemented by the component. Other components call them.
Required interfaces: called by the component but implemented elsewhere. The component cannot run until something supplies them.
Ports: named connection points on a component boundary that group provided and required interfaces.
Connectors: an assembly connector joins one component's required interface to another's provided interface. A delegation connector passes requests from the outer boundary to the part that handles them.
Realizing classifiers and artifacts: the classes that implement the component's behavior, and the files it is packaged into. Both can be listed inside the box.

A component can be as abstract as a billing unit in a design, or as concrete as a service you deploy and version on its own.

Why Use Component Diagrams?

Agree which operations two services provide to each other before either is written.
Make dependency direction explicit, so a cycle between two components is easy to see.
Decide which units can be versioned and released independently.

Core Components and Notation

Component

A component is drawn as a classifier rectangle with the keyword «component». A component icon may be placed in the right hand corner. When the icon is shown, the keyword may be hidden.

Provided Interface

A provided interface is a small circle on the end of a line from the component, labeled with the interface name. The symbol is called a lollipop or a ball. The component implements every operation that interface declares.

Required Interface

A required interface is a half circle on the end of a line from the component, labeled with the interface name. The symbol is called a socket. The component calls those operations but does not implement them, so something else has to supply them.

Assembly Connector

When one component requires an interface that another provides, draw the socket touching the ball. UML calls this an assembly connector.

Ball-and-socket only wires ports that carry exactly one interface. If a port carries several, or the parts have no ports, draw a plain connector line instead.

Port

A port is drawn as a small square on the component boundary, or inside it. The name is placed near the square, the type after a colon. Lollipops and sockets attach to the port rather than to the component body. A port can carry more than one interface. Instead of drawing a separate lollipop for each, draw one and list the names on it: IPlayback, IDownload. A port with several interfaces still cannot be wired with ball-and-socket, so its connections use plain lines.

Delegation Connector

A component can show the parts it is built from. A delegation connector is a line from a port on the component's own boundary to a port on one of those parts. Requests arriving from outside are handled by that part.

There is no special arrowhead or label. What makes the line a delegation is where it attaches: one end is on the component's own boundary. If both ends attach to inner parts, the same line is an assembly connector.

Ball and socket symbols carry only the interface name. When operation signatures matter, draw the interface as a classifier rectangle with the keyword «interface» and connect it with dependency arrows. A provided interface uses an InterfaceRealization: a dashed line with a hollow triangle arrowhead. A required interface uses a Usage dependency: a dashed line with an open arrowhead and the keyword «use».

Standard Stereotypes for Components

From the UML 2.5.1 standard profile:

Stereotype	Applies to	Meaning
`«Subsystem»`	Component	A unit of hierarchical decomposition for large systems
`«Service»`	Component	A stateless, functional component
`«Specification»`	Classifier	A component with interfaces only, and no realizing classifiers
`«Realization»`	Classifier	A component whose realizing classifiers implement a separate `«Specification»`

Practical Example: Video Streaming Platform

The diagram below models the main components of a video streaming platform.

The relationships it shows:

WebClient requires IStreamCatalog and IPlayback. It provides nothing, so it carries only sockets.
CatalogService provides IStreamCatalog, which returns title listings and search results.
CatalogService requires IMediaMetadata from MediaStore to read durations, resolutions, and cover art.
PlaybackService provides IPlayback, and requires ILicense from LicenseService to check playback rights before a stream starts.
PlaybackService also requires IMediaStorage from MediaStore to read video segments.
MediaStore provides two separate interfaces, so CatalogService gets metadata access without the ability to read video segments.

LicenseService and MediaStore require nothing, so each can be tested alone. PlaybackService needs two test doubles.

Best Practices

Name the interface, not the connection: ILicense states what crosses the boundary. A line labeled "calls license service" does not.
Split interfaces by responsibility: one interface per concern lets a consumer depend on only the part it uses, as MediaStore does above.
Add ports when a component has many interfaces: named groups keep the boundary readable.
Keep internal structure on its own diagram: the external view answers what a component needs. Draw parts and delegation connectors separately.
Match component boundaries to units you can release: if two components always ship together, the boundary between them is not doing any work.

Conclusion

A component diagram shows the pieces of a system and what each one needs from the others. Two teams can use it to settle an interface list before either writes code. It also shows which pieces are independent enough to release on their own.

It records no timing. The diagram states that PlaybackService requires ILicense, but not whether the license check runs before the first byte of video or halfway through. Order belongs on a sequence diagram. For where each component actually runs, use a deployment diagram.

A Self-Hosted Web Content Extraction API

Edgaras — Wed, 20 May 2026 09:59:37 +0000

Getting clean content out of a web page is harder than it looks, especially at scale. Every site is put together differently, so a scraper that works on one page falls apart on the next, and the part you actually care about is buried in menus, ads, cookie banners, and scripts. You can feed the whole page to an LLM and let it pull the content out, or pay for an extraction API, but both get expensive once you are handling more than a handful of pages. Many sites also render their content with JavaScript, so a plain HTTP fetch returns almost nothing to begin with.

The Web Loader Engine is a web content extraction service built in Rust that handles this. It loads each page in a headless Chromium browser and runs it through Mozilla Readability, so you get the actual content without the clutter around it. It can return Markdown, HTML, plain text, or a screenshot, all through a HTTP API call. Useful for RAG pipelines, scraping, archiving pages, and screenshots.

Quick start

Pull and run the prebuilt image:

docker run -d -p 14786:14786 --name web-loader \
  edgaras0x4e/web-loader-engine:latest

Check that it is up:

curl http://localhost:14786/health

That is the whole setup. No headless browser to install, no driver to wire up.

Your first extraction

Send a URL to /load and get structured content back:

curl -X POST http://localhost:14786/load \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Response:

{
  "url": "https://example.com",
  "title": "Example Domain",
  "content": "Title: Example Domain\nURL Source: https://example.com\n\n---\n\nThis domain is for use in documentation examples without needing permission. Avoid use in operations.\n\n[Learn more](https://iana.org/domains/example)",
  "metadata": {
    "processing_time_ms": 4,
    "cached": false
  }
}

The content field is ready to chunk and embed. The metadata tells you how long it took and whether the response came from cache.

Pick your output format

The same endpoint returns different formats based on the x-respond-with header. Accepted values are markdown, html, text, screenshot, and pageshot.

# Plain text, no markup
curl -X POST http://localhost:14786/load \
  -H "Content-Type: application/json" \
  -H "x-respond-with: text" \
  -d '{"url": "https://example.com"}'

Markdown is the default and is usually what you want for LLM input. Plain text is handy for keyword indexing, and HTML keeps structure when you need it.

Screenshots

For visual snapshots, ask for a screenshot (viewport) or pageshot (full page):

curl -X POST http://localhost:14786/load \
  -H "Content-Type: application/json" \
  -H "x-respond-with: screenshot" \
  -d '{"url": "https://example.com"}'

The engine renders the page, saves a PNG to SCREENSHOT_DIR, and returns a URL you can fetch from the same server:

{
  "url": "https://example.com",
  "title": null,
  "content": "",
  "screenshot_url": "/screenshots/httpsexamplecom_6eb6a747-ba80-47bf-91c5-2767aae1c5d0.png",
  "metadata": { "processing_time_ms": 1064, "cached": false }
}

Precision extraction

x-wait-for-selector waits for a CSS selector before extracting, so dynamic content has time to load.
x-target-selector extracts only a specific region of the page.
x-remove-selector strips elements you do not want, such as ads or footers.
x-with-links-summary and x-with-images-summary add a summary of links or images found on the page.
x-set-cookie and x-user-agent let you control the request, with rotate available for automatic user agent rotation.
x-no-cache: true forces a fresh fetch, bypassing the cache. Useful when you change selectors, since cached responses are returned as-is.

curl -X POST http://localhost:14786/load \
  -H "Content-Type: application/json" \
  -H "x-no-cache: true" \
  -H "x-wait-for-selector: h1" \
  -H "x-target-selector: div" \
  -H "x-remove-selector: a" \
  -d '{"url": "https://example.com"}'

Process URLs in batch

For crawling or bulk indexing, send many URLs at once to /load/batch and let the browser pool handle them concurrently:

curl -X POST http://localhost:14786/load/batch \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com/1", "https://example.com/2"]}'

{
  "results": [
    {
      "url": "https://example.com/1",
      "response": {
        "url": "https://example.com/1",
        "title": "Page Title",
        "content": "...",
        "metadata": { "processing_time_ms": 500, "cached": false }
      }
    }
  ],
  "total_processing_time_ms": 1234
}

The URLs are fetched in parallel rather than one after another, so a batch is much faster than looping. Four pages that each take about two seconds came back in roughly 4.4 seconds together, against about 18 seconds when fetched one at a time.

User agent rotation

Some sites get cranky when every request shows up with the same user agent. The engine can rotate through a pool of them for you. You set the strategy and the pool with environment variables, where USER_AGENT_ROTATION is off, round_robin, or random:

environment:
  - USER_AGENT_ROTATION=round_robin
  - USER_AGENT_POOL=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36|Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36|Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36
  - DEFAULT_USER_AGENT=Mozilla/5.0 (compatible; web-loader)

With round_robin each request moves to the next entry in the pool. You can also decide per request with the x-user-agent header: pass a string to use it as-is, rotate to force rotation even when the strategy is off, or default to skip rotation for that one call.

curl -X POST http://localhost:14786/load \
  -H "Content-Type: application/json" \
  -H "x-user-agent: rotate" \
  -d '{"url": "https://example.com"}'

Browser pool resilience

Rendering runs through a pool of headless Chromium pages, sized by BROWSER_POOL_SIZE (default 10). That pool is what lets batches run in parallel, and it is also the part most likely to break, since browsers crash. The engine checks each browser and recreates any that die or drop their connection, and a request retries a few times instead of failing on the first hiccup. You can kill every browser in the container and the next request still comes back fine, with the pool rebuilt behind it.

The /health endpoint shows the current state:

curl http://localhost:14786/health

{
  "status": "ok",
  "version": "0.1.4",
  "browser_pool": { "available": 10, "total": 10, "healthy": true, "recreation_count": 2 }
}

recreation_count goes up each time a dead browser is replaced, so it is worth keeping an eye on for a long-running deployment.

Built-in features

Beyond extraction, the engine ships with the parts you would otherwise build yourself:

Caching with a configurable TTL, so repeated URLs come back from cache instead of being fetched again.
Per-domain rate limiting and circuit breakers, so a slow or failing host does not take down your pipeline.
SSRF protection that blocks internal IP ranges, important when you accept URLs from users.
Proxy support that honors HTTP_PROXY, HTTPS_PROXY, and NO_PROXY, including Chromium egress routing.

Configuration

Everything is driven by environment variables. The defaults are sensible, and you only override what you need:

Variable	Default	Purpose
`API_PORT`	14786	Server port
`API_KEY`	(none)	Optional bearer-token auth
`BROWSER_POOL_SIZE`	10	Concurrent browser instances
`REQUEST_TIMEOUT`	30	Timeout in seconds
`CACHE_TTL`	3600	Cache lifetime in seconds
`SCREENSHOT_DIR`	/app/screenshots	Screenshot storage

A typical Compose setup:

services:
  web-loader:
    image: edgaras0x4e/web-loader-engine:latest
    ports:
      - "14786:14786"
    environment:
      - BROWSER_POOL_SIZE=10
      - CACHE_TTL=3600
    volumes:
      - screenshots:/app/screenshots
    restart: unless-stopped

volumes:
  screenshots:

Bottom line

The point is that one service takes you from a URL to clean content. Rendering, output formats, caching, rate limiting, security, batch fetching, user agent rotation, and a browser pool that recovers on its own are all part of it, so you are not stitching together a browser driver, a parser, and a cache by hand. It runs as a single container that you point at a URL to get back something you can actually use.

Try it:

docker run -d -p 14786:14786 edgaras0x4e/web-loader-engine:latest

GitHub: https://github.com/Edgaras0x4E/web-loader-engine
Docker Hub: https://hub.docker.com/r/edgaras0x4e/web-loader-engine

UML Deployment Diagrams

Edgaras — Thu, 09 Apr 2026 12:52:02 +0000

When designing complex software systems, understanding how your application components map to physical infrastructure is crucial. UML Deployment Diagrams provide a clear visual representation of how software artifacts are distributed across hardware and execution environments, making them essential for system architects, DevOps engineers, and development teams planning production deployments.

What is a UML Deployment Diagram?

A Deployment Diagram is a structural UML diagram that models the physical deployment of software artifacts onto hardware nodes and execution environments. It shows:

Hardware topology - The physical devices and servers that make up your infrastructure
Software placement - Which applications, libraries, and files run on which hardware
Network architecture - How different nodes communicate with each other
Execution environments - Runtime platforms like operating systems, containers, or virtual machines
Deployment configurations - How artifacts are configured and deployed in different environments

Why Use Deployment Diagrams?

Deployment diagrams are particularly valuable for:

Infrastructure planning - Design and document server topology before implementation
Cloud architecture - Model AWS, Azure, or GCP deployments with proper resource allocation
DevOps workflows - Communicate deployment strategies between development and operations teams
System documentation - Provide clear reference for how production systems are configured
Environment comparison - Visualize differences between development, staging, and production setups
Capacity planning - Identify hardware requirements and potential bottlenecks
Troubleshooting - Understand system architecture when diagnosing deployment issues

Core Components and Notation

Nodes

A Node is the fundamental building block of deployment diagrams, representing a computational resource where artifacts can be deployed. Nodes are drawn as 3D boxes (cubes) to distinguish them from other UML elements.

There are two primary types of nodes:

Device Nodes - Physical hardware resources marked with the «device» stereotype:

Servers, workstations, mobile devices, embedded systems
Any physical computing resource that can execute software
Examples: «server» Web Server, «mobile» iPhone, «pc» Developer Workstation

Execution Environment Nodes - Software platforms that provide runtime services, marked with the «executionEnvironment» stereotype:

Operating systems (Linux, Windows)
Runtime platforms (JVM, .NET Runtime, Node.js)
Containerization platforms (Docker, Kubernetes)
Application servers (Tomcat, nginx)

Execution environments are typically shown nested inside device nodes to represent the "runs on" relationship.

Artifacts

An Artifact represents a physical, deployable file or component in your system. Artifacts are drawn as rectangles labeled with the «artifact» stereotype. Optionally, a small document icon can be added in the upper-right corner for visual clarity.

Common artifact types include:

«executable» - Runnable programs (app.jar, server.exe, main.py)
«library» - Shared libraries (commons-lang.jar, libssl.so, react.dll)
«file» - Configuration or data files (config.yaml, application.properties)
«script» - Executable scripts (deploy.sh, Dockerfile, setup.py)
«document» - Documentation files (api-spec.pdf, README.md)
«source» - Source code files (Main.java, app.ts)

Artifacts are deployed to nodes using either:

Containment - Drawing the artifact inside the node box (implicit deployment)
Deploy dependency - A dashed arrow with «deploy» stereotype from artifact to node

Communication Paths

Communication Paths represent network connections between nodes, shown as solid lines connecting node boxes. They indicate that nodes can exchange information.

Communication paths can be labeled with:

Protocol information - Using stereotypes like «HTTP», «HTTPS», «TCP», «gRPC», «AMQP»
Port numbers - Showing which ports are used for communication
Connection names - Descriptive labels for the communication channel
Multiplicity - Numbers indicating how many connections exist

Example: A line labeled «HTTPS» port 443 connecting a Load Balancer to a Web Server.

Node Instances

While nodes represent types of computational resources, Node Instances represent specific running instances. The entire name (both instance name and type) is underlined in the format instanceName : NodeType.

Example: webServer01 : Ubuntu Server or prod-db-primary : PostgreSQL

The underline distinguishes instances (actual running systems) from node types (abstract architectural components).

Practical Example: Cloud Web Application

Let's model a typical web application deployed on AWS cloud infrastructure:

Infrastructure Components:

CloudFront CDN for content delivery
Application Load Balancer for traffic distribution
ECS (Elastic Container Service) for container orchestration
Two Docker containers: one for the web app, one for the API service
RDS PostgreSQL for relational data
S3 bucket for static assets (images, documents)

Key deployment relationships shown:

webapp.jar artifact deployed to web-container execution environment
api.jar artifact deployed to api-container execution environment
schema.sql artifact deployed to PostgreSQL database
static-assets/ deployed to S3 bucket
Communication paths showing HTTPS, HTTP, gRPC, and TCP connections with appropriate port numbers

Enterprise On-Premises Deployment

Traditional on-premises deployments can also be effectively modeled with deployment diagrams, showing physical hardware and network topology.

Scenario: Enterprise web application in a corporate data center

Infrastructure Components:

Hardware load balancer appliance for traffic distribution
Three web server machines running Apache
Two application server machines running JBoss
Primary and replica database servers
File server for shared storage
Network segmentation with DMZ and internal network

Node instances shown:

loadBalancer01 : F5 Load Balancer - Hardware load balancer in DMZ
webServer01, webServer02, webServer03 : Linux Server - Web tier servers in DMZ
appServer01, appServer02 : Linux Server - Application tier servers in internal network
dbPrimary : Oracle Server - Primary database server
dbReplica : Oracle Server - Read replica for reporting
fileServer01 : Windows Server - Shared file storage

This diagram clearly shows:

Physical server instances with specific names
Execution environments (Linux, JBoss, Apache, Oracle) nested within hardware
Network boundaries separating DMZ from internal network
Multiple instances for high availability
Communication paths with protocols and ports
Artifacts deployed to each tier

Best Practices

When creating deployment diagrams, follow these guidelines:

Start with the big picture - Begin with major nodes and communication paths, then add detail
Use appropriate stereotypes - Leverage standard UML stereotypes («device», «executionEnvironment») and create custom ones for cloud services when needed
Show execution environment hierarchies - Nest execution environments inside devices to show the full stack (e.g., Docker inside Linux inside AWS EC2)
Label communication paths clearly - Always indicate protocols and ports for network connections
Keep diagrams focused - Create separate diagrams for different environments (dev, staging, production) or architectural layers rather than cramming everything into one
Document artifact versions - When relevant, include version numbers with artifacts (api-v2.3.jar)
Indicate multiplicity - Show how many instances of nodes exist (e.g., 3 web servers behind a load balancer)
Use consistent naming - Follow naming conventions that match your actual infrastructure
Show dependencies clearly - Use deployment specifications to document configuration requirements
Update regularly - Keep deployment diagrams synchronized with actual infrastructure changes

Conclusion

UML Deployment Diagrams are indispensable for documenting and communicating how software systems are physically deployed across infrastructure. Whether you're planning a cloud migration, documenting microservices architecture, or troubleshooting production issues, deployment diagrams provide the clarity needed to understand the relationship between your software artifacts and the hardware they run on.

Using a Self-Hosted PDF OCR API with PaddleOCR

Edgaras — Sun, 22 Mar 2026 15:26:59 +0000

The problem

If you need to extract text from PDFs - especially large ones with 100+ pages - and don't want to pay for cloud OCR services or use LLM APIs on it, PaddleOCR can handle it locally on your own GPU.

paddleocr-pdf-api is an open-source Docker image that wraps PaddleOCR's vision-language model into a REST API. It runs on your GPU and lets you fetch results page-by-page as they're processed, without waiting for the entire document to finish.

When this is useful

Processing large volumes of PDFs - submit documents via API and process them one by one through a job queue
Sensitive documents that can't leave your network - everything runs locally, no external API calls
Large documents (100+ pages) - results stream page-by-page, so you can start consuming output before the full document is done
Integrating OCR into a pipeline - simple REST API that any language/tool can call
Less common languages - handles languages that many OCR tools struggle with

What's under the hood

Model: PaddleOCR-VL-1.5 (0.9B parameters)
GPU VRAM: ~8.5 GB
Output: Markdown (headings, tables, paragraphs) via JSON
Storage: SQLite + filesystem, persisted via Docker volume
Stack: FastAPI, PaddlePaddle GPU, pypdfium2 - single Python file

Setup

Requirements: Docker with NVIDIA Container Toolkit and a GPU with ~8.5 GB VRAM.

Create a docker-compose.yml:

services:
  paddleocr:
    image: edgaras0x4e/paddleocr-pdf-api:latest
    ports:
      - "8099:8000"
    volumes:
      - ocr-data:/data
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    restart: unless-stopped

volumes:
  ocr-data:

docker compose up -d

Usage

Submit a PDF

curl -X POST http://localhost:8099/ocr -F "file=@document.pdf"

{
  "job_id": "994e7b398bb44d8ab5eade4d2ef57a15",
  "filename": "document.pdf",
  "status": "queued"
}

Poll progress

curl http://localhost:8099/ocr/994e7b398bb44d8ab5eade4d2ef57a15

{
  "job_id": "994e7b398bb44d8ab5eade4d2ef57a15",
  "status": "processing",
  "total_pages": 185,
  "processed_pages": 42
}

Fetch a single page (as soon as it's ready)

No need to wait for the entire document:

curl http://localhost:8099/ocr/994e7b398bb44d8ab5eade4d2ef57a15/pages/1

{
  "page_num": 1,
  "markdown": "## Chapter 1\n\nLorem ipsum dolor sit amet..."
}

Fetch all pages

curl http://localhost:8099/ocr/994e7b398bb44d8ab5eade4d2ef57a15/result

Returns the full document with a pages array containing each page's markdown.

List jobs, cancel, delete

# List all jobs
curl http://localhost:8099/jobs

# Cancel a running job
curl -X POST http://localhost:8099/ocr/{job_id}/cancel

# Delete a job and its data
curl -X DELETE http://localhost:8099/ocr/{job_id}

Full API reference

Method	Endpoint	Description
`POST`	`/ocr`	Upload a PDF
`GET`	`/ocr/{job_id}`	Job status and progress
`GET`	`/ocr/{job_id}/pages/{page_num}`	Single page result
`GET`	`/ocr/{job_id}/result`	All pages
`POST`	`/ocr/{job_id}/cancel`	Cancel a job
`DELETE`	`/ocr/{job_id}`	Delete job and its data
`GET`	`/jobs`	List all jobs

API key authentication

To restrict access, set the API_KEY environment variable:

environment:
  - API_KEY=your-secret-key

All requests then require the header:

curl -H "X-API-Key: your-secret-key" http://localhost:8099/jobs

Configuration

Variable	Default	Description
`API_KEY`	(empty)	Optional authentication key
`OCR_DPI`	`200`	DPI for PDF page rendering (higher = better quality, slower)
`DB_PATH`	`/data/ocr.db`	SQLite database path
`UPLOAD_DIR`	`/data/uploads`	Upload storage path

Example: integrating into a Python script

A minimal example that submits a PDF and waits for results:

import requests
import time

API = "http://localhost:8099"

# Submit
resp = requests.post(f"{API}/ocr", files={"file": open("scan.pdf", "rb")})
job_id = resp.json()["job_id"]

# Poll until done
while True:
    status = requests.get(f"{API}/ocr/{job_id}").json()
    if status["status"] == "completed":
        break
    if status["status"] == "failed":
        raise Exception(status["error"])
    print(f"{status['processed_pages']}/{status['total_pages']} pages done")
    time.sleep(5)

# Get results
result = requests.get(f"{API}/ocr/{job_id}/result").json()
for page in result["pages"]:
    print(f"--- Page {page['page_num']} ---")
    print(page["markdown"])

How it works

PDF is uploaded and saved to disk
A background worker picks up queued jobs sequentially
Each page is rendered to an image using pypdfium2
PaddleOCR-VL extracts text and converts it to markdown
HTML artifacts and image placeholders are cleaned from the output
Results are stored in SQLite and available per-page as they complete
Jobs interrupted by a container restart are automatically re-queued

Source: github.com/Edgaras0x4E/paddleocr-pdf-api
Docker image: hub.docker.com/r/edgaras0x4e/paddleocr-pdf-api

A Developer's Guide to Useful Apache Modules

Edgaras — Tue, 04 Nov 2025 04:45:16 +0000

Apache is one of the most widely used web servers, and its real power comes from its modular design.

Below is a practical, example-based guide to Apache modules that are useful in real-world web development.

How to Enable/Disable Modules

# Enable a module
sudo a2enmod module_name

# Disable a module
sudo a2dismod module_name

# Restart Apache
sudo systemctl restart apache2

`mod_rewrite` - URL Routing & Clean URLs

<VirtualHost *:80>
    ServerName example.com

    RewriteEngine On
    RewriteRule ^user/([0-9]+)/?$ /profile.php?id=$1 [L,QSA]
</VirtualHost>

Used for clean URLs, routing logic, SEO-friendly paths, and framework rewrites.

`mod_ssl` - HTTPS Support

<VirtualHost *:443>
    ServerName example.com

    SSLEngine On
    SSLCertificateFile /etc/ssl/certs/example.crt
    SSLCertificateKeyFile /etc/ssl/private/example.key
</VirtualHost>

Enables TLS/SSL so the site can run securely over HTTPS.

`mod_headers` - Security & Cache Headers

<IfModule mod_headers.c>
    Header always set X-Frame-Options "DENY"
    Header always set X-Content-Type-Options "nosniff"
    Header always set Referrer-Policy "no-referrer"
</IfModule>

Allows setting and modifying HTTP response headers for security and performance.

`mod_expires` - Browser Cache Control

<IfModule mod_expires.c>
    ExpiresActive On
    ExpiresByType text/css "access plus 7 days"
    ExpiresByType image/png "access plus 1 year"
    ExpiresDefault "access plus 1 hour"
</IfModule>

Adds automatic expiration headers so browsers can cache static files.

`mod_proxy` and `mod_proxy_http` - Reverse Proxy to Apps

<VirtualHost *:80>
    ServerName api.example.com

    ProxyPass / http://127.0.0.1:4000/
    ProxyPassReverse / http://127.0.0.1:4000/
</VirtualHost>

Forwards requests to backend services like Node, Python, Docker, or another server.

`mod_security` - Web Application Firewall

SecRuleEngine On
Include /usr/share/modsecurity-crs/*.conf

Blocks common attacks such as SQL injection, XSS, and RCE using rule sets.

`mod_status` - Live Server Status Page

<Location "/server-status">
    SetHandler server-status
    Require ip 127.0.0.1
</Location>

Displays live Apache metrics: active connections, workers, load, uptime.

`mod_auth_basic` and `mod_authn_file` - Simple Password Protection

<Location "/admin">
    AuthType Basic
    AuthName "Restricted"
    AuthUserFile /etc/apache2/.htpasswd
    Require valid-user
</Location>

Adds quick HTTP basic authentication without touching application code.

`mod_evasive` - Auto-Blocking for DDoS / Brute Force

<IfModule mod_evasive20.c>
    DOSHashTableSize 2048
    DOSPageCount 5
    DOSPageInterval 1
    DOSBlockingPeriod 30
    DOSEmailNotify admin@example.com
</IfModule>

Detects repeated requests and temporarily blocks abusive traffic automatically.

Additional Useful Modules

`mod_deflate` or `mod_brotli` - Response Compression

<IfModule mod_deflate.c>
    AddOutputFilterByType DEFLATE text/html text/css application/json
</IfModule>

<IfModule mod_brotli.c>
    BrotliCompressionQuality 6
    AddOutputFilterByType BROTLI_COMPRESS text/html text/css application/javascript
</IfModule>

Compresses responses to reduce bandwidth and speed up page loads.

`mod_pagespeed` - Auto Performance Optimizer

ModPagespeed on
ModPagespeedEnableFilters rewrite_css,sprite_images,collapse_whitespace

Automatically optimizes assets: minifies, inlines, rewrites, lazyloads, etc.

`mod_geoip` / `mod_maxminddb` - Geo-Based Rules

<IfModule mod_maxminddb.c>
    MaxMindDBFile COUNTRY_DB /usr/share/GeoIP/GeoLite2-Country.mmdb
    MaxMindDBEnv GEOIP_COUNTRY_CODE COUNTRY_DB/country/iso_code
</IfModule>

<Location />
    Require all granted
    Require not env GEOIP_COUNTRY_CODE=CN
</Location>

Allows country-based routing, blocking, redirects, or localization.

Summary

Module	Purpose / Use Case
`mod_rewrite`	URL routing, clean URLs, SEO-friendly rewrites
`mod_ssl`	Enables HTTPS/TLS encryption
`mod_headers`	Sets custom security and cache headers
`mod_expires`	Controls browser caching for static files
`mod_proxy`	Reverse proxy to backend apps/services
`mod_security`	Web Application Firewall (WAF)
`mod_status`	Live server metrics/status page
`mod_auth_basic`	Simple HTTP basic authentication
`mod_evasive`	Auto-blocking for DDoS / brute force requests
`mod_deflate` / `brotli`	Response compression for faster load times
`mod_pagespeed`	Automatic asset optimization (minify, inline etc.)
`mod_geoip` / `maxminddb`	Geo-based routing, blocking, or localization

Ethereum Integration in PHP for Wallets and Transfers

Edgaras — Mon, 06 Oct 2025 18:38:04 +0000

If you build backends in PHP and want to talk to Ethereum without pulling in a full Node stack, this library gives you a clean methods for the main functionality: wallet management, ETH transfers (legacy and EIP‑1559), balances, transaction queries, and utilities.

GitHub: Edgaras0x4E/Ethereum

What you can do

Wallets: Create/import wallets, derive address/public key
Transfers: Send ETH using legacy (Type‑0) and EIP‑1559 (Type‑2) transactions; wait for confirmations
Balances & network: getBalance, getBalanceInEther, getBlockNumber, getNetworkInfo
Transactions: getTransaction, getTransactionReceipt, getTransactionStatus, getTransactionDetails
Address activity: Scan recent blocks with getTransactionsForAddress
Blocks: Fetch transactions with getTransactionsByBlockNumber
Utilities: Unit conversion, checksum addresses, hex helpers, hashing

Requirements

PHP 8.3+
Extensions: gmp, bcmath
An Ethereum JSON‑RPC endpoint (Infura)

Install

composer require edgaras/ethereum

Quick start: create a wallet and read balance

<?php

use Edgaras\Ethereum\Ethereum;
use Edgaras\Ethereum\Wallet;

$rpcUrl = 'https://sepolia.infura.io/v3/YOUR_API_KEY';
$chainId = 11155111; // Sepolia

$eth = new Ethereum($rpcUrl, $chainId);

// Create a new wallet (or import with new Wallet('0xPRIVATE_KEY_HEX'))
$wallet = $eth->createWallet();
$eth->setWallet($wallet);

echo "Address: {$wallet->getAddress()}\n";
echo "Balance: {$eth->getBalanceInEther()} ETH\n";

Send ETH (legacy Type‑0)

use Edgaras\Ethereum\Ethereum;
use Edgaras\Ethereum\Wallet;

$eth = new Ethereum($rpcUrl, $chainId);
$eth->setWallet(new Wallet('0xYOUR_PRIVATE_KEY_HEX'));

$txHash = $eth->sendEther('0xRecipientAddress...', '0.01');
echo "tx: $txHash\n";

// Optional: wait for confirmation
$receipt = $eth->waitForConfirmation($txHash, maxAttempts: 60, delaySeconds: 2);
echo "included in block: {$receipt['blockNumber']}\n";

Send ETH with EIP‑1559 (Type‑2)

use Edgaras\Ethereum\Ethereum;
use Edgaras\Ethereum\Wallet;
use Edgaras\Ethereum\Utils;

$eth = new Ethereum($rpcUrl, $chainId);
$eth->setWallet(new Wallet('0xYOUR_PRIVATE_KEY_HEX'));

// Set EIP‑1559 gas parameters (in gwei)
$maxPriorityFeePerGasGwei = '2';  // 2 gwei tip
$maxFeePerGasGwei = '20';         // 20 gwei max fee

// Convert to wei hex
$maxPriorityFeePerGas = Utils::toHex(Utils::gweiToWei($maxPriorityFeePerGasGwei));
$maxFeePerGas = Utils::toHex(Utils::gweiToWei($maxFeePerGasGwei));

$txHash = $eth->sendEtherEIP1559(
    '0xRecipientAddress...',
    '0.01',
    $maxFeePerGas,
    $maxPriorityFeePerGas
);
echo "EIP‑1559 tx: $txHash\n";

Practical examples

Minimal wallet overview (balance + recent txs):

use Edgaras\Ethereum\Ethereum;
use Edgaras\Ethereum\Utils;

$eth = new Ethereum($rpcUrl, $chainId);
$address = '0xRecipientAddress...';

$balanceEth = $eth->getBalanceInEther($address);
echo "Address: " . Utils::toChecksumAddress($address) . "\n";
echo "Balance: $balanceEth ETH\n\n";

$txs = $eth->getTransactionsForAddress($address, maxBlocksToScan: 1500, maxTxToShow: 20);
foreach ($txs as $t) {
    echo sprintf("[%s] %s | %s ETH | peer: %s | block: %d\n",
        $t['direction'], $t['hash'], $t['valueEth'], $t['peer'], $t['blockNumber']
    );
}

List transactions in a block:

use Edgaras\Ethereum\Ethereum;

$eth = new Ethereum($rpcUrl, $chainId);
$blockNumber = 9354804; // example
$txs = $eth->getTransactionsByBlockNumber($blockNumber, limit: 10);

foreach ($txs as $i => $tx) {
    $idx = $i + 1;
    echo "#$idx\n";
    echo "  hash:  " . ($tx['hash'] ?? '') . "\n";
    echo "  from:  " . ($tx['from'] ?? '') . "\n";
    echo "  to:    " . ($tx['to'] ?? '') . "\n";
    echo "  value: " . ($tx['value'] ?? '0x0') . " (wei hex)\n\n";
}

Utilities you’ll actually use

use Edgaras\Ethereum\Utils;

// Unit conversion
$wei = Utils::etherToWei('1.5');
$eth = Utils::weiToEther('0x204fce5e3e250261100000000'); // hex or decimals
$gwei = Utils::weiToGwei('0x4a817c800');

// Address helpers
$isValid = Utils::isValidAddress('0x242d35Cc6634C0532925a3b8D4C9db96C4b4d8b6');
$checksum = Utils::toChecksumAddress('0x242d35cc6634c0532925a3b8d4c9db96c4b4d8b6');

// Hex helpers
$hex = Utils::toHex('255'); // 0xff
$dec = Utils::fromHex('0xff'); // 255

EIP‑1559 in practice (why it matters)

Better fee predictability and reduced overpayment when the network is quiet
Dynamic fee market: you set a max fee and a priority tip; the base fee adjusts
Typed transactions: EIP‑2718 with proper hashing (0x02 || RLP(list)) for sender recovery

Pick EIP‑1559 for modern fee markets; fall back to legacy for maximum compatibility.

Production tips

Keep your private keys out of source control; inject via env/config vaults
Monitor base fee and adjust maxFeePerGas/maxPriorityFeePerGas dynamically
Wrap RPC errors and rate limits; the library exposes clear exceptions
Use waitForConfirmation with sensible timeouts and backoff in worker jobs

Laravel Project Backup to Azure Blob with Bash Script

Edgaras — Mon, 25 Aug 2025 22:13:48 +0000

If you’re running a Laravel app and want an easy way to back it up to Azure Blob Storage without Docker images or third-party SaaS tools, here’s a self-contained Bash script that does exactly that.

It backs up:

Your Laravel project files (with exclusions like vendor/ and logs)
Your MySQL database (via mysqldump)
Packages everything into a .tar.gz
Uploads to Azure Blob Storage using az CLI
Cleans up local backups older than X days

Requirements

bash, tar, gzip, find
mysqldump (MySQL/MariaDB client)
Azure CLI

The Script

#!/usr/bin/env bash
set -Eeuo pipefail


# ---- Paths ----
LARAVEL_DIR="/path/to/laravel/project" # Path to your Laravel project root
BACKUP_DIR="/path/to/local/backup/directory" # Local backup directory  

# ---- Azure Storage (account + key) ----
AZURE_STORAGE_ACCOUNT="<ACCOUNT_NAME>"
AZURE_STORAGE_KEY="<ACCOUNT-KEY>"
AZURE_CONTAINER="<CONTAINER-NAME>"

# ---- Retention (local only) ----
RETAIN_LOCAL_DAYS=7

# ---- Backup content exclusion ----
EXCLUDES=(
  "vendor"
  "node_modules"
  "storage/framework/cache"
  "storage/logs"
  ".git"
)

#############################################

timestamp_utc() { date -u +"%Y%m%dT%H%M%SZ"; }

require_cmd() {
  command -v "$1" >/dev/null 2>&1 || { echo "ERROR: Missing required command: $1" >&2; exit 1; }
}

read_env_var() {
  local key="$1"
  local val=""
  if [[ -f "$LARAVEL_DIR/.env" ]]; then
    val="$(grep -E "^${key}=" "$LARAVEL_DIR/.env" 2>/dev/null | tail -n1 | sed -E "s/^${key}=(.*)$/\1/" | tr -d '\r' || true)"
  fi
  if [[ -n "$val" && "${val:0:1}" == '"' && "${val: -1}" == '"' ]]; then
    val="${val:1:-1}"
  elif [[ -n "$val" && "${val:0:1}" == "'" && "${val: -1}" == "'" ]]; then
    val="${val:1:-1}"
  fi
  echo "$val"
}

dump_mysql() {
  local db_host db_port db_name db_user db_pass db_socket dump_path
  db_host="$(read_env_var "DB_HOST")"
  db_port="$(read_env_var "DB_PORT")"
  db_name="$(read_env_var "DB_DATABASE")"
  db_user="$(read_env_var "DB_USERNAME")"
  db_pass="$(read_env_var "DB_PASSWORD")"
  db_socket="$(read_env_var "DB_SOCKET")"
  dump_path="$1"

  require_cmd mysqldump

  db_host="${db_host:-127.0.0.1}"
  db_port="${db_port:-3306}"

  local args=( --user="$db_user" --single-transaction --quick --routines --events --triggers )
  if [[ -n "$db_socket" ]]; then
    args+=( --socket="$db_socket" )
  else
    args+=( --host="$db_host" --port="$db_port" )
  fi

  umask 077
  MYSQL_PWD="$db_pass" mysqldump "${args[@]}" "$db_name" > "$dump_path"
}

make_archive() {
  local src_dir="$1"
  local db_sql="$2"
  local out_tar_gz="$3"

  local stage
  stage="$(mktemp -d)"
  trap 'rm -rf "$stage"' RETURN

  mkdir -p "$stage/site" "$stage/db"

  pushd "$src_dir" >/dev/null
  local tar_excludes=()
  for e in "${EXCLUDES[@]}"; do
    tar_excludes+=( "--exclude=$e" )
  done
  tar -cf - "${tar_excludes[@]}" . | tar -C "$stage/site" -xf -
  popd >/dev/null

  cp "$db_sql" "$stage/db/database.sql"

  tar -C "$stage" -czf "$out_tar_gz" site db
}

upload_with_azcli() {
  local file="$1"
  AZURE_STORAGE_ACCOUNT="$AZURE_STORAGE_ACCOUNT" AZURE_STORAGE_KEY="$AZURE_STORAGE_KEY" \
    az storage blob upload \
      --container-name "$AZURE_CONTAINER" \
      --file "$file" \
      --name "$(basename "$file")" \
      --overwrite true >/dev/null
}

main() {
  [[ -d "$LARAVEL_DIR" ]] || { echo "ERROR: LARAVEL_DIR not found: $LARAVEL_DIR" >&2; exit 1; }
  mkdir -p "$BACKUP_DIR"

  local ts app_name base_name db_dump archive
  ts="$(timestamp_utc)"
  app_name="$(basename "$LARAVEL_DIR")"
  base_name="${app_name}-${ts}"
  db_dump="${BACKUP_DIR}/${base_name}.sql"
  archive="${BACKUP_DIR}/${base_name}.tar.gz"

  echo "[1/4] Dumping MySQL → $db_dump"
  dump_mysql "$db_dump"

  echo "[2/4] Creating archive → $archive"
  make_archive "$LARAVEL_DIR" "$db_dump" "$archive"

  echo "[3/4] Uploading to Azure via az CLI"
  upload_with_azcli "$archive"
  echo "Upload complete: $(basename "$archive")"

  echo "[4/4] Pruning local backups older than ${RETAIN_LOCAL_DAYS}d"
  find "$BACKUP_DIR" -type f -name "${app_name}-*.tar.gz" -mtime +"$RETAIN_LOCAL_DAYS" -print -delete || true
  find "$BACKUP_DIR" -type f -name "${app_name}-*.sql" -mtime +"$RETAIN_LOCAL_DAYS" -print -delete || true

  echo "Done."
}

main "$@"

How It Works

Database Dump
- Reads DB_HOST, DB_DATABASE, DB_USERNAME, DB_PASSWORD from .env
- Runs mysqldump
File Packaging
- Copies project files while excluding unnecessary directories
- Adds database.sql
- Compresses into tar.gz
Azure Upload
- Uses az storage blob upload with AZURE_STORAGE_ACCOUNT + AZURE_STORAGE_KEY
Retention Cleanup
- Deletes .sql and .tar.gz files older than RETAIN_LOCAL_DAYS

Usage

Save the script:

nano laravel-backup.sh
chmod +x laravel-backup.sh

Configure variables:

LARAVEL_DIR
BACKUP_DIR
AZURE_STORAGE_ACCOUNT
AZURE_STORAGE_KEY
AZURE_CONTAINER

Run manually:

./laravel-backup.sh

Or schedule with cron:

crontab -e
0 3 * * * /path/to/laravel-backup.sh >> /var/log/laravel-backup.log 2>&1

Efficiently Measure String Similarity in PHP Applications

Edgaras — Sun, 25 May 2025 15:26:36 +0000

Measuring string similarity accurately is important for tasks like detecting typos in user inputs, matching similar database entries, improving chatbot responses, and identifying duplicate content. PHP developers can simplify these tasks using specialized algorithms.

Installation

Include the library via Composer:

composer require edgaras/strsim

Then, use the Composer autoloader:

require __DIR__ . '/vendor/autoload.php';

Implementing Powerful String Similarity Algorithms

By using specialized classes, developers can easily integrate complex string similarity metrics:

Levenshtein: Ideal for detecting user input spelling mistakes in form validation.

use Edgaras\StrSim\Levenshtein;

$userInput = "recieve";
$correctWord = "receive";

$distance = Levenshtein::distance($userInput, $correctWord);
if ($distance <= 2) {
    echo "Did you mean '{$correctWord}'?";
}

Damerau-Levenshtein: Useful for correcting common keyboard typing errors in search features.

use Edgaras\StrSim\DamerauLevenshtein;

$distance = DamerauLevenshtein::distance("adress", "address");
if ($distance <= 2) {
    echo "Searching for 'address' instead.";
}

Hamming: Critical for error checking in transmitted binary data packets.

use Edgaras\StrSim\Hamming;

$errors = Hamming::distance("11001101", "10001111");
if ($errors > 0) {
    trigger_error("Data packet corrupted.");
}

Jaro: Ideal for short string comparisons and record matching.

use Edgaras\StrSim\Jaro;

$similarity = Jaro::distance("crate", "trace");
if ($similarity > 0.8) {
    echo "Highly similar words detected.";
}

Jaro-Winkler: Excellent for deduplicating customer records by comparing similar names.

use Edgaras\StrSim\JaroWinkler;

$similarity = JaroWinkler::distance("Jonathan Smith", "Jonathon Smyth");
if ($similarity > 0.9) {
    echo "Possible duplicate found.";
}

Longest Common Subsequence (LCS): Useful in text diff applications to detect common content.

use Edgaras\StrSim\LCS;

$length = LCS::length("contentversion1", "contentversion2");
echo "Common subsequence length: $length";

Smith-Waterman: Good for local alignment of DNA sequences in bioinformatics research.

use Edgaras\StrSim\SmithWaterman;

$alignmentScore = SmithWaterman::score("ACGTAG", "ACGACG");
if ($alignmentScore > $threshold) {
    echo "High genetic similarity detected.";
}

Needleman-Wunsch: Valuable for global alignment of DNA or protein sequences.

use Edgaras\StrSim\NeedlemanWunsch;

$score = NeedlemanWunsch::score("GATTACA", "GCATGCU");
echo "Alignment score: $score";

Cosine Similarity: Useful for comparing frequency patterns in short texts.

use Edgaras\StrSim\Cosine;

$similarity = Cosine::similarity("night", "nacht");
echo "Text similarity: $similarity";

Jaccard Index: Effective for comparing the overlap between sets of tokens.

use Edgaras\StrSim\Jaccard;

$index = Jaccard::index("token1 token2", "token2 token3");
echo "Token overlap: $index";

Monge-Elkan: Great for fuzzy matching of multi-word strings.

use Edgaras\StrSim\MongeElkan;

$similarity = MongeElkan::similarity("john smith", "jon smythe");
if ($similarity > 0.85) {
    echo "Likely match identified.";
}

Common Applications

Natural Language Processing: Improve chatbot accuracy by handling slight input variations.

Fuzzy Matching: Optimize database searches and user input validation.
Spell Checking: Implement typo tolerance in text entry fields.
Bioinformatics: Conduct detailed genetic sequence analyses.

By selecting the appropriate algorithm, developers can significantly enhance the reliability and responsiveness of their PHP applications dealing with textual or genetic data.