vaultwarden-debian/AGENTS.md

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 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.