Running Commodore

Commodore is written in Python and it requires external dependencies. We provide Commodore as a container image and a Python package on PyPI.

For local development, the procedure is documented in the README.

Commodore interacts with Git repositories that might require authorization. For this to work, Commodore needs to have access to an authorized SSH key.

PyPI

We recommend that you use the Commodore Python package provided on PyPI to make commodore available locally.

Prerequisites

Other documentation assumes that Helm 3 is available as helm and helm3, and Helm 2 is available as helm2 in $PATH. Please make sure you setup the Helm binaries accordingly on your local system.

As of 2021–11–03, Commodore doesn’t yet support Python 3.10+.

Installation

Generally, it’s best to create a separate virtualenv for Python utilities. Having separate virtualenvs avoids running into dependency conflicts when installing multiple Python utilities from PyPI.

  1. Check your Python version

    python3 --version

    This command should report something like

    Python 3.8.10
  2. Create a virtualenv in ~/.local/commodore-venv

    python3 -m venv ~/.local/commodore-venv
  3. Activate the virtualenv

    source ~/.local/commodore-venv/bin/activate
  4. Install Commodore into the virtualenv

    pip install syn-commodore
  5. Check that commodore was installed correctly

    commodore --version

Usage

If you’ve installed Commodore into a virtualenv, you need to activate the virtualenv whenever you want to run Commodore.

source ~/.local/commodore-venv/bin/activate

After that, you can run Commodore with

commodore --help
To leave the virtualenv, you can execute the deactivate command.

Docker

If you want, you can also use the Commodore container image locally.

In that case, the following shell functions can be placed in your shells configuration file (for example ~/.profile, ~/.bashrc, .zshrc etc.). By doing so, you can run commodore as if it was any other executable on your system.

Linux

On Linux it’s possible to use SSH agent and mounting the agents socket into the container.

commodore() {
  docker run \
    --interactive=true \
    --tty \
    --rm \
    --user="$(id -u)" \
    --env COMMODORE_API_URL=$COMMODORE_API_URL \
    --env COMMODORE_API_TOKEN=$COMMODORE_API_TOKEN \
    --env SSH_AUTH_SOCK=/tmp/ssh_agent.sock \
    --volume "${SSH_AUTH_SOCK}:/tmp/ssh_agent.sock" \
    --volume "${HOME}/.ssh/config:/app/.ssh/config:ro" \
    --volume "${HOME}/.ssh/known_hosts:/app/.ssh/known_hosts:ro" \
    --volume "${HOME}/.gitconfig:/app/.gitconfig:ro" \
    --volume "${PWD}:/app/data" \
    --workdir /app/data \
    projectsyn/commodore:${COMMODORE_VERSION:=latest} \
    $*
}

macOS

On macOS with Docker for Mac mounting the SSH agents socket into a container doesn’t work. Instead you need to mount as magic path that’s provided by Docker for Mac.

This only works for the stock ssh-agent coming along with macOS. If you use any other agent, you might be out of luck. Docker for mac doesn’t support mounting sockets.

That magic socket path belongs to root. One must run a container with --user=0 in order to access it. This doesn’t mess up your file permissions thanks to the magic of how volume mount work on Docker for Mac.

commodore() {
  docker run \
    --interactive=true \
    --tty \
    --rm \
    --user="0" \
    --env COMMODORE_API_URL=$COMMODORE_API_URL \
    --env COMMODORE_API_TOKEN=$COMMODORE_API_TOKEN \
    --env SSH_AUTH_SOCK=/tmp/ssh_agent.sock \
    --volume "/run/host-services/ssh-auth.sock:/tmp/ssh_agent.sock" \
    --volume "${HOME}/.ssh/config:/app/.ssh/config:ro" \
    --volume "${HOME}/.ssh/known_hosts:/app/.ssh/known_hosts:ro" \
    --volume "${HOME}/.gitconfig:/app/.gitconfig:ro" \
    --volume "${PWD}:/app/data" \
    --workdir /app/data \
    projectsyn/commodore:latest \
    $*
}

Instead you can also mount your SSH key into the container. The container will pickup that key and add it do an SSH agent running inside the container. You will be prompted to insert your SSH keys password if it has one.

commodore() {
  docker run \
    --interactive=true \
    --tty \
    --rm \
    --user="$(id -u)" \
    --env COMMODORE_API_URL=$COMMODORE_API_URL \
    --env COMMODORE_API_TOKEN=$COMMODORE_API_TOKEN \
    --volume "${HOME}/.ssh:/app/.ssh:ro" \
    --volume "${HOME}/.gitconfig:/app/.gitconfig:ro" \
    --volume "${PWD}:/app/data" \
    --workdir /app/data \
    projectsyn/commodore:latest \
    $*
}

If you have multiple SSH keys, you can mount only the one you need for commodore. This will remove the password prompt for each and every SSH key. Do this by using the following volumes instead of the line --volume "${HOME}/.ssh:/app/.ssh:ro" \

    --volume "${HOME}/.ssh/config:/app/.ssh/config:ro" \
    --volume "${HOME}/.ssh/known_hosts:/app/.ssh/known_hosts:ro" \
    --volume "/path/to/your/key:/app/.ssh/id_rsa:ro" \ (1)
1 Replace /path/to/your/key according to your needs.