feat: Add AGENTS.md and Gitea CI/CD workflow
- 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:
@@ -0,0 +1,68 @@
|
||||
name: Build and Release Debian Packages
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- master
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v3
|
||||
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y git curl gnupg ca-certificates apparmor build-essential patch psmisc python3
|
||||
sudo install -m 0755 -d /etc/apt/keyrings
|
||||
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
|
||||
sudo chmod a+r /etc/apt/keyrings/docker.gpg
|
||||
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
|
||||
|
||||
- name: Get latest Vaultwarden version
|
||||
id: get_version
|
||||
run: |
|
||||
LATEST_TAG=$(curl -s https://api.github.com/repos/dani-garcia/vaultwarden/releases/latest | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/' | cut -c 1-)
|
||||
echo "VAULTWARDEN_REF=$LATEST_TAG" >> $GITHUB_ENV
|
||||
echo "Latest Vaultwarden version: $LATEST_TAG"
|
||||
|
||||
- name: Build Debian package for MySQL
|
||||
run: ./build.sh -d mysql -o bookworm -a amd64 -r $VAULTWARDEN_REF
|
||||
|
||||
- name: Build Debian package for SQLite
|
||||
run: ./build.sh -d sqlite -o bookworm -a amd64 -r $VAULTWARDEN_REF
|
||||
|
||||
- name: Upload Debian packages
|
||||
uses: actions/upload-artifact@v3
|
||||
with:
|
||||
name: debian-packages
|
||||
path: dist/*.deb
|
||||
|
||||
release:
|
||||
needs: build
|
||||
runs-on: ubuntu-latest
|
||||
if: success() && github.ref == 'refs/heads/master'
|
||||
|
||||
steps:
|
||||
- name: Download Debian packages
|
||||
uses: actions/download-artifact@v3
|
||||
with:
|
||||
name: debian-packages
|
||||
|
||||
- name: Create Release
|
||||
uses: softprops/action-gh-release@v1
|
||||
with:
|
||||
files: "*.deb"
|
||||
tag_name: ${{ env.VAULTWARDEN_REF }}
|
||||
name: Vaultwarden Debian Packages ${{ env.VAULTWARDEN_REF }}
|
||||
body: |
|
||||
Debian packages for Vaultwarden version ${{ env.VAULTWARDEN_REF }}.
|
||||
Includes builds for MySQL and SQLite database backends on bookworm/amd64.
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
VAULTWARDEN_REF: ${{ github.event.inputs.vaultwarden_ref || needs.build.outputs.VAULTWARDEN_REF }}
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user