mrjackwills/oxker

A simple tui to view & control docker containers

oxker

A simple tui to view & control docker containers

Built in Rust, making heavy use of ratatui & Bollard

• Download & install
• Run
• Build step
• Tests

Download & install

Cargo

Published on crates.io, so if you have cargo installed, simply run

cargo install oxker

Docker

Published on Docker Hub and ghcr.io, with images built for linux/amd64, linux/arm64, and linux/arm/v6

via Docker Hub

docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock:ro --pull=always mrjackwills/oxker

via ghcr.io

docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock:ro --pull=always ghcr.io/mrjackwills/oxker

Nix

Using nix flakes, oxker can be ran directly with

nix run nixpkgs#oxker

Without flakes, you can build a shell that contains oxker using

nix-shell -p oxker

AUR

oxker can be installed from the AUR with using an AUR helper:

paru -S oxker

Homebrew

oxker can be installed on macOS using Homebrew:

brew install oxker

Pre-Built

See the pre-built binaries

or, download & install (x86_64 one liner)

wget https://www.github.com/mrjackwills/oxker/releases/latest/download/oxker_linux_x86_64.tar.gz &&
tar xzvf oxker_linux_x86_64.tar.gz oxker &&
install -Dm 755 oxker -t "${HOME}/.local/bin" &&
rm oxker_linux_x86_64.tar.gz oxker

or, for automatic platform selection, download, and installation (to $HOME/.local/bin)

One should always verify script content before running in a shell

curl https://raw.githubusercontent.com/mrjackwills/oxker/main/install.sh | bash

Run

oxker

In application controls

button	result
( tab ) or ( shift+tab )	Change panel, clicking on a panel also changes the selected panel.
( ↑ ↓ ) or ( j k ) or ( PgUp PgDown ) or ( Home End )	Change selected line in selected panel, mouse scroll also changes selected line.
( enter )	Run selected docker command.
( 1-9 )	Sort containers by heading, clicking on headings also sorts the selected column.
( 0 )	Stop sorting.
( F1 ) or ( / )	Enter filter mode.
( e )	Exec into the selected container - not available on Windows.
( h )	Toggle help menu.
( m )	Toggle mouse capture - if disabled, text on screen can be selected.
( q )	Quit.
( s )	Save logs to $HOME/[container_name]_[timestamp].log, or the directory set by --save-dir.
( esc )	Close dialog.

Available command line arguments

argument	result
-d [number > 0]	Set the minimum update interval for docker information in milliseconds. Defaults to 1000 (1 second).
-r	Show raw logs. By default, removes ANSI formatting (conflicts with -c).
-c	Attempt to color the logs (conflicts with -r).
-t	Remove timestamps from each log entry.
-s	If running via Docker, will display the oxker container.
-g	No TUI, essentially a debugging mode with limited functionality, for now.
--host [string]	Connect to Docker with a custom hostname. Defaults to /var/run/docker.sock. Will use $DOCKER_HOST environment variable if set.
--save-dir [string]	Save exported logs into a custom directory. Defaults to $HOME.
--use-cli	Use the Docker application when exec-ing into a container, instead of the Docker API.

Build step

x86_64

cargo build --release

Raspberry pi

requires docker & cross-rs

64bit pi (pi 4, pi zero w 2)

cross build --target aarch64-unknown-linux-gnu --release

32bit pi (pi zero w)

Tested, and fully working on pi zero w, running Raspberry Pi OS 32 bit, the initial logs parsing can take an extended period of time if thousands of lines long, suggest running with a -d argument of 5000

cross build --target arm-unknown-linux-musleabihf --release

If no memory information available, try appending either /boot/cmdline.txt or /boot/firmware/cmdline.txt with

cgroup_enable=cpuset cgroup_enable=memory

see https://forums.raspberrypi.com/viewtopic.php?t=203128 and docker/for-linux#1112

Untested on other platforms

Tests

As of yet untested, needs work

The work has been done, so far the tests don't effect any running containers, but this may change in the future.

cargo test

Run some example docker images

using docker/docker-compose.yml;

docker compose -f ./docker/docker-compose.yml up -d

or individually

docker run --name redis -d redis:alpine3.19

docker run --name postgres -e POSTGRES_PASSWORD=never_use_this_password_in_production -d postgres:alpine3.19

docker run -d --hostname my-rabbit --name rabbitmq rabbitmq:3

oxker's Issues

[NEW FEATURE] Custom keybindings

First of all: Hi, great work on this tool! I'd like to start using it by integrating it into my neovim config. This is an awesome effort, thanks for the hard work.

Is your feature request related to a problem? Please describe.
I'm a bit frustrated by the lack of configuration for keybindings. Namely :

• Using tab to swap between panels isn't really part of my workflow. I'd prefer vim-style bindings such as using H and L to swap between panels for example.
• Using q to quit the app fits my workflow, but I got frustrated when I saw the help panel and I tried to discard it with q, which .. quit the app. Wish I could change that myself.

This is just me though, and I'm sure other people would love to customize the tool how they see fit. A follow-up to this issue is probably the ability to customize the colors of the app (the white text on pink background on the help panel in my terminal is .. very hard to read)

Describe the solution you'd like
Ideally the user would be able to have a keybindings file stored wherever deemed relevant (e.g. $HOME/.config/oxker/keybindings.ron).

Implementation-wise :

• A Config struct, that would contain a field keybindings: KeybindingsConfig should be constructed
• The config needs to be injected and stored in the InputHandler
• Documentation should be written to empower the user to write their own bindings

Regarding the format of the config file, there's a metric ton of alternatives, including :

• TOML, pretty standard for Rust
• JSON, pretty standard
• YAML, pretty standard for Docker
• RON, a bit foreign to pretty much everyone, but offers probably the nicest DX of all described alternatives if that matters to you

I really like gitui's documentation and technical choice (RON), but I fully acknowledge that it might not be the most welcoming choice, especially for non-Rust folks. Nothing more frustrating than learning about a new tool and seeing a config file with an extension that you've never seen before.

All in all, I think RON or TOML would be great choices. Let me know what you think.

Describe alternatives you've considered
I described alternatives for config languages above.
For larger customization purposes, programs such as neovim allow the user to customize everything with Lua, but this is because the customization goes waaay beyond the scope of keybindings.

Additional context
Looks like input_handler/mod.rs contains the list of hardcoded keybindings.
Some functions may need to be renamed, e.g. s_key, enter_key, tab_key and the likes.

[NEW FEATURE] container name should be left-aligned

I'd wish container name would be left aligned in the "Containers" table.

This happens regularly when using docker compose.

[BUG] Heading bar loading icon color & position

Describe the bug
The loading icon in the heading bar is black on purple, and can be hard to read.
Loading icon shifting heading titles, shouldn't effect the heading positions

To Reproduce
Restart any container to see loading icon, and they headings shift

Expected behavior
Icon should be more visible and obvious, and shouldn't shift the heading titles

Additional context
Change the span to white

[NEW FEATURE] Publish as Docker image

Is your feature request related to a problem? Please describe.

Would be great to have this tool published as a Docker image on the main Docker registry, and maybe ghcr.io and quay.io as well. This would allow running it anywhere where Docker is installed, without having to install any additional machinery.

Describe the solution you'd like

Having automated builds and publishing to popular Docker image registries.

Describe alternatives you've considered

None really 🤷

Additional context

Currently using another popular Docker container dashboard called ctop, and find oxker much nicer actually. Just would love to have it available as image so I could run it as follows:

docker run --rm -it --volume /var/run/docker.sock:/var/run/docker.sock:ro ghcr.io/mrjackwills/oxker:latest

[NEW FEATURE] Sort columns reset

Is your feature request related to a problem? Please describe.
Clicking a column will sort Ascending & Descending, but cannot reset the sort

Describe the solution you'd like
First click sorts ascending, second click sorts descending, third click removes all the sorts

[NEW FEATURE] List Port

Describe the solution you'd like
Add a column for exposed port(s) for each container - a single container could expose many ports, so need to think the best way to display this, and also if any all interfaces, or 127.0.0.1 etc, and local to host mappings

Additional context
Maybe, in a not to distant future, enable the user to select which columns should be visible, would need to save this data somewhere

[BUG] GHCR build issues

Describe the bug
The new release workflow is building 4 images for GHCR, but it should only build 3.
See package here

To Reproduce

1. Run workflow
2. see an "unknown/unknown" image

Expected behavior
should only build for linux/x86, linux/aarm64, and linux/armv6

[BUG] unwrap err on rebuild

Describe the bug
If oxker is running, and one rebuilds containers, oxker will error out with a unwrap error, related to app_data mod.rs 308:39

To Reproduce
Steps to reproduce the behavior:

1. Run oxker in one terminal window
2. Rebuild running containers in another window, with docker compose pull && docker compose up -d
3. See error :(

Expected behavior
Oxker should be able to handle rebuilt containers, should be removed from memory, and then re-added once rebuild is complete

[NEW FEATURE] Right click copy

Is your feature request related to a problem? Please describe.
Enable copying of information when user presses the right mouse button, and maybe also when pressing 'c' button?

Describe the solution you'd like
If containers selected, copies container id(?), if logs selected, copies single log line

[BUG] Malformed escape codes in docker logs causes panic

Describe the bug
Malformed color codes in docker log output cause panic (regardless of -c)

To Reproduce

1. Use software in a docker container which spews out partial ANSI escape codes, for example ESC[\n
2. Oxker panics here when trying to parse the log (inside cansi::v3::categorise_text)

Here is a minimal demo of such a panic:

use cansi::v3::categorise_text;

fn main() {
    let x = categorise_text("oops\x1b[\n");
    println!("{}", x[0].text);
}

Expected behavior
Oxker is robust to garbage in log output

Desktop (please complete the following information):

• OS: Linux

I understand this may be considered an upstream issue of the cansi crate; I've opened an issue there as well: colored-rs/cansi#7

[NEW FEATURE] about column layout

container names are on the right side of the table, plus and trunkated even if there's some space so it not too easy to understand what its a container name

(on the image above, first line is "bitwarden" and second is "cloudflared")

Maybe its some idea behind, but at least have an option to switch to more "regular" view with "names" as first column, aligned to left side and trunkated to... 15-20 characters will be very helpful

[NEW FEATURE] restart should use a different colour

Is your feature request related to a problem? Please describe.
When restarting a container, the columns are still coloured as green

Describe the solution you'd like
A container in a restarting state should use a none green (as current), nor red/yellow color

[NEW FEATURE] A failed healthcheck should make container not green

Is your feature request related to a problem? Please describe.
The tool fools me into a sense of comfort until I read (unhealthy) and realize the green row is in fact in a bad state. Failing healthchecks should make rows red.

Describe the solution you'd like
I expect a failed healthcheck to color the container row red, or yellow, or some other color than "OK green".

[BUG] Double key strokes when trying to navigate on Windows

Describe the bug
Whenever I try to navigate, it registers double key strokes. See the gif below:

Those were single key strokes, it happens with every command (changing panels, opening help modal, etc).

To Reproduce
Steps to reproduce the behavior:

1. try to navigate

Expected behavior
Single key strokes should be registered.

Desktop (please complete the following information):

• OS: Windows 10

Additional context
Terminal: Windows Terminal using PowerShell 7.4.2

[NEW FEATURE] export logs

Is your feature request related to a problem? Please describe.
Enable to export of logs to a .log(?) file

Describe the solution you'd like
On a key press - "e"? - export the selected containers logs to a file, made sure to strip of all ANSI formatting
Saved to a known location - home folder? - or allow user to choose

[BUG] - Memory displayed incorrect

Describe the bug
Hi, the memory stats does not match with the original docker stats. Dozzle for example shows the correct stats but ctop (which seems abandoned) has a similar problem with the memory stats as oxker.

To Reproduce
Steps to reproduce the behavior:

1. start oxker
2. show memory stats
3. compare with docker stats

Expected behavior
The memory stats should be the same as docker stats.

Desktop (please complete the following information):

• v0.6.0 - aarch64 - Raspberry Pi OS

[NEW FEATURE] Delete / Remove containers

Describe the solution you'd like
I would like an additional option to delete / remove containers. The current cotnainer options are start, pause, restart, and stop.

[NEW FEATURE] Memory column spacing

Is your feature request related to a problem? Please describe.
The each entry in the memory column are not aligned

            0 B / 0 B
  18.64 MB / 33.55 MB
   9.76 MB / 16.78 MB
176.90 MB / 268.44 MB

Describe the solution you'd like
All three sections, the memory, the slash, and the limit, should be aligned with each other

      0 B  /       0 B
 18.64 MB  /  33.55 MB
  9.76 MB  /  16.78 MB
176.90 MB  / 268.44 MB

Describe alternatives you've considered
Could just ignore this completely

[NEW FEATURE] Exec Shell - Open a container command line

Hi, I discovered Oxker only a short time ago and I am delighted. I love how simple it is and its beautiful interface. So far I have been using ctop, it is not as nice but it has a feature that is a must for me which is "Exec Shell", that is, I can connect to the container through the console. The truth is that I would like to replace ctop by oxker for my daily use.

I would like to know if there are future plans to implement the connection to the container.

Screenshots:
https://i.imgur.com/7wIpc14.jpg
https://i.imgur.com/64L4EQw.jpg

[NEW FEATURE] long term - detach logic

Detach the internal data logic from the terminal, so that it can be used in a gui application (i.e via Tauri), split into workspaces? Or separate crates - with the data logic having a public api?

Additional context
Don't expect this to happen any time soon

[BUG] Multi-line coloured log incorrectly coloured

Describe the bug
When executed using the -c flag, multi-line coloured log entries only the first line of said entry has a colour applied to it

Expected behavior
All lines should correctly be colourised

[BUG] created_at clash

Describe the bug
Multiple containers can have the same created_at timestamp, meaning sorting will result in different results

To Reproduce
Steps to reproduce the behavior:

1. use a docker-compose to create multiple containers at the same time
2. sort by any column 3 times, when reset, order might not be the same as the start

Expected behavior
When no SortedOrder is set, containers should be sorted by a consistent behaviour

Additional context
Should try to create a unique created_at, could append something, such as the hashed name/image/id, to the created at, to make unique, sortable, value

[NEW FEATURE] put container name next to Logs title

Describe the solution you'd like
Instead of "Logs 120/300", show "Logs 120/300 - my_container_name"

Additional context
Uses up more screen space, although currently is a border so shouldn't matter. Would need to make sure that container name isn't too long, maybe just accept first 32 chars of container name?

[NEW FEATURE] position for popups

Describe the solution you'd like
Supply both a Vertical(top, centre, bottom) and Horozontal(left, centre, right) enum to "centered_info" function, so that a popup dialog can be positioned in one of those 9 regions.
The popup_layout split would then take one of nine index options [0/1/2][0/1/2]

So that an info popup, e.g. when text has been copied, can be placed in a no distracting location

[BUG] Unable to access docker daemon

Describe the bug

Oxker will not start.

To Reproduce

1. oxker
2. See the screen with the message and auto exit.

Trying to run oxker with no-gui for debugging results in a permanent hang with no messages printed after

2023-07-19T15:35:29.173577Z  INFO oxker: in debug mode

Expected behavior

A screen similar to that which is in the README screenshot. Essentially oxker should be aware of docker contexts, but must be aware of $DOCKER_HOST if set.

Screenshots

Desktop (please complete the following information):

• OS: macOS
• Virtualization Solution: OrbStack without the symlinked socket

My socket is in ~/.orbstack/run/docker.sock.

Additional context

Setting $DOCKER_HOST does not help.

$ docker context ls
NAME          DESCRIPTION                               DOCKER ENDPOINT                                  ERROR
colima-vz-8   colima [profile=vz-8]                     unix:///Users/austin/.colima/vz-8/docker.sock
default       Current DOCKER_HOST based configuration   unix:///var/run/docker.sock
orbstack *    OrbStack                                  unix:///Users/austin/.orbstack/run/docker.sock

[BUG] issue freeze when click on CPU to show from high to low

Hi
Currently when i run
docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock:ro --pull=always mrjackwills/oxker

and i click on the CPU from high to low it freezes up

Thank you

[BUG] disable oxker commands

Describe the bug
When running via docker, if restart, pause, or exit, the oxker container, can cause havoc with the terminal output

Expected behavior
Shouldn't be allowed to send commands to the oxker container

[BUG] New filter feature (more like feedback, not a bug)

First of all: Thanks to everyone who has contributed to oxker and this feature :)

Describe the bug

The feature works as intended, however while I'm in the filtering mode the program is incredibly slow - it takes several seconds to enter a single character and changing the filtering field (Name, Image, etc.) is also quite slow.

To Reproduce
Steps to reproduce the behavior:

1. Start oxker
2. Press '/' to enter filtering mode
3. Enter a query term or press 'left' / 'right' to change filtering field

Expected behavior
Instant updates in the program as per input.

Desktop (please complete the following information):

• server1: Linux ubuntu 5.15.0-118-generic #128-Ubuntu SMP Fri Jul 5 09:28:59 UTC 2024 x86_64 x86_64 x86_64 GNU/Linux
• server2: Linux ubuntu 5.15.0-113-generic #123-Ubuntu SMP Mon Jun 10 08:16:17 UTC 2024 x86_64 x86_64 x86_64 GNU/Linux

Additional context
I run oxker on two servers with lots of computing power. On average, there are 60 running containers on each server. For reference, I sometimes use another docker monitoring tool (ctop, written in Go) which also has a filtering feature and there it works without any lag, but I'm not sure why as I am no Rust/Go expert.

Thanks a lot in advance.

[NEW FEATURE] Sortable headings

Is your feature request related to a problem? Please describe.
Containers are always listed in the same order - based on age

Describe the solution you'd like
Enable, by clicking, or via key presses, the change the order of the containers based on each column

[NEW FEATURE] Add filtering feature

Hello,

First I'd like to thank you for creating this great software. I use it daily.

Would it be possible to add a filtering feature (i.e. by container name, state, etc.)?

Thanks in advance.

[BUG] - Crash when sorting

Describe the bug
When (rapidly) re-sorting containers, the application can freeze crash

To Reproduce
Steps to reproduce the behavior:

1. repeatedly change the sort pattern, either with 1-9 or clicking on a header

Expected behavior
It shouldn't crash

Screenshots
n/a

Desktop (please complete the following information):
Ubuntu 24.04 arm64, with 15+ containers

Additional context
I think in the end the docker data needs to be in it's own tokio thread, using a messaging system to update and retrieve data, rather than using the current Arc<Mutex> system, would be a sizable change to implement correctly - although should probably be done.

Track `Cargo.lock`

I opened a pull request to package oxker for nix package manager. Nix is highly focused on reproducibility and as a result requires the Cargo.lock file to pin specific dependency versions, otherwise it is impossible to build a cargo project for nixpkgs. As a result I've had to generate the Cargo.lock into a patch file to apply before building. This isn't ideal and makes maintaining more difficult as I will have to generate this file for every update.

Tracking the Cargo.lock file also make sense outside of the nix ecosystem and is considered best practice for binary applications as stated in the cargo book.

[NEW FEATURE] exec container option

Is your feature request related to a problem? Please describe.
I want to easily "jump into" a docker container.

Describe the solution you'd like
A clear and concise description of what you want to happen. Add a "exec" to the right hand "option pane" and default the execution string to bash -l:

Describe alternatives you've considered
Manually executing the exec is fine, but defeats the purpose.

Additional context
Happy to submit a PR here—just point me in the right direction in the code to get started.

[BUG] Duplicate log entries

Describe the bug
Have, on occasion, seen duplicate log entries in the log panel

To Reproduce
So far difficult to replicate

Expected behavior
Should only display each log entry once

Fixes
Should always record timestamp with each log entry, maybe in a tuple (timestamp, log_entry), and then only insert into the log Vec (or ideally a HashSet), if the (timestamp, log_entry) is unique.
Would need to change the way the -t arg is interpreted in order to display, or not display, the timestamp