diff --git a/_docs/local.md b/_docs/local.md index 1835582..45f64eb 100644 --- a/_docs/local.md +++ b/_docs/local.md @@ -4,6 +4,7 @@ title: Building Locally permalink: /local --- +Bluefin is cloud native, so all all the tooling can be run locally or on any server. ## Building Locally (Bluefin Example) @@ -29,54 +30,66 @@ permalink: /local ```bash sudo rpm-ostree rebase ostree-image-signed:docker://whatever/bluefin:latest ``` +# Justfile Documentation -# Justfile Overview +The `Justfile` in the `ublue-os/bluefin` repository defines various tasks for managing the build process, cleaning, validation, and ISO building. Here is a detailed breakdown of the tasks and their purposes: -This `Justfile` defines various tasks for managing and building container images and ISOs for a development environment. Here is an overview and some important points: +## Variables and Initial Setup +- `repo_organization`: Defines the organization name. +- `images`, `flavors`, `tags`: Associative arrays mapping different image, flavor, and tag names to their respective values. -### Aliases and Variables: -- `project_root` and `git_branch` variables are used to fetch the project's root directory and the current Git branch respectively. -- `run` is an alias for `run-container`. +## Tasks -### Default Task: -- `_default` task runs `just help`, which displays a help message. +### clean +Cleans the repository by removing build directories and the `previous.manifest.json` file. +- Uses `find *_build* -exec rm -rf {}` to remove directories and `rm -f previous.manifest.json` to delete the manifest file. -### Container and Image Management: -- `_container_mgr`: Executes a script to manage containers. -- `_base_image image`: Executes a script to set the base image. -- `_tag image target`: Executes a script to tag an image with a target. +### sudo-clean +Performs the same cleaning operations as `clean` but with elevated privileges using the `sudoif` function. -### Just Syntax Checking and Fixing: -- `just-check`: Checks the syntax of all `.just` files in the project. -- `just-fix`: Fixes the syntax of all `.just` files in the project. +### validate +Validates the combination of image, tag, and flavor provided as arguments. +- Checks if the provided image, tag, and flavor exist in the predefined associative arrays. +- Ensures that certain combinations (e.g., `gts` tag with `aurora` image) are not allowed. -### Build and Run Tasks: -- `build image="" target="" version=""`: Builds an image with specified parameters. -- `run-container image="" target="" version=""`: Runs a container with specified parameters. -- Commented out tasks (`run-booted-guest` and `run-booted-home`) suggest options for running booted images with different configurations. +### sudoif +A helper function to execute commands with elevated privileges if necessary. +- Uses `sudo` with `--askpass` if available, or directly if the user has root privileges. -### ISO Management: -- `build-iso image="" target="" version=""`: Creates an ISO from a local dev build image. -- `build-iso-installer-main image="" target="" version=""`: Creates an ISO using `build-container-installer:main`. -- `run-iso image="" target="" version=""`: Runs an ISO. -- `build-iso-ghcr image="" target="" version=""`: Creates an ISO from the current GHCR image. +### build +Builds an image with specified parameters (image, tag, flavor, and rechunk). +- Validates the input parameters, determines the image name, base image, target, Fedora version, and kernel release. +- Uses `podman build` to create the container image with appropriate build arguments and labels. +- Optionally calls the `rechunk` task if the `rechunk` parameter is set to 1. -### Cleanup and Listing: -- `clean`: Cleans the directory by removing ISOs and build files. -- `clean-images`: Removes built images. -- `list-images`: Lists built images. +### build-rechunk +A convenience task that calls the `build` task with the `rechunk` parameter set to 1. -### Private Help Task: -- `help`: Displays a help message explaining the usage of the Justfile. +### rechunk +Rechunks an image to optimize its storage. +- Ensures the image is already built and available in the local Podman store. +- Uses a series of `podman` commands to prune, create, and chunk the image. +- Updates permissions and cleans up temporary files and volumes. -### Specific Build Tasks: -- `bluefin`: Builds the `bluefin` image with `base` target and `gts` version. -- `bluefin-dx`: Builds the `bluefin` image with `dx` target and `gts` version. -- `bluefin-iso`: Builds an ISO for the `bluefin` image with `base` target and `gts` version. -- `bluefin-dx-iso`: Builds an ISO for the `bluefin` image with `dx` target and `gts` version. -- `aurora`: Builds the `aurora` image with `base` target and `stable` version. -- `aurora-dx`: Builds the `aurora` image with `dx` target and `stable` version. -- `aurora-iso`: Builds an ISO for the `aurora` image with `base` target and `stable` version. -- `aurora-dx-iso`: Builds an ISO for the `aurora` image with `dx` target and `stable` version. +### run +Runs a container from the built image. +- Validates the input parameters and ensures the image is built if not already available. +- Uses `podman run` to start the container interactively. -This `Justfile` is designed to streamline the process of building, running, and managing container images and ISOs in a development environment. The scripts in the `scripts` directory are responsible for the actual operations, while the `Justfile` provides an easy-to-use interface for developers. +### build-iso +Builds an ISO image from the container image. +- Validates the input parameters and determines the appropriate image name. +- Can pull the image from GHCR or use a locally built image. +- Generates a list of flatpaks to be included and creates the ISO using `podman run` with appropriate arguments. + +### build-iso-ghcr +A convenience task that calls the `build-iso` task with the `ghcr` parameter set to 1. + +### run-iso +Runs an ISO image in a virtualized environment. +- Validates the input parameters and ensures the ISO is built if not already available. +- Determines an available port and uses `podman run` to start the virtualized environment with the ISO. + +### changelogs +Tests changelogs for a specified branch. +- Uses a Python script to generate changelogs and outputs the results to specified files.