Skip to content

childmindresearch/styxdocker

Repository files navigation

Docker Runner for Styx compiled wrappers

Build codecov Ruff stability-stable MIT License pages

styxdocker is a Python package that provides Docker integration for Styx compiled wrappers. It allows you to run Styx functions within Docker containers, offering improved isolation and reproducibility for your workflows.

Installation

You can install styxdocker using pip:

pip install styxdocker

Usage

Here's a basic example of how to use styxdocker:

from styxdefs import set_global_runner
from styxdocker import DockerRunner

# Initialize the DockerRunner
runner = DockerRunner()

# Set the global runner for Styx
set_global_runner(runner)

# Now you can use any Styx functions as usual, and they will run in Docker containers

Advanced Configuration

The DockerRunner class accepts several parameters for advanced configuration:

  • image_overrides: A dictionary to override container image tags
  • docker_executable: Path to the Docker executable (default: "docker")
  • user_id: User ID to run the container as (default: current user ID on POSIX systems)
  • data_dir: Directory for temporary data storage
  • environ: Environment variables to set in the container

Example:

runner = DockerRunner(
    image_overrides={"python:3.9": "my-custom-python:3.9"},
    docker_executable="/usr/local/bin/docker",
    user_id=1000,
    data_dir="/tmp/styx_data",
    environ={"PYTHONPATH": "/app/lib"}
)

Error Handling

styxdocker provides a custom error class, StyxDockerError, which is raised when a Docker execution fails. This error includes details about the return code, command arguments, and Docker arguments for easier debugging.

Cross-Platform Support

styxdocker is designed to work on Linux, macOS, and Windows. On POSIX systems (Linux and macOS), it automatically uses the current user's ID for running containers, ensuring proper file permissions. On Windows, this feature is not available, but the package remains functional.

Contributing

Contributions to styxdocker are welcome! Please refer to the GitHub repository for information on how to contribute, report issues, or submit pull requests.

License

styxdocker is released under the MIT License. See the LICENSE file for details.

Documentation

For detailed API documentation, please visit our API Docs.

Support

If you encounter any issues or have questions, please open an issue on the GitHub repository.

Requirements

  • Python 3.10+
  • Docker installed and running on your system

Comparison with styxsingularity

While styxdocker and styxsingularity serve similar purposes, they have some key differences:

  • Container Technology: styxdocker uses Docker, while styxsingularity uses Singularity/Apptainer.
  • Platform Support: styxdocker works on Windows, Linux, and macOS, whereas styxsingularity is not supported on Windows.
  • User Permissions: styxdocker can run containers as the current user on POSIX systems, which can help with file permission issues.

Choose the package that best fits your infrastructure and requirements.