FourDigits CLI

A command line tool to make development and deployment easier within Four Digits.

It has the following commands:

1. "docker"
   • "build": Build docker images in our Gitlab CI pipelines
   • "tag": Create new Docker tag for existing Docker tag on registry
2. "gitlab"
   • "fix-coverage-paths": Change the generated coverage.xml so Gitlab can show coverage visualization in merge requests
3. "exonet"
   • "deploy": Deploy a project to Exonet
   • "db:download": Download a database from Exonet and import it locally
   • "db:copy": Copy a database from one environment to another
   • "db:shell": Open an interactive psql session on the database server for the given environment.
   • "minio:create": Create MinIO user, buckets, and access token
   • "minio:list": List all MinIO buckets accessible via the Exonet API token
   • "minio:download": Copy a remote MinIO bucket locally to Docker MinIO service
4. "docker-compose"
   • "sync": Sync files from a service to local folder
   • "sync:env": Shortcut for django:home/userapp/env -> env-docker
5. "mypy"
   • "diff": Run mypy limited to lines changed in the current Git diff
6. "mdbook"
   • "preprocessor": Replace ::: dotted.path markers with Python docstrings for mdBook preprocessing
7. "help"
   • "config": Explain the pyproject.toml configuration options

Install

With pipx:

pipx install fourdigits-cli

With pip:

sudo pip install --break-system-packages fourdigits-cli

With uv tool:

uv tool install fourdigits-cli

Upgrade

With pipx:

pipx upgrade fourdigits-cli

With pip:

sudo pip install --upgrade fourdigits-cli

With uv tool:

uv tool upgrade fourdigits-cli --upgrade

Enable auto complete

bash

Add this to ~/.bashrc:

eval "$(_4D_COMPLETE=bash_source 4d)"
eval "$(_FOURDIGITS_COMPLETE=bash_source fourdigits)"

Zsh

Add this to ~/.zshrc:

eval "$(_4D_COMPLETE=zsh_source 4d)"
eval "$(_FOURDIGITS_COMPLETE=zsh_source fourdigits)"

Usage

After installation the cli tool is available under fourdigits and 4d. For more information use:

fourdigits --help

Example: mdBook preprocessor

The mdBook preprocessor resolves Python docstrings from the source tree without importing project code:

[preprocessor.docstrings]
command = "fourdigits mdbook preprocessor --src-path /home/userapp/src"

Example: Build a docker image and deploy it to the test environment

Build an image for the tst environment and upload it to our registry:

$ fourdigits docker build tst --push
Docker build image <docker_tag>
 - file=Dockerfile
 - context=.
 - target=None
Docker create tag <tmp_tag> -> docker-registry.fourdigits.nl/fourdigits/<project>:tst
Docker push tag docker-registry.fourdigits.nl/fourdigits/<project>:tst
Docker create tag <tmp_tag> -> docker-registry.fourdigits.nl/fourdigits/<project>:<docker_tag>
Docker push tag docker-registry.fourdigits.nl/fourdigits/wijsproductportals:<docker_tag>

To deploy this to the tst environment, use the docker_tag (not the tmp_tag) from the previous step:

$ fourdigits exonet deploy tst <docker_tag>
{"id":...,"number":<number>,...}

You can see the progress of the deployment pipeline on https://drone.exonet.nl/exonet/containers-fourdigits/.

Troubleshooting

unauthorized

If you get:

unauthorized: unauthorized to access repository: fourdigits/<project>, action: push: unauthorized to access repository: fourdigits/<project>, action: push

You need to login to the registry:

docker login
docker login docker-registry.fourdigits.nl

Project configuration

The project is configured in the pyproject.toml file, available options and their defaults:

[project]
name = "default-project"

[tool.fourdigits]
exonet_project_name="<default is project name>"
docker_repo="<default is project name>"
slack_channel="<default is project name>"
docker_image_user="fourdigits"
# If a different server with same exonet setup is used, like industrial-auctions. Otherwise, don't define for default
database_ssh_username="admin@db01.industrial-auctions.com"
application_ssh_host="app01.industrial-auctions.com"
database_host="db01.industrial-auctions.com"

[tool.fourdigits.envs.<environment anem>]
exonet_environment="<default is environment name>"
# Every setting can be overridden per environment
slack_channel="custom-channel"

Example project with separate nextjs

[project]
name = "django-project"

[tool.fourdigits]
# default to project name

[tool.fourdigits.envs.tst]

[tool.fourdigits.envs.acc]

[tool.fourdigits.envs.prd]

[tool.fourdigits.envs.nextjs_tst]
exonet_project_name = "nextjs"
exonet_environment = "tst"
docker_repo = "nextjs"

[tool.fourdigits.envs.nextjs_acc]
exonet_project_name = "nextjs"
exonet_environment = "acc"
docker_repo = "nextjs"

[tool.fourdigits.envs.nextjs_prd]
exonet_project_name = "nextjs"
exonet_environment = "prd"
docker_repo = "nextjs"

Development

Running:

make develop

creates a virtualenv env/ with all development requirements.

To activate it:

source env/bin/activate

Releasing

To make a new release available on pypi, follow these steps:

1. Update version by edit fourdigits_cli/__init__.py and commit.
2. Run: make push-version
3. Update the installation of fourdigits-cli in https://gitlab.com/fourdigits/utils/docker-pipeline-image/-/blob/main/Dockerfile to the newest version.