PODCUST(1)

NAME
podcust - Podman Custodian Documentation

PODMAN CUSTODIAN
Documentation StatusUpdates

Python utility to manage specific deployed podman containers in Fedora.

•   Free software: Licensed under the Parity License

•   Documentation: Read the Docs

  Getting Started

From a Fedora Workstation installation:

$ dnf copr enable iolaum/podcust
$ dnf install podcust

  Features

•   Deployment and management of transmission docker container image from linuxserver.io documented here.

  Credits

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.

INSTALLATION

  Stable release

To install Podman Custodian, run this command in your terminal:

$ pip install podcust

This is the preferred method to install Podman Custodian, as it will always install the most recent stable release.

If you don’t have pip installed, this Python installation guide can guide you through the process.

  From sources

The sources for Podman Custodian can be downloaded from the Github repo.

You can either clone the public repository:

$ git clone git://github.com/Iolaum/podcust

Or download the tarball:

$ curl -OJL https://github.com/Iolaum/podcust/tarball/master

Once you have a copy of the source, you can install it with:

$ python setup.py install

USAGE

To use Podman Custodian in a project:

import podcust

PODCUST

  podcust package

  Subpackages

  podcust.demo package

  Submodules

  podcust.demo.custodian module

Custodian Class for Demo container.

exception podcust.demo.custodian.ContainerHealthError(container_name, container_id)
    Bases: Exception

    Exception raised when a container fails it’s health check.

    Inspired from: https://www.programiz.com/python-programming/user-defined-exception

Parameters

•   container_name – Name of container image.

•   container_id – Running Container id of container type container_name message – explanation of the error

class podcust.demo.custodian.DemoCust(name: str = 'localhost/httpdemo')
    Bases: object

    Main class for handling the httpdemo container.

    The httpdemo container just spawns an a container with an apache web server service serving the Fedora Test page through http.

Parameters
    name – The Repository name of the image this class is custodian for.

activate_container()
    Activate a demo’s container httpd service.

build_demo_image()
    Build an image for the demo container. Use the dockerfile located at this folder.

    The command to build a container is: podman build -f Dockerfile -t httpdemo

deactivate_container()
    Deactivate a demo’s container httpd service.

find_exited_containers()
    Find all containers of demo type that have run and exited.

    You can see here a sample output of the command we use to find the containers we want to remove: # noqa: E501 $ podman ps -a CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 1b5fe6643ece localhost/httpdemo:latest /sbin/init 2 days ago Exited (0) 2 days ago 0.0.0.0:8080->80/tcp strange_wu 3ea6bf480c47 localhost/httpdemo:latest /bin/bash 2 days ago Exited (0) 2 days ago 0.0.0.0:8080->80/tcp funny_williams 63604b048bc9 registry.fedoraproject.org/fedora:latest /bin/bash 2 days ago Exited (0) 2 days ago practical_kowalevski b3e4d5b363ce localhost/httpdemo:latest /sbin/init 2 days ago Exited (137) 2 days ago 0.0.0.0:8080->80/tcp pedantic_tesla c4e4a6847c3d localhost/httpdemo:latest /bin/bash 2 days ago Exited (0) 2 days ago 0.0.0.0:8080->80/tcp jolly_volhard dc9bffeef1c2 registry.fedoraproject.org/fedora:latest /bin/bash 2 days ago Exited (0) 2 days ago 0.0.0.0:8080->80/tcp zealous_blackburn0

find_stored_image_id() -> List[str]
    This function looks if the system has an appropriate container image and returns the id of that image.

    Current implementation assumes that the first match is the one we are after.

    TODO: Specify what tag we want to match?

get_running_container_id()
    Get the container ID for a running container (of demo type).

health_check()
    Runs basic checks to test container’s functionality.

    Verifying health check inspired by: https://stackoverflow.com/a/51242/1904901

image_id: str

name: str

remove_stored_image()
    Removes a stored container image corresponding to the name the class has been instantiated to.

removed_exited_containers()
    Remove all containers of demo type that have run and exited.

    Remove an image with: podman container rm 3ea6bf480c47

run_container()
    Start running the demo container.

stop_container()
    Stop demo running container.

exception podcust.demo.custodian.MissingContainers(container_name)
    Bases: Exception

    Exception raised when not one containers of expected type are running.

    Inspired from: https://www.programiz.com/python-programming/user-defined-exception

Parameters
    container_name – Name of container image. message – explanation of the error

exception podcust.demo.custodian.MultipleContainers(container_id1, container_id2)
    Bases: Exception

    Exception raised when more than one containers of a type are running.

    Inspired from: https://www.programiz.com/python-programming/user-defined-exception

Parameters

•   container_id1 – First container id of container type

•   container_id2 – Second container id of container type. message – explanation of the error

  Module contents

  podcust.transmission package

  Submodules

  podcust.transmission.custodian module

Custodian Class for Transmission container.

Using the Linuxserver.io transmission container image

This module is responsible for setting up and maintaining the container.

The container is intended to live inside the users home directory, in a hardcoded location. Namely $HOME/transmission/. The container is deployed within a pod named transmission.

class podcust.transmission.custodian.TransmissionCust(name: str = 'ghcr.io/linuxserver/transmission')
    Bases: object

    Main class for handling the transmission container.

Parameters
    name – The full repository name of the image this class is custodian for.

deploy()
    Create a pod named transmission to deploy our container. For a successful deployment the following steps must take place:

•   Create the necessary folders, and give them proper permissions.

•   Write the proper kube yaml file that we ‘ll use to deploy the container.

•   Execute the podman play command to start the pod with the transmission container.

image_id: str

name: str

pull_latest_transmission_image()
    Pull latest transmission container image from linuxserver.io

    The relevant shell command is:

    $ podman pull ghcr.io/linuxserver/transmission

username: str

  Module contents

  Submodules

  podcust.cli module

Console script for podcust.

Useful documentation at: https://click.palletsprojects.com/en/7.x/quickstart/#nesting-commands https://click.palletsprojects.com/en/7.x/complex/

  podcust.platform module

Retrieve Information about the platform the package is running on.

podcust.platform.podman_exists()
    Check that the podman package is installed and working properly. Raise an OSError if the podman –version command does not complete successfully.

  podcust.podcust module

Main module.

  podcust.tools module

Common podcust tools.

podcust.tools.get_user_input(message: str)
    Present a message to the user and capture user’s response. Validates that the string is alphanumeric latin characters up to 30 length. (Wanting to avoid to have to deal with escapted characters and other weird input. Admittedly this should be trusted input but I m in favor of taking the precaution. 30 alphanumeric characters should allow for complex enough passwords.)

Args:
    message: Message to pring to the user.

Returns:
    Reply from the user. Note that this is intended to be a trusted input.

  Module contents

Top-level package for Podman Custodian.

CONTRIBUTING

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

  Types of Contributions

  Report Bugs

Report bugs at https://github.com/Iolaum/podcust/issues.

If you are reporting a bug, please include:

•   Your operating system name and version.

•   Any details about your local setup that might be helpful in troubleshooting.

•   Detailed steps to reproduce the bug.

  Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.

  Implement Features

Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.

  Write Documentation

Podman Custodian could always use more documentation, whether as part of the official Podman Custodian docs, in docstrings, or even on the web in blog posts, articles, and such.

  Submit Feedback

The best way to send feedback is to file an issue at https://github.com/Iolaum/podcust/issues.

If you are proposing a feature:

•   Explain in detail how it would work.

•   Keep the scope as narrow as possible, to make it easier to implement.

•   Remember that this is a volunteer-driven project, and that contributions are welcome :)

  Get Started!

Ready to contribute? Here’s how to set up podcust for local development.

1.  Fork the podcust repo on GitHub.

2.  Clone your fork locally.

    $ git clone git@github.com:your_name_here/podcust.git
    $ cd podcust

3.  From the root of the repository create a python virtual environment to use for our project. Install the project in editable mode along with developer dependencies.

    $ python3 -m venv venv
    $ source venv/bin/activate
    (venv) $ pip install -e .[dev]

4.  Create a branch for local development.

    $ git checkout -b name-of-your-bugfix-or-feature

    Now you can make your changes locally.

5.  When you’re done making changes, check that your changes pass code quality checks and tests.

    $ make code
    $ make test

6.  Commit your changes and push your branch to GitHub.

    $ git add .
    $ git commit -m "Your detailed description of your changes."
    $ git push origin name-of-your-bugfix-or-feature

7.  Submit a pull request through the GitHub website.

  Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

1.  The pull request should include tests.

2.  If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.

3.  The pull request should work for Python 3.9, for PyPy and Fedora. Check the relevant GitHub Actions page and make sure that the tests pass.

  Tips

To run a subset of tests:

$ pytest tests.test_podcust

  Developing on Fedora Silverblue

If developing on Fedora Silverblue the following set up is suggested:

# Crete new toolbox
$ toolbox create dev
# Add toolbox entry to /etc/hosts to avoid
# warning: Could not canonicalize hostname: toolbox
$ sudo dnf install nano
$ sudo nano /etc/hosts
# 127.0.0.1 ... toolbox
$ toolbox enter dev
# Following commands are inside the toolbox
$ cd $source_code_root_repository
$ sudo dnf install make fedpkg python3-wheel python3-devel python3-sphinx python3-click hadolint
$ sudo dnf install python3-black python3-coverage python3-flake8 python3-mypy python3-pytest twine yamllint python3-check-manifest python3-pytest-runner
$ make code
$ make test
$ make fedpkg

  Deploying

A reminder for the maintainers on how to deploy. Make sure all your changes are committed (including an entry in HISTORY.rst). Then run:

$ bump2version patch # possible: major / minor / patch
# Auto committing has been disabled, update documentation and commit and tag manually!
$ git push
$ git push --tags

Travis will then deploy to PyPI if tests pass.

CREDITS

  Development Lead

•   Nikolaos Perrakis <nikperrakis@gmail.com>

  Contributors

None yet. Why not be the first?

HISTORY

  0.0.28 (2021-XX-XX)

•   Re-license project to parity license.

  0.0.27 (2021-02-25)

•   Migrate to Fedora 33

•   Migrate CI to GitHub actions.

•   Improve documentation and static code tests.

  0.0.26 (2020-10-04)

•   Working management functionality (alpha version) for Demo container.

  0.0.21 (2020-09-25)

•   Added draft functionality for demo http container management.

•   Added draft command line functionality.

  0.0.20 (2020-09-01)

•   Working Fedora tests through Travis CI

  0.0.19 (2020-08-30)

•   CI, job stages and deploy stage.

  0.0.6 (2020-08-30)

•   Polishing code quality support tools.

  0.0.5 (2020-08-28)

•   First release on PyPI.

•   genindex

•   modindex

•   search

AUTHOR
Nikolaos Perrakis

COPYRIGHT
2020, Nikolaos Perrakis