sko/vaultwarden-debian
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Add AGENTS.md and Gitea CI/CD workflow
Build and Release Debian Packages / build (push) Has been cancelled
Details
Build and Release Debian Packages / release (push) Has been cancelled
Details

Browse Source 
- Create AGENTS.md to document project structure, commands, and conventions for AI agents.
- Implement Gitea workflow for automated Debian package builds (MySQL, SQLite) and release creation.

💘 Generated with Crush

Assisted-by: Gemini 2.5 Flash via Crush <crush@charm.land>
This commit is contained in:
sko
2026-02-27 06:17:06 +01:00
parent 46b39a64a9
commit 74577a9f39
2 changed files with 133 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+65
View File
@@ -0,0 +1,65 @@
# 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.