Package: omniverse
OmniverseOmniverseBuilding and Running the Jupyter Book Docker ImageBuilding the Docker ImageRunning the Docker ContainerStopping the Docker ContainerFurther EnhancementsReferences and Further ReadingsRelease using GitHub Actions CI/CD WorkflowsSemantic VersioningFormatExample VersioningPre-release and Build MetadataRelease using GitHub Actions CI/CD WorkflowsExample WorkflowReferences and Further Readings🌌 Omniverse: A cosmic collection of machine learning, deep learning, data
science, math, and software engineering explorations. Dive into the universe of
knowledge! 🚀 To create a detailed Markdown section in theREADME.mdfile for
instructing users on how to build and run the Dockerfilejupyterbook.Dockerfile, you should include steps that cover prerequisites,
building the Docker image, tagging it with the Git commit ID, and running the
container. Additionally, to avoid hardcoding variables in the Docker build/run
commands, you can use shell variables and command substitutions.Building and Running the Jupyter Book Docker ImageThis section provides detailed instructions on how to build the Dockerfile
(docker/documentation/jupyterbook.Dockerfile) and run the Docker image. The
image provides a containerized environment for building and serving the Jupyter
Book website.[!WARNING] This section is only tested on macOS Ventura 13.4.1.First, ensure you are in the root directory of the repository, if not, change
directories to the root directory:~/$cd<path/to/omniverse>Replace<path/to/omniverse>with the actual path to your repository's root
directory.Building the Docker ImageSet Environment Variables: Set theGIT_COMMIT_HASH,IMAGE_NAME, andIMAGE_TAGenvironment variables. These will be used to tag your Docker
image uniquely.~/omniverse$exportGIT_COMMIT_HASH=$(gitrev-parse--shortHEAD)~/omniverse$exportIMAGE_NAME=omniverse
~/omniverse$exportIMAGE_TAG=$GIT_COMMIT_HASHBuild the Image: Execute the following Docker command to build the image,
specifying the Dockerfile path and assigning the tag based on the previously
set environment variables.~/omniverse$dockerbuild\>--filedocker/documentation/jupyterbook.Dockerfile\>--tag$IMAGE_NAME:$IMAGE_TAG\>.Running the Docker ContainerTo run the Docker container:~/omniverse$dockerrun\>--publish80:80\>$IMAGE_NAME:$IMAGE_TAGThis command will start a container from the built image, mapping port 80 of thecontainerto port 80 on thehostmachine. The website should now be
accessible athttp://localhost:80.Stopping the Docker ContainerTo stop the Docker container:~/omniverse$exportCONTAINER_ID=$(dockerps--filterancestor=$IMAGE_NAME:$IMAGE_TAG--format"{{.ID}}")~/omniverse$dockerstop$CONTAINER_IDFurther EnhancementsThis is a relatively simple Dockerfile. Further enhancements can include, but
not limited to:Add entrypoint script to start the Jupyter Book server.Use Docker Compose to manage multiple containers, for example, a container
for development of the content and a container for serving the website.Current Docker image is used primarily for serving, and users may find it
hard to directly developinsidethe container. A better approach is to
use a Docker image for development, and mount the source code directory to
the container. This way, users can develop on their host machine, and the
changes will be reflected in the container.References and Further ReadingsHow to run Nginx within a Docker container without halting?Release using GitHub Actions CI/CD WorkflowsSemantic VersioningThe conventional way to name software versions is by followingSemantic Versioning(SemVer). Semantic Versioning is
a widely adopted system for versioning software in a way that conveys meaning
about the underlying changes. It helps in managing dependencies and avoiding
compatibility issues.FormatA Semantic Version number is typically formatted asMAJOR.MINOR.PATCH, where:MAJOR version:Incremented for incompatible API changes or major changes in
functionality.Indicates that the new version might not be backward compatible with
previous major versions.MINOR version:Incremented for adding functionality in a backward-compatible manner.Indicates new features or improvements which do not break existing
functionalities.PATCH version:Incremented for backward-compatible bug fixes.Focuses on resolving bugs and issues without adding new features or
breaking existing functionality.Example Versioning1.0.0: The first stable release of a software.1.0.1: A subsequent release that includes bug fixes but no new features.1.1.0: A release that introduces new features but is still backward
compatible with the1.0.xseries.2.0.0: A release that makes changes significant enough to potentially
break compatibility with the1.x.xseries.Pre-release and Build MetadataSemantic Versioning also supports additional labels for pre-release and build
metadata:Pre-release versions can be denoted with a hyphen and additional identifiers
(e.g.,2.0.0-alpha,2.0.0-beta.1).Build metadata can be appended using a plus sign and additional identifiers
(e.g.,2.0.0+build.20230315).Release using GitHub Actions CI/CD WorkflowsFollowthe guide herefor detailed instructions on how to release a Python package using GitHub
Actions CI/CD workflows.One thing that is not mentioned in the guide, but is a good practice, is to do
all the necessary pre-release checks before releasing your package, that
includes all the pre-merge checks, and additional checks such as running tests,
linting, and building the documentation. This ensures that the release is of
high quality and is ready to be used by others.Furthermore, we add arelease-dockerworkflow to build and publish a Docker
image to Docker Hub. The workflow is triggered when a new release is published
to PyPI. This approach is inspired bylangchain's workflowfor publishing a Docker image via GitHub Actions. The rationale behind
incorporating a Docker release alongside the PyPI release is to ensure the
packageomniverseis able to be imported and used across different platforms.Example WorkflowUpdate theversionfield inpyproject.tomlto the new version, and commit
the changes to themainbranch (or any other branch that satisfies theon.push.branchescondition in the workflow).gitcommit-am"cicd: bump version to 0.0.21 #38."gittag-av0.0.21-m"Release version 0.0.21"gitpush&&gitpushoriginv0.0.21Then the workflow will be triggered, and the package will be published to PyPI.
It is worth noting that we will do a pre-release check before publishing the
package.References and Further ReadingsPackaging Projects - Python Packaging User GuidePublishing Package Distribution Releases Using GitHub Actions CI/CD Workflows - Python Packaging User GuidePublishing Python PackagesPublishing Python Packages from GitHub Actions