Package: hokusai
HOKUSAIHokusai is a Docker + Kubernetes CLI for application developers.Hokusai "dockerizes" applications and manages their lifecycle throughout development, testing, and release cycles.Hokusai wraps calls toKubectl,Docker,Docker-ComposeandGitwith a CLI, and defines a CI workflow.Hokusai currently only supports Kubernetes deployments on AWS, configured to pull from ECS container repositories (ECR), although other providers may be added in the future.Why Hokusai?AtArtsy, as we began working with Kubernetes, while impressed with its design, capabilities, and flexibility, we were in need of tooling we could deliver to agile development teams that addressed the day-to-day tasks of application development, delivery, introspection and maintenance, while providing a clean and uncomplicated interface.Transitioning teams to the Docker / Kubernetes ecosystem can be intimidating, and comes with a steep learning curve. We set out to create a Heroku-like CLI that would shepherd the application developer into the ecosystems of Docker and Kubernetes, and while introducing new tooling and concepts, outlining a clear practice for dependency management, local development, testing and CI, image repository structure, deployment and orchestration.InstallationMacOSWe recommend installing via Homebrew:$ brew update
$ brew tap artsy/formulas
$ brew install hokusaiIf you previously installed Hokusai via an alternate installation method, you may need to force thelinkstep.$ brew link --overwrite hokusaiIf you previously installed Hokusai via Pip, you may want to first uninstall it:$ pip uninstall hokusaiLinuxcurl -sSL https://raw.githubusercontent.com/artsy/hokusai/main/get-hokusai.sh | sudo bashNote: This method installs Hokusai to/usr/local/bin/hokusai.PipHokusai can be installed via Pip, on MacOS or Linux. If you do so, please first go throughPyenv,Python, andVirtualenvsteps.Python 3.7+ is required.pip install hokusaiNote: If Pip fails at upgrading your system Python packages, try:pip install hokusai --ignore-installedDockerWe also maintainHokusai Docker imagesfor running Hokusai in Docker.GithubRelease artifacts are available onGithub.AWS S3Release artifacts are also available in AWS S3. You can use thisconvenience scriptor Curl to fetch them.A note on Python 2.xHokusai currently supports Python 3.7+ only. The last version that supported Python 2.x wasv0.5.18.SetupWe assume that your org admin has already set up a Kubernetes cluster and an AWS infrastructure, and that your local environment has Git, Docker, and Docker-Compose installed. Perform the following steps to get Hokusai working:Ensure your org admin has completed the steps mentioned inAdministering Hokusai.Configure your local environment withAWS credentials.Runhokusai configure command.Optionally, enable Bash autocompletion:eval "$(_HOKUSAI_COMPLETE=source hokusai)"Getting StartedOnce Hokusai is configured, you can start using it on a project. Please seeGetting Started.Command ReferenceA full command reference can be found inCommand Reference.Review AppsHokusai can be used to simplify the process of spinning up a "review app" instance of your project, based on a feature branch or pull request.Full details are in theReview App reference.Hokusai FilesA descripton of all thefiles used by Hokusai.Developing HokusaiTo work on Hokusai itself, please set up:PyenvWe recommend usingPyenvto install the correct version of Python. For a tutorial of Pyenv, seethis guide.When installing on MacOS, please make sure to use brew-installedopensslandreadlinelibraries, and xcode-installedzliblibrary. And make sure these libraries are correctly linked. Like so:brew install openssl readline zlib

echo 'export PATH="/usr/local/opt/openssl@1.1/bin:$PATH"' >> ~/.bash_profile
echo 'export LDFLAGS="-L/usr/local/opt/openssl@1.1/lib"' >> ~/.bash_profile
echo 'export CPPFLAGS="-I/usr/local/opt/openssl@1.1/include"' >> ~/.bash_profile
echo 'export PKG_CONFIG_PATH="/usr/local/opt/openssl@1.1/lib/pkgconfig"' >> ~/.bash_profilePythonHokusai is currently tested on Python 3.9.10 so we recommend using that Python version.If you use Pyenv to install Python, you should see an output similar to this:pyenv install 3.9.10

    python-build: use openssl from homebrew
    python-build: use readline from homebrew

    Downloading Python-3.9.10.tar.xz...
    -> https://www.python.org/ftp/python/3.9.10/Python-3.9.10.tar.xz
    Installing Python-3.9.10...
    python-build: use tcl-tk from homebrew
    python-build: use readline from homebrew
    python-build: use zlib from xcode sdk

    Installed Python-3.9.10 to $HOME/.pyenv/versions/3.9.10With the desired Python version installed, activate it globally:pyenv global 3.9.10Note: If you want to create a PyInstaller distribution, Python must be installed with development libraries. Use the environment variablePYTHON_CONFIGURE_OPTS="--enable-framework"on Darwin andPYTHON_CONFIGURE_OPTS="--enable-shared"on Linux when runningpyenv install.VirtualenvWe recommend using a virtual environment to isolate Hokusai's dependencies from that of other projects on your local environment.The Pyenv install comes withpyenv-virtualenvwhich can be used to create virtual environments.PoetryUsePoetryto install Hokusai's dependencies as well as Hokusai itself ineditable mode. Please seethis guidefor working with Poetry.Install Poetry:pip install poetryInstall dependencies and Hokusai in editable mode:poetry installTo update dependencies:poetry lockTestingInstall MinikubeMinikubeis used for integration tests.brew install minikube
minikube start --kubernetes-version=<version of your Kubernetes clusters, example: v1.2.3>Run testsTo run unit and smoke tests:make testTo run integration tests:make integrationOnly specific modules, TestClasses, or even methods:python -m unittest test.unit.test_module.TestClass.test_methodTip: SetDEBUG=1environment variable to print boto loggingDistributing HokusaiBeta ReleaseMerging a branch intomainautomatically creates a beta version useful for testing. Ascriptthat runs in CI automatically generates a Beta version number and writes it intoVERSIONfile. The version number is based on the combination of the latest canonical version found inRELEASE_VERSIONfile and the latest Git commit inmainbranch.VERSIONfile in version control has just a dummy number (e.g. 999.999.999).To install the beta:MacOS$ brew uninstall hokusai
$ brew uninstall hokusai-beta
$ brew update
$ brew tap artsy/formulas
$ brew install hokusai-betaLinuxcurl -sSL https://raw.githubusercontent.com/artsy/hokusai/main/get-hokusai.sh | sudo bash -s betaOfficial ReleaseTo create an official release, such asv1.2.3, perform the following:Create a branch namedprepare-v1.2.3and make the following changes:Bump canonical version inRELEASE_VERSIONfile.UpateCHANGELOG.Open a PR to merge intomain. Please seepast PRsfor example.Open a PRto mergemainintorelease. Please seepast PRsfor example.A CIscriptwill copy the version inRELEASE_VERSIONfile toVERSIONfile.The NameThe project is named for the great Japanese artistKatsushika Hokusai(1760-1849).About ArtsyThis project is the work of engineers atArtsy, the world's
leading and largest online art marketplace and platform for discovering art.
One of our coreEngineering Principlesis beingOpen
Source by Defaultwhich means we strive to share as many details
of our work as possible.You can learn more about this work fromour blogand by following@ArtsyOpenSourceor explore our public data by checking outour API. If you're interested in a career at Artsy, read through
ourjob postings!