DEV Community: Edgaras

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.

How to Reliably Mount a CIFS Share Using systemd on Boot

Edgaras — Fri, 25 Apr 2025 07:40:21 +0000

Mounting a CIFS share at boot via /etc/fstab can often lead to issues if the network isn't ready. A more reliable solution is to create a systemd mount unit that ensures the network is online before attempting to mount.

Here's how you do it:

Step 1: Create a credentials file

Create a file to store your SMB credentials:

sudo nano /etc/smb-credentials

With content:

username=your_username
password=your_password

Secure it so only root can read:

sudo chmod 600 /etc/smb-credentials
sudo chown root:root /etc/smb-credentials

Step 2: Create the mount point

Make the local directory where the CIFS share will be mounted:

sudo mkdir -p /mnt/nas_share

Step 3: Create a systemd mount unit

Run the following command to create or edit the mount unit:

sudo systemctl edit --force --full mnt-nas_share.mount

Paste the following content:

[Unit]
Description=Mount SMB Share
After=network-online.target
Wants=network-online.target

[Mount]
What=//nas.local/share
Where=/mnt/nas_share
Type=cifs
Options=credentials=/etc/smb-credentials,iocharset=utf8,nounix,noserverino,nofail,_netdev,soft,vers=3.0
TimeoutSec=30

[Install]
WantedBy=multi-user.target

Explanation:

[Unit]

Description=Mount NAS HDD Share: Human-readable description.
After=network-online.target: Ensures the mount waits for the network to be up.
Wants=network-online.target: Pulls in the network-online target if not already present.

[Mount]

What=//nas.local/share: UNC path to the CIFS share.
Where=/mnt/nas_share: Local mount point.
Type=cifs: Filesystem type.
Options=...: Mount options:
- credentials=...: Path to the credentials file (should be root-only readable). iocharset=utf8: Character encoding.
- nounix, noserverino: Workarounds for specific CIFS behaviors.
- nofail: Don’t block boot if the mount fails.
- _netdev: Marks this mount as requiring network.
- soft: Causes the mount to time out if the server is unresponsive.
- vers=3.0: Explicitly uses SMB version 3.0.
- TimeoutSec=30: Maximum wait time before systemd considers the mount failed.

[Install]

WantedBy=multi-user.target: Starts the mount at boot in multi-user mode.

Step 4: Enable the mount

After saving the unit file, reload and enable it:

sudo systemctl daemon-reexec
sudo systemctl daemon-reload
sudo systemctl enable mnt-nas_share.mount
sudo systemctl start mnt-nas_share.mount

These commands:

daemon-reexec: Ensures systemd itself is up-to-date.
daemon-reload: Reloads unit files.
enable: Enables the mount to persist across reboots.
start: Immediately mounts the share.

Step 5: Verify the mount

Check the status with:

sudo systemctl status mnt-nas_share.mount

You should see the share is mounted without errors.

Using this method ensures your CIFS mounts only attempt to initialize when the network is available, solving the common Permission denied opening credential file problem caused by early mount attempts during boot.

Setting Up MySQL and MongoDB Together in Laravel 12

Edgaras — Sun, 13 Apr 2025 21:05:00 +0000

Sometimes you need relational data for parts of your app (MySQL) and flexible document storage for others (MongoDB). Here's how to set up both in Laravel 12.

Install MongoDB PHP Extension

sudo apt install ext-mongodb

Install Required Composer Packages

sudo composer require mongodb/mongodb
sudo composer require mongodb/laravel-mongodb:^5.2 --with-all-dependencies

`.env` example

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=<CHANGE-TO-YOUR-MYSQL-DATABASE>
DB_USERNAME=<CHANGE-TO-YOUR-MYSQL-USERNAME>
DB_PASSWORD=<CHANGE-TO-YOUR-MYSQL-PASSWORD>

MONGODB_USERNAME=<CHANGE-TO-YOUR-MONGODB-USERNAME>
MONGODB_PASSWORD=<CHANGE-TO-YOUR-MONGODB-PASSWORD>
MONGODB_SERVER=127.0.0.1
MONGODB_PORT=27017
MONGODB_DATABASE=<CHANGE-TO-YOUR-MONGODB-COLLECTION>
MONGODB_URI="mongodb://${MONGODB_USERNAME}:${MONGODB_PASSWORD}@${MONGODB_SERVER}:${MONGODB_PORT}/${MONGODB_DATABASE}?directConnection=true&serverSelectionTimeoutMS=2000&authSource=admin&appName=mongosh+2.2.2?tls=false&authSource=admin"

`config/database.php`


use Illuminate\Support\Str;

return [

'default' => env('DB_CONNECTION', 'mysql'),

'connections' => [


'mysql' => [
    'driver' => 'mysql',
    'url' => env('DB_URL'),
    'host' => env('DB_HOST', '127.0.0.1'),
    'port' => env('DB_PORT', '3306'),
    'database' => env('DB_DATABASE', 'laravel'),
    'username' => env('DB_USERNAME', 'root'),
    'password' => env('DB_PASSWORD', ''),
    'unix_socket' => env('DB_SOCKET', ''),
    'charset' => env('DB_CHARSET', 'utf8mb4'),
    'collation' => env('DB_COLLATION', 'utf8mb4_unicode_ci'),
    'prefix' => '',
    'prefix_indexes' => true,
    'strict' => true,
    'engine' => null,
    'options' => extension_loaded('pdo_mysql') ? array_filter([
    PDO::MYSQL_ATTR_SSL_CA => env('MYSQL_ATTR_SSL_CA'),
    ]) : [],
],

'mongodb' => [
    'driver' => 'mongodb',
    'dsn' => env('MONGODB_URI', 'mongodb://'.env('MONGODB_USERNAME').':'.env('MONGODB_PASSWORD').'@'.env('MONGODB_SERVER').':'.env('MONGODB_PORT').'/'.env('MONGODB_DATABASE').'?directConnection=true&serverSelectionTimeoutMS=2000&authSource=admin&appName=mongosh+2.2.2?tls=false&authSource=admin'),
    'database' => env('MONGODB_DATABASE'),
    ],
],

];

Model examples

MySQL Model (`User`)

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    protected $connection = 'mysql';

    protected $fillable = [
        'name', 'email',
    ];
}

MongoDB Model (`Post`)

<?php

namespace App\Models;

use MongoDB\Laravel\Eloquent\Model;

class Post extends Model
{
    protected $connection = 'mongodb';
    protected $collection = 'posts';

    protected $fillable = [
        'title',
        'body',
        'slug',
    ];
}

Example Controller

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Models\User;
use App\Models\Post;

class ExampleController extends Controller
{
    public function store(Request $request)
    {
        $user = User::create([
            'name' => 'John Doe',
            'email' => 'john@example.com',
        ]);

        $post = Post::create([
            'title' => 'MongoDB Example',
            'body' => 'This is stored in MongoDB.',
            'slug' => 'mongodb-example',
        ]);

        return response()->json([
            'user' => $user,
            'post' => $post,
        ]);
    }
}

That's it. You now have MySQL and MongoDB both fully working in a Laravel 12 app.

UML Use Case Diagrams

Edgaras — Sun, 06 Apr 2025 21:05:00 +0000

UML (Unified Modeling Language) is a tool in software engineering for visualizing, specifying, constructing, and documenting software system artifacts. One of the most widely used UML diagrams is the Use Case Diagram, which helps in modeling system functionality from the user's perspective.

What is a UML Use Case Diagram?

A Use Case Diagram is a high-level visual representation of how users (actors) interact with a system. It belongs to the behavioral category of UML diagrams, as it focuses on depicting system functionality and user interactions rather than its structure. It identifies the primary functions and the relationships between actors and use cases, helping to understand system behavior and user interactions.

Key Components of a Use Case Diagram

Actors – Represent users or external systems that interact with the system.
Use Cases – Depict functionalities or actions performed by the system.
Relationships – Define connections between elements, including:
- Associations – Lines that connect actors to use cases, showing interactions.
- Generalization – Represents inheritance between actors or use cases.
- Include – Represents mandatory dependency where one use case always invokes another.
- Extend – Represents optional behavior that extends another use case.
System Boundary – Defines the scope of the system.
Extension Points – Specific locations within a use case where additional behavior can be added via <<extend>>.

UML Use Case Diagram Notation

Actor

An actor represents an external entity (user or system) that interacts with the system. It is depicted as a stick figure:

Use Case

A use case represents a specific function or process performed by the system. It is depicted as an oval:

Association

An association is a line connecting actors to use cases, indicating interaction:

Generalization

A generalization relationship represents inheritance, where a specialized use case or actor inherits behavior from a more general one. It is depicted using a solid line with an unfilled arrowhead:

Include Relationship

An include relationship signifies that one use case always invokes another. It represents mandatory behavior where the base use case is incomplete without the included functionality. All included use cases must be shown in the diagram as they represent essential components of the system functionality. It is represented by a dashed arrow labeled <<include>> pointing from the base use case to the included use case.

Extend Relationship

An extend relationship shows optional behavior that may be added to a base use case under specific conditions. The base use case is complete on its own, and the extending use case only executes when certain conditions are met at specified extension points. Not all possible extensions need to be shown in the diagram since they represent optional enhancements rather than mandatory behavior. It is represented by a dashed arrow labeled <<extend>> pointing from the extending use case to the base use case.

System Boundary

A system boundary is a rectangle enclosing all use cases, defining the scope of the system.

Extension Points

Extension Points define specific locations within a use case where an <<extend>> relationship can introduce additional behavior. They indicate where an extending use case may insert its logic without modifying the base use case.

When to Use a Use Case Diagram?

When defining system requirements.
To communicate system behavior with stakeholders.
During initial design discussions.
As a reference for development and testing teams.

Conclusion

UML Use Case Diagrams offer a clear and structured way to visualize system interactions and functionalities from the user's perspective. Their value comes from simplifying complex systems into understandable components that represent real-world usage scenarios. By mapping actors, use cases, and their relationships, these diagrams help teams define accurate requirements, communicate system behavior effectively, and maintain focus on user needs throughout the development process. From initial design discussions to testing and implementation, Use Case Diagrams serve as a valuable reference that ensures all stakeholders share a common understanding of what the system should accomplish.

DEV Community: Edgaras

Deploying PaddleOCR PDF OCR service on Azure Container Apps

Engines and workload profiles

Setting up the environment

Deploying the app

Replica settings

Verifying the deployment

Making job state survive a restart

Conclusion

Bicep template

UML Component Diagrams

What is a UML Component Diagram?

Why Use Component Diagrams?

Core Components and Notation

Component

Provided Interface

Required Interface

Assembly Connector

Port

Delegation Connector

Standard Stereotypes for Components

Practical Example: Video Streaming Platform

Best Practices

Conclusion

A Self-Hosted Web Content Extraction API

Quick start

Your first extraction

Pick your output format

Screenshots

Precision extraction

Process URLs in batch

User agent rotation

Browser pool resilience

Built-in features

Configuration

Bottom line

UML Deployment Diagrams

What is a UML Deployment Diagram?

Why Use Deployment Diagrams?

Core Components and Notation

Nodes

Artifacts

Communication Paths

Node Instances

Practical Example: Cloud Web Application

Enterprise On-Premises Deployment

Best Practices

Conclusion

Using a Self-Hosted PDF OCR API with PaddleOCR

The problem

When this is useful

What's under the hood

Setup

Usage

Submit a PDF

Poll progress

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

Fetch all pages

List jobs, cancel, delete

Full API reference

API key authentication

Configuration

Example: integrating into a Python script

How it works

A Developer's Guide to Useful Apache Modules

How to Enable/Disable Modules

mod_rewrite - URL Routing & Clean URLs

mod_ssl - HTTPS Support

mod_headers - Security & Cache Headers

mod_expires - Browser Cache Control

mod_proxy and mod_proxy_http - Reverse Proxy to Apps

mod_security - Web Application Firewall

mod_status - Live Server Status Page

mod_auth_basic and mod_authn_file - Simple Password Protection

mod_evasive - Auto-Blocking for DDoS / Brute Force

Additional Useful Modules

mod_deflate or mod_brotli - Response Compression

mod_pagespeed - Auto Performance Optimizer

mod_geoip / mod_maxminddb - Geo-Based Rules

Summary

`mod_rewrite` - URL Routing & Clean URLs

`mod_ssl` - HTTPS Support

`mod_headers` - Security & Cache Headers

`mod_expires` - Browser Cache Control

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

`mod_security` - Web Application Firewall

`mod_status` - Live Server Status Page

`mod_auth_basic` and `mod_authn_file` - Simple Password Protection

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

`mod_deflate` or `mod_brotli` - Response Compression

`mod_pagespeed` - Auto Performance Optimizer

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

`.env` example

`config/database.php`

MySQL Model (`User`)

MongoDB Model (`Post`)