{"id":13346977,"url":"https://github.com/oracle/smith","last_synced_at":"2025-03-12T08:31:06.900Z","repository":{"id":66212448,"uuid":"95492373","full_name":"oracle/smith","owner":"oracle","description":"Smith: A microcontainer builder","archived":true,"fork":false,"pushed_at":"2019-12-13T20:42:48.000Z","size":1030,"stargazers_count":605,"open_issues_count":6,"forks_count":41,"subscribers_count":36,"default_branch":"master","last_synced_at":"2024-11-15T10:43:07.475Z","etag":null,"topics":["containers","docker"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oracle.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2017-06-26T21:48:39.000Z","updated_at":"2024-11-08T10:26:17.000Z","dependencies_parsed_at":"2023-02-21T23:15:09.357Z","dependency_job_id":null,"html_url":"https://github.com/oracle/smith","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Fsmith","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Fsmith/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Fsmith/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Fsmith/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oracle","download_url":"https://codeload.github.com/oracle/smith/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243184447,"owners_count":20249978,"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":["containers","docker"],"created_at":"2024-07-29T20:01:30.847Z","updated_at":"2025-03-12T08:31:06.081Z","avatar_url":"https://github.com/oracle.png","language":"Go","readme":"# `smith` - microcontainer builder #\n\n![smith](https://github.com/oracle/smith/raw/master/smith.png\n\"smith\")\n\n## What is `smith`? ##\n\n`smith` is a simple command line utility for building\n[microcontainers](https://blogs.oracle.com/developers/the-microcontainer-manifesto)\nfrom rpm packages or oci images.\n\n## Principles of microcontainers ##\n\n1. A microcontainer only contains the process to be run and its direct\n   dependencies.\n\n2. The microcontainer has files with no user ownership or special permissions\n   beyond the executable bit.\n\n3. The root filesystem of the container should be able to run read-only. All\n   writes from the container should be into a directory called `/write`. Any\n   unique config that an individual container instance will need should be\n   placed into a directory called `/read`. Ephemeral files such as pid files\n   can be written to `/run`.\n\n## Building and Running `smith` ##\n\nYou can build and run `smith` either as:\n- A Docker image\n- A Binary\n\nBoth methods are described below, but __the Docker route is recommended__ as the simplest and easiest option.\n\n### Docker based `smith` ###\n\n#### Dependencies ####\n- Docker\n\n#### Method #### \n1.  Clone `smith`:\n\n`git clone https://github.com/oracle/smith.git`\n\n2.  Build `smith` Docker image using the Dockerfile provided, optionally adding your own docker-repo-id to the tag:\n\n`sudo docker build -t [\u003cdocker-repo-id\u003e/]smith .`\n\n3.  Set up an alias (or script) to run `smith` from the command line:\n```\nsmith(){\n    sudo docker run -it --rm \\\n    --privileged -v $PWD:/write \\\n    -v cache:/var/cache \\\n    -v /tmp:/tmp \\\n    -v mock:/var/lib/mock [\u003cdocker-repo-id\u003e/]smith $@\n}\n```\nYou should now be able to start building microcontainers (see below).\n \n### Binary `smith` ###\n\n\n[![wercker status](https://app.wercker.com/status/3795ec11f790da9b58d5acbdd1dafc9d/s/master \"wercker status\")](https://app.wercker.com/project/byKey/3795ec11f790da9b58d5acbdd1dafc9d)\n\nBuilding can be done via the Makefile:\n\n    make\n\n#### Dependencies ####\n##### Build #####\n- Docker\n- Go\n\nTo install go run `sudo yum install golang-bin` or `sudo apt install golang-go` as appropriate\n\nGo dependencies are vendored in the vendor directory.\n\n##### Runtime #####\n\nTo build from RPMs, `smith` requires:\n\n- mock\n\nmock can have issues with non - RPM distros.\n\n**If you have problems installing or running `smith` natively on a non - RPM distro, best advice is to build it and run it in a Docker container (see above)**\n\nmock can be installed on Debian/Ubuntu with some extra care (see below).  Specifically you need at least mock\n1.2.  Version 1.1.X will not work because the -r flag does not support abspath to the mock config file.\nBe aware that your `smith` builds may still fail.\n\nDebian/Ubuntu specific instructions (_Here be Dragons_):\n\n```sudo apt install mock createrepo yum```\n\n```\n# Fedora rawhide chroot (which mock uses by default) does not play well with\n# Debian, so point /etc/mock/default.cfg to EPEL 7 (6 on Ubuntu):\nsudo ln -s /etc/mock/epel-7-x86_64.cfg /etc/mock/default.cfg \n```\n```\n# rpm on Debian has a patch to macros that messes up mock so undo it. Note\n# that updating your os will sometimes reset this file and you will have\n# to run this command again.\nsudo sed -i 's;%_dbpath\\t.*;%_dbpath\\t\\t%{_var}/lib/rpm;g' /usr/lib/rpm/macros\n```\n```\n# on debian/ubuntu for some reason yum tries to install packages for\n# multiple archs, so it is necessary to update the yum.conf section in\n# default.cfg to prevent that. If you switch your default.cfg you may\n# have to do this again.\nsudo sed -i '/\\[main\\]/a multilib_policy=best' /etc/mock/default.cfg\n```\n\nWhichever distro you are using check that your user is a member of the group mock:\n\n    $ groups\n\nIf your user is not a member of the group mock then add them:\n\n    $ usermod -aG mock \u003cyour_username\u003e\n\nOn Oracle Linux edit your /etc/mock/site-defaults.cfg and add:\n\n    config_opts['use_nspawn'] = False\n    \n#### Installing `smith` ####\n\nInstalling can be done via the Makefile:\n\n    sudo make install\n\n\n## Using `smith` ##\n\nTo use smith, simply create a smith.yaml defining your container and run\n`smith`. If you want to overlay additional files or symlinks, simply place them\ninto a directory called `rootfs` beside smith.yaml.\n\nIf you are building the same container multiple times without editing the\npackage line, the `-f` parameter will rebuild the container without\nreinstalling the package.\n\n## Building Microcontainers ##\n\nTo build a \"hello world\" container with `smith`:\n1. Create a new directory and cd to it\n\n```\nmkdir cat\ncd cat\n```\n\n2. Create a `smith.yaml` file with the following contents:\n```\npackage: coreutils\npaths:\n- /usr/bin/cat\ncmd:\n- /usr/bin/cat\n- /read/data\n```\n\n3. Create the rootfs directory.  Smith will put the contents of the `./rootfs` directory into the root directory of the image.\n\n`mkdir rootfs`\n\n4. Create the `read` directory under rootfs\n\n`mkdir rootfs/read`\n\n5.  Create the file `data` under `rootfs/read` with the following content:\n\n`Hello World!`\n\n- invoke smith with no parameters:\n\n`smith`\n\nYour image will be saved as image.tar.gz. You can change the name with a\nparameter:\n\n    smith -i cat.tar.gz\n\nSmith has a few other options which can be viewed using \"--help\"\n\n    smith --help\n\n## Build Types ##\n\nSmith can build from local rpm files or repositories. You can change the yum\nconfig by modifying your /etc/mock/default.cfg.\n\nSmith can also build directly from oci files downloaded via the download\ncommand, or an oci directly from a docker repository. Simply specify either in\nyour smith.yaml as package, for example:\n\n    package: https://registry-1.docker.io/library/fedora\n    paths:\n    - /usr/bin/cat\n    cmd:\n    - /usr/bin/cat\n    - /read/data\n\n\nTo build Smith directly from oci, the Docker command is slightly different:\n\n```bash\nsmith(){\n    docker run -it --rm \\\n    -v $PWD:/write \\\n    -v tmp:/tmp vishvananda/smith $@\n}\n```\n\n## Advanced Usage ##\n\nFor more detailed instructions on building containers, check out:\n- [Smith Lab](https://github.com/crush-157/smith-lab)\n- [How To Build a Tiny Httpd Container](https://hackernoon.com/how-to-build-a-tiny-httpd-container-ae622c37db39)\n\n## Upload ##\n\nYou can upload your image to a docker repository:\n\n    smith upload -r https://username:password@registry-1.docker.io/myrepo/cat -i cat.tar.gz\n\nImages will be uploaded to the tag `latest`. You can specify an alternative tag\nname to use appending it after a colon:\n\n    smith upload -r https://registry-1.docker.io/myrepo/cat:newtag\n\nIt automatically uploads to registry-1.docker.io using docker media types.\nOtherwise it tries to upload using oci media types.  If you want to upload to a\nprivate docker v2 registry that doesn't support oci media types, you can use\nthe -d switch:\n\n    smith upload -d -r https://myregistry.com/myrepo/cat -i cat.tar.gz\n\nYou can specify a tag name to upload to by appending it to the name\n\n## Download ##\n\n`smith` can also download existing images from docker repositories:\n\n    smith download -r https://registry-1.docker.io/library/hello-world -i hello-world.tar.gz\n\nIt will convert these to tar.gz oci layouts. The `latest` tag will be\ndownloaded. To download an alternative tag, append it after a colon:\n\n    smith download -r https://registry-1.docker.io/library/hello-world:othertag\n\n## Contributing ##\n\nSmith is an open source project. See [CONTRIBUTING](CONTRIBUTING.md) for\ndetails.\n\nOracle gratefully acknowledges the contributions to smith that have been made\nby the community.\n\n## Getting in touch ##\n\nThe best way to get in touch is Slack.\n\nClick [here](https://join.slack.com/t/oraclecontainertools/shared_invite/enQtMzIwNzg3NDIzMzE5LTIwMjZlODllMWRmNjMwZGM1NGNjMThlZjg3ZmU3NDY1ZWU5ZGJmZWFkOTBjNzk0ODIxNzQ2ODUyNThiNmE0MmI) to join the the [Oracle Container Tools workspace](https://oraclecontainertools.slack.com).\n\nThen join the [Smith channel](https://oraclecontainertools.slack.com/messages/C8BKS9HT5).\n\n## License ##\n\nCopyright (c) 2017, Oracle and/or its affiliates. All rights reserved.\n\nSmith is dual licensed under the Universal Permissive License 1.0 and the\nApache License 2.0.\n\nSee [LICENSE](LICENSE.txt) for more details.\n","funding_links":[],"categories":["Docker Images","Go","docker"],"sub_categories":["Builder"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foracle%2Fsmith","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foracle%2Fsmith","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foracle%2Fsmith/lists"}