dockerized

README

Dockerized

Run popular commandline tools without installing them.

dockerized <command>

Supported commands

If your favorite command is not included, it can be added very easily. See Customization.
Dockerized will also fall back to over 150 commands defined in jessfraz/dockerfiles.

• Cloud
  • aws
  • az (Azure CLI)
  • doctl
  • s3cmd
• Database
  • dolt
  • mssql
  • mysql
  • postgres
    • psql
    • pg_dump
    • pg_dumpall
• Dev-Ops & Docker
  • ansible
    • ansible-playbook
  • helm
• Git
  • git
  • gh (Github)
• Languages & SDKs
  • dotnet
  • go
    • gofmt
  • (haskell)
    • ghci
  • java
  • perl
  • php
    • composer
  • (prolog)
    • swipl (SWI-Prolog)
  • lua
  • node
    • npm
    • npx
    • vue
    • yarn
  • python
    • pip
    • python
    • python2
  • ruby
    • gem
    • rake
  • (rust)
    • rustc
  • typescript
    • tsc
• Networking
  • http
  • telnet
  • wget
• Unix
  • tree
  • zip
• Other
  • jq
  • mkdocs
  • (latex)
    • pdflatex
  • protoc
  • scrapy
  • swagger-codegen
  • youtube-dl (Youtube downloader)

Installation

• Make sure Docker is installed on your machine.

• Download the latest zip from our Release Page.

  • Extract it to a folder, for example your home directory.

• Add the dockerized/bin directory to your PATH

  Instructions

  Linux / MacOS:

  export PATH="$PATH:$HOME/dockerized/bin"
  

  Windows

  See: How to add a folder to PATH environment variable in Windows 10

Running from source

You can run dockerized directly from source-code.

Installation from Source

• Requirements:
  • Git
  • Docker
• Steps

  • Clone the repository

    git clone https://github.com/datastack-net/dockerized.git
    

  • Run dockerized:

    bin/dockerized --help
    

    • The first time you run dockerized, it will compile itself.
      • Compilation is done within docker, no dependencies needed.
    • To re-compile after changing the source code, run:
      • dockerized --compile (runs within docker)
      • dockerized --compile=host (runs on your machine, requires Go 1.17+)
    • You do not need to re-compile to add commands. See Add a command.

Usage

Run any supported command, but within Docker.

dockerized <command>

Examples:

dockerized node --version             # v16.13.0
dockerized vue create new-project     # create a project with vue cli
dockerized tsc --init                 # initialize typescript for the current directory
dockerized npm install                # install packages.json

See CLI Reference for all options.

Use Cases

• Quickly try out command line tools without the effort of downloading and installing them.
• Installing multiple versions of node/python/typescript.
• You need unix commands on Windows.
• You don't want to pollute your system with a lot of tools you don't use.
• Easily update your tools.
• Ensure everyone on the team is using the same version of commandline tools.

Design Goals

• All commands work out of the box.
• Dockerized commands behave the same as their native counterparts.
  • Files in the current directory are accessible using relative paths.
• Cross-platform: Works on Linux, MacOS, and Windows (CMD, Powershell, Git Bash).
• Suitable for ad-hoc usage (i.e. you quickly need to run a command, that is not on your system).
• Configurability: for use within a project or CI/CD pipeline.

Switching command versions

Ad-hoc

Add :<version> to the end of the command to override the version.

dockerized node:15

Listing versions

To see which versions are available, run:

dockerized node:?
# or
dockerized node:

Environment Variables

Each command has a <COMMAND>_VERSION environment variable which you can override.

• python → PYTHON_VERSION
• node → NODE_VERSION
• tsc → TSC_VERSION
• npm → NODE_VERSION ⚠ npm's version is determined by node.

See .env for a list of configurable versions.

Global

• Create a dockerized.env file in your home directory for global configuration.

  # dockerized.env (example)
  NODE_VERSION=16.13.0
  PYTHON_VERSION=3.8.5
  TYPESCRIPT_VERSION=4.6.2
  

Per project (directory)

You can also specify version and other settings per directory and its subdirectory. This allows you to "lock" your tools to specific versions for your project.

• Create a dockerized.env file in the root of your project directory.
• All commands executed within this directory will use the settings specified in this file.

Ad-hoc (Unix)

• Override the environment variable before the command, to specify the version for that command.

  NODE_VERSION=15.0.0 dockerized node
  

Ad-hoc (Windows Command Prompt)

• Set the environment variable in the current session, before the command.

  set NODE_VERSION=15.0.0
  dockerized node
  

Customization

Dockerized uses Docker Compose to run commands, which are defined in a Compose File. The default commands are listed in docker-compose.yml. You can add your own commands or customize the defaults, by loading a custom Compose File.

The COMPOSE_FILE environment variable defines which files to load. This variable is set by the included .env file, and your own dockerized.env files, as explained in Environment Variables. To load an additional Compose File, add the path to the file to the COMPOSE_FILE environment variable.

Including an additional Compose File

Globally

To change global settings, create a file dockerized.env in your home directory, which loads an extra Compose File. In this example, the Compose File is also in the home directory, referenced relative to the ${HOME} directory. The original variable ${COMPOSE_FILE} is included to preserve the default commands. Omit it if you want to completely replace the default commands.

# ~/dockerized.env
COMPOSE_FILE="${COMPOSE_FILE};${HOME}/docker-compose.yml"

# ~/docker-compose.yml

Per Project

To change settings within a specific directory, create a file dockerized.env in the root of that directory, which loads the extra Compose File. ${DOCKERIZED_PROJECT_ROOT} refers to the absolute path to the root of the project.

# ./dockerized.env
COMPOSE_FILE="${COMPOSE_FILE};${DOCKERIZED_PROJECT_ROOT}/docker-compose.yml"

# ./docker-compose.yml

Adding custom commands

After adding your custom Compose File to COMPOSE_FILE, you can add your own commands.

# docker-compose.yml
version: "3"
services:
  du:
    image: alpine
    entrypoint: ["du"]

Now you can run dockerized du to see the size of the current directory.

To learn how to support versioning, see Development Guide: Configurable Version.

You can also mount a directory to the container:

# docker-compose.yml
version: "3"
services:
  du:
    image: alpine
    entrypoint: ["du"]
    volumes:
      - "${HOME}/.config:/root/.config"
      - "${DOCKERIZED_PROJECT_ROOT}/foobar:/foobar"

Make sure host volumes are absolute paths. For paths relative to home and the project root, you can use ${HOME} and ${DOCKERIZED_PROJECT_ROOT}.

It is possible to use relative paths in the service definitions, but then your Compose File must be loaded before the default: COMPOSE_FILE=${DOCKERIZED_PROJECT_ROOT}/docker-compose.yml;${COMPOSE_FILE}. All paths are relative to the first Compose File. Compose Files are also merged in the order they are specified, with the last Compose File overriding earlier ones. Because of this, if you want to override the default Compose File, you must load it before your file, and you can't use relative paths.

To keep compatibility with docker-compose, you can specify a default value for DOCKERIZED_PROJECT_ROOT, for example: ${DOCKERIZED_PROJECT_ROOT:-.} sets the default to ., allowing you to run like this as well: docker-compose --rm du -sh /foobar.

To customize existing commands, you can override or add properties to the services section of the Compose File, for the command you want to customize. For example, this is how to set an extra environment variable for dockerized aws:

# docker-compose.yml
version: "3"
services:
  aws:
    environment:
      AWS_DEFAULT_REGION: "us-east-1"

If you'd like to pass environment variables directly from your dockerized.env file, you can expose the variable as follows:

# dockerized.env
AWS_DEFAULT_REGION="us-east-1"

# docker-compose.yml
version: "3"
services:
  aws:
    environment:
      AWS_DEFAULT_REGION: "${AWS_DEFAULT_REGION}"

For more information on extending Compose Files, see the Docker Compose documentation: Multiple Compose Files. Note that the extends keyword is not supported in the Docker Compose version used by Dockerized.

Localhost

Dockerized applications run within an isolated network. To access services running on your machine, you need to use host.docker.internal instead of localhost.

dockerized telnet host.docker.internal 8080 # instead of telnet localhost 8080

Limitations

• It's not currently possible to access parent directories. (i.e. dockerized tree ../dir will not work)
  • Workaround: Execute the command from the parent directory. (i.e. cd .. && dockerized tree dir)
• Commands will not persist changes outside the working directory, unless specifically supported by dockerized.