Running BuildKit in rootless mode increases your security and flexibility when building container images, especially on multi-user systems or CI environments where root privileges are restricted. This method uses a dedicated user and systemd service for isolation and automation, ensuring clean operation without elevated permissions. Docker is installed to provide a familiar runtime for container operations, while RootlessKit bridges the gap needed for rootless containerization.

Prerequisites#

  • Ubuntu (24.04+, fresh or existing)
  • Sudo privileges

Installation Steps#

1. Download and Extract BuildKit#

Download the BuildKit tarball and extract it to /opt/buildkit:

sudo mkdir -p /opt/buildkit
cd /opt/buildkit
sudo wget https://github.com/moby/buildkit/releases/download/v0.25.0/buildkit-v0.25.0.linux-amd64.tar.gz
sudo tar --strip-components=1 -xzvf buildkit-v0.25.0.linux-amd64.tar.gz

This will place BuildKit binaries into /opt/buildkit, making them accessible for your dedicated user and service.

2. Install Docker#

Update your repositories and install Docker from the official Docker repository:

sudo apt update
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt update
sudo apt install -y docker-ce

Docker provides the runtime that BuildKit can use when building container images.

3. Create BuildKit User#

Create a system user to run BuildKit with minimal permissions:

sudo adduser buildkituser --disabled-password --gecos ""

This user will only be used for BuildKit processes, keeping your system secure and clean.

4. Install RootlessKit#

Install RootlessKit, which is required to run BuildKit in rootless mode:

sudo apt install -y rootlesskit

RootlessKit helps simulate root privileges for BuildKit without requiring actual root access.

5. Create BuildKit Systemd Service and config#

Create BuildKit config at /opt/buildkit/buildkitd.toml

[worker.oci]
  # Specify the directory for the cache (optional)
  # cache = "/opt/buildkit/cache"

[grpc]
  addr = "unix:///opt/buildkit/buildkit.sock"

Create the BuildKit system service file at /etc/systemd/system/buildkit.service:

[Unit]
Description=BuildKit
After=network.target

[Service]
User=buildkituser
ExecStart=/usr/bin/rootlesskit /opt/buildkit/bin/buildkitd --rootless --config /opt/buildkit/buildkitd.toml --addr unix:///opt/buildkit/buildkit.sock --otel-socket-path /opt/buildkit/otel-grpc.sock
Restart=always
WorkingDirectory=/opt/buildkit
Environment=HOME=/home/buildkituser

[Install]
WantedBy=default.target

This ensures BuildKit starts as a dedicated, rootless service on boot, isolated from other processes.

6. Enable and Start the Service#

Reload systemd, enable the service, and start it:

sudo systemctl daemon-reload
sudo systemctl enable buildkit
sudo systemctl start buildkit

Verify the status:

sudo systemctl status buildkit

Example Usage#

Once running, you can build images using BuildKit’s client:

/opt/buildkit/bin/buildctl --addr unix:///opt/buildkit/buildkit.sock build --frontend dockerfile.v0 --local context=. --local dockerfile=.

This command builds a Dockerfile in your current directory using BuildKit’s rootless service.

Running BuildKit as rootless with a dedicated user and systemd service is ideal for secure CI/CD pipelines, developer environments, and production systems. You gain improved isolation and increased safety, making container builds more robust and easier to audit.