Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mrjackwills/oxker

A simple tui to view & control docker containers
https://github.com/mrjackwills/oxker

async docker rust terminal tokio tui

Last synced: 5 days ago
JSON representation

A simple tui to view & control docker containers

Awesome Lists containing this project

README 

        


	

	


	
oxker


	
A simple tui to view & control docker containers





	Built in Rust, making heavy use of ratatui & Bollard






	

		

	




- [Download & install](#download--install)

- [Run](#run)

- [Build step](#build-step)

- [Tests](#tests)



## Download & install



### Cargo

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



```shell

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**

```shell

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

```



**via ghcr.io**



```shell

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



```shell

nix run nixpkgs#oxker

```



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



```shell

nix-shell -p oxker

```



### AUR



oxker can be installed from the [AUR](https://aur.archlinux.org/packages/oxker) with using an [AUR helper](https://wiki.archlinux.org/title/AUR_helpers):



```shell

paru -S oxker

```



### Homebrew



oxker can be installed on macOS using [Homebrew](https://formulae.brew.sh/formula/oxker):



```shell

brew install oxker

```



### Pre-Built

See the pre-built binaries



or, download & install (x86_64 one liner)



```shell

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*



```shell

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

```



## Run



```shell

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.|

|```--no-stderr```| Do not include stderr output in logs.|

|```--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



```shell

cargo build --release

```



### Raspberry pi



requires docker & cross-rs



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



```shell

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



```shell

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 https://github.com/docker/for-linux/issues/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.



```shell

cargo test

```



Run some example docker images



using docker/docker-compose.yml;



```shell

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

```



or individually



```shell

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

```



```shell

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

```



```shell

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

```