dogi

dogi is a simple and transparent wrapper for docker run (and docker exec) to make common tasks easier. It allows using rootless containers, running GUIs, quickly mounting your current directory and much more!

Even though dogi was originally inspired by rocker and solves a similar problem (or the same), it aims to do so with minimum user effort. Additionally, it provides the ability to interact with the docker client directly (transparent).

# install binary
mkdir -pv ~/go/bin
wget -qO- https://github.com/ntorresalberto/dogi/releases/download/rolling/dogi-rolling-linux-amd64.tar.gz | tar xvz -C ~/go/bin

# add bash autocompletion
echo 'source <(dogi completion bash)' >> ~/.bashrc

# try it!
dogi run ubuntu

# update it easily
dogi update

Some optional setup steps might be required.

NOTE: You can also install from source: CGO_ENABLED=0 go install -a github.com/ntorresalberto/dogi@latest

Requirements

dogi relies on the docker engine CLI for its operations. Before using dogi, make sure:

• You have installed docker engine via the official guide. Docker installed through snap won't work, because dogi sometimes creates files and uses /tmp.
• You have the correct permissions to call docker cli withotu sudo. This can be setup with the post-installation steps.
• In order to use docker (and dogi) with GPU support, you must first follow the installation prerequisites instructions, and the configuration instructions. Otherwise, the following bug will appears :

docker : Error response from daemon: unknown or invalid runtime name: nvidia

Quickstart

---

• Examples
• Overview
  • For whom?
  • Design principles
  • Limitations
• For Developers
  • Compiling from source
• Optional Setup Steps

---

Examples

• Update dogi

    dogi update
    dogi update --commit=aee8c7f

• Launch a container capable of GUI applications

    dogi run ubuntu
    dogi run --no-user ubuntu # as root
    dogi run --home ubuntu # share your home directory inside container

• Open a new terminal inside an existing container

    dogi exec
    dogi exec --no-user # as root
    dogi exec <container-name>

• Launch a GUI command inside a container (xeyes is not installed in the ubuntu image by default)

    dogi run ubuntu -- bash -c "sudo apt install -y x11-apps && xeyes"
    dogi run ubuntu --no-user -- bash -c "apt update && apt install -y x11-apps && xeyes" # as root

    dogi run fedora -- bash -c "sudo dnf install -y xeyes && xeyes"
    dogi run fedora --no-user -- bash -c "dnf install -y xeyes && xeyes" # as root

• Launch an 3D accelerated GUI (opengl)

    dogi run ubuntu -- bash -c "sudo apt install -y mesa-utils && glxgears"
    dogi run ubuntu --no-user -- bash -c "apt install -y mesa-utils && glxgears" # as root

• Delete unused and/or dangling containers, images and volumes

    dogi prune

---

Overview

For whom?

You should find dogi useful if you:

• Run GUI applications inside docker containers
• Want to use containers as a development environment
• Run 3D accelerated applications inside docker containers (like opengl)
• Want to avoid using root inside containers instead of the default root
• Simply need to quickly mount your current directory to test something

Design principles

• transparent: dogi forwards any unrecognized arguments to docker, in case you ever need to do anything not currently supported.
• simple: aims to cover the most common use cases with the least user intervention (you shouldn't need to pass any extra flags/options most of the time). If you don't agree with the defaults, please say so.
• secure: there are many ways to expose the xorg server to containers, dogi tries to do it in the most secure way. Additionally, it proposes an easy way to avoid the potentially dangerous practice of root containers.
• minimalist: dogi thrives to have the least amount of dependencies and not do more than it needs.

Many (open source) hackers are proud if they achieve large amounts of code, because they believe the more lines of code they've written, the more progress they have made. The more progress they have made, the more skilled they are. This is simply a delusion.

from the suckless.org Manifest

Limitations

• Only supports debian-based images like ubuntu (because of apt commands used) and more recently fedora.

• Only supports X11 environments for GUI applications (because of xorg socket communication)

---

For developers

Installing from source

git clone https://github.com/ntorresalberto/dogi.git
cd dogi
make install
dogi -v         # test it!

Once installed, add autocompletion with:

echo 'source <(dogi completion bash)' >> ~/.bashrc

Optional setup steps

installing go

You need golang>=1.16 installed (check version with go version). On ubuntu, an updated version can easily be installed with one of these 2 ways:

sudo apt install golang         # ubuntu >= 22.04
sudo snap install go --classic

---

bash: dogi: command not found

This error message means your $PATH doesn't include the go binaries path. You can fix it like this or, if you only want to enable dogi, use:

echo "alias dogi=$(go env GOPATH)/bin/dogi" >> ~/.bashrc
source .bashrc

---

dogi: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.32' not found (required by dogi)

This error is usually caused by a container running an older version of glibc than your host system (where you compiled dogi). A possible cause of this is you didn't use CGO_ENABLED=0 in the go install, as specified in #quickstart.