github.com/Racer159/jackal@v0.32.7-0.20240401174413-0bd2339e4f2e/docs/5-jackal-tutorials/8-custom-init-packages.md (about)

     1  # Creating a Custom 'init' Package
     2  
     3  ## Introduction
     4  
     5  In most cases the default Jackal 'init' Package will provide what you need to get started deploying packages into the air gap, however there are cases where you may want to tweak this package to tailor it for your target environment. This could include adding or removing components or including hardened versions of components specific to your use case.
     6  
     7  In this tutorial, we will demonstrate how to build a custom [Jackal 'init' Package](../3-create-a-jackal-package/3-jackal-init-package.md) with `jackal package create`.
     8  
     9  When creating a Jackal 'init' package, you must have a network connection so that Jackal can fetch all of the dependencies and resources necessary to build the package. If your version of the 'init' package is using images from a private registry or is referencing repositories in a private repository, you will need to have your credentials configured on your machine for Jackal to be able to fetch the resources.
    10  
    11  ## System Requirements
    12  
    13  - For the default `init` package you will require an Internet connection to pull down the resources Jackal needs.
    14  
    15  ## Prerequisites
    16  
    17  Before beginning this tutorial you will need the following:
    18  
    19  - The [Jackal](https://github.com/Racer159/jackal) repository cloned: ([git clone instructions](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository))
    20  - Jackal binary installed on your $PATH: ([Installing Jackal](../1-getting-started/index.md#installing-jackal))
    21  - (if building a local [`jackal-agent`](../8-faq.md#what-is-the-jackal-agent)) The [Docker CLI](https://docs.docker.com/desktop/) installed and the tools to [Build your own CLI](../2-the-jackal-cli/0-building-your-own-cli.md)
    22  
    23  ## Building the init-package
    24  
    25  Creating the jackal 'init' package is as simple as creating any other package. All you need to do is run the `jackal package create` command within the Jackal git repository.
    26  
    27  ```bash
    28  $ cd jackal # Enter the jackal repository that you have cloned down
    29  $ jackal version
    30  vX.X.X
    31  $ git checkout vX.X.X # checkout the version that corresponds to your jackal version
    32  # Run the command to create the jackal package where the AGENT_IMAGE_TAG matches your jackal version
    33  $ jackal package create . --set AGENT_IMAGE_TAG=vX.X.X
    34  # Type `y` when prompted and then hit the enter key
    35  ```
    36  
    37  :::tip
    38  
    39  For development if you omit the `AGENT_IMAGE_TAG` Jackal will build a Jackal Agent image based on the source code within the Jackal git repository you cloned.
    40  
    41  :::
    42  
    43  :::note
    44  
    45  Prior to v0.26.0 `AGENT_IMAGE_TAG` was `AGENT_IMAGE` and would be set like: `jackal package create . --set AGENT_IMAGE=agent:vX.X.X`
    46  
    47  :::
    48  
    49  When you execute the `jackal package create` command, Jackal will prompt you to confirm that you want to create the package by displaying the package definition and asking you to respond with either `y` or `n`.
    50  
    51  <iframe src="/docs/tutorials/package_create_init.html" height="500px" width="100%"></iframe>
    52  
    53  :::tip
    54  
    55  You can skip this confirmation by adding the `--confirm` flag when running the command. This will look like: `jackal package create . --confirm`
    56  
    57  :::
    58  
    59  After you confirm package creation, Jackal will create the Jackal 'init' package in the current directory. In this case, the package name should look something like `jackal-init-amd64-vX.X.X.tar.zst`, although it might differ slightly depending on your system architecture.
    60  
    61  ## Customizing the 'init' Package
    62  
    63  The above will simply build the init package as it is defined for your version of Jackal. To build something custom you will need to make some modifications.
    64  
    65  The Jackal 'init' Package is a [composed Jackal Package](../3-create-a-jackal-package/2-jackal-components.md#composing-package-components) made up of many sub-Jackal Packages. The root `jackal.yaml` file is defined at the root of the Jackal git repository.
    66  
    67  ### Swapping Images
    68  
    69  As of v0.26.0 you can swap the `registry` and `agent` images by specifying different values in the `jackal-config.toml` file at the root of the project or by overriding them as we did above with `--set` on the command line. This allows you to swap these images for hardened or enterprise-vetted versions like those from [Iron Bank](https://repo1.dso.mil/dsop/opensource/Racer159/jackal/jackal-agent).
    70  
    71  For other components, or older versions of Jackal, you can modify the manifests of the components you want to change in their individual packages under the `packages` folder of the Jackal repo.
    72  
    73  :::tip
    74  
    75  If your enterprise uses pull-through mirrors to host vetted images you can run the following command to create a Jackal 'init' package from those mirrors (where `<registry>.enterprise.corp` are your enterprise mirror(s)):
    76  
    77  ```bash
    78  $ jackal package create . --set AGENT_IMAGE_TAG=vX.X.X \
    79    --registry-override docker.io=dockerio.enterprise.corp \
    80    --registry-override ghcr.io=ghcr.enterprise.corp \
    81    --registry-override quay.io=quay.enterprise.corp
    82  ```
    83  
    84  And if you need even more control over the exact Agent, Registry, and Gitea images you can specify that with additional `--set` flags:
    85  
    86  ```bash
    87  $ jackal package create . \
    88  --set AGENT_IMAGE_TAG=$(jackal version) \
    89  --set AGENT_IMAGE="opensource/jackal" \
    90  --set AGENT_IMAGE_DOMAIN="custom.enterprise.corp" \
    91  --set REGISTRY_IMAGE_TAG=2.8.3 \
    92  --set REGISTRY_IMAGE="opensource/registry" \
    93  --set REGISTRY_IMAGE_DOMAIN="custom.enterprise.corp" \
    94  --set GITEA_IMAGE="custom.enterprise.corp/opensource/gitea:v1.21.0-rootless"
    95  ```
    96  
    97  ⚠️ - The Gitea image is different from the Agent and Registry in that Jackal will always prefer the `rootless` version of a given server image. The image no longer must be tagged with `-rootless`, but it still needs to implement the [Gitea configuration of a rootless image](https://github.com/go-gitea/gitea/blob/main/Dockerfile.rootless). If you need to change this, edit the `packages/gitea` package.
    98  
    99  You can find all of the `--set` configurations by looking at the `jackal-config.toml` in the root of the repository.
   100  
   101  :::
   102  
   103  ### Removing Components
   104  
   105  You may not need or want all of the components in your 'init' package and may choose to slim down your package by removing them. Because the [Jackal Package is composed](../3-create-a-jackal-package/2-jackal-components.md#composing-package-components) all you need to do is remove the component that imports the component you wish to exclude.
   106  
   107  ## Troubleshooting
   108  
   109  ### Unable to read jackal.yaml file
   110  
   111  <iframe src="/docs/tutorials/package_create_error.html" height="120px" width="100%"></iframe>
   112  
   113  :::info Remediation
   114  
   115  If you receive this error, you may not be in the correct directory. Double-check where you are in your system and try again once you're in the correct directory with the jackal.yaml file that you're trying to build.
   116  
   117  :::