documentation

CLAUDE.md

@@ -0,0 +1,29 @@
+# Podman Quadlets Cookbook
+
+This project is a collection of Podman Quadlets for some widely used selfhosted software.
+Your role is to write and maintain the Podman Quadlets.
+You may be given Kustomize manifests, Helm charts, Docker Compose files, etc. that you HAVE TO convert in Podman Quadlets.
+
+## Rules
+
+- NEVER alter the files at the root of this GIT repository!
+- You are ONLY ALLOWED to edit files in the sub-directories.
+- Before writing or editing a Podman Quadlet, you MUST read the `podman-systemd.unit(5)` man page!
+
+## Architecture
+
+- Convention over configuration: place the files at the right place and the tooling (Makefile) will take care of placing that file at the right location.
+
+## Useful tools
+
+- `podlet`: Podlet generates Podman Quadlet files from a Podman command, Docker command, Docker compose file, or existing Podman object (container, image, pod, volume, network, etc).
+
+## Useful documentation
+
+- @README.md: to get an overview of the project.
+- @common.mk: to understand the development tooling.
+- `podman-systemd.unit(5)`: syntax of the Podman Quadlet files.
+- `podlet podman --help`: when you need to convert Docker commands.
+- `podlet compose --help`: when you need to convert Docker Compose files.
+- `podlet generate --help`: when you need to convert existing Podman objects.
+

README.md

@@ -5,9 +5,22 @@ This repository gathers all the recipes (hence the name "Cookbook") to deploy Op
 
 ## Current cookbooks
 
-- [nginx](nginx/): starts Nginx, content is initialized / updated from a GIT repository
-- [postgresql](postgresql/): starts a PostgreSQL server, handles automated major upgrades, periodic backup and initialization of the database from the last backup.
-- [nextcloud](nextcloud/): starts a Nextcloud server with all its dependencies, handles automated upgrades.
+- [base](base/): base configuration for Fedora CoreOS with fastfetch, tmpfiles setup, and QEMU guest agent.
+- [gitea](gitea/): self-hosted Git service, a lightweight GitHub/GitLab alternative.
+- [keycloak](keycloak/): open source identity and access management server with PostgreSQL backend.
+- [lego](lego/): Let's Encrypt/ACME client for automatic SSL/TLS certificate management and renewal.
+- [miniflux](miniflux/): minimalist RSS/Atom feed reader with PostgreSQL backend.
+- [nextcloud](nextcloud/): self-hosted file sync and share platform with all its dependencies, handles automated upgrades.
+- [nginx](nginx/): Nginx web server with content initialized and updated from a GIT repository.
+- [postgresql](postgresql/): PostgreSQL database server with automated major upgrades, periodic backup and restore capabilities.
+- [qemu-user-static](qemu-user-static/): multi-architecture container support using QEMU user-mode emulation.
+- [restic-server](restic-server/): REST server backend for restic backups with append-only mode and Prometheus metrics.
+- [samba](samba/): SMB/CIFS file sharing server for network storage access.
+- [seedbox](seedbox/): complete media server stack with Radarr, Sonarr, Lidarr, Prowlarr, qBittorrent, Jellyfin, and FlareSolverr.
+- [traefik](traefik/): modern HTTP reverse proxy and load balancer with automatic service discovery.
+- [vaultwarden](vaultwarden/): Bitwarden-compatible password manager server with PostgreSQL backend.
+- [vmagent](vmagent/): Victoria Metrics agent for collecting and forwarding metrics.
+- [vsftpd](vsftpd/): secure FTP server with TLS support and Let's Encrypt certificate integration.
 
 ## License
 

base/README.md

@@ -0,0 +1,41 @@
+# Podman Quadlet: Base
+
+## Overview
+
+The base cookbook provides foundational configuration for Fedora CoreOS systems. It includes:
+
+- **fastfetch**: A system information tool displayed on login, with color-coded output (red for root, blue for regular users).
+- **tmpfiles configuration**: Sets up required directories such as `/var/lib/virtiofs/data`.
+- **QEMU guest agent**: Optional installation for better VM integration.
+- **SSH key persistence**: Backs up and restores SSH host keys across reboots.
+
+This cookbook is used as an implicit dependency for other cookbooks that run on Fedora CoreOS.
+
+## Usage
+
+In a separate terminal, follow the logs.
+
+```sh
+sudo make tail-logs
+```
+
+Install the base configuration.
+
+```sh
+sudo make clean install
+```
+
+You should see the **install-fastfetch.service** downloading and installing fastfetch.
+On next login, fastfetch will display system information.
+
+To verify the installation:
+
+```sh
+fastfetch --version
+```
+
+Finally, remove the configuration and its data.
+
+```sh
+sudo make uninstall clean
+```

common.mk

@@ -133,7 +133,7 @@ pre-requisites::
 		exit 1; \
 	fi
 	@set -Eeuo pipefail; \
-	for tool in install systemctl systemd-analyze systemd-tmpfiles sysctl virt-install virsh qemu-img journalctl coreos-installer resize butane yq; do \
+	for tool in install systemctl systemd-analyze systemd-tmpfiles sysctl virt-install virsh qemu-img journalctl coreos-installer resize butane yq podlet; do \
 		if ! which $$tool &>/dev/null ; then \
 			echo "$$tool is not installed. Please install it first." >&2; \
 			exit 1; \

gitea/README.md

@@ -0,0 +1,57 @@
+# Podman Quadlet: Gitea
+
+## Overview
+
+Gitea is a lightweight, self-hosted Git service started as a Podman Quadlet. It provides a GitHub/GitLab-like experience for hosting Git repositories.
+
+This cookbook:
+
+- Runs Gitea as a rootless container with minimal privileges.
+- Uses PostgreSQL as the database backend (requires the `postgresql` cookbook).
+- Includes health checks to monitor the service status.
+- Supports automatic container image updates via Podman auto-update.
+
+## Prerequisites
+
+- The `postgresql` cookbook must be installed and running.
+- Configuration file `/etc/quadlets/gitea/config.env` must exist.
+
+## Usage
+
+In a separate terminal, follow the logs.
+
+```sh
+sudo make tail-logs
+```
+
+Install the Podman Quadlets and start Gitea.
+
+```sh
+sudo make clean install
+```
+
+You should see the **gitea.service** waiting for PostgreSQL to be available, then starting up.
+
+Verify Gitea is running:
+
+```sh
+curl -sSf http://127.0.0.1:3000/
+```
+
+Restart the **gitea.target** unit.
+
+```sh
+sudo systemctl restart gitea.target
+```
+
+Finally, remove the quadlets, their configuration and their data.
+
+```sh
+sudo make uninstall clean
+```
+
+## Integration tests
+
+```sh
+sudo make test
+```

keycloak/README.md

@@ -0,0 +1,58 @@
+# Podman Quadlet: Keycloak
+
+## Overview
+
+Keycloak is an open source identity and access management server started as a Podman Quadlet. It provides single sign-on (SSO), identity brokering, and user federation capabilities.
+
+This cookbook:
+
+- Builds a custom Keycloak container image locally for optimized startup.
+- Runs Keycloak with PostgreSQL as the database backend (requires the `postgresql` cookbook).
+- Includes a timer to periodically rebuild the container image.
+- Includes health checks to monitor the service status.
+
+## Prerequisites
+
+- The `postgresql` cookbook must be installed and running.
+- Configuration file `/etc/quadlets/keycloak/config.env` must exist.
+
+## Usage
+
+In a separate terminal, follow the logs.
+
+```sh
+sudo make tail-logs
+```
+
+Install the Podman Quadlets and start Keycloak.
+
+```sh
+sudo make clean install
+```
+
+You should see the **keycloak-build.service** building the optimized Keycloak container image.
+Then, the **keycloak.service** should start up after waiting for PostgreSQL to be available.
+
+Verify Keycloak is running:
+
+```sh
+curl -sSf http://127.0.0.1:8080/health
+```
+
+Restart the **keycloak.target** unit.
+
+```sh
+sudo systemctl restart keycloak.target
+```
+
+Finally, remove the quadlets, their configuration and their data.
+
+```sh
+sudo make uninstall clean
+```
+
+## Integration tests
+
+```sh
+sudo make test
+```

lego/README.md

@@ -0,0 +1,66 @@
+# Podman Quadlet: Lego
+
+## Overview
+
+Lego is a Let's Encrypt/ACME client started as a Podman Quadlet. It handles automatic SSL/TLS certificate issuance and renewal.
+
+This cookbook:
+
+- Runs an initial certificate fetch via **lego-run.service** when no certificates exist.
+- Schedules automatic certificate renewal via **lego-renew.timer**.
+- Stores certificates with secure permissions (umask 0077).
+- Supports renewal hooks to reload dependent services when certificates are renewed.
+
+## Prerequisites
+
+- Configuration file `/etc/quadlets/lego/config.env` must exist with ACME configuration.
+- DNS or HTTP challenge must be properly configured.
+
+## Usage
+
+In a separate terminal, follow the logs.
+
+```sh
+sudo make tail-logs
+```
+
+Install the Podman Quadlets and fetch the initial certificate.
+
+```sh
+sudo make clean install
+```
+
+You should see the **lego-run.service** fetching a certificate from Let's Encrypt.
+The certificate will be stored in `/var/lib/quadlets/lego/certificates/`.
+
+Check the certificate:
+
+```sh
+sudo ls -la /var/lib/quadlets/lego/certificates/
+```
+
+The **lego-renew.timer** will periodically check and renew the certificate before expiration.
+
+To manually trigger a renewal check:
+
+```sh
+sudo systemctl start lego-renew.service
+```
+
+Restart the **lego.target** unit.
+
+```sh
+sudo systemctl restart lego.target
+```
+
+Finally, remove the quadlets, their configuration and their data.
+
+```sh
+sudo make uninstall clean
+```
+
+## Integration tests
+
+```sh
+sudo make test
+```

miniflux/README.md

@@ -0,0 +1,57 @@
+# Podman Quadlet: Miniflux
+
+## Overview
+
+Miniflux is a minimalist RSS/Atom feed reader started as a Podman Quadlet. It is fast, lightweight, and focuses on simplicity.
+
+This cookbook:
+
+- Runs Miniflux as a rootless container with minimal privileges.
+- Uses PostgreSQL as the database backend (requires the `postgresql` cookbook).
+- Includes health checks to monitor the service status.
+- Supports automatic container image updates via Podman auto-update.
+
+## Prerequisites
+
+- The `postgresql` cookbook must be installed and running.
+- Configuration file `/etc/quadlets/miniflux/miniflux.conf` must exist.
+
+## Usage
+
+In a separate terminal, follow the logs.
+
+```sh
+sudo make tail-logs
+```
+
+Install the Podman Quadlets and start Miniflux.
+
+```sh
+sudo make clean install
+```
+
+You should see the **miniflux.service** waiting for PostgreSQL to be available, then starting up.
+
+Verify Miniflux is running by accessing the web interface or using the health check:
+
+```sh
+curl -sSf http://127.0.0.1:8080/healthcheck
+```
+
+Restart the **miniflux.target** unit.
+
+```sh
+sudo systemctl restart miniflux.target
+```
+
+Finally, remove the quadlets, their configuration and their data.
+
+```sh
+sudo make uninstall clean
+```
+
+## Integration tests
+
+```sh
+sudo make test
+```

nextcloud/README.md

@@ -0,0 +1,71 @@
+# Podman Quadlet: Nextcloud
+
+## Overview
+
+Nextcloud is a self-hosted file sync and share platform started as a Podman Quadlet. It provides cloud storage, collaboration, and productivity features.
+
+This cookbook runs a complete Nextcloud stack:
+
+- **nextcloud-app**: The main Nextcloud PHP application.
+- **nextcloud-nginx**: Nginx web server to serve Nextcloud.
+- **nextcloud-redis**: Redis for caching and session management.
+- **nextcloud-init**: Initializes the Nextcloud installation.
+- **nextcloud-upgrade**: Handles Nextcloud version upgrades.
+- **nextcloud-cron**: Scheduled background jobs via timer.
+- **nextcloud-collabora**: Optional Collabora Online for document editing.
+
+This cookbook uses PostgreSQL as the database backend (requires the `postgresql` cookbook).
+
+## Prerequisites
+
+- The `postgresql` cookbook must be installed and running.
+- Configuration file `/etc/quadlets/nextcloud/config.env` must exist.
+
+## Usage
+
+In a separate terminal, follow the logs.
+
+```sh
+sudo make tail-logs
+```
+
+Install the Podman Quadlets and start Nextcloud.
+
+```sh
+sudo make clean install
+```
+
+You should see the services starting in order:
+
+1. **nextcloud-redis.service** starts the Redis cache.
+2. **nextcloud-init.service** initializes Nextcloud if needed.
+3. **nextcloud-app.service** starts the PHP application.
+4. **nextcloud-nginx.service** starts the web server.
+5. **nextcloud-upgrade.service** runs any pending upgrades.
+6. **nextcloud-cron.timer** schedules background jobs.
+
+Access Nextcloud at `http://127.0.0.1/`.
+
+Restart the **nextcloud.target** unit.
+
+```sh
+sudo systemctl restart nextcloud.target
+```
+
+To manually run background jobs:
+
+```sh
+sudo systemctl start nextcloud-cron.service
+```
+
+Finally, remove the quadlets, their configuration and their data.
+
+```sh
+sudo make uninstall clean
+```
+
+## Integration tests
+
+```sh
+sudo make test
+```

qemu-user-static/README.md

@@ -0,0 +1,63 @@
+# Podman Quadlet: QEMU User Static
+
+## Overview
+
+QEMU User Static provides multi-architecture container support using QEMU user-mode emulation. This allows running containers built for different CPU architectures (e.g., ARM containers on x86_64 hosts).
+
+This cookbook:
+
+- Builds a custom container image with QEMU static binaries.
+- Registers QEMU interpreters with the kernel's binfmt_misc.
+- Includes a timer to periodically rebuild the container image.
+- Runs as a privileged one-shot service to register the interpreters.
+
+## Usage
+
+In a separate terminal, follow the logs.
+
+```sh
+sudo make tail-logs
+```
+
+Install the Podman Quadlets and register the QEMU interpreters.
+
+```sh
+sudo make clean install
+```
+
+You should see the **qemu-user-static-build.service** building the container image.
+Then, the **qemu-user-static.service** registers the QEMU interpreters with the kernel.
+
+Verify the registration:
+
+```sh
+ls /proc/sys/fs/binfmt_misc/
+```
+
+You should see entries for various architectures (e.g., `qemu-aarch64`, `qemu-arm`).
+
+Test running a container for a different architecture:
+
+```sh
+podman run --rm docker.io/arm64v8/alpine uname -m
+```
+
+This should output `aarch64` even on an x86_64 host.
+
+Restart the **qemu-user-static.target** unit.
+
+```sh
+sudo systemctl restart qemu-user-static.target
+```
+
+Finally, remove the quadlets, their configuration and their data.
+
+```sh
+sudo make uninstall clean
+```
+
+## Integration tests
+
+```sh
+sudo make test
+```

restic-server/README.md

@@ -0,0 +1,59 @@
+# Podman Quadlet: Restic Server
+
+## Overview
+
+Restic REST Server is a backend server for the restic backup tool, started as a Podman Quadlet. It provides a REST API for storing and retrieving backup data.
+
+This cookbook:
+
+- Runs the restic REST server as a rootless container.
+- Configures append-only mode for added security (backups can be added but not deleted).
+- Enables Prometheus metrics for monitoring.
+- Supports private repositories for multi-user setups.
+- Stores backup data in `/var/lib/virtiofs/data/restic-server/`.
+
+## Usage
+
+In a separate terminal, follow the logs.
+
+```sh
+sudo make tail-logs
+```
+
+Install the Podman Quadlets and start the restic REST server.
+
+```sh
+sudo make clean install
+```
+
+You should see the **restic-server.service** starting up.
+
+Verify the server is running:
+
+```sh
+curl -sSf http://127.0.0.1:8080/
+```
+
+Initialize a new repository (from a restic client):
+
+```sh
+restic -r rest:http://127.0.0.1:8080/myrepo init
+```
+
+The Prometheus metrics endpoint is available at:
+
+```sh
+curl http://127.0.0.1:8080/metrics
+```
+
+Finally, remove the quadlets, their configuration and their data.
+
+```sh
+sudo make uninstall clean
+```
+
+## Integration tests
+
+```sh
+sudo make test
+```

samba/README.md

@@ -0,0 +1,70 @@
+# Podman Quadlet: Samba
+
+## Overview
+
+Samba is an SMB/CIFS file sharing server started as a Podman Quadlet. It allows sharing files and directories over the network with Windows, macOS, and Linux clients.
+
+This cookbook:
+
+- Builds a custom Samba container image locally.
+- Runs Samba with configurable shares via drop-in configuration files.
+- Supports user authentication with system users mapped into the container.
+- Includes a timer to periodically rebuild the container image.
+- Only starts if at least one share configuration file exists.
+
+## Prerequisites
+
+- Share configuration files must exist in `/etc/quadlets/samba/smb.conf.d/` with names ending in `shares.conf`.
+
+## Usage
+
+In a separate terminal, follow the logs.
+
+```sh
+sudo make tail-logs
+```
+
+Install the Podman Quadlets and start Samba.
+
+```sh
+sudo make clean install
+```
+
+You should see the **samba-build.service** building the Samba container image.
+Then, the **samba.service** should start up.
+
+Verify Samba is running:
+
+```sh
+sudo systemctl status samba.service
+```
+
+Test connectivity from a client:
+
+```sh
+smbclient -L //localhost -N
+```
+
+Connect to a share:
+
+```sh
+smbclient //localhost/sharename -U username
+```
+
+Restart the **samba.target** unit.
+
+```sh
+sudo systemctl restart samba.target
+```
+
+Finally, remove the quadlets, their configuration and their data.
+
+```sh
+sudo make uninstall clean
+```
+
+## Integration tests
+
+```sh
+sudo make test
+```

seedbox/README.md

@@ -0,0 +1,75 @@
+# Podman Quadlet: Seedbox
+
+## Overview
+
+The Seedbox cookbook provides a complete media server stack started as Podman Quadlets. It includes all the tools needed for automated media acquisition and streaming.
+
+This cookbook includes the following services:
+
+- **qBittorrent**: BitTorrent client for downloading media.
+- **Radarr**: Movie collection manager and downloader.
+- **Sonarr**: TV series collection manager and downloader.
+- **Lidarr**: Music collection manager and downloader.
+- **Prowlarr**: Indexer manager for Radarr, Sonarr, and Lidarr.
+- **Jellyfin**: Media server for streaming your collection.
+- **FlareSolverr**: Proxy server to bypass Cloudflare protection for indexers.
+
+All services:
+
+- Run as rootless containers with minimal privileges.
+- Share a common storage directory structure.
+- Support automatic container image updates via Podman auto-update.
+
+## Prerequisites
+
+- Storage must be mounted at `/var/lib/virtiofs/data/`.
+- Each service stores its configuration in `/var/lib/virtiofs/data/<service>/config/`.
+
+## Usage
+
+In a separate terminal, follow the logs.
+
+```sh
+sudo make tail-logs
+```
+
+Install the Podman Quadlets and start the seedbox stack.
+
+```sh
+sudo make clean install
+```
+
+You should see all services starting up. Access the web interfaces:
+
+- **qBittorrent**: `http://127.0.0.1:8080/`
+- **Radarr**: `http://127.0.0.1:7878/`
+- **Sonarr**: `http://127.0.0.1:8989/`
+- **Lidarr**: `http://127.0.0.1:8686/`
+- **Prowlarr**: `http://127.0.0.1:9696/`
+- **Jellyfin**: `http://127.0.0.1:8096/`
+- **FlareSolverr**: `http://127.0.0.1:8191/`
+
+Restart the **seedbox.target** unit.
+
+```sh
+sudo systemctl restart seedbox.target
+```
+
+To restart individual services:
+
+```sh
+sudo systemctl restart jellyfin.service
+sudo systemctl restart qbittorrent.service
+```
+
+Finally, remove the quadlets, their configuration and their data.
+
+```sh
+sudo make uninstall clean
+```
+
+## Integration tests
+
+```sh
+sudo make test
+```

traefik/README.md

@@ -0,0 +1,59 @@
+# Podman Quadlet: Traefik
+
+## Overview
+
+Traefik is a modern HTTP reverse proxy and load balancer started as a Podman Quadlet. It provides automatic service discovery, SSL termination, and routing.
+
+This cookbook:
+
+- Runs Traefik as a rootless container with minimal privileges.
+- Supports automatic HTTPS with Let's Encrypt integration.
+- Includes health checks to monitor the service status.
+- Stores configuration in `/etc/quadlets/traefik/` and state in `/var/lib/quadlets/traefik/`.
+- Supports automatic container image updates via Podman auto-update.
+
+## Usage
+
+In a separate terminal, follow the logs.
+
+```sh
+sudo make tail-logs
+```
+
+Install the Podman Quadlets and start Traefik.
+
+```sh
+sudo make clean install
+```
+
+You should see the **traefik.service** starting up.
+
+Verify Traefik is running:
+
+```sh
+curl -sSf -H 'Host: ping' http://127.0.0.1/
+```
+
+Access the Traefik dashboard (if enabled in configuration):
+
+```sh
+curl http://127.0.0.1:8080/dashboard/
+```
+
+Restart the **traefik.target** unit.
+
+```sh
+sudo systemctl restart traefik.target
+```
+
+Finally, remove the quadlets, their configuration and their data.
+
+```sh
+sudo make uninstall clean
+```
+
+## Integration tests
+
+```sh
+sudo make test
+```

vaultwarden/README.md

@@ -0,0 +1,60 @@
+# Podman Quadlet: Vaultwarden
+
+## Overview
+
+Vaultwarden is a Bitwarden-compatible password manager server started as a Podman Quadlet. It provides a self-hosted alternative to the official Bitwarden server, compatible with all Bitwarden clients.
+
+This cookbook:
+
+- Runs Vaultwarden as a rootless container with minimal privileges.
+- Uses PostgreSQL as the database backend (requires the `postgresql` cookbook).
+- Includes health checks to monitor the service status.
+- Stores vault data in `/var/lib/virtiofs/data/vaultwarden/`.
+- Supports automatic container image updates via Podman auto-update.
+
+## Prerequisites
+
+- The `postgresql` cookbook must be installed and running.
+- Configuration file `/etc/quadlets/vaultwarden/config.env` must exist.
+
+## Usage
+
+In a separate terminal, follow the logs.
+
+```sh
+sudo make tail-logs
+```
+
+Install the Podman Quadlets and start Vaultwarden.
+
+```sh
+sudo make clean install
+```
+
+You should see the **vaultwarden.service** waiting for PostgreSQL to be available, then starting up.
+
+Verify Vaultwarden is running:
+
+```sh
+curl -sSf http://127.0.0.1:8080/
+```
+
+Access the web vault at `http://127.0.0.1:8080/` and configure your Bitwarden clients to use this server.
+
+Restart the **vaultwarden.target** unit.
+
+```sh
+sudo systemctl restart vaultwarden.target
+```
+
+Finally, remove the quadlets, their configuration and their data.
+
+```sh
+sudo make uninstall clean
+```
+
+## Integration tests
+
+```sh
+sudo make test
+```

vmagent/README.md

@@ -0,0 +1,59 @@
+# Podman Quadlet: vmagent
+
+## Overview
+
+vmagent is a Victoria Metrics agent started as a Podman Quadlet. It collects metrics from various sources and forwards them to a Victoria Metrics or Prometheus-compatible remote storage.
+
+This cookbook:
+
+- Runs vmagent as a rootless container with minimal privileges.
+- Uses environment-based configuration via global and local environment files.
+- Stores scraped data temporarily in `/var/lib/quadlets/vmagent/` for reliability.
+- Reads scrape configuration from `/etc/quadlets/vmagent/conf.d/`.
+- Supports automatic container image updates via Podman auto-update.
+
+## Prerequisites
+
+- Configuration file `/etc/quadlets/vmagent/vmagent.local.env` must exist.
+- Global configuration in `/etc/quadlets/vmagent/vmagent.global.env`.
+- Scrape targets configured in `/etc/quadlets/vmagent/conf.d/`.
+
+## Usage
+
+In a separate terminal, follow the logs.
+
+```sh
+sudo make tail-logs
+```
+
+Install the Podman Quadlets and start vmagent.
+
+```sh
+sudo make clean install
+```
+
+You should see the **vmagent.service** starting up and beginning to scrape configured targets.
+
+Verify vmagent is running:
+
+```sh
+sudo systemctl status vmagent.service
+```
+
+Check vmagent's own metrics:
+
+```sh
+curl http://127.0.0.1:8429/metrics
+```
+
+Finally, remove the quadlets, their configuration and their data.
+
+```sh
+sudo make uninstall clean
+```
+
+## Integration tests
+
+```sh
+sudo make test
+```

vsftpd/README.md

@@ -0,0 +1,73 @@
+# Podman Quadlet: vsftpd
+
+## Overview
+
+vsftpd (Very Secure FTP Daemon) is started as a Podman Quadlet. It provides a secure FTP server with TLS support.
+
+This cookbook:
+
+- Builds a custom vsftpd container image locally.
+- Supports TLS encryption with automatic certificate loading from Let's Encrypt (integrates with the `lego` cookbook).
+- Maps system users into the container for authentication.
+- Includes a timer to periodically rebuild the container image.
+- Reloads certificates automatically when renewed.
+
+## Prerequisites
+
+- Configuration file `/etc/quadlets/vsftpd/vsftpd.conf.d/local.conf` must exist.
+- For TLS support, the `lego` cookbook should be configured to provide certificates.
+
+## Usage
+
+In a separate terminal, follow the logs.
+
+```sh
+sudo make tail-logs
+```
+
+Install the Podman Quadlets and start vsftpd.
+
+```sh
+sudo make clean install
+```
+
+You should see the **vsftpd-build.service** building the vsftpd container image.
+Then, the **vsftpd.service** should start up.
+
+Verify vsftpd is running:
+
+```sh
+sudo systemctl status vsftpd.service
+```
+
+Test FTP connectivity:
+
+```sh
+ftp localhost
+```
+
+Or with TLS:
+
+```sh
+lftp -u username localhost
+```
+
+When Let's Encrypt certificates are renewed, the **vsftpd-load-renewed-certificate.service** automatically reloads them.
+
+Restart the **vsftpd.target** unit.
+
+```sh
+sudo systemctl restart vsftpd.target
+```
+
+Finally, remove the quadlets, their configuration and their data.
+
+```sh
+sudo make uninstall clean
+```
+
+## Integration tests
+
+```sh
+sudo make test
+```