{"id":13569959,"url":"https://github.com/ublue-os/boxkit","last_synced_at":"2025-06-17T10:14:28.440Z","repository":{"id":65966131,"uuid":"588021292","full_name":"ublue-os/boxkit","owner":"ublue-os","description":"Build your own custom OCI distrobox container","archived":false,"fork":false,"pushed_at":"2025-05-21T20:14:41.000Z","size":109,"stargazers_count":203,"open_issues_count":3,"forks_count":103,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-29T10:13:21.882Z","etag":null,"topics":["alpine","bash","boxkit","dotfiles","linux","oci","shell"],"latest_commit_sha":null,"homepage":"https://universal-blue.org","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ublue-os.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-01-12T06:10:22.000Z","updated_at":"2025-05-23T23:13:51.000Z","dependencies_parsed_at":"2023-04-26T21:48:43.000Z","dependency_job_id":"2041a622-a62a-4930-9c2f-681ee303712e","html_url":"https://github.com/ublue-os/boxkit","commit_stats":null,"previous_names":[],"tags_count":3,"template":true,"template_full_name":null,"purl":"pkg:github/ublue-os/boxkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ublue-os%2Fboxkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ublue-os%2Fboxkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ublue-os%2Fboxkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ublue-os%2Fboxkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ublue-os","download_url":"https://codeload.github.com/ublue-os/boxkit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ublue-os%2Fboxkit/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260336417,"owners_count":22993743,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alpine","bash","boxkit","dotfiles","linux","oci","shell"],"created_at":"2024-08-01T14:00:46.442Z","updated_at":"2025-06-17T10:14:23.427Z","avatar_url":"https://github.com/ublue-os.png","language":"Shell","funding_links":[],"categories":["Shell","bash"],"sub_categories":[],"readme":"# boxkit\n\n## What is boxkit ?\n\nboxkit is a set of GitHub actions and skeleton files to build custom toolbox and distrobox images. Basically, clone this repo, make any changes you need, and then generate your custom images.\n\nNote that boxkit can be used independently of Fedora or uBlue OS.\nboxkit requires you atleast understand the basics of [ContainerFiles](https://www.mankier.com/5/Containerfile) and [shell scripting.](https://www.shellscript.sh/)\n\n## Base images\n\nYou can use the Docker/OCI container image of practically any distribution as your base image to build your custom image off of. Note that the base images can also be used directly with distrobox/toolbox without any modifications.\n\nHere is a list of some base images you can use:\n\n- [toolbx Community images](https://github.com/toolbx-images/images)\n- [uBlue toolboxes](https://github.com/ublue-os/toolboxes)\n\nTry to derive your custom images from these base images so we can all help maintain them over time, you can't have bling without good stock!\n\nTag your image with `boxkit` to share with others!\n\n## How to use boxkit\n\n### How everything is organized\n\n- The ContainerFiles for the custom images are stored in the `ContainerFiles/` folder.\n- The setup scripts for the custom images (if needed) are stored in the `scripts/` folder.\n- The package lists for the setup scripts (if needed) are stored in the `packages/` folder.\n- The Github workflow that generates the images is `.github/workflows/build-boxkit.yml`\n\n### How to make your own images\n\n1. Fork this repo.\n2. Add the ContainerFiles for your custom images to the `ContainerFiles/` folder.\n3. Add the setup scripts you want to use for your custom images (if needed) to the `scripts/` folder.\n4. Add the package list you want to use for your custom images (if needed) to the `packages/` folder.\n5. Add the name of the ContainerFiles of your custom images to the following section in `build-boxkit.yml`:\n\n```yaml\njobs:\n  strategy:\n    matrix:\n      containerfile:\n      - [your_custom_image_1]\n      - [your_custom_image_2]\n```\n\n**Note:** \n- You can choose to only generate a single custom image if you want. \n- You can remove the boxkit and fedora-example images provided in the boxkit repo and only generate your own custom images.\n- The `scripts/` and `packages/` folders are optional, you can generate your custom images without them, but they are highly recommended to use.\n- The name of your custom image and ContainerFile **MUST** be the same. \u003cbr\u003e\n\n  e.g. If you want to create a custom image named *appbox-debian*, the corresponding ContainerFile must be named `appbox-debian` and must be stored inside the `ContainerFiles/` folder.\n- The URL for the generated images will be `ghcr.io/\u003cusername\u003e/\u003cimage_name\u003e` by default.\n\n### Signing your images\nAlthough optional, it is **Highly recommended** you use container signing for your images.\nTo sign your images, follow the steps below:\n\n1. [Install `cosign`.](https://docs.sigstore.dev/cosign/system_config/installation/)\n2. Generate cosign keypairs. \u003cbr\u003e\n   When it asks you to enter a password, **DONOT ENTER A PASSWORD,** Just press enter.\n\n   ```bash\n   cosign generate-key-pair\n   ```\n\n   This will create two files named `cosign.pub` and `cosign.key`, which are your public and private keys, respectively.\n3. Go to the repository settings of your forked boxkit github repo. (**NOT your GitHub/Account settings**)\n   - Go to *Security* \u003e *Secrets and variables* \u003e *Actions*\n   - Click on *New repository secret*\n   - Create a new secret named `SIGNING_SECRET`\n   - Copy the content inside your `cosign.key` file to the textbox that appears when you create the `SIGNING_SECRET` repository secret.\n   - Alternatively, you can use GitHub's CLI client.\n     ```bash\n     gh secret set SIGNING_SECRET \u003c cosign.key\n     ```\n\n   **DONOT SHARE YOUR `cosign.key` FILE OR `SIGNING_SECRET` PUBLICLY, STORE THE `cosign.key` FILE SOMEWHERE SECURE AND DONOT INCLUDE IT IN YOUR GIT REPOSITORY.**\n\n4. Delete the `cosign.pub` key that exists on the repository's root folder and copy the `cosign.pub` file you created to the repository's root folder.\n\nCongratulations, you have successfully enabled container signing for all your custom images.\n\n## Using the custom images\n\nWe use the default boxkit image as an example to show you how to create a distrobox/toolbox container using a custom image.\n\nIf you use distrobox:\n\n    distrobox create -i ghcr.io/ublue-os/boxkit -n boxkit\n    distrobox enter boxkit\n    \nIf you use toolbox:\n\n    toolbox create -i ghcr.io/ublue-os/boxkit -c boxkit\n    toolbox enter boxkit\n\n**NOTE:**\n- You can use `chezmoi` to pull down your dotfiles and set up git sync.\n- It is recommended to use the [Ptyxis](https://flathub.org/apps/app.devsuite.Ptyxis) terminal, which provides seamless integration with various podman/distrobox/toolbx containers. \n\n## Custom images built with boxkit\n\nHere is a list of some awesome custom images built using boxkit.\n\n- [DaVinci Box](https://github.com/zelikos/davincibox) - Container for DaVinci Resolve installation and runtime dependencies on Linux.\n- [obs-studio-portable](https://github.com/ublue-os/obs-studio-portable) - OCI container image of OBS Studio that bundles a curated collection of 3rd party plugins.\n- [bazzite-arch](https://github.com/ublue-os/bazzite-arch) - A ready-to-game Arch Linux based OCI designed for use exclusively in distrobox.\n\n## Verification\n\nThese images are signed with sisgstore's [cosign](https://docs.sigstore.dev/quickstart/quickstart-cosign/). You can verify the signature by downloading the `cosign.pub` key from this repo and running the following command:\n\n    cosign verify --key cosign.pub ghcr.io/ublue-os/boxkit\n    \nIf you're forking this repo you should [read the docs](https://docs.github.com/en/actions/security-guides/encrypted-secrets) on keeping secrets in github. You need to [generate a new keypair](https://docs.sigstore.dev/cosign/key_management/signing_with_self-managed_keys/) with cosign. The public key can be in your public repo (your users need it to check the signatures), and you can paste the private key in Settings -\u003e Secrets -\u003e Actions.\n\n![Alt](https://repobeats.axiom.co/api/embed/7c5f037d792c6deb1946e5bc040f64a0fc8abeab.svg \"Repobeats analytics image\")\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fublue-os%2Fboxkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fublue-os%2Fboxkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fublue-os%2Fboxkit/lists"}