USDocker - Useful Scripts for Docker

npm version Build Status

USDocker is a colletion of useful scripts to make easier brings a service up, down the service, check status and a lot of other features. It turns a docker image as an appliance.

Usdocker is highly customizable.

Command Line Basic Usage

The most common usage is:

usdocker SERVICE COMMAND

If you want start a mysql service you only need to:

usdocker mysql up

If you call usdocker SERVICE without the command you get the help for the service

Installing usdocker

USDocker is a npm package. Normally you do not want install only the USDocker but a usefull script running on top of USDocker library. The install will be:

npm install -g @usdocker/usdocker  # This package is mandatory
npm install -g usdocker-<SCRIPT\>  # Here the USDocker package.

See below the list of official scripts available, documentation and how to install it:

Did not found the service you want? Feel free to create it and send to us again! Follow our guide, read about the API and directories to create your own script. After created your script you may want add to this list creating a pull request.

Most common Useful Scripts commands

  Usage: usdocker <script> [options] [command] 

  USDocker is a colletion of useful scripts to make easier brings a service up or down, check status and a lot of other features.

  Options:

    -V, --version                 output the version number
    -d, --dump                    Dump the scripts options
    --dump-global                 Dump the global options
    -s, --set <key-pair>          Set a script configuration. Key-pair is key=value (default: )
    -g, --get <key>               Get a script option (default: )
    --global <key-pair>           Set a global configuration for usdocker. Key-pair is key=value (default: )
    -r, --refresh [searchFolder]  refresh the list of available scripts
    -v, --verbose                 Print extra information
    --yes                         answer YES to any question
    --no                          answer NO to any question
    --home <path>                 The home directory for USDOCKER. May also be setting using USDOCKER_HOME environment variable
    --no-link                     No link the current container with the running containers (default: true)
    --reset-config                reset all config to the default values
    --reset-datadir               reset all user data. Be careful because this operation is not reversible!
    --reset-userdir               reset all config user data. Be careful because this operation is not reversible!
    -h, --help                    output usage information

Refreshing USDocker local database

After install a new script you have to refresh the LIST by using:

usdocker -rv    # based on the current usdocker installation
usdocker -v --refresh <folder>   # based on a specific folder

By the default a USDocker container is linked with the current running containers.

For example:

usdocker mysql up      # Will up the the MySQL container
usdocker wordpress up  # Will up the wordpress and link with the MySQL container automatically

This behavior can be override using the --no-link argument:

usdocker wordpress --no-link up  # Will up the wordpress without link with any container. 

Running with extra information

Add the parameter -v to your command line.

Manipulating the script setup

The USDocker script are customizable by variables. Here you can see how to customize your script;

Discover what configuration are available

usdocker <your_script> --dump

Get the current value

usdocker <your_script> --get key

Set a new value

usdocker <your_script> --set key=value

Caution If you put a wrong value here you can stop the service or cause damage on your computer.

Reseting data

Reset only the user environment

usdocker SERVICE --reset-userdir

Reset the user data including database, data produced by the user and others:

usdocker SERVICE --reset-datadir

Note that this operation is irreversible.

Setting the Docker Host

USDocker points to the local socket by default. But you can change this by using the command:

API Not authenticated (for windows or mac)

usdocker --global http://127.0.0.1:2736

Docker machine

usdocker --global machine:///path/to/dockermachine/dir

Linux Socket (default)

usdocker --global /var/run/docker.sock

Running on Windows or Mac

If you running on Windows or Mac you probably set or the Docker Machine or the API Not Authenticated;

In both cases you need to map a local directory into the host server.

usdocker --global mappingDirFrom=/mnt/c/
usdocker --global mappingDirTo=C:/

API

You can use USDocker in your node.js projects for wrap the “docker run” and do basic operations like PULL, RUN, STOP and others.

Here an example:

const usdocker = require('@usdocker/usdocker');

let docker = usdocker.dockerRunWrapper(configGlobal);
docker
    .image('ubuntu:16.04')
    .isInteractive(true)
    .isDetached(false)
    .commandParam('bash')
;

usdocker.up('ubuntu-container', docker, function(normal, verbose) {
    // do something
});

Check for the API documentaton clicking here

More Information

Contributing

If you wanna contributing to our project and create your own Useful Script for Docker, follow our guide, read about API and directories to create your own. After created your script you may want add to this list creating a pull request.

Live/Production environment

This is script can safely run on live/production environment. But we strongly recommend you backup the data saved into $USD_DATA directory.

Important Note

USDocker was implemented to run on the same machine where the docker daemon is running.

This script not intended to run from local to remote machines throught docker-machine.

If you have a Windows or Mac environment please can install the USDOCKER directly into the remote machine and run USDOCKER from there.

Disclaimer

THIS SOFTWARE IS PROVIDED “AS IS” AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.