Wolfi

https://github.com/wolfi-dev/os
Admin
Wolfi is a lightweight GNU software distribution and APK package repository designed for...
Tokens:9,669
Snippets:156
Trust Score:9.1
License:Apache-2.0
Update:4 months ago
Show doc for...
Tokens:
Raw
### Start Development Container

Source: https://github.com/wolfi-dev/os/blob/main/CONTRIBUTING.md

Starts a containerized development environment using the Wolfi SDK image, mounting the current working directory.

```shell
make dev-container
```

--------------------------------

### Run Wolfi Base Image

Source: https://github.com/wolfi-dev/os/blob/main/README.md

Quickly try out Wolfi by running the wolfi-base image. This command starts an interactive terminal session within the container.

```bash
docker run -it cgr.dev/chainguard/wolfi-base
```

--------------------------------

### Basic Caddyfile Configuration

Source: https://github.com/wolfi-dev/os/blob/main/caddy/index.html

Example of a Caddyfile to serve static files over HTTPS. Replace ':80' with your domain name and set the site root.

```caddyfile
yourdomain.com {
    root * /var/www/html
    file_server
}
```

--------------------------------

### Python 3 Wrapper Script Example

Source: https://github.com/wolfi-dev/os/blob/main/python-as-wrapper/README.md

This shell script is installed by python3-as-python3.X packages. It ensures that when 'python3' is invoked, the actual executable used is the specified python3.X version, which is crucial for correct sys.executable values and shbangs.

```shell
#!/bin/sh
exec python3.13 "$@"
```

--------------------------------

### Check Shbang Script Usage Example

Source: https://github.com/wolfi-dev/os/blob/main/python-as-wrapper/README.md

This example demonstrates how to use the 'check-shbang' utility within a test environment to verify that a script's shbang line points to the expected Python executable.

```yaml
test:
  environment:
    contents:
      packages:
        - check-shbang
    pipeline:
      - runs: |
          check-shbang python3.13 /usr/bin/my-entry-point
```

--------------------------------

### Example: Ignore Regex Patterns in Package Updates

Source: https://github.com/wolfi-dev/os/blob/main/docs/CI_CHECKS.md

Demonstrates how to use `ignore-regex-patterns` in a melange YAML file to prevent issues with development or debugging tags from upstream projects.

```yaml
update:
  enabled: true
  ignore-regex-patterns:
    - '.*x-.*'
  ...
```

--------------------------------

### Binary Version Check

Source: https://github.com/wolfi-dev/os/blob/main/pipelines/test/tw/INDEX.md

Checks the versions of specified binaries. Use this to ensure that the correct versions of command-line tools are installed.

```yaml
test:
  pipeline:
    - uses: test/tw/ver-check
      with:
        bins: myapp mycli
```

--------------------------------

### Check Installed Package Shell Scripts for Dependencies

Source: https://github.com/wolfi-dev/os/blob/main/pipelines/test/tw/INDEX.md

Use `shell-deps-check-packages` to verify that shell scripts within an installed package have all required commands available. This is crucial for ensuring package integrity.

```yaml
test:
  pipeline:
    - uses: test/tw/shell-deps-check-packages
      with:
        package: ${{package.name}}
```

--------------------------------

### Basic Ruby Package Testing Structure

Source: https://github.com/wolfi-dev/os/blob/main/CLAUDE.md

Defines a basic testing structure for Ruby packages, including environment setup and pipeline steps for gem checking and functionality verification.

```yaml
test:
  environment:
    contents:
      packages:
        - ruby-${{vars.rubyMM}}
  pipeline:
    - uses: test/tw/gem-check  # Verify gem installation
    - name: Verify library loading
      runs: |
        ruby -e "require 'gem_name'; puts 'Successfully loaded gem'"
    - name: Test basic functionality
      runs: |
        ruby <<-EOF
        require 'gem_name'

        begin
          # Actual functionality tests with sample inputs and expected outputs
          # Use raise to fail the test on unexpected results
          puts "All tests passed!"
        rescue => e
          puts "Test failed: #{e.message}"
          exit 1
        end
        EOF
```

--------------------------------

### Validate Systemd Service Files

Source: https://github.com/wolfi-dev/os/blob/main/pipelines/test/tw/INDEX.md

Use `verify-service` to validate systemd service/unit files for proper formatting and adherence to best practices. This pipeline is essential for packages installing systemd services.

```yaml
test:
  pipeline:
    - uses: test/tw/verify-service
```

--------------------------------

### Set up QEMU runner for kernel files

Source: https://github.com/wolfi-dev/os/blob/main/CLAUDE.md

This command is needed only once to download kernel files required for the QEMU runner.

```bash
make fetch-kernel
```

--------------------------------

### Switch to Let's Encrypt Staging Environment

Source: https://github.com/wolfi-dev/os/blob/main/caddy/index.html

Instructions to switch to Let's Encrypt's staging environment for testing TLS certificate acquisition to avoid rate limits.

```text
Switch to Let's Encrypt's staging environment to avoid being accidentally rate limited. Once you get everything else working, it's safe to switch back.
```

--------------------------------

### Build a package

Source: https://github.com/wolfi-dev/os/blob/main/CLAUDE.md

Standard command to build a specific package within the repository.

```bash
make package/<package-name>
```

--------------------------------

### Create GCP Compute Instance for Development

Source: https://github.com/wolfi-dev/os/blob/main/docs/DEVELOPMENT.md

Provisions a Google Cloud Platform Compute Engine instance with Container-Optimized OS for remote Docker development.

```bash
# Create a COS compute instance
gcloud compute instances create wolfi-os-dev \
    --image-project cos-cloud --image-family cos-101-lts \
    --zone us-central1-b \
    --machine-type c3-highcpu-176
```

--------------------------------

### Build Entire Wolfi OS

Source: https://github.com/wolfi-dev/os/blob/main/HOW_TO_PATCH_CVES.md

Run 'make' to build the entire Wolfi OS. This command is used for verifying package updates and build success.

```shell
make
```

--------------------------------

### Enable QEMU environment variables

Source: https://github.com/wolfi-dev/os/blob/main/CLAUDE.md

Set environment variables to enable the QEMU runner for builds and tests.

```bash
export QEMU_KERNEL_IMAGE=$(pwd)/kernel/boot/vmlinuz; export MELANGE_OPTS="--runner=qemu"
```

--------------------------------

### Build Wolfi Package with Build Log

Source: https://github.com/wolfi-dev/os/blob/main/docs/CI_CHECKS.md

Use this command to build a Wolfi package locally and generate a detailed build log. This is useful for running CI checks, like vulnerability scans, in a local development environment.

```bash
MELANGE_EXTRA_OPTS="--create-build-log"

```

--------------------------------

### Test a package

Source: https://github.com/wolfi-dev/os/blob/main/CLAUDE.md

Command to run tests for a specific package.

```bash
make test/<package-name>
```

--------------------------------

### Build an Individual Package

Source: https://github.com/wolfi-dev/os/blob/main/CONTRIBUTING.md

Builds a specific package using the 'make' command, which invokes melange. The build system includes a cache that can be enabled with USE_CACHE=yes.

```text
make package/<your-new-package-name>
```

```text
USE_CACHE=yes make package/<your-new-package-name>
```

--------------------------------

### Build a package using Docker

Source: https://github.com/wolfi-dev/os/blob/main/CLAUDE.md

Fallback command to build a package using Docker if the standard build fails.

```bash
make docker-package/<package-name>
```

--------------------------------

### Reproduce Individual Wolfi Package

Source: https://github.com/wolfi-dev/os/blob/main/REPRODUCIBILITY.md

Steps to test an individual Wolfi package for reproducibility. This involves building the package twice, moving the resulting package directories, and then comparing their checksums.

```bash
# doas make package/execline
...
# doas mv packages packages-1
# doas make package/execline
...
# doas mv packages packages-2
# sha256sum packages-1/$(uname -m)/*.apk | sed -e s:packages-1:packages-2:g | sha256sum -c
packages2/x86_64/execline-2.9.0.1-r0.apk: OK
packages2/x86_64/execline-dev-2.9.0.1-r0.apk: OK
```

--------------------------------

### CMakeLists.txt Configuration

Source: https://github.com/wolfi-dev/os/blob/main/cmake-3/wolfi-tests/CMakeLists.txt

Defines the project name, minimum CMake version, and the executable target. This is a standard CMake build script.

```cmake
project(HelloWorld)
cmake_minimum_required(VERSION 3.31.7...3.999)

add_executable(hello_wolfi main.cpp)
```

--------------------------------

### Scan Local Packages with Build Log

Source: https://github.com/wolfi-dev/os/blob/main/docs/CI_CHECKS.md

Utilize the `wolfictl scan` command with the `--build-log` option to perform vulnerability scans on your local packages using the generated build log. This helps identify potential CVEs before merging.

```bash
wolfictl scan .  --build-log
```

--------------------------------

### Explore APK contents

Source: https://github.com/wolfi-dev/os/blob/main/CLAUDE.md

Examines the contents of a built APK package using the `tar` command. Replace placeholders with actual package name and version.

```bash
tar tzv -f packages/$(uname -m)/<package-name-and-version>.apk
```

--------------------------------

### Check Site Files Permissions

Source: https://github.com/wolfi-dev/os/blob/main/caddy/index.html

Command to list files in the web root directory and check their permissions.

```bash
ls -la /var/www/html
```

--------------------------------

### Build a Single Package in Wolfi

Source: https://github.com/wolfi-dev/os/blob/main/HOW_TO_PATCH_CVES.md

Run 'make package/${PACKAGE_NAME}' to build a specific package. Replace ${PACKAGE_NAME} with the actual package name. This is a more targeted build verification.

```shell
make package/${PACKAGE_NAME}
```

--------------------------------

### Download Wolfi Package Collection

Source: https://github.com/wolfi-dev/os/blob/main/REPRODUCIBILITY.md

Use gsutil to download the entire Wolfi package collection for local verification. This command synchronizes the remote bucket to a local directory.

```bash
gsutil -m rsync gs://wolfi-production-registry-destination/os/ wolfi-packages/os/
```

--------------------------------

### Scan Package for Vulnerabilities

Source: https://github.com/wolfi-dev/os/blob/main/CONTRIBUTING.md

Scans a built package file for vulnerabilities using the wolfictl scan command. The command requires the path to the .apk file.

```shell
wolfictl scan ./packages/some-architecture/your-package-name-and-version.apk
```

--------------------------------

### Inspect Wolfi Base Image Details

Source: https://github.com/wolfi-dev/os/blob/main/README.md

Inside the wolfi-base container, you can inspect system details like the kernel version and OS release information.

```bash
uname -a
cat /etc/os-release
```

--------------------------------

### Create Advisory with wolfictl

Source: https://github.com/wolfi-dev/os/blob/main/HOW_TO_PATCH_CVES.md

Use the 'wolfictl adv create' command to add or update advisory data for a CVE in a package. Follow the interactive prompts to specify package, vulnerability, and fixed version.

```console
$ wolfictl adv create
Auto-detected distro: Wolfi

Package: █
Type to find a package. Ctrl+C to quit.
```

--------------------------------

### Scan for vulnerabilities

Source: https://github.com/wolfi-dev/os/blob/main/CLAUDE.md

Scans a package for vulnerabilities using `wolfictl`. Replace placeholders with actual package name and version.

```bash
wolfictl scan ./packages/$(uname -m)/<package-name-and-version>.apk
```

--------------------------------

### Bump Epoch for Dependent Packages

Source: https://github.com/wolfi-dev/os/blob/main/docs/DEVELOPMENT.md

Finds all YAML files in the current directory that depend on a specific package (e.g., 'go') and bumps their epoch using 'wolfictl'.

```bash
# Bump the epoch of all packages that depend on the latest version of go
grep -l " - go$" *.yaml | xargs wolfictl bump
```

--------------------------------

### Run Wolfi Lint Check Locally

Source: https://github.com/wolfi-dev/os/blob/main/docs/CI_CHECKS.md

Command to run the Wolfi linting check locally using the `wolfictl` tool to help iterate and fix failed lint rules.

```bash
wolfictl lint
```

--------------------------------

### NACK a CVE with wolfictl

Source: https://github.com/wolfi-dev/os/blob/main/HOW_TO_PATCH_CVES.md

Use 'wolfictl adv create' to record a NACK for a CVE if a package is not affected. Specify the package, vulnerability, status as 'not_affected', and a justification.

```console
$ wolfictl adv create
Auto-detected distro: Wolfi

Package: zlib
Vulnerability: CVE-2023-77777
Status:
  not_affected
Justification:
  vulnerable_code_not_present
```

--------------------------------

### Build a Package with Melange

Source: https://github.com/wolfi-dev/os/blob/main/docs/DEVELOPMENT.md

Builds a package using melange, requiring a privileged Docker environment. Appends local and remote repositories and uses a local signing key.

```bash
# build a package
docker run --privileged -v "$PWD":/work --entrypoint=melange --workdir=/work ghcr.io/wolfi-dev/sdk build --keyring-append local-melange.rsa.pub --keyring-append https://packages.wolfi.dev/os/wolfi-signing.rsa.pub --signing-key local-melange.rsa --repository-append https://packages.wolfi.dev/os  --repository-append /work/packages --empty-workspace --arch x86_64 $package
```

--------------------------------

### Create Docker Context for Remote Instance

Source: https://github.com/wolfi-dev/os/blob/main/docs/DEVELOPMENT.md

Creates a new Docker context named 'remote-wolfi-os-dev' that points to the SSH connection of the remote GCP instance.

```bash
# Use vscodes helper command to translate this into your ssh configuration
# Ensure you only copy the "ssh ..." portion, not the full path to `ssh`
#   >Remote-SSH: Add New SSH Host

# Create and use a new docker context associated with
docker context create remote-wolfi-os-dev --docker "host=ssh://compute.${INSTANCE_ID}"
```

--------------------------------

### Check Caddy Home Directory Permissions

Source: https://github.com/wolfi-dev/os/blob/main/caddy/index.html

Command to check the permissions of the Caddy home directory.

```bash
ls -la /var/lib/caddy
```

--------------------------------

### Generate Melange Signing Key

Source: https://github.com/wolfi-dev/os/blob/main/docs/DEVELOPMENT.md

Creates a local melange signing key pair for package development. Mounts the current directory to /src within the container.

```bash
# create a local development melange signing key
docker run -v $(pwd):/src --entrypoint=melange ghcr.io/wolfi-dev/sdk keygen /src/local-melange.rsa
```

--------------------------------

### View Caddy Logs

Source: https://github.com/wolfi-dev/os/blob/main/caddy/index.html

Command to view the logs for the Caddy service.

```bash
journalctl --no-pager -u caddy
```

--------------------------------

### Check Binaries for Runtime Library Dependencies

Source: https://github.com/wolfi-dev/os/blob/main/pipelines/test/tw/INDEX.md

Use `ldd-check` to verify that all shared library dependencies for binaries are resolvable. This pipeline is useful for ensuring runtime executability.

```yaml
test:
  pipeline:
    - uses: test/tw/ldd-check
```

--------------------------------

### Verify C/C++ Header File Compilation

Source: https://github.com/wolfi-dev/os/blob/main/pipelines/test/tw/INDEX.md

Use `header-check` to verify that C/C++ header files have valid syntax and includes. This pipeline ensures the correctness of header files in packages.

```yaml
test:
  pipeline:
    - uses: test/tw/header-check
```

--------------------------------

### Environment Variable Configuration for Python Wrappers

Source: https://github.com/wolfi-dev/os/blob/main/python-as-wrapper/README.md

The python3-as-env and python-as-env packages allow dynamic selection of the Python version via environment variables. Set PYTHON3_AS or PYTHON_AS to a specific python3.X executable to control which Python interpreter is invoked.

```shell
export PYTHON3_AS=python3.13
```

```shell
export PYTHON_AS=python3.10
```

--------------------------------

### Check Shell Scripts for Command Dependencies

Source: https://github.com/wolfi-dev/os/blob/main/pipelines/test/tw/INDEX.md

Use `shell-deps.check` to verify that shell scripts have all necessary command dependencies and are compatible with busybox. This pipeline helps ensure script portability.

```yaml
test:
  pipeline:
    - uses: test/tw/shell-deps-check
      with:
        files: "**/bin/*"
        path: /usr/bin
```

--------------------------------

### GitHub Action for Release Monitor Update

Source: https://github.com/wolfi-dev/os/blob/main/docs/UPDATES.md

This snippet shows how a GitHub Action can be used to query the Release Monitor REST API for new package versions. It's designed to send a single request per package per day to avoid overloading the API.

```yaml
      - name: Update packages
        uses: wolfi-dev/actions/melange-update@v0.0.1
        with:
          # Use release-monitoring.org as the backend
          backend: release-monitoring.org
```

--------------------------------

### Apply Patch to C Dependency

Source: https://github.com/wolfi-dev/os/blob/main/docs/CI_CHECKS.md

When a CVE fix is not yet released upstream for a C dependency, create a patch file in the Wolfi repo and apply it using the melange `patch` pipeline. Ensure the patch source is referenced.

```yaml
  - uses: patch
    with:
      # Patch source: https://patch-diff.githubusercontent.com/raw/madler/zlib/pull/843.patch
      patches: CVE-2023-45853.patch
```

--------------------------------

### Fetch SSH Command for Remote Access

Source: https://github.com/wolfi-dev/os/blob/main/docs/DEVELOPMENT.md

Retrieves the SSH command equivalent for connecting to a GCP instance via IAP, useful for configuring remote Docker contexts.

```bash
# Get the instance id
INSTANCE_ID=gcloud compute instances list --format "json(id)" --filter "name=packager-relaxing-bat" | jq -er '.[].id'

# Fetch the ssh equivalent of gcloud's IAP ssh helper command
gcloud compute ssh --zone "us-central1-b" "packager-relaxing-bat" --tunnel-through-iap --dry-run
```

--------------------------------

### Ensure Package Contains No Documentation Files

Source: https://github.com/wolfi-dev/os/blob/main/pipelines/test/tw/INDEX.md

Use `no-docs` to ensure a package does not contain any documentation files. This is important for runtime-only or specialized packages.

```yaml
test:
  pipeline:
    - uses: test/tw/no-docs
```

--------------------------------

### Lint YAML file after update

Source: https://github.com/wolfi-dev/os/blob/main/CLAUDE.md

Ensures proper formatting of YAML files after modifications.

```bash
./lint.sh <filename.yaml>
```

--------------------------------

### Check DNS Records

Source: https://github.com/wolfi-dev/os/blob/main/caddy/index.html

Command to query DNS records for a domain, useful for verifying A/AAAA records.

```bash
dig example.com
```

--------------------------------

### Reload Caddy Configuration

Source: https://github.com/wolfi-dev/os/blob/main/caddy/index.html

Command to reload the Caddy configuration after making changes to the Caddyfile.

```bash
systemctl reload caddy
```

--------------------------------

### Lint YAML files

Source: https://github.com/wolfi-dev/os/blob/main/CLAUDE.md

Lints YAML files using the provided script. Specify a filename to lint a single file.

```bash
./lint.sh [filename.yaml]
```

--------------------------------

### Verify Package Symlinks

Source: https://github.com/wolfi-dev/os/blob/main/pipelines/test/tw/INDEX.md

Use `symlink-check` to verify that symlinks in packages point to valid targets and to detect absolute symlinks. This pipeline helps prevent broken links.

```yaml
test:
  pipeline:
    - uses: test/tw/symlink-check
```

--------------------------------

### Check Caddy Service Status

Source: https://github.com/wolfi-dev/os/blob/main/caddy/index.html

Command to check the current status of the Caddy service.

```bash
systemctl status caddy
```

--------------------------------

### Update Go Dependency Version

Source: https://github.com/wolfi-dev/os/blob/main/HOW_TO_PATCH_CVES.md

Use this command within a melange pipeline's `runs` block to update a Go dependency to a specific version. Ensure this runs after source fetching and before the build.

```yaml
go get golang.org/x/text@v0.3.8
go mod tidy
```

--------------------------------

### Basic Package Type Validation

Source: https://github.com/wolfi-dev/os/blob/main/pipelines/test/tw/INDEX.md

Performs a basic validation of the package type. This is a fundamental check for any package.

```yaml
test:
  pipeline:
    - uses: test/tw/devpackage
```

--------------------------------

### Verify Package Contains Specific Files

Source: https://github.com/wolfi-dev/os/blob/main/pipelines/test/tw/INDEX.md

Use `contains-files` to verify that a package contains expected files. This pipeline is useful for asserting the presence of critical files.

```yaml
test:
  pipeline:
    - uses: test/tw/contains-files
      with:
        files: "/usr/bin/myapp /etc/myapp/config.yaml"
```

--------------------------------

### Debug test failures

Source: https://github.com/wolfi-dev/os/blob/main/CLAUDE.md

Command to debug test failures, requires a TTY.

```bash
make test-debug/<package-name>
```

--------------------------------

### Add Patch to Melange Pipeline

Source: https://github.com/wolfi-dev/os/blob/main/HOW_TO_PATCH_CVES.md

Add a 'patch' pipeline item to the Melange YAML file for a package to apply a downloaded patch. Ensure the patch file name matches the CVE ID.

```yaml
- uses: patch
  with:
    patches: CVE-2018-25032.patch
```

--------------------------------

### Validate Python Package Dependencies

Source: https://github.com/wolfi-dev/os/blob/main/pipelines/test/tw/INDEX.md

Use `pip-check` to validate Python package dependencies and detect version conflicts. This is essential for maintaining a stable Python environment.

```yaml
test:
  pipeline:
    - uses: test/tw/pip-check
```

--------------------------------

### Update Package Epoch for Shared Object Changes

Source: https://github.com/wolfi-dev/os/blob/main/docs/CI_CHECKS.md

When a shared object version changes, increment the epoch field in the package's YAML file to ensure downstream dependencies are updated correctly. This is a manual step required when the 'so name check' CI fails.

```yaml
package:
  name: libfoo
  epoch: 0 // need to increment this by one
```
Tokens:
Raw