conorsheehan1 / osxdocker

A CLI for working with docker on OSX

osxdocker

A CLI for working with docker on OSX

Currently it just handles docker logs, because I found it annoying starting up a screen session to get to the docker vm every time I wanted to clear logs. See: https://stackoverflow.com/questions/42527291/clear-logs-in-native-docker-on-mac

Install

# installs osxdocker and recommended docker and screen dependencies
brew install conorsheehan1/conorsheehan1/osxdocker

# installs osxdocker cli only, assumes you have docker and screen on your path
pip3 install osxdocker

Usage

# clear logs
osxdocker clear_log $some_container_name

# list available commands and flags
osxdocker

This cli uses https://github.com/google/python-fire
Check out the docs for more details on usage, setting up bash completion, etc.
Also worth noting:

1. Because the package uses fire, it can be imported like a normal python package. e.g.

   from osxdocker.docker_logs import DockerLogs
   DockerLogs().log_path('foo')

2. This cli doesn't support --version due to a quirk with fire.

   osxdocker version # works fine
   osxdocker --version # won't work

Edge cases and gotchas

Container names are unique, but containers are filtered by regex, so you can still run into issues.
e.g. You have two containers, named foo and foo_too.
osxdocker cat_log foo will fail because it matches foo and foo_too.
osxdocker cat_log ^foo$ will work because it matches foo exactly.

Developer notes

See docs/source/dev.md

osxdocker's Issues

Support id arg from cli

Most docker commands take an id or a name. e.g. docker logs
Currently (v0.1.2) osxdocker only supports names.

osxdocker/osxdocker/docker_logs.py

Line 41 in 356f9ed

def clear_log(self, container_name):

I see two main options:

1. Use one arg and figure out if it's a name or an id.

   def clear_logs(container_name_or_id):
       # this could be complicated / have edgecases. 
       # need to look into constraints for valid names and ids.
       if(container_name_or_id is name):
           # do something to convert to id

2. Use 2 kwargs.
   Would make cli more verbose, but handle edgecases.
   e.g. osxdocker clear_log --name foo instead of osxdocker clear_log foo.

   def getContainerId(id=None, name=None):
       if (name):
           # do something to convert to id
       return id

Look into supporting volumes

https://stackoverflow.com/questions/55603421/accessing-docker-volume-content-on-macos/55648186

Possible to manipulate volume data?

Typehints

• add typehints
• use sphinx-autodoc-typehints and remove types from doc strings
• remove comment from python version, must be >= 3.6 to use typhints anyway

possible:

• enforce types and runtime? e.g. pydantic
• run lint check for typehints with mypy e.g. https://github.com/timothycrosley/isort/blob/f58f985460ed354a2286c58738872d6795f6c5ed/scripts/lint.sh#L6

Generate docs

1. pydoc vs sphinx (chose sphinx)
2. type annotations?
3. add to readthedocs?

Run integration tests in github action

Can't run until docker is added to osx images.
https://github.community/t5/GitHub-Actions/Why-is-Docker-not-installed-on-macOS/m-p/39364#M3782

brew install docker docker-machine, brew cask install docker both failed.
https://github.com/ConorSheehan1/osxdocker/runs/561085373?check_suite_focus=true
https://github.com/ConorSheehan1/osxdocker/runs/561110666?check_suite_focus=true

Ensure version is in sync

The version of this project is tracked in three places.

1. as a git tag (needed for the deploy github action)
2. in __init__.py, (needed for the osxdocker version command)
3. in pyproject.toml (needed for flit / poetry)

Get something to keep these in sync.

• bumpversion? https://github.com/peritus/bumpversion? need to use fork for now: https://github.com/c4urself/bump2version
• issue with poetry? python-poetry/poetry#144

Add screenshots

Since I can't run the tests in CI, it'd be nice to show that it works. Even if it is only for a specific python and OSX version.

Add README.md to sphinx docs

Blocked by sphinx-doc/sphinx#7000

Split tests in unit and integration

• Unit tests should be runnable without docker / screen (local and CI).
• Integration tests require docker / screen , and won't be able to run on github actions until #5 is resolved.

Refactor to use python bindings for screen

e.g. https://github.com/Christophe31/screenutils

Would save on mix between os.system and subprocess calls.
Could refactor to allow users to pass through code to manipulate logs.

Match docker API

Blocked until API is stable. Must close the following first:

• #15

• major version change
• update screenshots
• match docker api:
  • cat_log -> logs
  • clear_log -> clear_logs
  • log_path -> logs_path

Automate publishing to pypi

1. ensure github tags and pypi tags are in sync.

Move config to pyproject.toml

• tool.isort
• tool.black

possible:

• c4urself/bump2version#42 (has feature approved tag, but last comment said won't do 🤷 )

Cache packages in github action

For example: https://github.com/python-poetry/poetry/blob/9734ca39e8f8c6b69b7cbb173d0f774d389b7d4f/.github/workflows/main.yml#L57

Ensure pyproject.toml and pipfile stay in sync

Try https://github.com/python-poetry/poetry
Use https://github.com/kk6/poetrify to convert Pipfile to pyproject.toml, then remove Pipfile
Pipenv also not supported by readthedocs readthedocs/readthedocs.org#3181
But poetry is readthedocs/readthedocs.org#6151

Add homebrew tap version to readme