Package: mantis-cli
mantis-cliMantis is a CLI (command line interface) tool designed as a wrapper upon docker and docker compose commands for your project.Using few commands you can:encrypt and decrypt your environment filesbuild and push docker imagescreate docker contextszero-downtime deploy your applicationprint logs of your containersconnect to bash of your containers using SSHclean docker resourcesuse specific commands using Django, PostgreSQL and Nginx extensionsand much moreInstallationpipinstallmantis-cliConfigurationCreate amantis.jsonconfiguration file in JSON format.
You can use<MANTIS>variable in your paths if needed as a relative reference to your mantis file.Explanation of config argumentsargumenttypedescriptionmanager_classstringclass path to mantis manager classextensionsdictDjango, Postgres, Nginxproject_namestringslug of your project name used as prefix for containersencryptiondictencryption settingsencryption.deterministicboolif True, encryption hash is always the same for same valueencryption.folderboolpath to folder with your environment filesconfigsdictconfiguration settingsconfigs.folderstringpath to folder with your configuration filesbuilddictbuild settingsbuild.toolstring"docker" or "compose"composedictdocker compose settingscompose.commandstringstandalone "docker-compose" or "docker compose" plugincompose.namestringdocker compose suffix: "docker-compose.ENVIRONMENT.NAME.yml"compose.folderstringpath to folder with compose filesenvironmentdictenvironment settingsenvironment.folderstringpath to folder with environment filesenvironment.file_prefixstringfile prefix of environment fileszero_downtimearraylist of services to deploy with zero downtimeproject_pathstringpath to folder with project files on remote serverconnectionsdictdefinition of your connections for each environmentTODO:default valuesSeetemplate filefor exact JSON structure.ConnectionsConnection for each environment except localhost can be defined either as an SSH or Docker context:For example:"connections":{"stage":"context://<context_name>","production":"ssh://<user>@<host>:<port>"}EncryptionIf you plan to use encryption and decryption of your environment files, you need to create encryption key.Generation of new key:mantis--generate-keySave key tomantis.keyfile:echo<MANTIS_KEY>>/path/to/encryption/folder/mantis.keyThen you can encrypt your environment files using symmetric encryption.
Every environment variable is encrypted separately instead of encrypting the whole file for better tracking of changes in VCS.mantis<ENVIRONEMNT>--encrypt-envDecryption is easy like this:mantis<ENVIRONEMNT>--decrypt-envWhen decrypting, mantis prompts user for confirmation.
You can bypass that by forcing decryption which can be useful in CI/CD pipeline:mantis<ENVIRONEMNT>--decrypt-env:forceUsageGeneral usage of mantis-cli has this format:mantis[--mode=remote|ssh|host][environment]--command[:params]ModesMantis can operate in 3 different modes depending on a way it connects to remote machhineRemote mode--mode=remoteRuns commands remotely from local machine using DOCKER_HOST or DOCKER_CONTEXT (default)SSH mode--mode=sshConnects to host via ssh and run all mantis commands on remote machine directly (nantis-cli needs to be installed on server)Host mode--mode=hostRuns mantis on host machine directly without invoking connection (used as proxy for ssh mode)EnvironmentsEnvironment can be eitherlocalor any custom environment likestage,productionetc.
The environment is also used as an identifier for remote connection.CommandsCommand / ShortcutDescription--bash:paramsRuns bash in container--build[:params] / -bBuilds all services with Dockerfiles--check-configValidates config file according to template--check-envCompares encrypted and decrypted env files--check-health:containerChecks current health of given container--clean[:params] / -cClean images, containers, networks--contextsPrints all docker contexts--create-contextCreates docker context using user inputs--decrypt-env[:params,env_file,return_value]Decrypts all environment files (force param skips user confirmation)--deploy / -dRuns deployment process: uploads files, pulls images, runs zero-downtime deployment, removes suffixes, reloads webserver, clean--down[:params]Calls compose down (with optional params)--encrypt-env[:params,env_file,return_value]Encrypts all environment files (force param skips user confirmation)--exec:paramsExecutes command in container--generate-keyCreates new encryption key--get-container-name:serviceConstructs container name with project prefix for given service--get-container-suffix:serviceReturns the suffix used for containers for given service--get-deploy-replicas:serviceReturns default number of deploy replicas of given services--get-healthcheck-config:containerPrints health-check config (if any) of given container--get-healthcheck-start-period:containerReturns healthcheck start period for given container (if any)--get-image-name:serviceConstructs image name for given service--get-image-suffix:serviceReturns the suffix used for image for given service--get-number-of-containers:servicePrints number of containers for given service--get-service-containers:servicePrints container names of given service--has-healthcheck:containerChecks if given container has defined healthcheck--healthcheck[:container] / -hcExecute health-check of given project container--kill[:params]Kills all or given project container--logs[:params] / -lPrints logs of all or given project container--manage:paramsRuns Django manage command--networks / -nPrints docker networks--pg-dump[:data_only,table]Backups PostgreSQL database [data and structure]--pg-dump-data[:table]Backups PostgreSQL database [data only]--pg-restore[:filename,table]Restores database from backup [data and structure]--pg-restore-data:paramsRestores database from backup [data only]--psqlStarts psql console--pull[:params] / -pPulls required images for services--push[:params]Push built images to repository--read-keyReturns value of mantis encryption key--remove[:params]Removes all or given project container--remove-suffixes[:prefix]Removes numerical suffixes from container names (if scale == 1)--restart[:service]Restarts all containers by calling compose down and up--restart-service:serviceStops, removes and recreates container for given service--run:paramsCalls compose run with params--scale:service,scaleScales service to given scale--send-test-emailSends test email to admins using Django 'sendtestemail' command--servicesPrints all defined services--services-to-buildPrints all services which will be build--sh:paramsRuns sh in container--shellRuns and connects to Django shell--start[:params]Starts all or given project container--status / -sPrints images and containers--stop[:params]Stops all or given project container--try-to-reload-webserverTries to reload webserver (if suitable extension is available)--up[:params]Calls compose up (with optional params)--upload / -uUploads mantis config, compose fileand environment files to server--zero-downtime[:service]Runs zero-downtime deployment of services (or given service)Few examples:mantis--version
mantislocal--encrypt-env
mantisstage--build
mantisproduction--logs:container-name# you can also run multiple commands at oncemantisstage--build--push--deploy-s-lCheckmantis --helpfor more details.Flow1. BuildOnce you define mantis config for your project and optionally create encryption key, you can build your docker images:mantis<ENVIRONMENT>--buildMantis either usesdocker-compose --buildordocker buildcommand depending on build tool defined in your config.
Build image names use '_' as word separator.2. PushBuilt images needs to be pushed to your repository defined in compose file (you need to authenticate)mantis<ENVIRONEMNT--push3. DeploymentDeployment to your remote server is being executed by calling simple command:mantis<ENVIRONMENT>--deployThe deployment process consists of multiple steps:If using --mode=ssh, mantis uploads mantis config, environment files and compose file to serverpulling docker images from repositorieszero-downtime deploymentof running containers (if any)calling docker compose up to start containersremoving numeric suffixes from container names (if scale==1)reloading webserver (if found suitable extension)cleaning docker resources (without volumes)Docker container names use '-' as word separator (docker compose v2 convention).4. InspectOnce deployed, you can verify the container status:mantis<ENVIRONEMNT>--statuslist all docker networks:mantis<ENVIRONMENT>--networksand also check all container logs:mantis<ENVIRONEMNT>--logsIf you need to follow logs of a specific container, you can do it by passing container name to command:mantis<ENVIRONMENT>--logs:<container-name>5. Another useful commandsSometimes, instead of calling whole deployment process, you just need to call compose commands directly:mantis<ENVIRONEMNT>--up
mantis<ENVIRONEMNT>--down
mantis<ENVIRONEMNT>--restart
mantis<ENVIRONEMNT>--stop
mantis<ENVIRONEMNT>--kill
mantis<ENVIRONEMNT>--startCommands over a single container:mantis<ENVIRONMENT>--bash:container-name
mantis<ENVIRONMENT>--sh:container-name
mantis<ENVIRONMENT>--run:paramsZero-downtime deploymentMantis has own zero-downtime deployment implementation without any third-party dependencies.
It uses docker compose service scaling and docker health-checks.Works as follows:a new service container starts using scalingmantis waits until the new container is healthy by checking its health status. If not health-check is defined, it waits X seconds defined by start periodreloads webserver (to proxy requests to new container)once container is healthy or start period ends the old container is stopped and removednew container is renamed to previous container's namewebserver is reloaded againRelease notesMantis uses semantic versioning. See more inchangelog.