feat: add custom image support

Author: helton

README.md

@@ -17,8 +17,12 @@ hbox offers the following features:
 - **Support for Pipes**: Supports the use of pipes in `hbox run`, enabling efficient command chaining.
 - **Convenient Shims**: Creates `shims` (alias shortcuts) for all installed packages, simplifying command entry from `hbox run <package alias> <commands>` to `<package alias> <commands>`.
 - **Accessible Internal Binaries**: Provides direct access to internal binaries within images. Users can override the default entrypoint to access essential tools and utilities within containers directly.
-- **Customizable Environment Variables**: Allows setting environment variables for each package, enabling finer control over runtime configurations.]()
+- **Customizable Environment Variables**: Allows setting environment variables for each package, enabling finer control over runtime configurations.
 - **Support for Docker and Podman**: Provides seamless support for both Docker and Podman container engines, offering flexibility in container runtime choices.
+- **Custom Images**:
+  - **Building Custom Images**: Allows users to build custom images on demand, either replacing existing packages or introducing new ones. Users can define build contexts, Dockerfiles, and build arguments within the configuration file.
+  - **Dynamic Build Arguments**: Supports dynamic and user-defined build arguments, using internal variables like **hbox_package_name** and **hbox_package_version** to tailor the build process to specific needs.
+  - **Registry and Local Images**: Manages images pulled from registries and locally built images, providing flexibility in how images are sourced and utilized within the hbox environment.
 
 ## Installation
 
@@ -250,7 +254,7 @@ The configuration below is for index (`$HBOX_DIR/index/<shard>/<package>.json`)
 
 | Property                | Type      | Description                                                                                                                                                                                                                                      |
 |-------------------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `image`                 | `string`  | The Docker image to be used for the package. Example: `"docker.io/busybox"`                                                                                                                                                                      |
+| `image`                 | `object`  | The image configuration, which can include build instructions. Example: `{ "name": "hbox.${hbox_package_name}", "build": { "context": "/path/to/context", "dockerfile": "Dockerfile", "args": { "VERSION": "${hbox_package_version}" }}}`        |
 | `ports`                 | `array`   | An array of port mappings for the container. Each port mapping has a `host` and `container`. Example: `[{"host": 8090, "container": 8091}, {"host": 8091, "container": 8092}]`                                                                   |
 | `volumes`               | `array`   | An array of volume mappings for the container. Each volume mapping has a `source` and `target`. Example: `[{"source": ".", "target": "/app"}]`                                                                                                   |
 | `current_directory`     | `string`  | The working directory inside the container. Example: `"/app"`                                                                                                                                                                                    |
@@ -260,7 +264,7 @@ The configuration below is for index (`$HBOX_DIR/index/<shard>/<package>.json`)
 
 #### Property Details
 
-- **image**: Specifies the Docker image to be used. This is a required property for defining the container image from which the package will be run.
+- **image**: Specifies the image configuration, which can include build instructions. This allows for dynamic and user-defined build arguments, using internal variables like **hbox_package_name** and **hbox_package_version**.
 
 - **ports**: Defines the port mappings between the host and the container. Each port mapping includes:
     - `host`: The port on the host machine.
@@ -292,7 +296,9 @@ Example of a `$HBOX_DIR/index/g/golang.json`:
 
 ```json
 {
-  "image": "docker.io/golang",
+  "image": {
+    "name": "docker.io/golang"
+  },
   "volumes": [
     {
       "source": ".",
@@ -326,7 +332,9 @@ Example of a `$HBOX_DIR/overrides/busybox.json`:
 
 ```json
 {
-  "image": "docker.io/busybox",
+  "image": {
+    "name": "docker.io/busybox"
+  },
   "ports": [
     {
       "host": 8090,
@@ -432,6 +440,61 @@ If you enable logs in your `$HBOX_DIR/config.json` file, they will appear in the
 
 **Note**: Be careful when sharing your logs, as they may contain sensitive information such as API keys and environment variables.
 
+## How To
+
+### Creating packages from custom images
+
+To build custom images, you need to have a Dockerfile and a `.json` hbox config.
+
+Let's take the [pkl](https://pkl-lang.org/) as an example and create a `Dockerfile` for it:
+
+```Dockerfile
+FROM alpine:latest
+
+ARG VERSION=0.25.3
+
+RUN apk add --no-cache curl
+
+WORKDIR /usr/local/bin
+
+RUN curl -L -o pkl https://github.com/apple/pkl/releases/download/${VERSION}/pkl-alpine-linux-amd64 && \
+    chmod +x pkl
+
+ENTRYPOINT ["pkl"]
+```
+
+Since this is a custom package, we need to make it visible to hbox, so we will add it into the `$HBOX_DIR/overrides` folder as `pkl.json`.
+Let's also make use of hbox internal variables to pass values to the Dockerfile and tag the image accordingly:
+
+```json
+{
+  "image": {
+    "name": "hbox.${hbox_package_name}",
+    "build": {
+      "context": "/home/helton/dockerfiles",
+      "dockerfile": "/home/helton/dockerfiles/pkl.Dockerfile",
+      "args": {
+        "VERSION": "${hbox_package_version}"
+      }
+    }
+  }
+}
+```
+
+Now we can safely add `pkl` as a package into hbox
+
+```sh
+> hbox add pkl 0.25.3
+[+] Building 4.8s (8/8) FINISHED
+...
+ => => naming to docker.io/library/hbox.pkl:0.25.3  
+Added 'pkl' version '0.25.3'. Current version is '0.25.3'.
+> which pkl
+/home/helton/.hbox/shims/pkl
+> pkl --version
+Pkl 0.25.3 (Linux 5.15.0-1053-aws, native)
+```
+
 ## Next steps
 
 If you want to see my ideas for the future of the project, check out the [ROADMAP](ROADMAP.md).

src/commands.rs

@@ -192,7 +192,14 @@ pub fn configure_setting(path: String, value: Option<String>) -> Result<(), Box<
 fn do_add_package(name: &String, version: &String, package: Package) -> Result<(), Box<dyn Error>> {
     let mut new_package = package.clone();
     new_package.versions.current = version.clone();
-    if crate::runner::pull(&new_package) {
+
+    let should_add_package = if new_package.index.image.is_local() {
+        crate::runner::build(&new_package)
+    } else {
+        crate::runner::pull(&new_package)
+    };
+
+    if should_add_package {
         if !&package.index.only_shim_binaries {
             add_shim(&name, None)?;
         }

src/configs/context.rs

@@ -0,0 +1,21 @@
+use crate::packages::Package;
+
+pub struct Context {
+    package_name: String,
+    package_version: String,
+}
+
+impl Context {
+    pub fn from(package: &Package) -> Self {
+        Self {
+            package_name: package.name.clone(),
+            package_version: package.versions.current.clone(),
+        }
+    }
+
+    pub fn apply(&self, mut text: String) -> String {
+        text = text.replace("${hbox_package_name}", &self.package_name);
+        text = text.replace("${hbox_package_version}", &self.package_version);
+        text
+    }
+}

src/configs/index.rs

@@ -2,6 +2,7 @@ use crate::configs::app::AppConfig;
 use crate::serialization::parse_json;
 use log::debug;
 use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
 use std::error::Error;
 use std::path::Path;
 
@@ -45,7 +46,7 @@ impl IndexConfig {
 
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct Package {
-    pub image: String,
+    pub image: Image,
     pub volumes: Option<Vec<Volume>>,
     pub ports: Option<Vec<Port>>,
     pub current_directory: Option<String>,
@@ -58,7 +59,10 @@ pub struct Package {
 impl Package {
     pub fn new(name: &str) -> Self {
         Package {
-            image: format!("docker.io/{}", name),
+            image: Image {
+                name: format!("docker.io/{}", name),
+                build: None,
+            },
             volumes: None,
             ports: None,
             current_directory: None,
@@ -69,6 +73,25 @@ impl Package {
     }
 }
 
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct Image {
+    pub name: String,
+    pub build: Option<Build>,
+}
+
+impl Image {
+    pub fn is_local(&self) -> bool {
+        self.build.is_some()
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct Build {
+    pub context: String,
+    pub dockerfile: String,
+    pub args: Option<HashMap<String, String>>,
+}
+
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct Volume {
     pub source: String,

src/configs/mod.rs

@@ -1,4 +1,5 @@
 pub mod app;
+pub mod context;
 pub mod index;
 pub mod user;
 pub mod version;

src/packages.rs

@@ -65,7 +65,19 @@ impl Package {
     pub fn print(&self, verbose: bool) {
         info!("- [{}]", self.name);
         if verbose {
-            info!("  - image: {}", self.index.image);
+            info!("  - image:");
+            info!("    - name: {}", &self.index.image.name);
+            if let Some(build) = &self.index.image.build {
+                info!("    - build:");
+                info!("      - dockerfile: {}", build.dockerfile);
+                info!("      - context: {}", build.context);
+                info!("      - args:");
+                if let Some(args) = &build.args {
+                    for (arg_name, arg_value) in args.iter() {
+                        info!("        - {}: {}", arg_name, arg_value);
+                    }
+                }
+            }
             if let Some(ports) = &self.index.ports {
                 info!("  - ports:");
                 for port in ports {

src/runner.rs

@@ -1,3 +1,4 @@
+use crate::configs::context::Context;
 use crate::configs::index::Binary;
 use crate::configs::user::UserConfig;
 use crate::packages::Package;
@@ -8,9 +9,32 @@ use std::path::Path;
 use std::process::{Command, Stdio};
 use std::thread;
 
+pub fn build(package: &Package) -> bool {
+    let config = UserConfig::load().unwrap_or_default();
+    let context = Context::from(package);
+    let image_name = context.apply(package.index.image.name.clone());
+    let image = format!("{}:{}", image_name, package.versions.current);
+
+    let mut args = vec!["build".to_string(), "-t".to_string(), image];
+    if let Some(build) = &package.index.image.build {
+        args.push("-f".to_string());
+        args.push(build.dockerfile.clone());
+        if let Some(build_args) = &build.args {
+            for (key, value) in build_args {
+                args.push("--build-arg".to_string());
+                args.push(format!("{}={}", key, context.apply(value.clone())));
+            }
+        }
+        args.push(build.context.clone());
+    }
+
+    run_command_with_args(config.engine.as_str(), &args, None)
+}
+
 pub fn pull(package: &Package) -> bool {
     let config = UserConfig::load().unwrap_or_default();
-    let image = format!("{}:{}", package.index.image, package.versions.current);
+    let image_name = Context::from(package).apply(package.index.image.name.clone());
+    let image = format!("{}:{}", image_name, package.versions.current);
     run_command_with_args(config.engine.as_str(), &["pull".to_string(), image], None)
 }
 
@@ -77,9 +101,11 @@ fn add_default_flags(package: &Package, args: &mut Vec<String>) {
 }
 
 fn add_container_image(package: &Package, args: &mut Vec<String>) {
+    let context = Context::from(&package);
     args.push(format!(
         "{}:{}",
-        package.index.image, package.versions.current
+        context.apply(package.index.image.name.clone()),
+        package.versions.current
     ));
 }