HOKUSAI 
Hokusai is a Docker + Kubernetes CLI for application developers.
Hokusai "dockerizes" applications and manages their lifecycle throughout development, testing, and release cycles.
Hokusai wraps calls to Kubectl, Docker, Docker-Compose and Git with 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?
At Artsy, 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.
Point People
Installation
MacOS
We recommend installing via Homebrew:
$ brew update
$ brew tap artsy/formulas
$ brew install hokusai
The Homebrew build requires Apple silicon. On an Intel Mac, install with Pip instead.
Older releases shipped an Intel binary that ran under Rosetta, and hokusai configure installed an Intel kubectl. If your global config sets kubectl-dir, run hokusai configure again after upgrading so it replaces that kubectl with a native one. file <kubectl-dir>/kubectl should report arm64.
If you previously installed Hokusai via an alternate installation method, you may need to force the link step.
$ brew link --overwrite hokusai
If you previously installed Hokusai via Pip, you may want to first uninstall it:
$ pip uninstall hokusai
Linux
curl -sSL https://raw.githubusercontent.com/artsy/hokusai/main/get-hokusai.sh | sudo bash
Note: This method installs Hokusai to /usr/local/bin/hokusai.
Pip
Hokusai can be installed via Pip on MacOS (Apple silicon or Intel) or Linux. This is the supported method on Intel Macs.
Python 3.10 is required, exactly. boto3 needs 3.10 or newer, and the PyInstaller version that builds the release binaries caps it below 3.11. On Python 3.11 or newer, pip install hokusai does not fail. It silently installs hokusai 1.1.0, so check hokusai version after installing.
The simplest route is uv, which downloads Python 3.10 for you and puts hokusai on your PATH:
brew install uv
uv tool install --python 3.10 hokusai
uv tool update-shell
If you already have Python 3.10, for example from pyenv install 3.10, install into a virtualenv:
python3.10 -m venv ~/.venvs/hokusai
~/.venvs/hokusai/bin/pip install hokusai
Then add ~/.venvs/hokusai/bin to your PATH.
Docker
We also maintain Hokusai Docker images for running Hokusai in Docker.
Github
Release artifacts are available on Github.
AWS S3
Release artifacts are also available in AWS S3. You can use this convenience script or Curl to fetch them.
A note on Python 2.x
Hokusai currently supports Python 3.10 only. See Pip. The last version that supported Python 2.x was v0.5.18.
Setup
We 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 in Administering Hokusai.
-
Configure your local environment with AWS credentials.
-
Optionally, enable Bash autocompletion:
eval "$(_HOKUSAI_COMPLETE=source hokusai)"
Getting Started
Once Hokusai is configured, you can start using it on a project. Please see Getting Started.
Command Reference
A full command reference can be found in Command Reference.
Review Apps
Hokusai 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 the Review App reference.
Hokusai Files
A descripton of all the files used by Hokusai.
Developing Hokusai
To work on Hokusai itself, please set up:
mise
We use mise to manage Python, Poetry, and the virtualenv. Install mise, then run:
mise install
This installs Python 3.10 and Poetry 1.2.2, and creates a .venv virtualenv that is activated automatically in the project directory.
Then install dependencies and Hokusai in editable mode:
poetry install
To update dependencies:
poetry lock
Testing
Install Minikube
Minikube is used for integration tests.
brew install minikube
minikube start --kubernetes-version=<version of your Kubernetes clusters, example: v1.2.3>
Run tests
To run unit tests:
make test
To run integration tests:
make integration-local
Only specific modules, TestClasses, or even methods:
python -m unittest test.unit.test_module.TestClass.test_method
Tip: Set DEBUG=1 environment variable to print boto logging
Distributing Hokusai
Beta Release
Merging a branch into main automatically creates a beta version useful for testing. A script that runs in CI automatically generates a Beta version number and writes it into VERSION file. The version number is based on the combination of the latest canonical version found in RELEASE_VERSION file and the latest Git commit in main branch. VERSION file 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-beta
Linux
curl -sSL https://raw.githubusercontent.com/artsy/hokusai/main/get-hokusai.sh | sudo bash -s beta
Official Release
To create an official release, such as v1.2.3, perform the following:
-
Create a branch named
prepare-v1.2.3and make the following changes:- Bump canonical version in RELEASE_VERSION file.
- Upate CHANGELOG.
- Open a PR to merge into
main. Please see past PRs for example.
-
Open a PR to merge
mainintorelease. Please see past PRs for example.
A CI script will copy the version in RELEASE_VERSION file to VERSION file.
The Name
The project is named for the great Japanese artist Katsushika Hokusai (1760-1849).
About Artsy
This project is the work of engineers at Artsy, the world's leading and largest online art marketplace and platform for discovering art. One of our core Engineering Principles is being Open Source by Default which means we strive to share as many details of our work as possible.
You can learn more about this work from our blog and by following @ArtsyOpenSource or explore our public data by checking out our API. If you're interested in a career at Artsy, read through our job postings!
Release files for hokusai 4.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| hokusai-4.0.0.tar.gz | 44.2 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| hokusai-4.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 106.8 kB
Release files / hokusai-4.0.0.tar.gz
| Download URL | hokusai-4.0.0.tar.gz |
|---|---|
| Size | 44.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
96febb4a0aa434d389d9f98022095d4987eda1c05e56349f7fe67b6ad846f428
|
|
BLAKE2b-256 checksum How to use checksums |
64bafde41b0f918da78a083e35d882b5cf8e71db017cb040a7fd6c9f86603d73
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.8.0 pkginfo/1.9.6 readme-renderer/42.0 requests/2.31.0 requests-toolbelt/1.0.0 urllib3/2.0.7 tqdm/4.66.1 importlib-metadata/7.0.1 keyring/24.3.0 rfc3986/2.0.0 colorama/0.4.6 CPython/3.10.22
|
Release files / hokusai-4.0.0-py3-none-any.whl
| Download URL | hokusai-4.0.0-py3-none-any.whl |
|---|---|
| Size | 62.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0c2ec28c9ac7bab70aed6f5b9d78b3a1ab8d9c6cb65d88bfe9271d99af87aefd
|
|
BLAKE2b-256 checksum How to use checksums |
206dfd4459aedbd2769d3965922397be75250010cc146ebc0ea96b0340d53f5e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.8.0 pkginfo/1.9.6 readme-renderer/42.0 requests/2.31.0 requests-toolbelt/1.0.0 urllib3/2.0.7 tqdm/4.66.1 importlib-metadata/7.0.1 keyring/24.3.0 rfc3986/2.0.0 colorama/0.4.6 CPython/3.10.22
|
Security for hokusai 4.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
