# AGENTS.md - Vaultwarden Debian Packaging Project

This document provides essential information for AI agents working in this repository, covering project overview, commands, structure, and key conventions.

## Project Overview

This repository is dedicated to creating Debian packages for the [Vaultwarden](https://github.com/dani-garcia/vaultwarden) server. It leverages Docker for building the Vaultwarden binary and `sed` for customizing Debian package control files and scripts.

## Essential Commands

### Build and Package

*   **`just all`**
    *   **Description**: Builds Debian packages for `mysql` and `sqlite` database types, targeting the `bookworm` Debian release. After building, it lists the contents of the `dist/` directory.
    *   **Example**: `just all`

*   **`./build.sh [options]`**
    *   **Description**: The primary script for building a single Debian package. It fetches the Vaultwarden source, applies necessary patches, and generates the `.deb` file.
    *   **Options**:
        *   `-r <VERSION_TAG>`: Specify the Vaultwarden version tag (e.g., `1.19.0`). If omitted, the script fetches the latest release from GitHub.
        *   `-o <OS_VERSION_NAME>`: Specify the Debian OS version (e.g., `bullseye`, `bookworm`, `trixie`).
        *   `-d <DB_TYPE>`: Specify the database backend (`sqlite`, `mysql`, `postgresql`).
        *   `-a <ARCH_DIR>`: Specify the target architecture (`amd64`, `arm64`).
        *   `-p <PACKAGENAME>`: Custom package name.
        *   `-i <PACKAGEDIR>`: Custom package installation directory.
        *   `-u <SERVICEUSER>`: Custom service user.
        *   `-e <EXECUTABLENAME>`: Custom executable name.
        *   `-s`: Disable systemd database integration.
    *   **Examples**:
        *   `./build.sh -r 1.28.0 -o bookworm -d postgresql -a amd64`
        *   `./build.sh -o bullseye -d sqlite`

*   **`./vaultwarden-builder.sh`**
    *   **Description**: An automation script that sets up build dependencies (Docker), clones/updates this repository, runs `./build.sh` for predefined Debian versions (`bullseye`, `bookworm`) and the detected architecture, and then starts a Python HTTP server to serve the generated `.deb` packages from the `dist/` directory.
    *   **Usage**: Run from a clean Debian environment to set up the full build toolchain and generate all standard packages.
    *   **Example**: `./vaultwarden-builder.sh`

## Code Organization and Structure

*   **`/` (Root Directory)**: Contains core build scripts (`build.sh`, `vaultwarden-builder.sh`), `Justfile` for common tasks, `README.md`, `COPYING` license file, and various `.dist` template files (e.g., `control.dist`, `postinst.dist`) used for Debian packaging.
*   **`webserver/`**: Stores example configuration files for popular web servers (e.g., `Apache-VirtualHost.example.conf`, `Nginx-VirtualHost.example.conf`) to assist with reverse proxy setup for Vaultwarden.
*   **`patch/`**: Contains architecture-specific patch files (e.g., `patch/amd64/Dockerfile.patch`, `patch/arm64`) that are applied to Dockerfiles during the build process to adapt them for Debian packaging.
*   **`dist/`**: This directory is created by the build scripts and serves as the output location for the generated `.deb` packages.
*   **`git/`**: During the `build.sh` execution, the upstream `dani-garcia/vaultwarden` repository is cloned into this directory.

## Naming Conventions and Style Patterns

*   **Shell Scripts**: Variables typically use `snake_case` (e.g., `os_version_name`, `db_type`), while script-level constants are often `UPPER_CASE` (e.g., `DEBIAN_VERSIONS`, `REPO_URL`).
*   **Debian Template Files**: Files intended as templates for Debian packaging components follow a `*.dist` naming convention (e.g., `control.dist`, `postinst.dist`).
*   **Placeholders**: Configuration files and scripts use `@@PLACEHOLDER@@` (e.g., `@@PACKAGENAME@@`, `@@SERVICEUSER@@`) which are replaced by `sed` during the build process.

## Testing Approach and Patterns

Formal unit or integration testing frameworks are not explicitly present in this repository. The primary method of verification involves:

1.  **Successful Package Generation**: Ensuring that the `build.sh` script completes without errors and produces valid `.deb` packages in the `dist/` directory.
2.  **`vaultwarden-builder.sh` Verification**: The `vaultwarden-builder.sh` script includes a check for the existence of the `dist/` directory, acting as a basic build success indicator.

## Important Gotchas and Non-Obvious Patterns

*   **Extensive `sed` Usage**: The `build.sh` script heavily relies on `sed` commands to dynamically generate and modify various Debian packaging files (`control`, `postinst`, `postrm`, `prerm`, `service`, `sysusers.conf`, `tmpfiles.conf`) and the Dockerfile. Agents should be aware that many configuration aspects are templated and patched.
*   **OpenSSL 3 Compatibility**: For older Debian releases like `bullseye`, the `build.sh` script automatically enables the `vendored_openssl` Cargo feature to ensure compatibility with OpenSSL 3, which is a significant dependency consideration.
*   **Systemd Unit Disabled by Default**: After installation of the generated `.deb` package, the Vaultwarden systemd service unit is *disabled* by default. Users must manually configure Vaultwarden through its environment file (`/etc/vaultwarden/config.env`) and enable the service.
*   **Reverse Proxy Requirement**: Vaultwarden is typically deployed behind a reverse proxy. The `webserver/` directory provides example configurations for Apache and Nginx to facilitate this setup.
*   **Dynamic Version and Architecture Detection**: The `build.sh` script can automatically detect the latest Vaultwarden version from GitHub and the system's architecture if not explicitly provided, making it flexible for various build environments.