Skip to main content
Version: v1

Pygmy

The Pygmy project describes the tool as follows:

pygmy is the single tool needed to get the local amazee.io Docker Drupal Development Environment running on your Linux based system. It is built to work with Docker for Mac! (quite a lot for such a small whale 🐳)

This page is for developers who set up a machine for a Vortex project or need their SSH key back in the CLI container. It explains what Pygmy provides, how to install and run it and how to reconnect the CLI container to Pygmy's SSH agent.

Pygmy provides the shared services the Vortex container stack relies on:

  • An HTTP reverse proxy for readable URLs. With a certificate you pass to pygmy up --tls-cert, it also handles HTTPS.
  • A DNS resolver for *.docker.amazee.io, so each project's local URL resolves to your machine.
  • An SSH agent, so your SSH key is available inside the CLI container.
  • A local mail catcher that receives and displays outgoing mail at http://mailhog.docker.amazee.io/.

A single Pygmy instance serves every project on your machine: start it once after each boot, and every local stack routes through it.

The docker-compose.yml that ships with Vortex depends on Pygmy twice. The nginx service joins the external amazeeio-network that Pygmy creates, and the cli service takes its SSH agent volume from Pygmy's amazeeio-ssh-agent container. The network and the agent container must exist before Docker Compose creates nginx and cli, so start Pygmy before ahoy up.

If the network is missing, ahoy up fails, because Docker Compose returns an error for a missing external network. If Pygmy's containers exist but aren't running, the stack starts without your SSH key in the CLI container.

ahoy doctor checks that the 4 Pygmy containers are running: the SSH agent, the mail catcher, the proxy and the DNS resolver. It looks for their names in the output of pygmy status:

amazeeio-ssh-agent
amazeeio-mailhog
amazeeio-haproxy
amazeeio-dnsmasq

Installation​

Follow the Pygmy installation instructions. For how Pygmy sets up DNS resolution on each operating system, see the Pygmy documentation.

Usage​

The following commands manage the Pygmy services:

pygmy up       # Start the services. Required to run only once per system boot.
pygmy down     # Stop the services.
pygmy restart  # Restart the services.
pygmy status   # Show the status of the services.
pygmy clean    # Stop and remove all services. Useful if you have issues with pygmy.

SSH key in the CLI container​

The CLI container uses the SSH agent from Pygmy's amazeeio-ssh-agent container. The CLI container mounts the agent's volume through volumes_from and connects to the agent's socket only when it starts.

Pygmy adds your default key, ~/.ssh/id_rsa, to the agent. To use a different key, add it yourself:

pygmy addkey --key ~/.ssh/path/to/key

A key you add that way lasts only until the agent container is replaced, for example by pygmy restart. To load a different key every time Pygmy starts, pass it with --key, as in pygmy up --key ~/.ssh/path/to/key. Pygmy then loads that key in place of the default key. pygmy restart takes the same --key option.

Whichever way you load a different key, set VORTEX_SSH_FILE to its path in .env.local, so that Doctor checks for the key you use.

pygmy restart removes the agent container and creates a new one. If the stack is running at the time, the CLI container stays attached to the previous agent, so the SSH key is missing inside the CLI container. The same happens when the stack starts while Pygmy's containers are stopped.

To reattach the CLI container to the current agent:

  1. If you use a different key, add it to the agent again, or restart with pygmy restart --key ~/.ssh/path/to/key. A plain pygmy restart loads only the default key.

  2. Recreate the CLI container:

    ahoy up --no-deps --force-recreate cli

    A plain ahoy up leaves the CLI container attached to the old agent. Docker Compose leaves a running container alone when its configuration hasn't changed.

ahoy doctor checks that the SSH key is available in the CLI container and prints the command from step 2 when the key is missing.

Confirm that the key is back: ahoy doctor prints [ OK ] SSH key is available within the CLI container.