Skip to content
Switch branches/tags
This branch is 8 commits ahead of dockito:master.

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Dockito Vault

A solution to use SSH keys while building images.

Here is an example installing Node.js dependencies:

RUN ONVAULT npm install

The Dockerfile

During build, you can use the ONVAULT utility to run any command using the private keys.

The private keys are removed automatically after the command completes.

First you need to install the ONVAULT utility, by adding the following statements in your Dockerfile (example works for Debian/Ubuntu):

# installs Dockito Vault ONVAULT utility
RUN apt-get update -y && \
    apt-get install -y curl && \
    curl -L > /usr/local/bin/ONVAULT && \
    chmod +x /usr/local/bin/ONVAULT

The script's only dependency is curl (being installed above).

Or on Alpine Linux:

# installs Dockito Vault ONVAULT utility
RUN apk add -Uuv bash curl && \
    curl -L > /usr/local/bin/ONVAULT && \
    chmod +x /usr/local/bin/ONVAULT

Then use it on any command that requires the private keys:

RUN ONVAULT npm install --unsafe-perm

Here is a complete Node.js example using these concepts:

FROM node:0.10.38

# installs Dockito Vault ONVAULT utility
RUN apt-get update -y && \
    apt-get install -y curl && \
    curl -L > /usr/local/bin/ONVAULT && \
    chmod +x /usr/local/bin/ONVAULT

RUN mkdir -p /usr/src/app
WORKDIR /usr/src/app

COPY package.json /usr/src/app/
RUN ONVAULT npm install --unsafe-perm
COPY . /usr/src/app

CMD [ "npm", "start" ]

How it works

It is composed of two pieces:

  • an HTTP server running at that serves the private keys;
  • a bash script ONVAULT that need to be installed in the image to allow accessing the private keys during the build process.

The server IP may be different depending in the docker version your are running or if you are using a custom bridge network for docker. Execute this command below to find out the ip used by docker:

ifconfig docker0 | grep 'inet ' | cut -d: -f2 | awk '{ print $2}'

Custom configurations

Environment variables

Some custom configurations are allowed through environment variables

  • VAULT_HOST: custom host for the vault server (example
  • VAULT_PORT: custom host+port for the vault server (example tcp:
  • VAULT_URI: custom URI for the vault server (example
  • VAULT_SSH_KEY: custom ssh key name used during ONVAULT command (example id_rsa)
  • VAULT_SSH_CONFIG: custom ssh config file used during ONVAULT command (example config)

SSH config file

Other ssh configurations can be achieved through your own ssh config file. Since the vault has access to the whole .ssh directory the ssh config file is available when running the ONVAULT command. Which means any configuration in the ssh config file will be applied to the ssh connection.

An example where you could use the ssh config file is when you need use different private keys for different hosts.


# use this key for github host
IdentityFile ~/.ssh/github_docker_key

# or use this key for my
IdentityFile ~/.ssh/myprivatehost_key

# otherwise will use the id_rsa key for any other host

If platform-specific commands are in your ~/.ssh/config, you can use the VAULT_SSH_CONFIG environment variable to specify an alternate file within the ~/.ssh directory.

SSH key password/passphrase

If your key is protected by passphrase, you can pass to ONVAULT the passphrase, so it before use the key will remove the password at the container.

ONVAULT --disable-pwd %password% npm install


In case you have symlink for any ssh file. Will be necessary map the volume of the symlink destination into the docker vault server. Otherwise will not be possible to resolve the symlink while copying the ssh files with the ONVAULT command.

The private keys server

Run the server setting a volume to your ~/.ssh folder:

docker run -p -v ~/.ssh:/vault/.ssh dockito/vault

This ip may be different. Check out the "How it works" session to find out the right ip in case this one is not working for you.

There is also a docker-compose.yml file in this project, allowing you to run it (by cloning the project) with:

docker-compose up vault

Happy codding!

Usage in runtime

Although its main purpose is to fix the issue of building Docker images, it can also be used as a source of secrets for some running container:

docker run -v ~/.ssh:/vault/.ssh --name vault dockito/vault
docker run --link vault image-with-onvault ONVAULT npm install --unsafe-perm


Because NPM dependencies are installed locally, the dependencies installed in the base-image won't be available in development time, so you will need to npm install them again:

git clone
cd vault
docker-compose run vault npm install
docker-compose up vault


A Dockerfile using this technique requires the special vault service running. Meaning it is not possible to run any build process at the Docker Hub.

As the vault service is not running an ssh-agent (instead copying the contents of files), the password cannot be entered prior to execution.


Initial implementation by Paulo Ragonha. Based on the ideas of Max Claus Nunes and Eduardo Nunes.


Secret store to be used on Docker image building



No packages published