{"id":19659972,"url":"https://github.com/samyak2/guntainer","last_synced_at":"2025-05-01T01:52:20.308Z","repository":{"id":47005864,"uuid":"382111068","full_name":"Samyak2/guntainer","owner":"Samyak2","description":"A minimal rootless container runtime on Linux","archived":false,"fork":false,"pushed_at":"2021-09-17T16:48:26.000Z","size":52,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-01T01:52:05.383Z","etag":null,"topics":["containers","go","golang","linux","linux-namespaces"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Samyak2.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-07-01T17:36:39.000Z","updated_at":"2024-08-27T08:05:04.000Z","dependencies_parsed_at":"2022-08-26T10:41:27.349Z","dependency_job_id":null,"html_url":"https://github.com/Samyak2/guntainer","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Samyak2%2Fguntainer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Samyak2%2Fguntainer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Samyak2%2Fguntainer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Samyak2%2Fguntainer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Samyak2","download_url":"https://codeload.github.com/Samyak2/guntainer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251810899,"owners_count":21647626,"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","go","golang","linux","linux-namespaces"],"created_at":"2024-11-11T15:44:54.118Z","updated_at":"2025-05-01T01:52:20.285Z","avatar_url":"https://github.com/Samyak2.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# guntainer\n\nA minimal rootless container implementation on Linux. ~~Copied from~~ Inspired by Liz Rice's amazing [talk](https://youtu.be/8fi7uSYlOdc) on implementing containers from scratch.\n\n## Features\n\n - *Rootless*: never use `sudo` to run a container\n - *Images*: guntainer can build container images, with a `Gunfile` to define the structure.\n\n## Getting started\n\nInstall using (Go 1.16+ recommended):\n```\ngo install github.com/Samyak2/guntainer@latest\n```\n(ensure `GOBIN` is in path)\n\n\nConfirm that the installation succeeded.\n```\nguntainer help\n```\n\nTo run a container image, use the `run` subcommand.\nSee [here](#run-examples) for more information and examples.\n```\nguntainer run --help\n```\n\nTo build a container image using a `Gunfile`, use the `build` subcommand.\nSee [here](#building-images) for more information and examples.\n```\nguntainer build --help\n```\n\n## Building images\n\nguntainer can build new images out of existing ones, in a similar way to `docker build`. Images are described using a `Gunfile`, whose format is very much a work-in-progress. Following is the structure of a Gunfile (at least the things that currently work):\n```Gunfile\nUsing \"\u003carchive_of_root_FS\u003e\"\n\nExec \"some command\"\n```\n\nMore examples can be found [here](./examples/).\n\nTo build the image from [example_02](./examples/02_alpine_vim/), we can use:\n```\nguntainer build example_02.tar examples/02_alpine_vim/Gunfile\n```\n\nThis will generate an `example_02.tar` which is the newly built image with `vim` installed. Run it using:\n```\nguntainer run example_02.tar /bin/sh\n```\n\nYou should be able to use `vim` inside the container now.\n\n## `run` Examples\n\nThese are examples of running an existing Linux distro inside guntainer.\n\n### Alpine\n\nGet the Alpine \"mini root filesystem\" from [here](https://alpinelinux.org/downloads/) ([direct link](https://dl-cdn.alpinelinux.org/alpine/v3.14/releases/x86_64/alpine-minirootfs-3.14.0-x86_64.tar.gz) of the specific version this was tested with).\n\nRun the container with (replace the archive path if necessary) (you can also use `sh` instead of `ash`):\n\n```sh\nguntainer run alpine-minirootfs-3.14.0-x86_64.tar.gz /bin/ash\n```\n\nMost programs will work. Running `hostname` should say `guntainer`.\n\nInternet will not work out of the box as no DNS servers are configured. Use the following to access internet (replace the IP address as necessary):\n```sh\necho \"nameserver 8.8.8.8\" \u003e /etc/resolv.conf\n```\n\n### Ubuntu\n\nGet the Ubuntu Base image from [here](http://cdimage.ubuntu.com/ubuntu-base/releases/) ([direct link](http://cdimage.ubuntu.com/ubuntu-base/releases/21.04/release/ubuntu-base-21.04-base-amd64.tar.gz) to the specific version used).\n\nRun using:\n```sh\nguntainer run ubuntu-base-21.04-base-amd64.tar.gz /bin/bash\n```\n\nRunning `hostname` should say `guntainer`.\n\nIssues:\n - `apt` will not work out of the box. Refer [this](https://github.com/opencontainers/runc/issues/2517#issuecomment-657139999) thread for [details](https://github.com/opencontainers/runc/issues/2517#issuecomment-764163674).\n\n    Workaround (pls don't run this outside a container):\n    ```sh\n    sed -i '/_apt/d' /etc/passwd\n    ```\n - Internet will not work out of the box. Workaround:\n    ```sh\n    echo \"nameserver 8.8.8.8\" \u003e /etc/resolv.conf\n    ```\n\n## TODO\n\n - [x] Better CLI using [cobra](https://github.com/spf13/cobra)\n - [ ] Use cgroups for resource limits\n - [ ] (a bit ambitious) be OCI compliant\n - [ ] Fix Ubuntu issues\n - [x] Dockerfile equivalent\n - [ ] Download images from URL, like go's package management\n - [ ] Figure out how to store metadata along with the built image. Could do it similar to docker images (OCI) or do something more hacky.\n - [ ] Optional logging - `-v` flag should enable more logs.\n\n## Resources\n\nIf you're looking to implement your own container runtime, these links are great to start with:\n - [Mythili Vutukuru's lecture](https://youtu.be/4BG-hE72r_I) on containers - provides a good overview of the Linux concepts behind containers (namespaces and cgroups)\n - [Containers From Scratch by Liz Rice](https://youtu.be/8fi7uSYlOdc) - most of the code is from this talk. Liz Rice implements it live on the stage while explaining how it works.\n    - The corresponding [code respository](https://github.com/lizrice/containers-from-scratch) is a good reference and also links to another slide deck for implementing rootless containers\n\n## Implementation details\n\n - The root FS archive is extracted in a temporary directory and `chroot`ed into. The directory is cleaned up once the container exits.\n - Rootless is implemented by mapping the current user's UID and GID to 0 (root) inside the container. This means that inside the container you are root while the same user outside the container is your user.\n - The Gunfile is implemented [here](./gunfile/). It uses [participle](https://github.com/alecthomas/participle) to parse the Gunfile and build an AST.\n - To save the built image I had to implement a custom tar wrapper to handle in-container symlinks. I called it [guntar](./guntar/).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamyak2%2Fguntainer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamyak2%2Fguntainer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamyak2%2Fguntainer/lists"}