{"id":29822305,"url":"https://github.com/uber/makisu","last_synced_at":"2025-07-29T01:02:54.817Z","repository":{"id":52716008,"uuid":"155477605","full_name":"uber-archive/makisu","owner":"uber-archive","description":"Fast and flexible Docker image building tool, works in unprivileged containerized environments like Mesos and Kubernetes.","archived":true,"fork":false,"pushed_at":"2021-04-20T10:38:19.000Z","size":8134,"stargazers_count":2403,"open_issues_count":64,"forks_count":155,"subscribers_count":42,"default_branch":"master","last_synced_at":"2025-07-22T08:52:59.619Z","etag":null,"topics":["ci-cd","container","docker","docker-image","kubernetes","mesos","uber"],"latest_commit_sha":null,"homepage":"","language":"Go","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/uber-archive.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-10-31T01:03:55.000Z","updated_at":"2025-07-16T06:21:48.000Z","dependencies_parsed_at":"2022-08-21T20:40:11.121Z","dependency_job_id":null,"html_url":"https://github.com/uber-archive/makisu","commit_stats":null,"previous_names":["uber/makisu"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/uber-archive/makisu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uber-archive%2Fmakisu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uber-archive%2Fmakisu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uber-archive%2Fmakisu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uber-archive%2Fmakisu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uber-archive","download_url":"https://codeload.github.com/uber-archive/makisu/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uber-archive%2Fmakisu/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267612616,"owners_count":24115494,"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","status":"online","status_checked_at":"2025-07-28T02:00:09.689Z","response_time":68,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["ci-cd","container","docker","docker-image","kubernetes","mesos","uber"],"created_at":"2025-07-29T01:01:15.241Z","updated_at":"2025-07-29T01:02:54.808Z","avatar_url":"https://github.com/uber-archive.png","language":"Go","readme":"\n![Makisu](assets/logo/Lockup.svg \"Makisu Logo\")\n\n[![Build Status](https://travis-ci.com/uber/makisu.svg?branch=master)](https://travis-ci.com/uber/makisu)\n[![GoReportCard](https://goreportcard.com/badge/github.com/uber/makisu)](https://goreportcard.com/report/github.com/uber/makisu)\n[![Github Release](https://img.shields.io/github/release/uber/makisu.svg)](https://github.com/uber/makisu/releases)\n\n**This project will be deprecated and be archived by 4th of May 2021**\n\nThe makisu project is no longer actively maintained and will soon be archived. Please read the details [in this issue](https://github.com/uber/makisu/issues/365).\n\nMakisu is a fast and flexible Docker image build tool designed for unprivileged containerized environments such as Mesos or Kubernetes.\n\nSome highlights of Makisu:\n\n* Requires no elevated privileges or containerd/Docker daemon, making the build process portable.\n* Uses a distributed layer cache to improve performance across a build cluster.\n* Provides control over generated layers with a new optional keyword [`#!COMMIT`](#explicit-commit-and-cache), reducing the number of layers in images.\n* Is Docker compatible. Note, the Dockerfile parser in Makisu is opinionated in some scenarios. More details can be found [here](docs/PARSER.md).\n\nMakisu has been in use at Uber since early 2018, building thousands of images every day across 4\ndifferent languages. The motivation and mechanism behind it are explained in https://eng.uber.com/makisu/.\n\n\n- [Building Makisu](#building-makisu)\n- [Running Makisu](#running-makisu)\n  - [Makisu anywhere](#makisu-anywhere)\n  - [Makisu on Kubernetes](#makisu-on-kubernetes)\n- [Using Cache](#using-cache)\n  - [Configuring distributed cache](#configuring-distributed-cache)\n  - [Explicit Commit and Cache](#explicit-commit-and-cache)\n- [Configuring Docker Registry](#configuring-docker-registry)\n- [Comparison With Similar Tools](#comparison-with-similar-tools)\n- [Contributing](#contributing)\n- [Contact](#contact)\n\n\n# Building Makisu\n\n## Building Makisu image\n\nTo build a Docker image that can perform builds inside a container:\n```\nmake images\n```\n\n## Building Makisu binary and build simple images\n\nTo get the makisu binary locally:\n```\ngo get github.com/uber/makisu/bin/makisu\n```\nFor a Dockerfile that doesn't have RUN, makisu can build it without Docker daemon, containerd or runc:\n```\nmakisu build -t ${TAG} --dest ${TAR_PATH} ${CONTEXT}\n```\n\n# Running Makisu\n\nFor a full list of flags, run `makisu build --help` or refer to the README [here](docs/COMMAND.md).\n\n## Makisu anywhere\n\nTo build Dockerfiles that contain RUN, Makisu needs to run in a container.\nTo try it locally, the following snippet can be placed inside your `~/.bashrc` or `~/.zshrc`:\n```shell\nfunction makisu_build() {\n    makisu_version=${MAKISU_VERSION:-latest}\n    cd ${@: -1}\n    docker run -i --rm --net host \\\n        -v /var/run/docker.sock:/docker.sock \\\n        -e DOCKER_HOST=unix:///docker.sock \\\n        -v $(pwd):/makisu-context \\\n        -v /tmp/makisu-storage:/makisu-storage \\\n        gcr.io/uber-container-tools/makisu:$makisu_version build \\\n            --commit=explicit \\\n            --modifyfs=true \\\n            --load \\\n            ${@:1:${#@}-1} /makisu-context\n    cd -\n}\n```\nNow you can use `makisu_build` like you would use `docker build`:\n```shell\n$ makisu_build -t myimage .\n```\nNote:\n* Docker socket mount is optional. It's used together with `--load` for loading images back into Docker daemon for convenience of local development. So does the mount to /makisu-storage, which is used for local cache. If the image would be pushed to registry directly, please remove `--load` for better performance.\n* The `--modifyfs=true` option let Makisu assume ownership of the filesystem inside the container. Files in the container that don't belong to the base image will be overwritten at the beginning of build.\n* The `--commit=explicit` option let Makisu only commit layer when it sees `#COMMIT` and at the end of the Dockerfile. See [\"Explicit Commit and Cache\"](#explicit-commit-and-cache) for more details.\n\n## Makisu on Kubernetes\n\nMakisu makes it easy to build images from a GitHub repository inside Kubernetes. A single pod (or job) is\ncreated with an init container, which will fetch the build context through git or other means, and place\nthat context in a designated volume. Once it completes, the Makisu container will be created and executes\nthe build, using that volume as its build context.\n\n### Creating registry configuration\n\nMakisu needs registry configuration mounted in to push to a secure registry.\nThe config format is described in [documentation](docs/REGISTRY.md).\nAfter creating configuration file on local filesystem, run the following command to create the k8s secret:\n```shell\n$ kubectl create secret generic docker-registry-config --from-file=./registry.yaml\nsecret/docker-registry-config created\n```\n\n### Creating Kubernetes job spec\n\nTo setup a Kubernetes job to build a GitHub repository and push to a secure registry, you can refer to our Kubernetes job spec [template](examples/k8s/github-job-template.yaml) (and out of the box [example](examples/k8s/github-job.yaml)) .\n\nWith such a job spec, a simple `kubectl create -f job.yaml` will start the build.\nThe job status will reflect whether the build succeeded or failed\n\n# Using cache\n\n## Configuring distributed cache\n\nMakisu supports distributed cache, which can significantly reduce build time, by up to 90% for some of Uber's code repos.\nMakisu caches docker image layers both locally and in docker registry (if --push parameter is provided), and uses a separate key-value store to map lines of a Dockerfile to names of the layers.\n\nFor example, Redis can be setup as a distributed cache key-value store with this [Kubernetes job spec](examples/k8s/redis.yaml).\nThen connect Makisu to redis cache by passing `--redis-cache-addr=redis:6379` argument.\nIf the Redis server is password-protected, use `--redis-cache-password=password` argument.\nCache has a 14 day TTL by default, which can be configured with `--local-cache-ttl=14d` argument.\n\nFor more options on cache, please see [Cache](docs/CACHE.md).\n\n## Explicit commit and cache\n\nBy default, Makisu will cache each directive in a Dockerfile. To avoid committing and caching everything, the layer cache can be further optimized via explicit caching with the `--commit=explicit` flag.\nDockerfile directives may then be manually cached using the `#!COMMIT` annotation:\n\n```Dockerfile\nFROM node:8.1.3\n\nADD package.json package.json\nADD pre-build.sh\n\n# A bunch of pre-install steps here.\n...\n...\n...\n\n# A step to be cached. A single layer will be committed and cached here on top of base image.\nRUN npm install #!COMMIT\n\n...\n...\n...\n\n# The last step of the last stage always commit by default, generating and caching another layer.\nENTRYPOINT [\"/bin/bash\"]\n```\nIn this example, only 2 additional layers on top of base image will be generated and cached.\n\n# Configuring Docker Registry\n\nFor the convenience to work with any public Docker Hub repositories including library/.*, a default config is provided:\n```\nindex.docker.io:\n  .*:\n    security:\n      tls:\n        client:\n          disabled: false\n      // Docker Hub requires basic auth with empty username and password for all public repositories.\n      basic:\n        username: \"\"\n        password: \"\"\n```\nRegistry configs can be passed in through the `--registry-config` flag, either as a file path of as a raw json blob (converted to json using [yq](https://github.com/kislyuk/yq)):\n```\n--registry-config='{\"gcr.io\": {\"uber-container-tools/*\": {\"push_chunk\": -1, \"security\": {\"basic\": {\"username\": \"_json_key\", \"password\": \"\u003cescaped key here\u003e\"}}}}}'\n```\nFor more details on configuring Makisu to work with your registry client, see the [documentation](docs/REGISTRY.md).\n\n# Comparison With Similar Tools\n\n### Bazel\n\nWe were inspired by the Bazel project in early 2017. It is one of the first few tools that could build Docker compatible images without using Docker or any form of containerizer.\nIt works very well with a subset of Docker build scenarios given a Bazel build file. However, it does not support `RUN`, making it hard to replace most docker build workflows.\n\n### Kaniko\n\nKaniko provides good compatibility with Docker and executes build commands in userspace without the need for Docker daemon, although it must still run inside a container. Kaniko offers smooth integration with Kubernetes, making it a competent tool for Kubernetes users.\nOn the other hand, Makisu has some performance tweaks for large images with multi-phase builds by avoiding unnecessary disk scans, and offers more control over cache generation and layer size through #!COMMIT, make it optimal for complex workflows.\n\n### BuildKit / img\n\nBuildKit and img depend on runc/containerd and supports parallel stage executions, whereas Makisu and most other tools execute Dockefile in order.\nHowever, BuildKit and img still need seccomp and AppArmor to be disabled to launch nested containers, which is not ideal and may not be doable in some production environments.\n\n# Contributing\n\nPlease check out our [guide](docs/CONTRIBUTING.md).\n\n# Contact\n\nTo contact us, please join our [Slack channel](https://join.slack.com/t/uber-container-tools/shared_invite/enQtNTIxODAwMDEzNjM1LWIwYzIxNmUwOGY3MmVmM2MxYTczOTQ4ZDU0YjAxMTA0NDgyNzdlZTA4ZWVkZGNlMDUzZDA1ZTJiZTQ4ZDY0YTM).\n","funding_links":[],"categories":["Build tools","Docker Images","Misc","Tools and Libraries","Go"],"sub_categories":["Observability","Builder","Development Tools"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuber%2Fmakisu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuber%2Fmakisu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuber%2Fmakisu/lists"}